# Remote agents and machines

> Pair a Mac or Linux machine so it runs your tickets, choose whose work it takes, and keep it healthy from the Remote Agents settings.

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 › Organization › Remote Agents**. Each machine signs in to Claude itself, and By Dawn never holds
that sign-in (see [Claude accounts, sign-in and seats](https://docs.bydawn.com/claude-accounts/)).

## 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](#faq)).

## Pair a machine

Pairing takes about two minutes. The guide in By Dawn gives you every command to copy, filled in for your organization.

1. Open **Settings › Organization › Remote Agents** and choose **Add remote agent**. On an empty list
   the button is **Pair a machine**.

2. **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**.

3. **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**.

4. **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**.

5. **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**.

6. **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](https://docs.bydawn.com/claude-accounts/#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](#whose-work-a-machine-runs)).

## 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](https://docs.bydawn.com/claude-accounts/#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

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 › You › 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](https://docs.bydawn.com/models-and-runtimes/#machine)).

## 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](#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](https://docs.bydawn.com/claude-accounts/)).
- **Re-pair…**, **Revoke** and **Remove from list** are covered [below](#re-pair-revoke-and-remove).

## 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

1. 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.
2. 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.
3. 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

| 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

**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.

> **Caution:** Revoking can't be undone. If you only want a machine to stop taking other people's work, make it personal instead.

## FAQ

**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

- [Claude accounts, sign-in and seats](https://docs.bydawn.com/claude-accounts/): sign machines in and set the organization's Claude rules.
- [Models and runtimes](https://docs.bydawn.com/models-and-runtimes/): choose where and how a ticket runs.

Source: https://docs.bydawn.com/remote-agents/