CodeHerderSearch⌘KRequest access →

How do I add a device?

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.
  • The server address. The API base URL of your CodeHerder server is https://api.codeherder.com. If your ch build has no built-in address (typical when you self-host), set it before you sign in.

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.

  1. Install ch on the machine that will run the device:

    curl -fsSL https://app.codeherder.com/cli/install.sh | sh

    This needs curl or wget, plus 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 the side rail (under Help).

  2. Set the server address, sign in, and set your workspace:

    ch login --addr https://api.codeherder.com
    export CH_WORKSPACE_ID=<your-workspace-id>

    ch login --addr stores the server address and opens your browser to cache the credential, so you don’t need CH_TOKEN on this machine. If you use an API key or profile instead of ch login, export CH_ADDR=https://api.codeherder.com first. Without a stored or exported address, ch stops with “no server address”. 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.

  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 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 <device> --workspace <workspace>

    Name the device by its ID or its hostname. See Managing your devices for the full command.

    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 logs a line saying there’s no device token yet and keeps running idle. No device shows 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 the server address, 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 a coding CLI installed on the device is signed out of its AI provider, the device’s health badge reads Unhealthy and its Harness auth check fails. The engine holds back only the work that needs that CLI on that device. Other work still lands there, so Not staffable does not appear for this. Sign each CLI in, or run ch device-server --harness-exclude <name> for one you don’t use. The device re-checks within about five minutes. 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.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close