# How do I add a device?

Source: https://codeherder.com/docs/adding-a-device/

Two ways to connect a machine to CodeHerder — install the ch CLI on a machine you have, or launch a device on AWS.

A **device** is any machine running `ch device-server` — that’s what executes your agents’ work. There are two ways to add one: install the CLI and run `ch device-server` on a machine you already have (this page), or [launch one in your own AWS account](https://codeherder.com/docs/launch-a-device-on-aws/) with a single click if you don’t have spare hardware to leave running. Either way there is **no separate register command** — running `ch device-server` yourself, from a terminal, both registers the device and starts it.

If you just want to try CodeHerder end to end, the [Quickstart](https://codeherder.com/docs/quickstart/) walks through connecting your first device as part of a larger flow. This page is the focused answer to “how do I add a device?” for a machine you already have.

## Before you start

You need a way to authenticate, and a workspace to connect to:

- **A credential.** `ch device-server` accepts a browser sign-in (`ch login`), an API key (`CH_TOKEN`), or a named credential profile (`CH_PROFILE`, or `--profile`). Use whichever fits: `ch login` is fastest for a machine you’ll sit at while setting it up; an API key or profile suits a headless box or a service account. See [Credentials and profiles](https://codeherder.com/docs/credentials/) for how to sign in or mint a key.
- **A workspace.** Run `ch workspace list` to see which ones you can connect to, and note the one you want.
- **`CH_ADDR`** — the API base URL of your CodeHerder server, `{{api_base}}`.

`ch device-server` doesn’t read a repository’s committed project defaults file, even when you run it from inside one — see [The ch device-server exception](https://codeherder.com/docs/project-config/#the-ch-device-server-exception).

## Add the device

If you just want to run a session on the machine you’re sitting at right now, `ch start` is quicker: it installs no service and does the registration below for you, the first time it’s needed. Run `ch start --check` first if you want to see whether it will succeed before it does anything. That registration comes with a catch, though — it’s a **personal** device, not offered other people’s tasks until you promote it. See [Start a session in your own checkout](https://codeherder.com/docs/local-sessions/) and [Personal devices](https://codeherder.com/docs/devices/#personal-devices) for what that means. The steps below are for a device meant to serve the whole workspace from the start.

1. **Install `ch`** on the machine that will run the device: `curl -fsSL {{app_base}}/cli/install.sh | sh` This needs `curl` and `openssl`. It detects your platform, verifies the signed release and its checksum, and installs `ch` to `~/.local/bin/ch`. No sign-in is needed to run it. To download a build by hand instead — or if you’re on Windows, which has no native build yet and runs `ch` under WSL — see the **Install CLI** page in your workspace sidebar.
2. **Sign in and set your workspace** (and `CH_ADDR` if you self-host): `ch login export CH_WORKSPACE_ID =< your-workspace-id > export CH_ADDR = {{api_base}}` `ch login` opens your browser and caches the credential, so you don’t need `CH_TOKEN` on this machine. `CH_WORKSPACE_ID` accepts a name, slug, or ID from `ch workspace list`. Running a headless machine or a service instead? Use an API key or profile in place of `ch login` — see [Credentials and profiles](https://codeherder.com/docs/credentials/).
3. **Run the device server:** `ch device-server` The first time it finds no saved device token, it asks: `Register this device now? [Y/n]:` Press Enter (or type `y`) to accept the default and register: this creates the device, mints a device token bound to your identity, stores it locally, and connects. See [Device tokens](https://codeherder.com/docs/device-tokens/) for what that token is and how to rotate it if it’s ever compromised. Type `n` to decline — nothing is registered, and the command exits so you can run it again once you’re ready. With `CH_WORKSPACE_ID` (or `--workspace`) set, registering also links the new device to that workspace in the same step — the happy path above. Leave `CH_WORKSPACE_ID` unset, or hit a problem linking it, and the device still registers — just **unlinked**. This can also happen with `CH_WORKSPACE_ID` set, if the workspace name doesn’t resolve: registration prints `link workspace ...` or `resolve workspace ...` and exits, but the device itself is already created. Re-running `ch device-server` won’t retry the link on its own — it just reconnects with the saved token. Link it by hand instead: `ch device workspaces create < deviceI d > --workspace < workspac e >` See [Managing your devices](https://codeherder.com/docs/devices/#link-a-device-to-another-workspace) for the full command and how to find the device’s ID. This prompt only appears when `ch device-server` is attached to a real terminal. Run it non-interactively instead — under a background service or inside a container, before you’ve ever registered — and it skips the prompt entirely: it prints a note that there’s no token yet and keeps running idle, with no error and no device showing up in your workspace. Register from a terminal first, then hand the same machine to a background service — see [Running the device server as a service](https://codeherder.com/docs/running-the-device-server/) for that order. A missing credential is a different problem from a missing token: if `ch device-server` finds no sign-in, no `CH_TOKEN`, and no profile it can load, it stops immediately with an on-screen explanation of what to set, rather than running idle.

## Confirm it worked

- On a workspace with no devices yet, **Set up → Devices** shows a guided connect panel that walks through these same steps and updates itself the moment your device connects.
- Once a device exists, its row on the **Devices** page shows a status dot that flips to **Online** as soon as the server is up.
- Or, from the CLI: `ch device list`.

If the device doesn’t appear at all, confirm you actually saw and accepted the registration prompt above — a non-interactive run never registers on its own, so double-check your credential, `CH_WORKSPACE_ID`, and `CH_ADDR`, then try running `ch device-server` again from a terminal.

## Before agents can use it

Being Online isn’t the same as being ready for work. While any coding CLI installed on the device is signed out of its AI provider, the device shows a **Not staffable** badge, and the engine holds back any task that needs that CLI. Sign each one in, or uninstall the ones you don’t use. See **Device health and readiness checks** in [Managing your devices](https://codeherder.com/docs/devices/#device-health-and-readiness-checks), or run `ch workspace readiness` for a workspace-wide summary.

## Keep it running

Running `ch device-server` in a terminal is fine for a quick test, but the device goes **Offline** the moment that terminal closes. To keep a device Online across logout and reboot, run the device server as a background service — see [Running the device server as a service](https://codeherder.com/docs/running-the-device-server/).

Once your device is Online, [Managing your devices](https://codeherder.com/docs/devices/) covers concurrency, health checks, draining, retiring devices, and [giving it a friendlier name](https://codeherder.com/docs/devices/#naming-a-device) than its hostname.

## Related guides

- [Launch a device on AWS](https://codeherder.com/docs/launch-a-device-on-aws/) — no spare machine? launch one in your own AWS account instead
- [Quickstart](https://codeherder.com/docs/quickstart/) — the full path from a fresh account to a merged pull request
- [Managing your devices](https://codeherder.com/docs/devices/) — day-to-day device health, concurrency, and troubleshooting
- [Running the device server as a service](https://codeherder.com/docs/running-the-device-server/) — keep the device Online across logout and reboot
- [Credentials and profiles](https://codeherder.com/docs/credentials/) — obtain and store `CH_TOKEN`, sign in, and manage named profiles