Chan manual
Devserver
Set up a devserver and connect to its terminals and workspaces from the Computers window.
The devserver runs chan on another machine for remote development. It can also run locally with a separate CHAN_HOME to isolate its state. Chan Desktop connects to the devserver as the client shell; sessions, window layouts, and terminals all live on the devserver.
For visual connection examples, see the ssh and Eternal Terminal guide. For managed access on your own domain, see the gateway guide and Host a gateway. To use a devserver from a browser instead of Chan Desktop, see Chan in a browser.
Pick where to run it:
- On macOS: a lima-vm, or a remote machine via ssh.
- On Windows: the native x64 standalone CLI, a WSL sandbox, or a remote machine via ssh.
- On Linux: an isolated devserver on the same machine (all platforms support
CHAN_HOME=/path), a docker container, or a remote machine via ssh.
Install on the host
On macOS, Linux, or FreeBSD, install chan:
$curl -fsSL https://chan.app/install.sh | sh
On native Windows x64, run this from PowerShell:
PS>irm https://chan.app/install.ps1 | iex
The Unix installer writes ~/.local/bin/chan and the symlink cs -> chan. The Windows installer writes chan.exe, cs.cmd, and a Git Bash cs shim under %LOCALAPPDATA%\chan-cli\bin and adds it to your user PATH.
Start the devserver
$~/.local/bin/chan devserver start
In a new native Windows terminal, use chan devserver start.
This installs the devserver as a background service listening on localhost:8787, using the default service manager for your platform:
- On Linux it uses systemd: a user-scoped service that survives logout once linger is on (chan enables it, or asks you to run
sudo loginctl enable-linger). - On macOS it uses launchd: the service runs while you are logged in.
- On Windows it uses chan's own daemon mode, which works on all platforms.
- You can override the choice with
--service=[auto,none,chan,systemd,launchd]. The actions arestart,stop,status,restart,join, androtate-token;--servicegoes after the action. chan devserver rotate-tokenmints a new token and prints it with the new URL, for a token you suspect has leaked. A running devserver drops the old token at once, so reopen any browser tab that used the old URL. Tokens also rotate by themselves at the first start after they turn 30 days old.chan devserver runruns in the foreground.chan devserver ls,connect,disconnect, andforgetmanage the desktop's connections to remote devservers. A connected devserver's workspaces are managed from a terminal on your desktop too:chan workspace serve /path --on NAME,chan close /path --on NAME, andchan workspace forget /path --on NAME, where NAME is the devserver's label or URL aschan devserver lsshows it and the path is on that machine.
Connect from the main window
Now add the devserver to Chan Desktop:
- Open the Computers screen (
Cmd+Pon macOS,Ctrl+Shift+Pon Windows and Linux), turn to the last card, and click Add devserver. - Fill in Name, Address, and Connect script. Examples:
- lima-vm from macOS:
- Address:
localhost:8787 - Script:
limactl shell default ~/.local/bin/chan devserver join
- Address:
- WSL from Windows:
- Address:
localhost:8787 - Script:
wsl ~/.local/bin/chan devserver join
- Address:
- Remote machine via ssh:
- Address:
localhost:9901 - Script:
ssh -L localhost:9901:127.0.0.1:8787 user@host '~/.local/bin/chan devserver join --port 8787'
- Address:
- lima-vm from macOS:
- Optionally tick Auto-hide control terminal on success so the terminal running the connect script hides itself once connected.
- Click Add devserver. The new devserver's card comes to the front; click its header's on/off connection control, or select the header and press
o.
The control terminal
Connecting opens a window titled Control Terminal - NAME that runs the connect script in a real terminal on your desktop, through your login shell. If ssh asks to accept a host key or for a password, answer it there. On the remote side, join prints the devserver's address and token:
chan devserver: listening on http://127.0.0.1:8787/?t=Zr8mT2xQwN6vLb3HcY5dKp7sJf9aGe4u
CHAN_DEVSERVER_TOKEN=Zr8mT2xQwN6vLb3HcY5dKp7sJf9aGe4u
Chan Desktop reads the token from the control terminal, so you never copy it, and a rotated token is picked up on the next connect. Then it reaches the devserver through the tunnel and the card turns connected. A devserver's first start opens one terminal window, which appears as a native window titled with the remote host's name.
The control terminal stays open while the script runs: it is the connection. With Auto-hide control terminal on success ticked it hides itself once the connection is up; show it again from its row, Control terminal, the first one on the devserver's card.
Disconnect and dropped connections
Disconnect (o on the card) ends the connect script and closes the devserver's windows on your desktop. Everything on the devserver keeps running: terminals, programs, workspaces, and window layouts. Connect again and every shown window reopens where it was. Chan Desktop does not connect devservers by itself when it starts.
When something goes wrong, the control terminal is where to look:
- The tunnel is interrupted while the script still runs: the devserver's windows show
reconnecting to the chan serverand keep trying. Reconnect runs the connect script again; Abandon disconnects. - The script exits with an error, for example when ssh loses the connection: the devserver's windows close, and the control terminal stays open with the script's last words and
process exited (255); press Ctrl+D to close this tab. Its row on the card flashes for attention. Read why, close it, and connect again.
An ssh tunnel dies with the network, when you close the laptop lid or change Wi-Fi. Eternal Terminal reconnects across those interruptions: its et --tunnel 9901:8787 --command '~/.local/bin/chan devserver join --port 8787' user@host is the same forward as ssh's -L. The connection guide has both scripts side by side.
The same actions work from a terminal on your desktop: chan devserver ls, chan devserver connect NAME, and chan devserver disconnect NAME.
Connect through a gateway
A gateway is a set of services you host yourself; it is not an online service. It reaches your devservers, and devservers shared with you, through its tunnel instead of a connect script. Press g on the Computers screen, or click its title, to flip to the Gateways screen, then:
- Turn to the Add gateway card and enter the gateway's URL (
https://...) and an optional name. - Click the gateway card's on/off connection control, or select its header and press
o, then sign in in your browser. One sign-in covers the whole account. - Flip back to Computers with
g: the gateway's devservers are listed there, each marked "via" the gateway.
Reach a gateway through WireGuard
Chan can run a userspace WireGuard peer inside the devserver or desktop process to reach a gateway behind a WireGuard peer. It creates no OS network interface or host routes and needs no root privileges or separate VPN client.
On the devserver, supply the gateway PAT through CHAN_TUNNEL_TOKEN and point --tunnel-wireguard (or CHAN_TUNNEL_WIREGUARD) at the local wg-quick file:
$chan devserver run \
--tunnel-url https://proxy.example.com/v1/tunnel \
--tunnel-wireguard /absolute/path/to/devserver.conf
The tunnel URL's destination must be inside the peer's AllowedIPs. An http:// ingress inside WireGuard is also accepted: WireGuard pins the peer's key and encrypts the connection. The gateway token is still required.
On the desktop, add or edit a gateway in the launcher and set WireGuard file to its local wg-quick file. Use an absolute path or one starting with ~/. The file is validated when you save and takes effect as soon as it is saved: changing the path starts the new tunnel, and clearing it ends the old one. To re-read a file edited in place, clear the field, save, and set it again.
Both clients read the same wg-quick subset:
- One
[Interface]: requiredPrivateKeyandAddress, optionalMTU. - Exactly one
[Peer]: requiredPublicKey,Endpoint(host or IP address with a port), andAllowedIPs; optionalPresharedKeyandPersistentKeepalive. DNS,Table,FwMark,ListenPort,PreUp,PostUp,PreDown,PostDown,SaveConfig, unknown keys, and additional peers are refused.
On Unix, the file must have no group or other permission bits; use chmod 600 /absolute/path/to/devserver.conf. Windows ACLs are not checked by this reader; restrict access to the file yourself because it contains the private key.
See the gateway guide for the desktop connection and the chan-wireguard design for the implementation.
Open remote terminals and workspaces
A connected devserver's card offers New terminal (t). Its registered workspaces appear on the card; open a workspace window from its row with New window (w). The command launcher's Computers scope does the same from any window on that devserver.
Once connected, remote terminals and workspaces behave like local ones: run chan open {path} in a devserver terminal to create a workspace on that machine, or chan workspace serve {path} --on NAME from a terminal on your desktop. Disconnecting keeps the remote sessions alive and running; reconnect and pick up where you left off.
The clipboard and file transfer work across the connection too: see Copy and paste freely and Download and upload freely on the Terminal page.
To inspect connected clients and manage workspace leadership, see Collaboration & sessions.
On Linux devservers managed by systemd with fdstore support, you can restart the devserver process without losing your shells: the PTY file descriptors are parked in the systemd fdstore while the devserver restarts, then loaded back up, so your agents continue working and your terminals are always alive.
Under the hood: design.md describes the devserver over a TCP tunnel and through a gateway, and gateway/design.md the gateway you host.