Server configuration

The site build generates the tables from the server's source: the help screen, the configuration loader and the Docker image. Each setting comes from the first source that has it:

1. a flag of zidane-server start,
2. a ZIDANE_SERVER_* environment variable,
3. a key in <data dir>/server.json,
4. the default.

The server validates everything at start and names the source of a bad value. It never reads the generic PORT variable.

zidane server: Invalid ZIDANE_SERVER_PORT: expected a port (an integer from 0 to 65535).

Commands#

zidane server <command> and zidane-server <command> are the same program.

Start flags#

Token and health flags#

Environment variables#

An Image value is what server/Dockerfile sets. The other variables keep their default in the image.

zidane-server start --no-channels, or ZIDANE_NO_CHANNELS=1, never starts channels. The channels check, status and reload commands are in channels.

Booleans are 1, true, yes, on or 0, false, no, off. Lists are comma-separated (workspace roots are separated like PATH). An empty variable counts as unset.

server.json#

<data dir>/server.json uses JSON types (numbers, booleans, arrays), not strings. An unknown key is a boot error. Relative paths resolve against the data dir.

{
  "host": "0.0.0.0",
  "behindProxy": true,
  "trustedProxies": ["10.0.1.0/24"],
  "name": "build-box",
  "workspaceRoots": ["/srv/code", "workspaces"],
  "allowedOrigins": ["https://agents.example.com"],
  "rateLimit": { "perSecond": 100, "burst": 400 }
}

Exposure, webhooks and the env file#

exposure says whether the internet can reach the port of the clients. It is private (the default) or public. With public, the server refuses remote installs, lending itself as a machine (running another host's commands) and a bootstrap token. It also refuses other browser origins next to the web app, and pairing or join codes that live longer than 10 minutes (exposure).

channelsPort (--channels-port, ZIDANE_SERVER_CHANNELS_PORT) opens a second port. That port serves channel webhooks and /healthz only, and answers 404 to the rest. Make that port public. Keep the port of the clients private.

--env-file <file> on zidane-server start reads an env file, a file of KEY=value lines, before the configuration loads. A variable that is already set wins. The file must be mode 600. zidane machine share --env-file reads the ZIDANE_MACHINE_* variables of a machine the same way (servers and machines).

Data dir#

--data-dir <dir> (or ZIDANE_SERVER_DATA_DIR) sets the storage root, like ZIDANE_STORAGE_DIR for the rest of zidane (folders). Everything, sessions included, lands in <dir>/.zidane. Without it, the server uses zidane's usual folders for its user. The image sets /data (file list).

Provider keys#

The server's agents read provider keys from its environment, under the same names as on a laptop (the list). A key saved from a window into the server's credentials.json wins over the variable. The variables stay in the agents' environment, so their tools can read them.