Docs/Gateway/More than one machine
Gateway

Running agents on more than one machine

3 min read

A fleet is one Gateway plus every Director that reports to it - and Directors can live on different computers. The recommended default is the hosted Gateway, run for you; a self-hosted Gateway plays the same role. Every machine's Director dials out to that one Gateway, the Fleet Map shows it all as one place, and your phone reaches everything through it.

Adding another machine

  1. Install DevThrottle on it

    The second machine runs the same app - install as usual.

  2. Enroll it with your Gateway

    The setup wizard's gateway step does the joining. On the hosted gateway, keep the Hosted gateway card and sign in with the same account - the machine is enrolled the moment the wizard shows Connected. If you run your own gateway, pick Self-hosted gateway: it scans for gateways it can reach, and takes a typed address when the scan cannot see yours. Either way, the new machine's Director dials out to the Gateway and keeps that connection open. Directors never accept an inbound connection and never talk to each other - on a normal install nothing on your machine listens. The one exception is a self-hosted Gateway: the machine you install it on listens on a port (7878) and must be reachable at its address. The hosted Gateway involves no listener of yours at all.

  3. Watch it appear

    The new machine's Director registers with the Gateway and shows up on the Cockpit's Directors page and the Fleet Map, with its sessions in the shared roster. Health is shown per Director, not per machine: a healthy Director wears no badge, one answering late shows Wobbly, an unreachable one shows Offline, and one shut down on purpose reads Not running. An offline Director dims in place and never disappears - its last-known sessions stay listed, dated - and the fleet calls a whole machine unreachable only when every Director on it is.

Starting work on the other machine

From anywhere in the fleet, a session can be started on a specific machine:

  • From the phone: the New session screen lists every machine - pick one, pick a repo.
  • From a terminal or an agent: cc-devthrottle session spawn <repo> --machine <name>. If no Director is running there, the Gateway asks that machine's launcher to start one - and if the machine is unreachable you get a clear error, never a silent local fallback.
Tip
Nothing needs starting by hand before you can aim work at a machine. Each machine's launcher starts when you log in - a per-user entry, never a machine-wide service - so a logged-in machine can take a session even when its Director is not yet running.
Note
Advanced: a small helper (cc-launcher) can register with the Gateway so it can start, stop, or restart that machine's Director remotely over the Gateway's API - with the main build and protected slots guarded behind an explicit human confirmation. There is no button for this yet; it is an API-level capability for people scripting their fleet.