Help CenterChangelog

Connecting a machine

Agents run on your own machines through a small program called the runner. Once it's online, that machine's projects become available for tasks.

Updated Jul 5, 2026

Agents in fbuild run on your own machines, not in the cloud. A small program called the runner connects a machine to your workspace so agents can work there.

Connect a machine #

  1. In the console, go to Soldiers and choose to add a machine — this mints a one-time enrollment token and shows you a command.
  2. Run that command on the machine you want to connect. The runner installs, enrolls with your workspace, and comes online.
  3. The machine now appears in Soldiers as online, and its repositories become selectable projects when you create a task.

How projects map to workspaces #

A team machine connects to every workspace you're a member of at once (it discovers them from your token), so one connect covers all your workspaces.

When the runner discovers a repository, it routes it to a workspace automatically:

  • If the repo name matches one of your workspaces, it lands there — e.g. better-i18n/helpway goes to the helpway workspace, egosorg/egos goes to egos.
  • Otherwise it groups by the repo's GitHub owner — e.g. other better-i18n/* repos surface under the workspace tied to that owner.

Discovered repos show up as candidates you can opt into the workspace; a repo shows online whenever a connected machine has it checked out.

Pin a repo to a specific workspace #

If auto-routing puts a repo in the wrong workspace (common when several products share one GitHub owner), map it explicitly. This always wins over auto-routing:

Code
npx @fbuildai/runner@latest add-project <owner>/<repo> --dir <local-path> --org <workspace>

For example, to make the better-i18n/helpway checkout show up in the helpway workspace:

Code
npx @fbuildai/runner@latest add-project better-i18n/helpway --dir ~/dev/helpway --org helpway

Good to know #

  • One machine, many workspaces. The same computer can join several workspaces without conflicts.
  • It stays connected. The runner reconnects on its own after a network blip or a sleep/wake.
  • Your repos stay yours. The runner only exposes projects you've granted — it does not scan your whole machine.
  • Terminals persist. A terminal you open for a project re-attaches to the same live shell when you come back.

Once a machine is online, head to Creating & running a task.