> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Runners

> Enroll, monitor, and manage the Macs that train your objects.

A **runner** is a Mac enrolled with Foundry that pulls training jobs from the queue, builds reference objects locally, and uploads the results. The **Runners** page (**Foundry → Runners** in the [dashboard](https://app.holos.io)) is where you enroll runners, watch what they're doing, and manage their credentials.

<Note>
  Foundry runners are available to select customers only, and this page is visible to members with the **Foundry Manager** role. [Contact us](mailto:hello@holos.io) to set up runners for your organization.
</Note>

## Runner status

Each runner reports a live status derived from when it was last seen and whether it holds a job:

| Status       | Meaning                                                                                                                         |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **Training** | Actively building a reference object. Its current job and progress are shown inline.                                            |
| **Idle**     | Online and healthy, waiting for the next job.                                                                                   |
| **Stalled**  | Holds a job whose progress has stopped reporting (a crash or power loss). The job is automatically requeued for another runner. |
| **Offline**  | Hasn't checked in recently.                                                                                                     |

For each runner the page also shows its name, host machine, who enrolled it, when it was last seen, and how many jobs it has recently completed. You can give each runner a custom icon and color to tell your fleet apart at a glance.

## Enrolling a runner

The easiest way to enroll a Mac is from the Foundry app itself — no credentials to copy or paste.

1. Install the Foundry app on the Mac (the Holos team provides it as part of your setup).
2. Open it and **sign in** to your Holos organization.
3. Click **Enroll this Mac**.

Foundry mints the machine credentials, stores them securely in the Mac's Keychain, and the runner starts pulling jobs right away. It shows up on this page within moments.

### Enroll from the dashboard (alternative)

If you'd rather create the credentials yourself, you can add a runner from the dashboard and configure the Mac by hand:

1. Click **Add runner** and give it a name.
2. Foundry generates a **client ID** and **client secret**.
3. Configure the runner Mac with the client ID and secret.

<Warning>
  The client secret is shown **exactly once**, at creation. Copy it immediately and keep it somewhere safe. Foundry never displays it again. If you lose it, rotate the secret to get a new one.
</Warning>

Either way, the runner Mac uses its credentials to mint short-lived access tokens on its own. Nothing about enrollment opens an inbound connection to the Mac: the runner only makes outbound requests to Foundry.

## Setting up the runner Mac

The runner software is a small macOS app the Holos team provides as part of your Foundry setup. Once it's enrolled, it runs in the background, polls for queued jobs, and processes one job at a time. It updates itself automatically, so the Mac stays current without manual maintenance.

<Note>
  Training reference objects is disk-intensive: a runner Mac needs a good amount of free space (tens of gigabytes) to claim a job. The runner won't start a job unless enough space is available.
</Note>

## Managing runners

From each runner's menu you can:

* **Rotate secret**: issue a fresh client secret and invalidate the old one. Use this on a schedule or if a secret may have been exposed. The new secret is shown once.
* **Revoke**: permanently disable the runner's credentials so it can no longer claim jobs. Use this when you retire a Mac.
* **Rename** and **restyle**: update the display name, icon, and color.

The Foundry app on the runner Mac can do the equivalent from the machine itself: **rotate its credentials**, **remove its enrollment**, and **release the job it's currently training** back to the queue for another runner to pick up.

<Note>
  Rotating or revoking takes effect on the runner's next request. A runner mid-training will finish or lose its current job depending on timing; the job requeues automatically if interrupted.
</Note>