Remote agents and machines
This page shows you how to pair a machine with your organization so By Dawn’s agents can run tickets on it, and how to look after it once it’s paired. By the end you’ll have a machine that takes work, and you’ll know what each part of its row in By Dawn tells you.
A remote agent is a machine running the By Dawn agent, a small program that takes tickets from By Dawn and runs a coding agent on them. It can be a Mac mini under a desk or a cloud VM, so tickets keep running while you work on something else. Paired machines belong to the organization, so every member sees the same list in Settings, then Organization, then Remote Agents. Each machine signs in to Claude itself, and By Dawn never holds that sign-in (see Claude accounts, sign-in and seats).
Before you start
Section titled “Before you start”- You need to be an org admin to pair a machine. A pair code lets a machine join the organization and run its work, so only admins can create one. Anyone else who tries sees You don’t have permission to add machines here.
- A macOS or Linux machine you can reach in a terminal. The agent needs outbound internet only, with no open ports or static IP. There’s no Windows agent.
- Room on your plan. Your plan sets how many machines the organization can pair. If it has none left, the pairing guide tells you why (see FAQ).
Pair a machine
Section titled “Pair a machine”Pairing takes about two minutes. The guide in By Dawn gives you every command to copy, filled in for your organization.
-
Open Settings, then Organization, then Remote Agents and choose Add remote agent. On an empty list the button is Pair a machine.
-
Install the agent. Run one of the two install commands on the machine: Homebrew on macOS, or the one-line installer for Linux or anything with
curl. If it’s already installed, skip ahead. Choose Next: start setup. -
Start setup on that machine. Run the command under Run on the remote machine. Setup pairs the machine, installs the agent so it starts when the machine boots, sets up its permissions, then asks two questions. When it asks, choose It is asking me for these.
-
Answer its two questions. Copy the Workspace id and the Pair code from the guide as setup asks for each one. The pair code works once and expires after 10 minutes; the guide counts down. Setup asks for the code rather than taking it on the command line, so it never lands in the machine’s shell history. Choose I answered — wait for it to connect.
-
Check it’s your machine. The guide shows Listening for a connection…, which usually takes a few seconds. When it says the machine connected, compare the fingerprint under Confirm the key fingerprint with the one the agent printed on the machine when it started. If the two match exactly, this is your machine. Choose Next: sign in to Claude.
-
Sign it in to Claude. A new machine runs no work until it’s signed in to Claude. Choose Sign in to Claude and follow Sign a machine in to Claude, or choose Skip for now and do it later from the machine’s row.
The machine now shows under Online and starts taking work. Unless you change it, any ticket in the organization can run there (see Whose work a machine runs).
What a machine’s row tells you
Section titled “What a machine’s row tells you”The strip at the top of the page answers “is my fleet healthy?” without reading rows. It says Fleet healthy, No machines online, or Claude access disabled on a number of machines, then counts the machines online, offline and revoked. If any online machine needs a Claude sign-in, a need sign-in chip appears too, and choosing it shows only those machines.
Machines are grouped by whether By Dawn can reach them, each group in name order:
- Online machines get a full row, described below.
- Offline machines get one line. A laptop that’s asleep is normal, so this isn’t shown as a fault. A machine with no contact for over two weeks is marked stale: it’s still paired, but you may want to check on it.
- Revoked machines sit in a collapsed group at the end, kept only so you can tidy them away.
An online machine’s row shows:
| Part | What it tells you |
|---|---|
| Whole team or Only a name | Whose tickets the machine runs. A lock marks a personal machine. |
| The Claude badge | Whether the machine is signed in to Claude. When it needs a sign-in, the badge is the button that starts one. |
| Wrong org, Limit reached, Signed out | A Claude problem that stops new jobs going to the machine, or to one of its seats. See When a machine needs attention. |
| running or idle | How many tickets and sessions it’s working on. Choose the count to see which tickets, and the browser tabs each one has open. |
| up to a number of parallel jobs | How many tickets it takes at once. |
| Runtimes, Browser, Computer control, Screen recording | What it can run. A dashed chip is something it lacks or hasn’t reported. On a Mac, hover an amber chip for the System Settings permission to grant. |
| Low disk space, Disk almost full | A full disk makes the machine stop taking new jobs. Its row says since when, and What you can do lists the fixes. |
| CPU and Mem | Load, as 5-minute averages. Host strained means Auto is sending new work to less loaded machines. |
| Platform, agent version and fingerprint | What the machine is, and the key it paired with. |
Under the row, the Claude usage panel shows the account’s usage windows.
Whose work a machine runs
Section titled “Whose work a machine runs”Each machine either takes anyone’s work or only its owner’s:
- Whole team (shared) is where every machine starts. Any ticket in the organization may run there, and Auto counts it as fleet capacity.
- Only its owner (personal): it runs only tickets its owner starts or is assigned. Nobody else can send work to it or pin a ticket to it.
A machine’s owner is the admin who created its pair code. To change a machine, open its row’s Actions menu (⋮) and choose Share with whole team or Keep to its owner only. Only the owner or an org admin sees that option. Changing it never stops work that’s already running.
For the machine running the By Dawn desktop app, the same choice is under Settings, then You, then This computer as Who can run work on this machine.
Which machine a ticket runs on is set in the ticket’s run config. It can be Auto, which picks the least busy machine that can run the ticket, the project’s default, or a machine you name (see Models and runtimes).
Change a machine’s settings
Section titled “Change a machine’s settings”Everything you can change is in the row’s Actions menu (⋮). Settings that By Dawn stores, such as the name and the number of jobs, can be changed while the machine is offline. Claude sign-in runs on the machine, so it needs the machine online.
- Rename changes the display name only. The machine stays paired.
- Set parallel jobs… sets how many tickets the machine works on at once, from 1 to 64. Higher numbers need more cores and memory. Your plan also caps the total across the organization, and By Dawn says so if you go over it.
- Build slots… sets how many builds and test suites this machine runs at once, or turns slots off on it (see Builds and tests).
- Sign in to Claude…, Switch account…, Sign out of Claude and Add seat… manage the machine’s Claude sign-in (see Claude accounts, sign-in and seats).
- Re-pair…, Revoke and Remove from list are covered below.
Builds and tests
Section titled “Builds and tests”When several tickets compile or run test suites on one machine at once, they fight over its CPU and memory and every run slows down. Heavy slots fix that: each machine runs a few builds and tests at a time and queues the rest. You turn them on in the Builds & tests card at the top of the Remote Agents page. You can also search settings for “heavy slots”. The setting is Off until an org admin changes it.
| Setting | What happens |
|---|---|
| Off | Builds and tests run the way they always have. Nothing is measured. |
| Observe | Machines measure how often builds and tests overlap, without holding any back. |
| On | Each machine runs a few builds and tests at once. The rest wait their turn instead of slowing every run down. |
Turn heavy slots on
Section titled “Turn heavy slots on”- In Builds & tests, choose Observe and Save. Nothing is held back yet. Each machine starts measuring how often its builds and tests overlap and how hard they load it.
- Leave it for a few working days. The card then says whether slots would help, and names the machine with the strongest case. Expand machines measured for each machine’s figures. If slots would help, the card shows a Turn on button.
- Choose Turn on, or On and Save. Each machine picks the change up within a few seconds.
If Observe says slots wouldn’t help, leave it on Off or Observe. Fewer parallel jobs on a busy machine is the cheaper fix.
What each machine shows
Section titled “What each machine shows”| Setting | The machine’s row |
|---|---|
| Off | Nothing, unless someone already set this machine’s slots or turned them off on it. The row then says so. |
| Observe | Build slots · Observing, with the machine’s slot count and what it measured: time spent on builds and tests, how often they overlapped, and peak CPU and memory. It adds slots would help when they would. |
| On | A Build slots meter showing how many are in use and how many builds are waiting. A builds queued badge sits beside the machine’s name while any wait. |
The number of slots is sized from each machine’s cores and memory. To change it for one machine, choose Build slots… in its menu and set Builds & tests at once, or turn slots off for that machine alone. The menu item is there in every setting. While the org is Off, what you save waits until heavy slots are turned on. Only an org admin can change these.
Re-pair, revoke and remove
Section titled “Re-pair, revoke and remove”Re-pair… is for a machine that lost its pairing, for example after its disk was restored. It opens the same guide for that machine, and its setup command re-pairs in place, keeping the machine’s identity key. By Dawn retires the old entry when it creates the new code, and the machine comes back as a new entry, so check the fingerprint as before.
Revoke stops a machine taking jobs for good, for example when it’s lost or retired. A revoked machine can’t come back on its own: to use it again, pair it as a new machine.
Remove from list takes a machine off the page. A machine that’s still active is revoked first, so it stops taking work. Its job history is kept.
What happens to work when no machine is online?
It waits. The fleet strip says No machines online and that work queues until one returns. Nothing is lost.
Why can't I create a pair code?
The guide names the reason. Your workspace has no remote-agent capacity means the organization has paired as many machines as its plan allows, so a workspace owner needs to upgrade or revoke a machine. Your workspace’s plan is suspended means a payment needs resolving in billing settings; upgrading won’t help. Your workspace doesn’t have remote agents yet means the plan doesn’t include them.
The guide keeps listening, but the machine says it's online. What happened?
The machine was paired here before and reused that registration, so it’s already in your list. Your pair code wasn’t spent, and you can use the guide again for another machine.
Why does a machine get no work even though it's online?
Check its row. It may not be signed in to Claude, be signed in to the wrong Claude organization, be out of disk, or report no coding runtime (Runtimes unknown). It may also be personal to someone else.
Where to go next
Section titled “Where to go next”- Claude accounts, sign-in and seats: sign machines in and set the organization’s Claude rules.
- Models and runtimes: choose where and how a ticket runs.