Run on your other computers

A worker is another of your own computers that runs Runs in its environment, while one Orbital server, the control plane, keeps every Run’s history and drives its Workflow. Without a worker nothing changes: every Run executes on the control plane’s own computer, with no network in between.

Each worker needs Orbital installed, the repositories and project folders its Runs work in, and its own signed-in harnesses. Provider logins stay on the worker and never cross the link.

Pair a worker

1. Start the control plane with a port for workers to link to:

   orbital serve --bind 0.0.0.0 --worker-port 4400

   Without --worker-port it listens for no worker.

2. Open Settings > Workers, give the worker a name, such as attic, and choose Pair worker. The control plane and secret are shown once.

3. On the worker, save them as a pairing file only you can read, such as ~/.orbital/attic.json:

   { "worker": "attic", "controlPlane": "homelab", "secret": "the secret shown" }

   chmod 600 ~/.orbital/attic.json

4. Start Orbital on the worker, naming the control plane’s address and worker port:

   orbital serve --works-for homelab.local:4400 --pairing ~/.orbital/attic.json

The worker appears as connected in Settings > Workers, with its environment and the harnesses it can run. Choose it as a Project’s default worker, or for one Run, and the Run executes there.

The link is encrypted with TLS 1.3. The key is derived from the worker’s own secret, so nobody without the pairing file can connect as the worker or read what it carries. The control plane keeps only a digest of the secret.

Desktops on other computers connect with their own credential, which orbital client add <name> issues and orbital client revoke <name> withdraws.

Revoke a worker

Choose Revoke beside the worker. Its link closes at once and every later connection is refused, so the worker stops. Runs already placed on it keep their history and environment, and revoking does not prove its processes stopped. Pair it again to issue a new pairing file; the old one stays refused.

To stop new Runs going to a worker while its current ones finish, choose Drain instead.

Restart a worker

Stop the worker’s orbital serve and start it again with the same pairing file. It reconnects under the same name, and the control plane carries on the operations it had already asked for: one that finished is answered from its recorded result rather than run again, and one whose outcome the worker cannot know is reported as uncertain instead of repeated.

Only one process may hold a pairing at a time. When a second one connects, the first is superseded and stops.

When the control plane restarts or the network drops

A worker finishes the operations it already accepted and then waits. It dials the control plane again every second until it is back, with no step from you. The control plane keeps its pairings in ~/.orbital/workers.json, so workers rejoin a restarted control plane with their existing pairing files, and each Run carries on in the environment it recorded.

Both ends ask the operating system to probe a link that has been quiet for 15 seconds, so a computer that vanished without closing its connection is noticed. How soon depends on the operating system’s keepalive settings: on Linux, by default, about eleven minutes after the probes start. Until then the worker shows as connected, and its Runs wait rather than fail.