xiantong Docs
Server

Remote Server

Run xiantong as a remote server with browser, desktop, and CLI access

xiantong can run as a remote server, keeping long-running sessions alive on a remote machine and making them available from the desktop app, browser, or CLI.

This page keeps the generic configuration model. Use the install package, internal deployment artifact, or runtime command provided by your xiantong distribution.

Prerequisites#

  • A Linux or macOS host
  • Runtime dependencies required by your distribution
  • A reachable hostname or IP
  • A XIANTONG_SERVER_TOKEN for authentication
  • TLS, a private network, or a secure tunnel for non-local access

Generate a token:

export XIANTONG_SERVER_TOKEN=$(openssl rand -hex 32)
echo $XIANTONG_SERVER_TOKEN

Start the Server#

XIANTONG_SERVER_TOKEN=$XIANTONG_SERVER_TOKEN XIANTONG_RPC_HOST=0.0.0.0 XIANTONG_RPC_PORT=9100 xiantong-server

With TLS:

XIANTONG_SERVER_TOKEN=$XIANTONG_SERVER_TOKEN XIANTONG_RPC_HOST=0.0.0.0 XIANTONG_RPC_TLS_CERT=/path/to/cert.pem XIANTONG_RPC_TLS_KEY=/path/to/key.pem xiantong-server

Web UI#

Open the server URL in a browser and log in with the server token:

https://your-server:9100

Never expose the server on a network without TLS or a secure tunnel.

Connecting Clients#

Desktop app: add a workspace and choose Connect to Remote Server.

CLI:

export XIANTONG_SERVER_URL=wss://your-server:9100
export XIANTONG_SERVER_TOKEN=<token>

xiantong-cli ping
xiantong-cli sessions

Environment Variables#

VariableDescription
XIANTONG_SERVER_TOKENBearer token for authentication
XIANTONG_SERVER_URLServer URL for clients
XIANTONG_RPC_HOSTBind address
XIANTONG_RPC_PORTBind port
XIANTONG_RPC_TLS_CERTPEM certificate file
XIANTONG_RPC_TLS_KEYPEM private key file
XIANTONG_WEBUI_DIRWeb UI static asset directory
XIANTONG_DEBUGEnable debug logging

Run at Startup#

Linux systemd service example:

[Unit]
Description=xiantong Server
After=network.target

[Service]
Type=simple
User=<your-user>
WorkingDirectory=/opt/xiantong
EnvironmentFile=/etc/xiantong/server.env
ExecStart=/usr/local/bin/xiantong-server
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Secure Access#

Prefer Tailscale, SSH tunnels, or a reverse proxy such as Caddy or nginx. Bind the server to localhost when a reverse proxy handles external access.

Browser Tool#

The built-in browser can bridge from a remote workspace to a connected desktop client. Browser windows open on the local desktop client and use local cookies and signed-in sessions.

PreviousDeep Links