How do I add 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 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 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 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.

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 and Personal devices for what that means. The steps below are for a device meant to serve the whole workspace from the start.

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.
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.
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 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 <deviceId> --workspace <workspace>
```
See Managing your devices 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 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, 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.

Once your device is Online, Managing your devices covers concurrency, health checks, draining, retiring devices, and giving it a friendlier name than its hostname.

Launch a device on AWS — no spare machine? launch one in your own AWS account instead
Quickstart — the full path from a fresh account to a merged pull request
Managing your devices — day-to-day device health, concurrency, and troubleshooting
Running the device server as a service — keep the device Online across logout and reboot
Credentials and profiles — obtain and store CH_TOKEN, sign in, and manage named profiles

Last updated 3 October 2026