Skip to content

Add a server

A server is a Linux machine that runs agents for you. Once it is a host of your control plane, a project can live on it: its agents run there, on its files, and keep working when your Mac is asleep or closed. Every paired window, iPhone and iPad sees it within seconds, with nothing to do on each.

A server joins by connecting out to the control plane over HTTPS, so nothing has to reach it and no port needs opening. See Projects, hosts and worktrees.

Before you start

  • A window paired with your control plane. See Set up Agents on this Mac.
  • A Linux machine on x86-64 or ARM64. This guide calls it devbox.example.com.
  • The server can reach the control plane's address over HTTPS. If the control plane runs on your Mac, that means the server is on the same network as the Mac and can resolve its .local name.
  • curl on the server, and its CA certificates if the control plane has a publicly trusted certificate.
  • For installing over ssh instead of running a command yourself: a server you can ssh to from Terminal on this Mac, by a name in ~/.ssh/config or as user@host[:port]. The control plane makes the ssh connection with your config, agent and keys, so it must be able to reach the server. A control plane on another machine needs a private key.
  • Runtimes on the server, installed and signed in there as the user your agents run as. See Runtimes.

Steps

Run a command on the server

  1. In the window, open Settings ▸ Control plane, and click Show beside Hosts.
  2. Click Add a Server…. With Run a command chosen, the sheet shows one command, which works once.
  3. Click Copy.
  4. On the server, as the user your agents should run as, paste the command into a shell and run it.

It downloads the host into ~/.agents-server, checks it, starts it, and says devbox joined the control plane. Where the server has a systemd user session, the host runs as the user service agents-host; to keep it running after you log out, run the loginctl enable-linger line it prints.

The sheet says devbox joined. and lists the git repositories it found on the server, unticked (see Choose its projects). The server is listed under Hosts, and has a heading of its own in the projects list.

Or add it over ssh

  1. In Settings ▸ Control plane ▸ Hosts, click Add a Server…, then choose Over ssh.
  2. In Server, type the server. The box offers the hosts in your ~/.ssh/config, each with the user@host ssh resolves it to; choose one, or type any user@host, user@host:port or ssh://user@host:port. Under the box, the sheet says what ssh makes of it, such as ssh reaches it as agents@devbox.example.com:2222.
  3. Give it a Name, or leave the one guessed from the server.
  4. Leave Key empty to log in as ssh does from Terminal, or click Choose… to use one key for this install only.
  5. Click Install.

If the server's key is already in your known_hosts, the install goes straight on. If it isn't, the sheet says This server's key isn't in your known_hosts. Its key is: and a fingerprint. Check it matches the server: on the server, ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub prints it. Click Trust and Install. The key is trusted for this install and the server's tunnel; your known_hosts is not changed. If the key has changed since your known_hosts saw it, nothing is installed: remove the old key with ssh-keygen -R if the server was rebuilt, and try again.

The sheet ticks through Checking the system… and Installing Agents…, then says devbox joined.

The key is read once, for this install. The control plane keeps neither the key nor the ssh connection, and afterwards the server connects out by itself like any other.

A server that can't reach this Mac: use an ssh tunnel

A server your ~/.ssh/config reaches through a ProxyJump or ProxyCommand, such as a cloud workspace behind a bastion, usually cannot dial back to this Mac. For such a server, Use an ssh tunnel is on by default. Turn it on for any other server that can't reach this Mac, or off for one behind a bastion that can. Once you set it, the sheet leaves it as you set it. Only a control plane on this Mac can hold a tunnel.

With a tunnel, the control plane keeps an ssh session open to the server, logging in as ssh does for you from Terminal. That session forwards port 8791 on the server's loopback back to the control plane, and nothing else: any LocalForward, RemoteForward or DynamicForward in your config is not opened on it. The server's host dials https://127.0.0.1:8791, and the certificate is still checked by its pin. The key, if you chose one, is still read only for the install.

If the server won't open that port (something else has it, or its sshd has AllowTcpForwarding no), or the session drops, the server goes offline. Under Hosts its line says ssh tunnel down and ssh's reason. The control plane starts the session again by itself, waiting longer each time it fails, and at once when this Mac wakes or its network changes. When you remove the server, the tunnel closes.

What the control plane passes to ssh, and how each common ~/.ssh/config option fares, is in the ssh contract.

Choose its projects

Nothing on the server becomes a project by itself (#656). Once it joins, Add a Server lists each git repository directly inside the paths under Auto-detect (~, ~/src and the like, ~ being the server's home), each unticked, and the same list opens later from Choose Projects… on the server's row under Hosts, or on This Mac's.

  1. Tick the repositories to add. One that is already a project is shown ticked and greyed.
  2. To add a folder that is not listed, type its path on the server, such as ~/work/app, and click Add Folder. It joins the list, ticked.
  3. Click Add N Projects, or Skip to add none.

With Suggest projects on a host off, nothing is listed and only the folder box is there.

Put a project on it

  1. Choose File ▸ Add Project On or File ▸ Clone Project On, then the server's name.
  2. For a folder, choose one on the server, then click Add as project. A clone goes into your home folder on the server.

The project appears under the server's heading. Start agents in it the usual way; the runtime menu offers the runtimes on the server.

Let the server use this Mac's Claude sign-in

If Claude on the server has no sign-in of its own, the window asks Let devbox use this Mac's Claude sign-in? the first time an agent there needs it. Click Allow, and the server's agents use Claude as you, through this Mac, whenever this Mac is awake. The sign-in itself stays on this Mac. Click Don't Allow to sign Claude in on the server instead.

Add another Mac

A second Mac joins the same way, with Agents Host.

  1. In Settings ▸ Control plane ▸ Hosts, click Add by Code…, then Copy.
  2. On the other Mac, install and open Agents Host. Under Join one elsewhere, paste the code and click Join.

Agents Host says This Mac runs its agents for a control plane elsewhere. It runs no control plane of its own. Its projects appear under its own heading in every window.

Remove a server

  1. In Settings ▸ Control plane ▸ Hosts, find the server, open its ··· menu and choose Remove…, then Remove.

It stops connecting, and every window and device stops seeing it. Its agents are left running where they are, and ~/.agents-server on the server is not touched.

Or add it from a workspace provider

If the server is a workspace of a provider you have added (a Docker container, a DigitalOcean droplet, a Codespace), open Settings ▸ Control plane ▸ Providers and choose Add as Host… beside it. Add a Server opens over ssh, with the address the provider gives already filled in. Once the server joins, it is linked to its workspace, so it can be started and stopped from Agents. See Start workspaces from Agents.

When the server is offline

If the server loses its network, or the host stops, Hosts marks it offline and its projects go grey. Agents already working there keep working. The host reconnects by itself when it can, and you see everything that happened meanwhile. Check again, in its ··· menu, asks at once.

A server linked to a provider's workspace shows Stopped instead when its workspace is stopped, with Start on its row and over its chats on every screen.

Updating a server

A server's host does not update itself yet. To update it, add it again: click Add a Server… and run the new command on the server. It stops the host running there and starts the new one on the same folder, so do it when no agent there is in the middle of a turn.

If it doesn't work

  • That is not a host code. The command was changed on its way. Copy it again.
  • Hosts other than Macs run Linux. The machine is not Linux.
  • … is not a machine the host is built for. Agents hosts need x86-64 or ARM64.
  • This machine has no CA certificates to check the control plane with. Install ca-certificates on the server.
  • The download did not match its checksum. Something between the server and the control plane changed the download. Run the command again.
  • The host started but has not joined yet. Read the log it names. Most often the server cannot reach the control plane's address, or the code had run out; add it again for a new command.