How do I add a device?

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; the device self-registers the first time it comes online.

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 CLI credential so the device server can authenticate:

• CH_TOKEN — your API key. Alternatively, select a named credential profile with CH_PROFILE (or --profile).
• CH_ADDR — only if you self-host. The default is the hosted https://api.codeherder.com.

Both CH_TOKEN and your workspace ID are shown on the Install CLI page in your workspace sidebar (under Set up). See Credentials and profiles for how to obtain and store them.

Add the device

1. Install ch on the machine that will run the device. The download and platform-specific instructions are on the Install CLI page in your workspace sidebar.

2. Set your credential and workspace (and CH_ADDR if you self-host):

   export CH_TOKEN=...
   export CH_WORKSPACE_ID=...
   export CH_ADDR=https://api.codeherder.com   # only if self-hosting

   Both CH_TOKEN and CH_WORKSPACE_ID are on the Install CLI page.

3. Run the device server:

   ch device-server

   On first run it self-registers: it 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. With CH_WORKSPACE_ID (or --workspace) set, it also links the new device to that workspace in the same step — the happy path above. Leave both unset and the device still self-registers, just unlinked — see Managing your devices for how to link it afterward. Every run after that just reads the saved token and reconnects — you never register again.

Confirm it worked

• Open the Devices page in your workspace sidebar (under Set up). The new device appears and flips to Online once the server is up.
• Or, from the CLI: ch device list.

If the device doesn’t appear, check that ch device-server is still running and that CH_TOKEN/CH_WORKSPACE_ID/CH_ADDR point at the right workspace and server.

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.

Related guides

• 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