Server | Zidane

Server

Run the zidane chat host on another machine and attach the TUI, the desktop app or a browser over a WebSocket.

zidane-server runs the zidane chat host on a VPS, a home server or a container. Sessions, settings, provider keys, project files and the agents' commands live on that machine. Your windows attach over a WebSocket with a device token, and a run keeps going when you close them.

Text

 TUI   desktop   browser   attach
   \      |         |        /
    +-- wss:// + device token --+
              |            ^
      JSON-RPC requests  ipc.signal
              v            |
 +-----------------------------------+
 | zidane-server                     |
 |   chat host: sessions and runs    |
 |   tools run here, as its user     |
 |   data:  /data/.zidane            |
 |   files: /data/workspaces         |
 +-----------------------------------+

The server and the local daemon#

The server and the local daemon run the same chat engine and speak the same protocol. The hostKind field of the handshake says which host a client talks to.

Host	`hostKind`	Serves	Reached over	Runs tools on	Survives closing the window	Turn it on
In the window	`in-process`	That window	Nothing	Your computer, as you	No	Default
Local daemon	`daemon`	The windows of one computer	A unix socket, guarded by file permissions	Your computer, as you	Yes	The daemon setting (how)
zidane-server	`server`	Any device that holds a token	A WebSocket with TLS and a device token	The server, as its user	Yes, and restarts of your device	Install it, then add it as a remote host

A window can use both. This computer's sessions run in the daemon (or in the window). A server's sessions run on the server. The server also opens a unix socket of its own for the health and token commands on its machine.

When to use the server#

You want	Why the server fits
Runs that outlive your laptop's lid	The run is on the server. Any window can attach to it again
Agents next to the code on a build box	Commands run in the server's folders, with its tools
One set of sessions from several devices	Every client sees the same sessions and signals
Commands on a GPU box or a second computer, with the sessions in one place	Add the computer as a machine
A web UI for your own agents	`createServerHost` speaks the protocol from a page

For one machine, the daemon is enough.

What lives where#

Thing	On the server	On your device
Sessions, transcripts, running turns	Yes	No
Agent settings, `SYSTEM.md`, skills, MCP servers, extensions	Yes	Only for This computer's sessions
Provider keys	The server's environment and `credentials.json`	Your own, for local sessions
Project folders, shell commands, terminals	Inside the server's workspace roots	No
Theme, keybindings, window layout	No	Yes
Device tokens	A SHA-256 of each	The token, in `credentials.json`

Try it on one machine#

With the terminal app installed, zidane server is the same program as zidane-server.

Terminal

zidane server start                         # listens on 127.0.0.1:4280

# In another terminal: a token for this device, printed once on stdout.
(umask 077; zidane server token create --name laptop > laptop.token)
zidane --host ws://127.0.0.1:4280 --token-file laptop.token

For another machine, install the server there and deploy it behind TLS. Remote hosts are off by default in the TUI and the desktop app. Turn them on first.

Pages#

Page	Covers
Install	Docker, the release binary, the `zidane` command, from source, and the first token
Deploy	systemd, Docker Compose, Coolify, Caddy and nginx, backups, upgrades, resource limits
Servers and machines	One main server, other computers as machines, join codes, moving a session
Security	Tokens, TLS and proxies, origins, limits, the audit log, what a token can do
Clients	The desktop app, the TUI, browsers, the Node client, machines, settings sync, ACP
Operations	Logs, health, storage warnings, troubleshooting
Configuration	Every command, flag, variable and `server.json` key, generated from the source
Protocol	The handshake, every method and signal, errors, captured examples

Limits#

A server restart interrupts running turns. With crash recovery on or set to ask (the default), the restarted server resumes them, or asks in a window first (crash recovery). Tool calls the restart cut off are reported to the model as interrupted. Before a planned restart, zidane-server wait-idle waits for runs to end.
Server sessions have no dev browser. The browser panel drives a page on your computer.
Installs from a window go to the server user's scope only. A project's skills, extensions and MCP servers are files in its folder.
Extension popups, panels and palette items come from your device's extensions. A server session's / commands and inline suggestions run on the server.
Claude Code import fills the local store, so imported sessions do not show on a server.
Session folders are on the server. A window never sends its own working directory.