# 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](https://zidane.si/docs/daemon.md) run the same chat engine and speak the same [protocol](https://zidane.si/docs/server-protocol.md). 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](https://zidane.si/docs/daemon.md#turn-it-on)) |
| 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](https://zidane.si/docs/servers-and-machines.md) |
| A web UI for your own agents | [`createServerHost`](https://zidane.si/docs/ui-adapters.md#zidane-server-over-websocket) 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`.

```bash
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](https://zidane.si/docs/server-install.md) the server there and [deploy](https://zidane.si/docs/server-deploy.md) it behind TLS. Remote hosts are off by default in the TUI and the desktop app. [Turn them on](https://zidane.si/docs/server-clients.md#turn-remote-hosts-on) first.

## Pages

| Page | Covers |
| - | - |
| [Install](https://zidane.si/docs/server-install.md) | Docker, the release binary, the `zidane` command, from source, and the first token |
| [Deploy](https://zidane.si/docs/server-deploy.md) | systemd, Docker Compose, Coolify, Caddy and nginx, backups, upgrades, resource limits |
| [Servers and machines](https://zidane.si/docs/servers-and-machines.md) | One main server, other computers as machines, join codes, moving a session |
| [Security](https://zidane.si/docs/server-security.md) | Tokens, TLS and proxies, origins, limits, the audit log, what a token can do |
| [Clients](https://zidane.si/docs/server-clients.md) | The desktop app, the TUI, browsers, the Node client, machines, settings sync, ACP |
| [Operations](https://zidane.si/docs/server-operations.md) | Logs, health, storage warnings, troubleshooting |
| [Configuration](https://zidane.si/docs/server-config.md) | Every command, flag, variable and `server.json` key, generated from the source |
| [Protocol](https://zidane.si/docs/server-protocol.md) | 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](https://zidane.si/docs/durability.md)). 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.