Servers and machines

On the main server (the zidane-server that keeps your sessions), make a join code (a one-time code that adds a computer):

zidane server machine invite

On the computer that you want to add, run setup with the address of the main server and the code:

zidane machine setup --join wss://main.example.ts.net#K7Q2-9XPM

The computer is now a machine of the main server: a computer that runs commands for the main server's sessions. Sessions on the main server can run their commands in its folders, as local@<name>.

How the parts fit#

A machine opens the connection to the main server. It needs no open port.

Example: one server, two machines, one laptop#

The example has four computers on one Tailscale network. Each computer runs Tailscale and is logged in.

1. 1

   Install the main server

   On main, install the zidane command and run setup:

   npm install -g zidane-tui
   zidane server setup --via tailscale

   Setup installs a systemd service that runs as a zidane user, with its data in /var/lib/zidane. It serves the server on your tailnet (your Tailscale network) with tailscale serve, on port 443. If another program on main already uses port 443, setup uses port 8443 and tells you. To choose the port, add --tailscale-port <n>. At the end it prints the address, a device token and a first join code. The token shows only once. Copy it to a file on the laptop now.

2. 2

   Make a join code for each machine

   On main, run the command as the service user, with its data folder:

   sudo -u zidane /var/lib/zidane/bin/zidane-server machine invite --name gpu --data-dir /var/lib/zidane
   sudo -u zidane /var/lib/zidane/bin/zidane-server machine invite --name mini --data-dir /var/lib/zidane

   Each command prints one code. A code works once, for 10 minutes. --name sets the name of the machine. Without it, the machine gives its own name.

3. 3

   Add the GPU server

   On gpu, install the zidane command and run setup with the first code:

   npm install -g zidane-tui
   zidane machine setup --join wss://main.example.ts.net#K7Q2-9XPM

   When setup asks which user runs the machine, pick the dedicated zidane user. Then it asks for the folders to share. The default is /var/lib/zidane/projects. Setup shows each step and runs them when you say yes. It installs the zidane-machine systemd service. It adds the zidane user to the video and render groups and runs nvidia-smi -L as that user. Then it waits up to 60 seconds for the machine to connect.

4. 4

   Add the Mac mini

   On mini, run the same two commands with the second code. Run setup as yourself, without sudo. It asks for your password when a step needs it.

   On macOS, the machine runs as you, as the LaunchDaemon (a macOS service that starts at boot) dev.zidane.machine. The default folder is ~/projects. The log is ~/Library/Application Support/zidane-machine/logs/machine.log.

5. 5

   Connect the laptop

   Turn on remote hosts first (how). In the desktop app, open Settings › Accounts › Hosts › Add a server. Enter wss://main.example.ts.net and paste the token. In the terminal app, run:

   zidane --host wss://main.example.ts.net --token-file ~/main.token

6. 6

   Run a session on a machine

   Start a new chat on main. In the desktop app, the composer's Runs on menu lists gpu and mini under the server. In the terminal app, the new session asks for the host, then the environment, where each machine has its own group. Pick a machine, then a folder on it. The session stays on main. Its commands run on the machine.

7. 7

   List the machines

   On main, run:

   sudo -u zidane /var/lib/zidane/bin/zidane-server machines --data-dir /var/lib/zidane

   The table has the columns NAME, STATUS, VERSION, LAST SEEN, ROOTS and GPU. Add --json to get { serverVersion, machines }. The Hosts page of each app shows the same list (desktop, terminal).

Move a session#

To move a session between this computer, a worktree and a machine, in any direction:

1. Open the move dialog. In the desktop app or the web app, open the session menu (on the sidebar row or in the session header), then choose Move to…. In the terminal app, open the session details (ctrl+shift+x), then press m.
2. Pick where the session runs. An offline machine shows, but you cannot pick it.
3. If the target is a machine, pick a folder on it. The folder must be inside the folders that the machine shares.
4. If the session has messages, confirm the move.
5. Optional: if the session runs in a worktree, tick Remove the old worktree if it has no uncommitted changes. It is off by default. In the terminal app, press r in the confirmation.

If the session runs or Zidane still prepares it, it cannot move. Wait until it is idle. A message you send during the move waits, then runs in the new place.

When you remove the old worktree, the branch stays. Zidane keeps the worktree when it has uncommitted changes, when a forked session still uses it, or when its machine is offline. The app then tells you why. If the move gives no new folder on the same computer, the session goes to the main checkout, because its old folder is the worktree.

Find problems with doctor#

On the main server, run zidane server doctor. It shows one line for each machine:

On a machine, run zidane machine doctor. It reads the setup record and the status that the machine writes. It shows whether the service runs, whether the machine is connected and since when, and its version next to the main server's. It also shows who owns each shared folder, and whether the service user can use the GPU. It exits with 1 when something fails.

If the main server refuses the machine, make a new join code on the main server. Then run zidane machine setup --join again on the machine with the new code.

Updates#

Update only the main server (upgrades). The machines follow.

A machine installs the version of its main server by itself. When the main server runs another release, the machine downloads that release and checks it. It waits until no command, background task or terminal runs on it. Then it puts the new binary in place, keeps the old one as zidane-server.previous, and restarts. If the download fails, it tries again after one hour.

The machine keeps the new version once it stays connected for one minute. If the new version starts twice and never stays connected that long, the machine puts the old binary back and restarts with it.

A computer that shares with zidane machine share from the zidane app does not update itself.

Security#

• A machine sees the commands, paths and file contents of the sessions that use it. It never gets provider keys, settings, transcripts or other tokens. The main server can run any command on the machine as its service user. On Linux, use the dedicated zidane user.
• A join code works once, for 10 minutes. --ttl sets 30 seconds to 1 hour. A main server with exposure: public (a server that the internet can reach) allows 10 minutes at most. After five wrong tries, the code stops working. The main server keeps only a hash of it.
• Setup trades the code for a token of scope machine, which can only register a machine. Setup saves it in a file that only the service user can read, and never prints it. To drop a machine, revoke its token on the main server: zidane server token revoke gpu.

More: server security.

Limits#

• A main server that listens only on loopback cannot add machines. Give it an address that the machines can reach, such as Tailscale.
• A computer is a machine of one main server at a time. Setup for a second main server offers to change the first.
• Setup works on Linux with systemd and on macOS. Elsewhere, run zidane-server machine share under your own service manager.
• On Linux, a shared folder cannot have a space in its path.
• When you run setup again, it restarts the service. This ends the commands that the machine runs.
• The main server keeps at most 16 live machine tokens for each creator. Join codes from the command line all count in one group. When the group is full, setup stops and the join code stays unused. Revoke a machine token that you do not use, then run setup again.