zidane 7.2.5 → 8.0.4

package/docs/SERVER.md

@@ -0,0 +1,1085 @@
+# zidane-server
+
+zidane-server runs a zidane chat host on another machine (a VPS, a home
+server, a container). Sessions, settings, provider credentials and the
+tools' working directories live on that machine; TUI windows and the
+desktop app on your laptop attach to it over a WebSocket with a device
+token. Runs keep going when the window closes, and any window you attach
+later picks them up.
+
+It is the same host the local daemon runs (see [IPC.md](./IPC.md)), served
+over the network instead of a unix socket. Internals:
+[IPC.md § Remote server](./IPC.md#remote-server-zidane-server).
+
+- [Opt-in and kill switch](#opt-in-and-kill-switch)
+- [Install](#install): [Docker image](#docker-image), [release binaries](#release-binaries), [from source](#from-source)
+- [Deploy on Coolify](#deploy-on-coolify)
+- [Configuration](#configuration)
+- [TLS or a reverse proxy](#tls-or-a-reverse-proxy)
+- [Tokens](#tokens)
+- [Connecting](#connecting)
+- [Security model](#security-model)
+- [Settings sync](#settings-sync)
+- [Operations](#operations)
+- [Limitations](#limitations)
+
+## Opt-in and kill switch
+
+Nothing connects to a remote host unless you say so: either an explicit
+`--host` (or `ZIDANE_HOST_URL`) at launch, or Settings → Remote hosts
+(experimental, off by default) and a server saved on Settings → Hosts.
+`ZIDANE_NO_REMOTE=1` (or `zidane --no-remote`, which sets it for the
+process) on the client wins over everything: the CLI refuses an explicit
+`--host` with a message naming the switch, ignores a `ZIDANE_HOST_URL` from
+the environment (one warning on stderr, then the window runs locally), and
+the window behaves as if Remote hosts were off (no Hosts tab, saved hosts not
+even read).
+
+The server listens on loopback by default and refuses to bind any other
+interface without TLS or an explicit `--behind-proxy`.
+
+## Install
+
+Three ways, all the same server:
+
+- [Docker image](#docker-image) from GitHub Container Registry
+  (recommended; plain Docker, Compose, Coolify),
+- [release binaries](#release-binaries) for darwin and linux (arm64, x64),
+- [from source](#from-source) (a checkout of this repository).
+
+Every release (`vX.Y.Z` tag) publishes both, from the same commit and only
+after the release workflow's gates passed (typecheck, lint, tests, binary
+and image smoke tests).
+
+### Docker image
+
+`ghcr.io/tahul/zidane-server`, for `linux/amd64` and `linux/arm64`:
+
+```bash
+docker run -d --name zidane --restart unless-stopped \
+  -v zidane-data:/data -p 127.0.0.1:4280:4280 \
+  ghcr.io/tahul/zidane-server:7.2
+# Create a token for each device (printed once):
+docker exec zidane zidane-server token create --name laptop
+```
+
+| Tag | What it points at |
+|---|---|
+| `7.2.5` | Exactly that release. Never moves. |
+| `7.2` | The latest `7.2.x` patch release. **Recommended**: fixes without surprises. |
+| `7` | The latest `7.x` release. |
+| `latest` | The latest release. Fine to try things; pin `X.Y` or an exact version for anything you keep. |
+
+A pre-release (`v8.0.0-beta.1`) is published under its own version only
+(`8.0.0-beta.1`), never `X.Y`, `X` or `latest`. The image's
+`org.opencontainers.image.version` label is the release version.
+
+Each image carries a build provenance attestation (Sigstore, from the
+release workflow) plus buildx's SLSA provenance and SBOM. Check that an
+image was built by this repository's release workflow:
+
+```bash
+gh attestation verify oci://ghcr.io/tahul/zidane-server:7.2.5 --owner tahul
+```
+
+#### With Docker Compose
+
+`server/docker-compose.selfhost.yml` runs the image with a named volume,
+loopback-only port and an optional Caddy. From a checkout (or just that
+file):
+
+```bash
+# Server only, published on 127.0.0.1:4280 for a proxy you already run:
+ZIDANE_SERVER_VERSION=7.2 docker compose -f server/docker-compose.selfhost.yml up -d
+
+# Or with the bundled Caddy (automatic HTTPS; the domain must point at this machine):
+ZIDANE_SERVER_VERSION=7.2 ZIDANE_DOMAIN=zidane.example.com docker compose -f server/docker-compose.selfhost.yml --profile caddy up -d
+
+# Create a token for each device (printed once):
+docker compose -f server/docker-compose.selfhost.yml exec zidane-server zidane-server token create --name laptop
+```
+
+`ZIDANE_SERVER_VERSION` is the image tag (default `latest`); put it in a
+`.env` file next to the command so every `docker compose` call agrees.
+
+Then, on the laptop (save the token in a 0600 file first):
+
+```bash
+zidane --host wss://zidane.example.com --token-file ~/.config/zidane/box.token
+```
+
+#### What is in the image
+
+The image (`server/Dockerfile`, one file for plain Docker, Compose and
+Coolify) is a slim Debian (base images pinned by tag and digest) with
+`git`, `openssh-client` (git over ssh, keys in `/data/.ssh`), `ripgrep`,
+`bash`, `ca-certificates` and `tini`, a non-root `zidane` user (uid 1000),
+the compiled server binary, and `/data` as the storage volume. Projects go
+in `/data/workspaces`, the image's workspace root
+(`ZIDANE_SERVER_WORKSPACE_ROOTS`): mount them there
+(`- /home/me/code:/data/workspaces`) or clone them there from a session.
+Its command is `start`, and its listening defaults are environment
+variables (so a platform's UI can change them; a flag would beat them):
+`ZIDANE_SERVER_HOST=0.0.0.0`, `ZIDANE_SERVER_BEHIND_PROXY=1` (for a
+TLS-terminating proxy only) and `ZIDANE_SERVER_TRUSTED_PROXIES=private`
+(see [TLS or a reverse proxy](#tls-or-a-reverse-proxy)). Its `HEALTHCHECK`
+runs `zidane-server health --http` (`GET /healthz` on the server's port,
+every 10 s after a 30 s start period); `STOPSIGNAL` is SIGTERM, and the
+drain it starts is bounded by `ZIDANE_SERVER_DRAIN_TIMEOUT_MS` (default
+8 s, under Docker's default 10 s stop timeout; both Compose files set
+`stop_grace_period: 30s`). Raise the drain only together with the stop
+timeout (`docker stop -t`, `docker run --stop-timeout`,
+`stop_grace_period`), or Docker kills the server mid-drain.
+
+> **Migrating from an earlier image.** The image now defaults to
+> `ZIDANE_SERVER_BEHIND_PROXY=1` and `ZIDANE_SERVER_TRUSTED_PROXIES=private`.
+> A deployment that serves TLS from the server itself (`ZIDANE_SERVER_TLS_CERT`
+> / `_TLS_KEY`, or `--tls-cert` / `--tls-key` in a custom command) must set
+> `ZIDANE_SERVER_BEHIND_PROXY=0` and an empty `ZIDANE_SERVER_TRUSTED_PROXIES=`:
+> TLS together with behind-proxy is a boot error ("TLS on the server and
+> behind-proxy are exclusive"), since every direct TLS client would otherwise
+> get a 403 for its missing `X-Forwarded-Proto`. The generic `PORT` variable
+> is no longer read: use `ZIDANE_SERVER_PORT`.
+
+The image and Compose run `--behind-proxy`: every upgrade must come
+through the proxy with `X-Forwarded-Proto: https`, and a connection to the
+published `127.0.0.1:4280` reaches the container from the Docker bridge
+gateway, not from loopback. So connect through the proxy
+(`wss://zidane.example.com`), use `docker exec <container> zidane-server
+health` / `token …` for local operations (the unix socket, no token), or
+run a separate loopback-only server without `--behind-proxy` for local
+use. `GET /healthz` answers on the published port either way.
+
+### Release binaries
+
+Each [GitHub release](https://github.com/Tahul/zidane/releases) carries
+`zidane-server-v<version>-<os>-<arch>.tar.gz` for `darwin-arm64`,
+`darwin-x64`, `linux-x64` and `linux-arm64` (the binary, `LICENSE`, this
+directory's `README.md`, in a `zidane-server-v<version>-<os>-<arch>/`
+directory) and a `SHA256SUMS` file. One self-contained executable, no
+runtime to install. The linux builds need glibc (Debian, Ubuntu, Fedora…;
+not Alpine/musl). The darwin builds are ad-hoc signed, not notarized:
+downloaded with a browser, clear the quarantine flag first
+(`xattr -d com.apple.quarantine zidane-server`); `curl` sets none.
+
+```bash
+V=7.2.5 T=linux-x64            # darwin-arm64, darwin-x64, linux-x64, linux-arm64
+curl -fLO "https://github.com/Tahul/zidane/releases/download/v$V/zidane-server-v$V-$T.tar.gz"
+curl -fLO "https://github.com/Tahul/zidane/releases/download/v$V/SHA256SUMS"
+grep " zidane-server-v$V-$T.tar.gz\$" SHA256SUMS | shasum -a 256 -c   # or sha256sum -c
+gh attestation verify "zidane-server-v$V-$T.tar.gz" --owner tahul    # built by the release workflow
+tar -xzf "zidane-server-v$V-$T.tar.gz"
+sudo install -m 0755 "zidane-server-v$V-$T/zidane-server" /usr/local/bin/
+zidane-server start                    # 127.0.0.1:4280
+zidane-server token create --name laptop
+```
+
+Run this way (loopback, no `--behind-proxy`), `zidane --host
+ws://127.0.0.1:4280 --token-file …` works on the server itself without TLS
+(`ws://` is accepted for loopback only). For other machines, use an SSH
+tunnel (`ssh -L 4280:127.0.0.1:4280 box`, then the same command) or set up
+TLS / a proxy below.
+
+Any machine with `zidane` installed already has the server too:
+`zidane server start` is `zidane-server start`.
+
+### From source
+
+From a checkout of the repository:
+
+```bash
+# The image, built locally (BuildKit; cross-compiles for another platform with --platform):
+docker build -f server/Dockerfile -t zidane-server .
+docker build --platform linux/amd64 -f server/Dockerfile -t zidane-server:amd64 .
+# Both platforms at once need a docker-container builder (or the containerd image store):
+docker buildx create --name multiarch --driver docker-container
+docker buildx build --builder multiarch --platform linux/amd64,linux/arm64 -f server/Dockerfile .
+
+# Compose, building the image from the checkout instead of pulling it:
+docker compose -f server/docker-compose.selfhost.yml -f server/docker-compose.build.yml up -d --build
+
+# The binary:
+bun run server:build                         # → server/dist/zidane-server (this machine)
+bun run scripts/build-server.ts linux-x64    # → server/dist/linux-x64/zidane-server
+./server/dist/zidane-server start            # 127.0.0.1:4280
+./server/dist/zidane-server token create --name laptop
+
+# The release archives, as the release workflow makes them (→ server/dist/release/):
+bun run server:release:package
+```
+
+### Distribution
+
+- **Docker image**: `ghcr.io/tahul/zidane-server`, built and pushed by
+  the release workflow's `server-image` job (`.github/workflows/release.yml`)
+  for `linux/amd64` and `linux/arm64` after the `release` job (every gate,
+  npm packages, GitHub release) succeeded. The Dockerfile's build stage
+  runs on the builder's platform and cross-compiles the binary for the
+  target one (Bun's `--compile --target`), so only the runtime stage's
+  `apt-get` runs under emulation. The `linux/amd64` image is loaded and
+  smoke-tested before anything is pushed. A rerun of the job pushes the
+  same tags again (an idempotent overwrite of that version).
+- **Binary**: `scripts/build-server.ts` compiles `src/server/main.ts`
+  with `bun build --compile` for darwin and linux (arm64, x64). It checks
+  the import graph first and fails if the TUI, OpenTUI, a React renderer
+  or tree-sitter reaches it. `scripts/package-server-release.ts`
+  (`bun run server:release:package`) builds the four targets and writes
+  the release archives and `SHA256SUMS` (reproducible: fixed order, mtime
+  and owner). The release job (macOS, so darwin binaries get their ad-hoc
+  signature) builds, smoke-tests the darwin-arm64 binary and checks the
+  sums before the GitHub release exists, then attests and uploads them
+  right after it is created, before any npm publish.
+- **npm**: `server/` is the `zidane-server` workspace package. Its
+  `zidane-server` launcher runs the lean binary when one is built next to
+  it (`server/dist/`) and reports the package's version (a stale build is
+  skipped with a warning), else `zidane server …` from `zidane-tui`'s
+  platform binary (same code, checked to be the same version). The server
+  runs in its own process group: one Ctrl-C or `systemctl stop` reaches
+  it once and drains it (a second signal at least a second later skips the
+  drain); if the launcher dies, the server notices (a pipe on its fd 3
+  closes) and shuts down gracefully. It is `private` for now: no separate
+  per-platform npm packages until there is demand.
+
+**Maintainers, once**: GHCR creates the package private on its first push.
+After the first release, open the package (github.com/Tahul → Packages →
+`zidane-server` → Package settings): set *Change visibility* to
+**Public**, and check it is linked to the repository (the image's
+`org.opencontainers.image.source` label links it; otherwise *Connect
+repository*). Until then, pulls without a login fail.
+
+## Deploy on Coolify
+
+[Coolify](https://coolify.io) pulls the released image
+(`ghcr.io/tahul/zidane-server`; or builds it from this repository), runs
+it on its `coolify` Docker network and puts its Traefik in front: Traefik
+terminates TLS (WebSockets included), sets `X-Forwarded-Proto` /
+`X-Forwarded-For`, and proxies to the container's port. The image's
+defaults are made for that: behind a proxy, proxies believed from any
+private address (`private`; Traefik's address on the network is not fixed),
+configuration by environment only, a health check that needs no `curl`.
+
+**The assumption behind `private`**: the server's port is reachable only
+through Traefik and the private Docker network. Leave Coolify's *Ports
+Mappings* empty (a published host port bypasses Traefik, and any peer on a
+private network could then claim `https`). To tighten it, set
+`ZIDANE_SERVER_TRUSTED_PROXIES` to the `coolify` network's subnet
+(`docker network inspect coolify -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}'`
+on the server). See [the caveats of `private`](#caveats-of-private).
+
+**Without *Persistent Storage* on `/data`, every redeploy starts from an
+empty data dir**: sessions, settings, provider keys, device tokens and the
+audit log are gone. The image declares `/data` a `VOLUME`, but without a
+mount Docker makes an anonymous volume per container, and Coolify creates
+a new container on each deploy. Add the volume (step 4) before you store
+anything. The server warns at start (`the data dir is not on a persistent
+volume; it will be lost when the container is recreated`) when it runs in
+a container and finds no named volume or host directory mounted over its
+data dir.
+
+### 1. Create the application (Docker Image, recommended)
+
+1. *+ New* → **Docker Image**. *Image Name*:
+   **`ghcr.io/tahul/zidane-server:7.2`** (Coolify moves the tag into its
+   *Tag* field). Pin `X.Y` (patch releases only) or an exact version
+   (`7.2.5`); an empty tag means `latest`. See [the tags](#docker-image).
+   *Save*.
+2. *Configuration* → *General*: *Ports Exposes* **`4280`** (a Docker
+   Image application starts with `80`: replace it). *Ports Mappings*: empty.
+3. *Domains*: `https://zidane.example.com` (or a generated one). Traefik
+   handles the certificate.
+4. **Required:** *Persistent Storage* → *Add* → *Volume Mount*: name
+   `zidane-data`, *Destination Path* **`/data`**. Without it, every
+   redeploy loses all data (above). A *Directory Mount* works too, but the
+   host directory must be writable by uid 1000 (`chown 1000:1000 <dir>`).
+5. *Health check*: **leave Coolify's dashboard health check disabled**;
+   the image's `HEALTHCHECK` (`zidane-server health --http`) is used
+   (Coolify ignores the dashboard check while the image has one, and the
+   dashboard's HTTP check would need `curl` or `wget`, which the image does
+   not ship). To test by hand, in the application's *Terminal*:
+   `zidane-server health --http` (or `zidane-server health`, over the unix
+   socket).
+   *Stop timeout*: the server drains for up to 8 s
+   (`ZIDANE_SERVER_DRAIN_TIMEOUT_MS`), under the 10 s Docker gives a
+   container by default; if you raise the drain, raise the application's
+   stop grace period with it (where your Coolify version offers it; the
+   Compose build pack below sets `stop_grace_period: 30s`).
+6. *Environment Variables* (below). Mark secrets (the bootstrap token,
+   provider keys) as runtime-only (not *Available at Buildtime*; with the
+   Docker Image nothing is built, and with the Dockerfile build pack the
+   Dockerfile reads no build argument but `BUN_IMAGE` / `RUNTIME_IMAGE` /
+   `ZIDANE_VERSION`: secrets have no business in a build).
+7. *Deploy*. The log shows the image pulled, then `zidane server listening
+   on ws://0.0.0.0:4280` and `Stored the bootstrap token …`; the status
+   turns healthy within ~30 s; `https://zidane.example.com/healthz` answers
+   `ok`.
+
+### From source: Dockerfile build pack (alternative)
+
+To deploy `main` (or your fork) rather than a release, let Coolify build
+`server/Dockerfile`:
+
+1. *+ New* → *Public Repository* (or your fork through a GitHub App /
+   deploy key) → this repository, branch `main`.
+2. *Build Pack*: **Dockerfile**. *Base Directory*: **`/`**. *Dockerfile
+   Location*: **`/server/Dockerfile`** (the build context is the repository
+   root, filtered by the root `.dockerignore`).
+3. Then steps 2 to 7 above (*Ports Exposes* `4280`, domain, the `/data`
+   volume, health check, variables, deploy).
+
+### Environment variables
+
+Everything has a working default; set what you need.
+
+| Variable | Value |
+|---|---|
+| `ZIDANE_SERVER_BOOTSTRAP_TOKEN` | A first client token, so you can connect before you ever open a shell: run `zidane-server token generate` (or `zidane server token generate`, any machine with zidane; `docker run --rm <image> token generate`), paste the `zds_…` line. It stays visible in the container's configuration (Coolify's UI, `docker inspect`, terminal shells): revoke `bootstrap` once you have device tokens. See [Tokens](#tokens). |
+| `ZIDANE_SERVER_BOOTSTRAP_TOKEN_FILE` | Instead of the above (not both): the path of a file holding the token, e.g. a secret file mounted with Coolify's *Persistent Storage* → *File Mount* (`/run/secrets/zidane-bootstrap`). Keeps the token out of the environment. |
+| `ZIDANE_SERVER_NAME` | The name windows show (default: the container's hostname, which Docker makes the short container id unless the platform sets one; the Compose files set `zidane-server`). |
+| `ANTHROPIC_API_KEY`, `OPENAI_CODEX_API_KEY`, `OPENROUTER_API_KEY`, … | Provider keys the server's agents use ([the list](#provider-keys)). Or set them later from a window. |
+| `ZIDANE_SERVER_TRUSTED_PROXIES` | Default `private`; the `coolify` network's subnet to tighten. |
+| `ZIDANE_SERVER_ALLOWED_ORIGINS` | Browser origins allowed to connect (default none; the TUI and the desktop app send none). |
+| `ZIDANE_SERVER_PORT` | Only if you change *Ports Exposes* (then both must agree). The generic `PORT` is not read. |
+| `ZIDANE_SERVER_DRAIN_TIMEOUT_MS` | How long SIGTERM waits for running turns (default `8000`, under Docker's 10 s stop timeout). |
+| any other `ZIDANE_SERVER_*` | [Configuration](#configuration). |
+
+### Docker Compose build pack (alternative)
+
+`server/docker-compose.yml` is the same deployment as a Compose
+file, with Coolify's conventions: *Build Pack* **Docker Compose**, *Base
+Directory* **`/`**, *Docker Compose Location*
+**`/server/docker-compose.yml`**. It runs the released image,
+`ghcr.io/tahul/zidane-server:${ZIDANE_SERVER_VERSION:-latest}` (set
+`ZIDANE_SERVER_VERSION` to `7.2` or an exact version in its variables), and
+declares `SERVICE_URL_ZIDANE_4280` (Coolify generates a URL from your wildcard
+domain and routes it to port 4280; or enter your own domain on the
+`zidane` service as `https://zidane.example.com:4280`), a named volume on
+`/data`, the variables above as editable `${VAR}` / `${VAR:-default}`
+entries, and the health check spelled out. No `ports:` and no Caddy.
+
+### 2. Connect
+
+Save the bootstrap token in a 0600 file on your laptop, then:
+
+```bash
+zidane --host wss://zidane.example.com --token-file ~/.config/zidane/coolify.token
+```
+
+Or add it as a saved host: TUI Settings → Remote hosts on, Settings → Hosts
+→ `+ add a server`; desktop app Settings › General › Experimental › Remote
+hosts, then Settings › Hosts › Add a server. URL
+`wss://zidane.example.com`, the token.
+
+### 3. Per-device tokens, then retire the bootstrap one
+
+In the application's *Terminal* (it opens as the `zidane` user):
+
+```bash
+zidane-server token create --name laptop     # printed once: store it on the laptop
+zidane-server token create --name desktop
+zidane-server token revoke bootstrap         # drops its connections at once
+```
+
+Then delete `ZIDANE_SERVER_BOOTSTRAP_TOKEN` in Coolify (or leave it: a
+revoked value is never brought back; the server warns at start). Removing
+the variable alone does not revoke the stored token.
+
+### Upgrading, backups
+
+- **Upgrade**: with the Docker Image, bump the tag (*Configuration* →
+  *General* → *Docker Registry* → *Docker Image Tag*, e.g. `7.2` → `7.3`)
+  and *Redeploy*; on a moving tag (`7.2`, `7`, `latest`) a *Redeploy*
+  alone pulls the newest image under it (so does a *Restart*: pin an exact
+  version if you want neither to change it). Compose build pack: change
+  `ZIDANE_SERVER_VERSION`, *Redeploy*. Dockerfile build pack: *Redeploy*
+  (or automatic deployments on push) builds the branch again. The volume
+  carries over (only if you added one: step 4); the old container gets
+  SIGTERM, drains its runs for up to 8 s and exits 0; windows reconnect.
+- **Backups**: the `/data` volume holds everything (sessions, settings,
+  credentials, tokens, audit log, workspaces). Use Coolify's storage
+  backups for the volume if your version offers them, or stop the
+  application and archive the volume on the server:
+  `docker run --rm -v <volume>:/data -v "$PWD":/backup debian:trixie-slim tar czf /backup/zidane-data.tgz -C /data .`
+  (`docker volume ls` shows the name Coolify gave it). Copying
+  `sessions.db` while the server runs can catch the WAL mid-write.
+
+## Configuration
+
+Sources, highest first: flags, `ZIDANE_SERVER_*` environment variables,
+`<data dir>/server.json`, defaults. The generic `PORT` variable is never
+read (a `PORT` exported for something else must not move the server). Every value is validated at boot; an
+error names the flag, variable or file key. An empty variable counts as
+unset (`ZIDANE_SERVER_TRUSTED_PROXIES=` clears the image's default);
+`ZIDANE_SERVER_BEHIND_PROXY=0` turns off what the image turns on.
+
+| Setting | Flag | Environment | `server.json` | Default |
+|---|---|---|---|---|
+| Interface | `--host` | `ZIDANE_SERVER_HOST` | `host` | `127.0.0.1` |
+| Port | `--port` | `ZIDANE_SERVER_PORT` | `port` | `4280` (`0`: any free port) |
+| TLS certificate / key (PEM; not with behind-proxy: a boot error) | `--tls-cert` / `--tls-key` | `ZIDANE_SERVER_TLS_CERT` / `_TLS_KEY` | `tlsCert` / `tlsKey` (relative to the data dir) | none |
+| Interface (image) | | | | `0.0.0.0` (the image sets `ZIDANE_SERVER_HOST`) |
+| Behind a TLS proxy | `--behind-proxy` | `ZIDANE_SERVER_BEHIND_PROXY=1` (`0` off) | `behindProxy` | `false` (the image: on) |
+| Trusted proxies (IPs / CIDRs / `private`; needs behind-proxy) | `--trusted-proxies <list>` | `ZIDANE_SERVER_TRUSTED_PROXIES` (comma-separated) | `trustedProxies` | none: any peer (a warning at start); the image: `private`; Compose: its network |
+| Name shown to clients | `--name` | `ZIDANE_SERVER_NAME` | `name` | the machine's hostname; in a plain `docker run` or Coolify's Dockerfile build pack, the container's hostname (Docker's default: the short container id; set a name); both Compose files set `zidane-server` |
+| Unix socket | `--socket <path\|off>` | `ZIDANE_SERVER_SOCKET` | `socket` | `<data dir>/server.sock` |
+| Heartbeat (ms, `0` off) | | `ZIDANE_SERVER_HEARTBEAT_MS` | `heartbeatMs` | `20000` |
+| Max message size (bytes): a bigger incoming frame closes the connection, a bigger reply is answered with an error (`ResponseTooLarge`; clients page what can be big) | | `ZIDANE_SERVER_MAX_MESSAGE_BYTES` | `maxMessageBytes` | 32 MiB |
+| Rate limit per connection | | `ZIDANE_SERVER_RATE_LIMIT` / `_RATE_BURST` | `rateLimit: { perSecond, burst }` | 50/s, burst 200 (`0` off) |
+| Browser origins allowed | | `ZIDANE_SERVER_ALLOWED_ORIGINS` (comma-separated) | `allowedOrigins` | none |
+| Upgrades per client address | | `ZIDANE_SERVER_UPGRADE_RATE_LIMIT` / `_UPGRADE_RATE_BURST` | `upgradeRateLimit: { perSecond, burst }` | 5/s, burst 30 (`0` off) |
+| Open connections per token | | `ZIDANE_SERVER_MAX_CONNECTIONS_PER_TOKEN` | `maxConnectionsPerToken` | 16 |
+| Open connections per client address | | `ZIDANE_SERVER_MAX_CONNECTIONS_PER_ADDRESS` | `maxConnectionsPerAddress` | 32 |
+| Workspace roots: where session folders may be (the first is the default) | `--workspace-root <dir>` (repeatable) | `ZIDANE_SERVER_WORKSPACE_ROOTS` (path-delimited, absolute) | `workspaceRoots` (relative to the data dir) | `<data dir>/workspaces` (`/data/workspaces` in the image) |
+| Drain bound at shutdown (ms) | | `ZIDANE_SERVER_DRAIN_TIMEOUT_MS` | `drainTimeoutMs` | `8000` (fits Docker's 10 s stop timeout) |
+| Lend this server as a machine to its clients' computers (`local@<server>`, [MACHINES.md § Reverse direction](./MACHINES.md#reverse-direction)) | `--allow-as-machine` | `ZIDANE_SERVER_ALLOW_AS_MACHINE=1` | `allowAsMachine` | off |
+| Installs, updates and removals of skills, extensions and MCP servers from clients ([Installs from a client](#installs-from-a-client)) | `--no-remote-installs` (off) | `ZIDANE_SERVER_ALLOW_REMOTE_INSTALLS=0` | `allowRemoteInstalls` | on |
+| Storage root | `--data-dir` | `ZIDANE_SERVER_DATA_DIR` | | zidane's usual user dir |
+| Bootstrap client token ([Tokens](#tokens)) | | `ZIDANE_SERVER_BOOTSTRAP_TOKEN`, or `ZIDANE_SERVER_BOOTSTRAP_TOKEN_FILE` (a file holding it; not both) | | none |
+| Log connections to stderr | `--verbose` | | | off |
+
+`private` stands for every private address a proxy can have: `10.0.0.0/8`,
+`172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `::1`, `fc00::/7`,
+`fe80::/10` (not CGNAT `100.64.0.0/10`: add it next to `private` if your
+proxy is there). It mixes with addresses and CIDRs (`private,100.64.0.0/10`).
+
+#### Caveats of `private`
+
+`private` trusts every private address, so it is only as safe as the
+network in front of the port:
+
+- **Never publish the container's port without a `127.0.0.1:` binding**
+  while `private` is set (`-p 127.0.0.1:4280:4280`, not `-p 4280:4280`;
+  on Coolify, no *Ports Mappings* at all). Published on every interface,
+  any machine on your LAN, VPN or cloud VPC has a private address.
+- **Rootless Docker, Docker Desktop and other setups that publish ports
+  through a userland proxy or source NAT** make every client, the internet
+  included, arrive from a private address (the proxy's or the bridge
+  gateway's). With them, `private` trusts everyone: set the proxy's exact
+  address instead, or keep the port off any network others reach.
+- **What a peer wrongly trusted can do**: send its own
+  `X-Forwarded-Proto: https` and `X-Forwarded-For`, so the per-address
+  upgrade and connection limits can be dodged (a fresh forged address per
+  attempt) and the audit log records whatever address it claims. It still
+  needs a valid token to connect. It is not a token leak either: the
+  clients refuse `ws://` to anything but loopback, so a token never
+  travels in the clear to a non-loopback host because of this setting.
+
+### Provider keys
+
+The server's agents read provider keys from its environment exactly as the
+local daemon does (a key stored in the data dir's `credentials.json`, set
+from a window or the server's own TUI, wins over the variable):
+`ANTHROPIC_API_KEY`, `OPENAI_CODEX_API_KEY` (OpenAI; `OPENAI_API_KEY`
+alone does not mark it configured), `OPENROUTER_API_KEY`,
+`CEREBRAS_API_KEY`, `XAI_API_KEY`, `ARCEE_API_KEY`, `BASETEN_API_KEY`,
+`MISTRAL_API_KEY`, `ZAI_API_KEY`, and for a local OpenAI-compatible
+endpoint `LOCAL_LLM_BASE_URL` (+ `LOCAL_LLM_API_KEY`,
+`LOCAL_LLM_DEFAULT_MODEL`, `LOCAL_LLM_CONTEXT_WINDOW`). The variables stay
+in the agents' environment (their tools see them, as on a laptop).
+
+`--data-dir /data` keeps everything under `/data/.zidane` (as
+`ZIDANE_STORAGE_DIR` does). The image sets `ZIDANE_SERVER_DATA_DIR=/data`.
+
+Commands:
+
+```
+zidane-server start [flags]                Serve the host (zidane server start).
+zidane-server token create --name <name>   Create a device token, printed once on stdout.
+zidane-server token list                   List tokens (never their secrets).
+zidane-server token revoke <id|name>       Revoke a token; its live connections drop.
+zidane-server token generate               Print a fresh token, stored nowhere (for ZIDANE_SERVER_BOOTSTRAP_TOKEN).
+zidane-server health [--timeout <ms>]      daemon.info over the unix socket; exit 0 when healthy.
+zidane-server health --http                GET /healthz on the configured port (loopback for 0.0.0.0); exit 0 on 200.
+zidane-server --version
+```
+
+## TLS or a reverse proxy
+
+Tokens and transcripts must not cross a network in the clear, so a
+non-loopback `--host` needs one of:
+
+1. **TLS in the server**: `--tls-cert` / `--tls-key`. Clients use
+   `wss://host:4280`. In Docker, mount the files and set
+   `ZIDANE_SERVER_TLS_CERT` / `_TLS_KEY`, `ZIDANE_SERVER_BEHIND_PROXY=0` and
+   an empty `ZIDANE_SERVER_TRUSTED_PROXIES` (see the commented block in
+   `server/docker-compose.selfhost.yml`). TLS and `--behind-proxy` together are a
+   boot error: the image turns behind-proxy on, so override it (also when
+   you pass `--tls-cert` / `--tls-key` in your own command).
+2. **A TLS-terminating reverse proxy** and `--behind-proxy`. The proxy
+   must upgrade WebSockets, set `X-Forwarded-Proto: https`, and not time
+   out idle streams (runs can be quiet for minutes; the 20 s heartbeat keeps
+   the connection busy, but give it room). Every upgrade must carry
+   `X-Forwarded-Proto` and every entry in it must be `https`; anything else
+   is a 403, from loopback too (a same-host proxy that forgot the header
+   would otherwise pass plain-HTTP clients through). Local tools use the
+   unix socket. Publish the server's port on loopback only
+   (`127.0.0.1:4280:4280`), so the proxy is the only way in.
+
+   Set `--trusted-proxies` (`trustedProxies`) to the proxy's addresses or
+   networks: upgrades from any other peer are refused (403), and only those
+   peers' forwarded headers are believed. Without it, every peer's
+   `X-Forwarded-*` headers are believed: anyone who reaches the port
+   directly can claim `https` and any client address (audit log,
+   per-address limits). The server says so at start (on stderr, after the
+   listening line, and as `warnings` in the audit log's `server.start`
+   entry), and so does `zidane server start`.
+
+   - **Caddy or nginx on the same host**, server run as a binary:
+     `--trusted-proxies 127.0.0.1,::1`.
+   - **The image behind a proxy on the host**: the proxy reaches the
+     published `127.0.0.1:4280` through the container network's gateway;
+     trust that network's subnet (`docker network inspect <network>`).
+   - **Compose** (`server/docker-compose.selfhost.yml`): its `zidane` network has a
+     fixed subnet, `172.30.80.0/24` (`ZIDANE_NETWORK_SUBNET` to change it),
+     and the server trusts exactly that network
+     (`ZIDANE_SERVER_TRUSTED_PROXIES` defaults to it): the bundled `caddy`
+     service, and a proxy on the host through the gateway. Any process on
+     the host that can reach `127.0.0.1:4280` comes in through that gateway
+     too, so it is trusted as a proxy: keep the published port on loopback.
+   - The image's own default (`docker run`, Coolify) is `private`: any
+     peer with a private address is believed, which holds when the port is
+     reachable only from the proxy's private network (published on
+     loopback, or not published at all as on Coolify; read
+     [the caveats](#caveats-of-private)). Tighten it with
+     `-e ZIDANE_SERVER_TRUSTED_PROXIES=<subnet>`; an empty value trusts
+     every peer (and warns).
+
+   The client address (audit log, per-address limits) is read from
+   `X-Forwarded-For`, from the right: the entry your proxy added, skipping
+   trusted proxies of a chain. Entries further left are whatever the client
+   sent. Have the proxy set the header to the peer it saw rather than
+   append to the client's (nginx below: `$remote_addr`, not
+   `$proxy_add_x_forwarded_for`); Caddy and Cloudflare already do the
+   right thing.
+
+Caddy (handles upgrades, headers and timeouts on its own):
+
+```
+zidane.example.com {
+  reverse_proxy 127.0.0.1:4280
+}
+```
+
+nginx:
+
+```nginx
+location / {
+  proxy_pass http://127.0.0.1:4280;
+  proxy_http_version 1.1;
+  proxy_set_header Upgrade $http_upgrade;
+  proxy_set_header Connection "upgrade";
+  proxy_set_header Host $host;
+  proxy_set_header X-Forwarded-Proto $scheme;
+  proxy_set_header X-Forwarded-For $remote_addr;
+  proxy_read_timeout 1h;
+  proxy_send_timeout 1h;
+  proxy_buffering off;
+}
+```
+
+Cloudflare Tunnel (`cloudflared`, WebSockets are on by default; it sets
+`X-Forwarded-Proto: https`):
+
+```yaml
+ingress:
+  - hostname: zidane.example.com
+    service: http://127.0.0.1:4280
+  - service: http_status:404
+```
+
+Cloudflare's proxy closes WebSockets idle for 100 s; the heartbeat
+(every 20 s) keeps them alive, so leave `heartbeatMs` on.
+
+## Tokens
+
+- `token create --name <device>` prints a `zds_…` token once, on stdout
+  (the message goes to stderr). Store it; it cannot be shown again.
+- The server keeps only a SHA-256 of each token, in
+  `<data dir>/server-tokens.json` (mode 0600). `token list` shows id, name,
+  scope, created, last used and revoked, never secrets.
+- Scope: `client` (open windows, the default) or `machine`
+  (`--scope machine`): a computer lending this server its folders and shell
+  (`zidane machine share`, see [MACHINES.md](./MACHINES.md)). A machine
+  token can only register a machine, never act as a window; revoking it
+  drops the machine (its sessions wait, then stop). Sharing a machine gives
+  this server a shell on it as the sharing user, inside the folders it
+  declared for file operations only.
+- **`tokens.createMachineToken { name }`**: a connected client mints a
+  `machine` token here, so a window's "share this computer" is one step
+  (the TUI's and the desktop app's Hosts pages). Any client token may: in
+  the single-user model a client token is already an admin's (it can run
+  commands here through terminals and `sessions.workspaceExec`). The name
+  gets `-2`, `-3`, … when a live token holds it; audited as `token.create`
+  with `via: "tokens.createMachineToken"` and `createdBy` (the asking
+  token), refusals included. A client token may hold 16 live machine tokens
+  it minted (`createdBy` in `token list --json`); revoke some to mint more.
+  A machine id is bound to the token it first registered with: another
+  machine token can't take it over until that one is revoked or the
+  machine forgotten ([MACHINES.md § Security model](./MACHINES.md#security-model)).
+  The token is returned once, to
+  that client, and stored by its local host in its credentials
+  (`machine:<server id>`).
+- `token revoke <id|name>` works while the server runs (the server watches
+  the file and re-reads it every 2 s); every connection the token opened is
+  dropped within seconds, and one whose upgrade was accepted just before is
+  refused when it opens.
+- Last use is kept apart, in `server-tokens.usage.json`: the server never
+  rewrites the token file, so it can't undo a revocation the CLI just wrote.
+- A token file that exists but can't be read or parsed is not "no tokens":
+  the running server keeps the last tokens it read, says so on stderr,
+  and picks the file up again once it is fixed; `token create` / `revoke`
+  refuse to write over it. A readable file without a token means that token
+  is revoked.
+- Rotation: create a new token for the device, switch the device to it,
+  revoke the old one. One token per device makes revoking a lost laptop
+  painless.
+- `token generate` prints a fresh token and stores nothing.
+- **Bootstrap token** (`ZIDANE_SERVER_BOOTSTRAP_TOKEN`, for a platform
+  with no shell before the first deploy): at start the value must be a
+  well-formed token (`zds_` + 43 base64url characters; anything else is a
+  boot error that does not echo it). If no token with that value exists,
+  its hash is stored as the live `client` token named `bootstrap` (audited
+  as `token.create`); if a different `bootstrap` token is live, it is
+  revoked first (`token.revoke`; its connections drop), so changing the
+  variable rotates it. A value that was revoked is never brought back: the
+  server warns and ignores it. The server never prints it, and removes the
+  variable from its own environment at start, so processes it spawns from
+  then on (agents' tools, terminals) do not inherit it. **That does not make
+  it secret**: the value stays in the container's configuration, so
+  `docker inspect`, shells opened with `docker exec` or Coolify's
+  *Terminal* (they get the container's environment), the platform's UI, and
+  `/proc/1/environ` (readable by the server's own user, so by its agents'
+  commands too) all still show it. **Revoke it once device tokens exist**
+  (`token revoke bootstrap`); deleting the variable alone keeps the stored
+  token.
+
+  `ZIDANE_SERVER_BOOTSTRAP_TOKEN_FILE` is the alternative that keeps the
+  value out of the environment: the path of a file holding the token
+  (surrounding whitespace ignored), read at start with the same validation
+  and the same rotation rules. Mount it as a secret (Coolify: *Persistent
+  Storage* → *File Mount*, or Docker / Compose secrets under
+  `/run/secrets/`). Setting both variables is a boot error; an unreadable
+  file is one too. On Coolify, either works: the plain variable (simplest)
+  or a mounted secret file.
+
+## Connecting
+
+```bash
+zidane --host wss://zidane.example.com --token-file ~/.config/zidane/box.token   # the TUI, every session on the server
+pass show zidane/box | zidane attach --host wss://… --token -                     # the thin client, token on stdin
+ZIDANE_HOST_URL=wss://… ZIDANE_HOST_TOKEN=zds_… zidane                           # from the environment
+```
+
+Prefer `--token-file <path>` (or `-` for stdin) or `ZIDANE_HOST_TOKEN`:
+`--token zds_…` still works but puts the token in the process list and
+your shell history, and the CLI says so on stderr. `--token -` reads stdin
+up to end of file: from a terminal, paste the token and press Ctrl-D; piping
+it suits `zidane attach` and scripts, not the TUI (which needs the terminal
+on stdin; use `--token-file <(pass show …)` there).
+
+`wss://` is required, except `ws://` to loopback (an SSH tunnel). The CLI
+keeps the URL and token in memory and removes `ZIDANE_HOST_URL` and
+`ZIDANE_HOST_TOKEN` from its environment, so tools it spawns inherit
+neither. The footer shows `host: <name>`. `zidane run` (the TUI with a
+prompt) resolves the host the same way; headless runs (`zidane run --json`,
+`-p … --json-schema`) always run on this machine: they refuse `--host`, and
+ignore (and scrub) `ZIDANE_HOST_URL` with a warning.
+
+### From the TUI's Hosts page
+
+Turn on Settings → Remote hosts, then Settings → Hosts → `+ add a server`:
+the URL (`wss://…`, or `ws://` to loopback), then the token (masked). The
+window keeps a connection to every saved server next to This computer:
+the sessions list groups sessions by host, opening one runs it on its
+host, and a new session asks which host (and, on a server, which of its
+folders) first. While a server session is open, Settings edits that
+server's settings. Details: [TUI.md § Several hosts](./TUI.md#several-hosts-remote-hosts).
+
+Saved hosts: `<user dir>/hosts.json` on the client (0600; names, URLs,
+the server's id and version), with each token in the client's
+`credentials.json` under `hosts:<id>`, never in `hosts.json`. Adding a host
+connects first and saves nothing unless the server answers with the token.
+`--host` / `ZIDANE_HOST_URL` stay ad hoc and are never saved; with Remote
+hosts on, such a server is the window's default host next to This
+computer and the saved ones.
+
+### From the desktop app's Hosts page
+
+Same opt-in (Settings › General › Experimental › Remote hosts), same saved
+hosts (the GUI and the TUI share `hosts.json` and the tokens), then
+Settings › Hosts › Add a server: URL, token (masked), Test, Add. The app
+keeps a connection to every saved server next to This computer: the
+sidebar groups sessions by host, a new chat picks its host (and a server
+folder) first, a server session's chat header says which server it runs
+on, and while one is open Settings edits that server's settings. A session
+is known by its host and its id together, so a server that shares this
+computer's data dir lists the same session ids as two sessions, each
+opened and edited on its own host. Details:
+[IPC.md § GUI several hosts](./IPC.md#gui-several-hosts).
+
+A refused token fails the connect with `token refused (401)` or `forbidden
+(403): …`, not an opaque WebSocket error: the client asks the server why
+over plain HTTP. The messages are fixed texts, never the response body (a
+proxy may echo the request, the token included); a 403 says why only when
+the server labels it (`X-Zidane-Refusal`: `origin`, `insecure-transport`,
+`untrusted-proxy`, `scope`), else it is a generic "refused by the server
+or a proxy in front of it". That request never follows a redirect: a 3xx
+fails the connect ("the server redirects"), and the token goes to the URL's
+own origin only. Connecting gives up after 15 s.
+
+Host URLs carry no credentials: a URL with `user:pass@`, a query string or
+a fragment is refused ("put the token in the token field"), and messages
+name a host by scheme, host and path only. A `hosts.json` entry saved
+before this check is read without them (it then fails auth: add it again).
+
+A saved server is known by the id it answered with when it was added. If
+another server answers at its URL later (reinstalled, or the name now
+points elsewhere), the window closes that connection at once, shows the
+host as `different server` ("A different server answers at <url>") and
+does not retry; nothing that server says is recorded under the saved
+host. Remove the host and add it again if the server was reinstalled.
+
+## Security model
+
+- **Transport**: TLS (in the server or the proxy). Plain WebSocket only on
+  loopback.
+- **Auth**: a live `client` token on every upgrade (`Authorization: Bearer`,
+  or a subprotocol entry for clients that can't set headers). Missing,
+  unknown and revoked tokens get the same 401, before any JSON-RPC. The
+  subprotocol fallback puts the token in `Sec-WebSocket-Protocol`, which
+  proxies may log: prefer clients that send `Authorization` (the CLI does,
+  under Bun), or have the proxy keep that header out of its logs.
+  Tokens are hashed at rest and compared in constant time; logs and the
+  audit log name tokens by id and name only.
+- **Origins**: browsers send `Origin`, CLI clients don't. An upgrade with
+  an origin not in `allowedOrigins` (empty by default) is a 403, so a web
+  page can't reach the server with a stolen token.
+- **Limits**: frames over `maxMessageBytes` close the connection (1009);
+  a reply over it is answered with a `ResponseTooLarge` error instead (the
+  connection stays); a client that stops reading is dropped once more than
+  8 MiB of pushed signals wait for it (it reconnects and resumes);
+  a token bucket per connection rate-limits requests (JSON-RPC error
+  -32012, the connection survives; a large over-budget message is refused
+  without being parsed). Upgrades are rate-limited per client address
+  (429), and open connections capped per token and per client address
+  (429).
+- **Audit log**: `<data dir>/server-audit.jsonl` (0600, rotated past 5 MB):
+  connects and disconnects (token id and name, address, client version,
+  reason), token create and revoke, server start and stop, settings sync
+  (`sync.claim` / `push` / `reset` / `release`: device, category, counts,
+  never a value; [Settings sync](#settings-sync)), and every
+  install, update or removal from a client (`catalog.install` /
+  `catalog.remove` / `catalog.update` / `mcp.upsert` / `mcp.remove`: kind,
+  spec or name, `ok`, the error or `refused`, token id and name; never an
+  MCP server's secrets). Refused upgrades
+  (address, reason, the forwarded client behind a proxy) go to
+  `server-audit.failures.jsonl`, so a flood can't rotate the entries above
+  away: the first refusal per address and minute in full, the rest of the
+  minute as one `auth.failure.summary` (count by reason). Writes are
+  buffered and asynchronous, flushed at shutdown.
+- **What crosses the wire**: requests and signals of the chat host
+  protocol: prompts, transcripts and streamed output, tool calls and their
+  results, settings, approvals. The server's agents use the server's
+  provider credentials (its environment, e.g. `ANTHROPIC_API_KEY`, or the
+  credentials in its data dir); the window's own credentials and
+  keybindings stay on the window's machine. A client can set and remove
+  the server's provider API keys (`auth.*`): keys go in, never come back
+  out through `auth.*`, and are not logged. OAuth sign-ins run on the
+  server with the browser on the client ([Sign-in from a
+  client](#sign-in-from-a-client)): tokens never cross the wire. MCP
+  servers' secrets are redacted from `catalog.mcps` (a best effort over
+  free-form arguments: [IPC.md](./IPC.md)).
+- **A token is shell access to the server.** Whoever holds a client token
+  can run commands there as the server's user (the agent's shell tool, `!`
+  commands, terminals), so they can read anything that user can read,
+  provider keys and the token hashes included. The workspace file methods
+  (`sessions.workspaceReadFile` / `WriteFile` / `ListFiles` / `FileSize`,
+  the files panel) and `sessions.workspaceExec`'s working directory are
+  confined to the workspace roots (real paths, symlinks followed) and never
+  reach the data dir (`credentials.json`, tokens, audit log), even when a
+  root contains it; a worktree the server made for the session is allowed.
+  That keeps credentials out of casual reach, not out of a determined
+  client's: commands the agent or the user runs are not confined. Treat a
+  token like an SSH key, and run the server as a user whose files you are
+  ready to expose.
+- **`allowAsMachine` does not widen that.** With it on, any client token
+  can also ask this server to be a machine of the client's computer
+  (`machine.attach`, then `machine.call` for each command or file
+  operation), served by the same confined executor a shared machine runs:
+  paths and `cwd` real-path inside the workspace roots, never the data
+  dir nor zidane's other folders or the credential folders the sandbox
+  hides (even when an operator root contains them), its commands under
+  this server's own `sandbox*` settings. Each executor is keyed by the
+  asking token and its host id (another token never reaches one), at most
+  4 per token. That is
+  what terminals and `sessions.workspaceExec` already let the same token
+  do. Off by default all the same: a server you only use as a host has no
+  reason to answer it. Every `machine.*` method is refused while it is off
+  (`allowAsMachine is off`), and clients see it in `ipc.hello`
+  (`machineServe: true`).
+- **Unix socket**: `<data dir>/server.sock`, mode 0600, unauthenticated,
+  like the local daemon's. In the image it lives on `/data` and only the
+  `zidane` user (and `docker exec`) can reach it; `zidane-server health`
+  uses it. `--socket off` removes it (the image's healthcheck, over HTTP,
+  keeps working).
+- **`GET /healthz`** (and `HEAD`) on the server's port answers `200 ok`
+  to anyone, before every check above: no token, no proxy headers, no rate
+  limit, no audit line, no host details (no name, no version); `503` while
+  shutting down, `405` for other methods. It says the listener is up.
+- **Where tools run**: on the server, as the server's user, in the
+  session's working directory, which must be inside a workspace root. The
+  host checks the roots at every entry point that takes a folder:
+  `sessions.create`, folder changes, orchestration workers (the
+  `orchestration.createWorker` request and the model's `sessions` tool,
+  verb `create`), `environments.list`, `commands.list` / `completeArgs`,
+  `catalog.*`, `models.list`; a launch-override folder outside them is
+  dropped (with `ZIDANE_DEBUG` set, a line names the session and the
+  path), folder listings stay inside them, symlinks resolved and paths
+  compared in their canonical spelling (case-insensitive filesystems). A session
+  without a folder (the orchestration main) works in the first root. That
+  guards against mistakes, not a hostile client (see above).
+
+## Settings sync
+
+A window can copy this computer's settings to a saved server, one way:
+nothing comes back. Per saved server: TUI Settings → Hosts → the server →
+`ctrl+s`; desktop app Settings › Hosts → the server's card → Sync. Only with
+Remote hosts on: off, none of it loads and no file is watched.
+
+- **Modes**: *Off* (the default), *Import once* (push the selected
+  categories now), *Keep in sync* (push them as they change: watchers on the
+  files below, plus the window's own settings changes).
+- **Categories**, ticked per server:
+
+  | Category | What goes | How it lands on the server |
+  |---|---|---|
+  | Agent settings | Host-scoped settings (safe mode, run limits, compaction, interaction mode, subagent models…), never the window's own (`isWindowOnlySetting`), nor what describes this computer: the sandbox (every `sandbox*` key: syncing would let a client turn the server's sandbox off), `useDaemon`, `remoteHosts`, `environments`, nor the enabled lists (`isSyncableSetting`; the server skips them too) | `settings.set` |
+  | Safe-mode allowlists | Each project's safelist (`projects.json`) | For the projects the server has: the same path inside a workspace root, else the one folder of that name directly in a root; others are skipped. The server's own entries stay; entries this computer dropped go |
+  | `SYSTEM.md` and user skills | The user-scope `SYSTEM.md`, the user-scope skills (`~/.agents/skills`, `~/.zidane/skills`), as files | Written in the server user's `~/.zidane/` (skills replaced whole, staged then swapped). A skill dropped here is removed there |
+  | MCP servers | The user-scope `mcps.json` servers, their `env` and `headers` included | `mcp.upsert` / `mcp.remove` (behind `allowRemoteInstalls`). A stdio server whose command is not on the server's PATH comes back with a warning: it may not run there |
+  | Extensions | Those installed from npm or GitHub (their `.install.json`); local ones are listed as not syncable | `catalog.install` (behind `allowRemoteInstalls`, audited). Installed once; never updated or removed by sync |
+  | Provider API keys | Off by default. Each key is opted in on its own, after a warning: it copies a secret to another machine | `auth.setApiKey`, only for providers the device opted in (the server checks) |
+
+  MCP OAuth tokens never sync (they are bound to the device): sign in on
+  the server from the window ([Sign-in from a client](#sign-in-from-a-client)).
+- **One source per server.** The server keeps a record (`sync.json`, 0600):
+  the device that syncs to it (id and name) and the token it claimed with,
+  its categories and opted-in keys, the fields it set, the overrides.
+  Another device sees "synced from <device>" and pushes nothing until it
+  takes over (asks first); a takeover drops the previous device's marks,
+  not the values. The source is the device id AND that token: a device id
+  is the client's word, so the same id over another token is another
+  source and must take over too. This is coordination between one user's
+  devices, not a boundary between users (any client token can take over;
+  it can already run commands here).
+- **Synced fields are marked.** The server's settings, in any window, say
+  "synced from <device>" next to a synced setting.
+- **Overrides.** A synced field edited on the server (a window's
+  `settings.set`, `mcp.*`, `catalog.remove`, `auth.*`; or on disk: its value
+  no longer matches what sync wrote) is an override: pushes skip it. The
+  setting says so ("edited here, not synced"); reset it there (TUI `ctrl+r`
+  on the row, desktop app *Sync again*) or on the Sync page, and the next
+  push (sent at once by the source) writes it again.
+- **No sync back** in this version.
+- **Offline.** Changes wait on this computer (`hosts-sync.json`: the
+  categories still to push, at most one entry each, the newest value
+  winning since there is one source) and go when the server reconnects, also
+  after a restart.
+- **Off, or removing the server**, keeps what the server has; the server
+  stops naming this device as its source.
+
+On this computer: `<user dir>/device.json` (0600: a random device id made
+once, the host name) and `<user dir>/hosts-sync.json` (0600: per saved
+server, mode, categories, opted-in providers, what waits, a hash of what
+was last pushed, the last outcome; never a key).
+
+On the server: pushes are bounded (a skill: 200 files, 1 MiB a file, 4 MiB
+in all; 16 MiB of files a push; `SYSTEM.md` 256 KiB; settings 256 KiB),
+skill names are plain names and file paths plain relative paths (no `..`,
+no absolute path, written inside the skill's folder only; a skill folder
+that is a link is left alone). Every `sync.claim`, `sync.push`, `sync.reset`
+and `sync.release` is in the audit log with its token (category, device,
+counts; never a value or a key). A token can already run commands on the
+server, so sync adds no privilege; extension and MCP installs still follow
+`allowRemoteInstalls`.
+
+## Sign-in from a client
+
+OAuth accounts (providers such as Claude Pro/Max, ChatGPT, xAI, Cursor, and
+MCP servers that use OAuth) are created on the server from a window: the
+browser opens on the client, the tokens land in the server's
+`credentials.json` / `mcp-credentials.json`. TUI: Settings › Authentication,
+`o` on a provider; MCP servers tab, `o` on an HTTP server. Desktop app:
+Settings › Authentication › Sign in, and Sign in on an MCP server row.
+
+- **Loopback flows** (Anthropic, OpenAI Codex, xAI, MCP servers): the server
+  starts the login (`auth.oauth.begin`) and keeps the PKCE verifier and the
+  `state`; the authorization URL sends the browser back to a loopback
+  address on the CLIENT, which listens there and forwards the code
+  (`auth.oauth.complete`); the server checks the `state` and exchanges the
+  code. A provider's redirect is fixed (Anthropic `localhost:53692`, Codex
+  `localhost:1455`, xAI `127.0.0.1:56121`): when that port is busy on the
+  client, the window says so and takes the address the browser lands on,
+  pasted. An MCP server's redirect is any free loopback port the client
+  picks (registered by the server through dynamic client registration).
+  The server binds no callback port of its own.
+- **Paste-back** (Anthropic's code page, any flow whose browser can't reach
+  the loopback): the code (or the whole address) is pasted in the window
+  and sent the same way.
+- **Device-code and polling flows** (Cursor, third-party providers): the
+  window shows the code and URL; the server polls.
+- **A provider's questions** (a choice between flows, a free-text prompt)
+  are the window's to answer, never picked by the server: `begin` /
+  `complete` answer with a `step`, the window shows it and answers with
+  `auth.oauth.respond`. A window that can't show one (today's TUI and
+  desktop app for a choice; a prompt goes to their paste box) ends the
+  sign-in saying so.
+- **Providers that would listen on the server**: a sign-in whose provider
+  doesn't honor `callbackServer: false` (pi-ai's stock flows, a third
+  party's loopback flow) would bind a port on the server that the client's
+  browser can't reach: it is refused ("sign in on the server machine or
+  use an API key"). zidane's Anthropic, Codex and xAI flows honor it;
+  paste, device and polling flows never listen.
+- **Security**: a flow has a random id, belongs to the connection that
+  began it (another connection's `complete` / `cancel` is refused), takes
+  one code, ends on a `state` mismatch, and expires after 10 minutes; a
+  dropped connection abandons its flows. Codes and tokens are never logged
+  and never sent to the client: `complete` answers with the provider's
+  status (or the MCP server's name). The server never opens a browser.
+
+## Installs from a client
+
+> **On by default, deliberately.** A client token can already run any
+> command on the server (terminals, `sessions.workspaceExec`), so installs
+> add no privilege; they make the server's catalog manageable from a
+> window. Turn it off when windows should not change the server user's
+> skills, extensions and MCP servers: `--no-remote-installs`,
+> `ZIDANE_SERVER_ALLOW_REMOTE_INSTALLS=0`, or `"allowRemoteInstalls": false`
+> in `server.json`.
+
+With `allowRemoteInstalls` on (the default), a window installs skills and
+extensions (from GitHub or npm), updates extensions, removes them, and adds
+or removes MCP servers on the server, with the same forms as for This
+computer (TUI: `i` / ctrl+u / ctrl+x / `a` on the server's tabs; desktop
+app: the server's Skills / Extensions / MCP servers panels). Every window
+attached to the server re-reads the catalog (`catalog:changed`), and the
+server rebuilds its agents.
+
+- **User scope only**: what is installed goes to the server user's
+  `~/.agents/*` / `~/.zidane/*` (`HOME`, `/data` in the image). A project's
+  skills, extensions and MCP servers are files in its folder (inside the
+  workspace roots), which the agent and the files panel already edit;
+  only user-scope entries are removable from a client.
+- **Specs**: GitHub (`owner/repo[#ref][:dir]`, GitHub and skills.sh URLs) and
+  npm only; anything path-like (`./x`, `/x`, `~`, `..`, `file:`) is refused.
+  An install runs `git` / the package registry ON THE SERVER, bounded to 5
+  minutes: past it the install is stopped (its `git` / package-manager
+  child killed, no further step started) and rolled back (staging folder
+  removed, a replaced version restored) before the refusal is answered;
+  its progress lines come back with the result.
+- **MCP servers' secrets** (`env`, `headers`) typed in a window are stored
+  in the server's `mcps.json` and never come back (`catalog.mcps` redacts
+  them; the reply names the server only).
+- **Gate and audit**: a client token can already run commands on the
+  server, so installs add no privilege; they are still a separate switch
+  (`--no-remote-installs`, `ZIDANE_SERVER_ALLOW_REMOTE_INSTALLS=0`,
+  `"allowRemoteInstalls": false`) and every attempt, refused or failed ones
+  included, is in the audit log with its token. With it off, every install
+  method is refused and windows hide the actions (`ipc.hello` no longer says
+  `remoteInstalls`). Plugins are discovered from their scan paths, as on
+  This computer: they are turned on and off over the wire, not installed.
+
+## Operations
+
+- **Data layout** (the image's volume):
+
+  ```
+  /data/.zidane/
+    sessions.db (+ -wal, -shm)   sessions
+    settings, credentials        as the host writes them
+    host-id                      the host's stable id
+    server.json                  optional configuration
+    server-tokens.json           token hashes (0600)
+    server-tokens.usage.json     last use per token (0600)
+    server-audit.jsonl (+ .1)    audit log (0600)
+    server-audit.failures.jsonl (+ .1)  refused upgrades, aggregated (0600)
+    sync.json                    settings sync record: source device, synced fields, overrides (0600)
+    server.sock                  unix socket, while running
+    workspaces/                  default workspace root (the image uses /data/workspaces)
+  ```
+
+  `HOME` is `/data` in the image, so git config and other dotfiles the
+  agents' tools write persist on the volume too.
+- **Backups**: stop the server (`docker compose stop zidane-server`; it
+  drains running turns for up to 8 s), copy the volume, start it again:
+  `docker run --rm -v zidane_zidane-data:/data -v "$PWD":/backup debian:trixie-slim tar czf /backup/zidane-data.tgz -C /data .`
+  Copying `sessions.db` while the server runs can catch the WAL mid-write.
+- **Upgrades**: bump the image tag (or keep a moving one: `7.2`), then
+  `docker compose pull && docker compose up -d` (plain Docker: `docker
+  pull`, then remove and `docker run` the container again with the same
+  volume); a release binary: replace it and restart. The volume carries
+  over. SIGTERM shuts down gracefully (connections
+  closed, the host drained for up to `ZIDANE_SERVER_DRAIN_TIMEOUT_MS`,
+  8 s by default, then exit); windows reconnect and reload their open
+  session. Keep the drain under the container's stop timeout (Docker:
+  10 s by default; the Compose files give 30 s), or Docker sends SIGKILL
+  mid-drain.
+- **Version skew**: client and server must speak the same IPC protocol
+  version; a mismatch is refused at the handshake with both versions and
+  which side to upgrade. Within a protocol version, older and newer clients
+  both attach; a newer one degrades on methods the server lacks, and a
+  server too old to serve the window's sessions is refused with a message
+  naming it. No client ever drains or restarts a server.
+- **Health**: `zidane-server health` exits 0 and prints
+  `ok server "<name>" v<version> protocol <n> pid <pid> up <s>s`;
+  `zidane-server health --http` exits 0 and prints `ok <url>` (the image's
+  `HEALTHCHECK`). `curl -fsS https://zidane.example.com/healthz` from
+  outside. `docker inspect -f '{{.State.Health.Status}}' <container>`.
+- **Smoke tests**: `bun run server:smoke` (the binary) and
+  `bun run server:smoke:image` (the image, twice: with its defaults —
+  healthcheck, socket health, token via `docker exec`, a direct upgrade
+  refused, a connection through a proxy — and Coolify-like —
+  `ZIDANE_SERVER_PORT=8080`, a bootstrap token from `token generate`,
+  `/healthz`, a tokenless upgrade refused with 401, the bootstrap token
+  through a proxy; SIGTERM exits 0 in both; then a container without a
+  volume, which must warn that its data dir is not persistent;
+  `ZIDANE_SMOKE_IMAGE=<ref>` or `--image <ref>` smokes an image already
+  built instead of building one). CI runs both (`server` job), plus
+  `bun run server:release:package` (the four release archives and their
+  `SHA256SUMS`) and the image's `linux/amd64` + `linux/arm64` buildx build.
+
+## Limitations
+
+What a server session does not do (yet), in the TUI and the desktop app:
+
+- **Installs are user scope only** ([Installs from a
+  client](#installs-from-a-client)): a project's skills, extensions and MCP
+  servers are edited as files in its folder; plugins are not installed
+  from a client. Editing an existing MCP server's fields from a window
+  (beyond replacing it) is not offered.
+- **This window's extension UI only.** Extension popups (completion
+  providers), panels and palette items are this computer's extensions; a
+  server session gets none from the server's. Its `/` commands and inline
+  ghost text do run on the server.
+- **No dev browser.** The browser panel drives a page on this computer, so
+  it is offered for This computer's sessions only; a server's agents get no
+  browser tools from a window.
+- **`!` shell commands** run on the server, in the session's folder,
+  streamed live like a local `!` (`sessions.workspaceExecStream`): esc kills
+  the process group there; at most 4 running per connection and 1 MiB of
+  output each (then the command is stopped, as locally); a dropped
+  connection kills them. Against an older server they are buffered
+  (10 minutes; esc stops waiting, not the command).
+- **Session folders are on the server**, inside its workspace roots. A
+  client never sends its own working directory to a server: a new session
+  starts in the server's first root, or in the folder picked in the
+  new-session flow (`fs.listDirs`).
+- **No durable execution.** A server restart interrupts running turns
+  (a commented Restate sidecar placeholder sits in
+  `server/docker-compose.selfhost.yml`).
+- **Machines** ([MACHINES.md](./MACHINES.md)): computers lend this server
+  their folders and shell (`zidane machine share`, or "share this computer"
+  in a window's Hosts page), and with `allowAsMachine` this server lends
+  itself to its clients' computers over their own connection. What is not
+  done yet: [MACHINES.md § Not in v1](./MACHINES.md#not-in-v1).
+- **Claude Code import is local**: it imports this machine's Claude data
+  into this machine's store, so imported sessions don't show on a server.