Device tokens

Every device that runs ch device-server authenticates with a device token — a credential created automatically the first time the server starts, and never asked for again. This page covers what that token is, what happens if a device gets displaced by an unexpected second connection, and how to rotate a token you suspect has leaked.

What a device token is

ch device-server mints its device token itself the first time it runs on a machine — see How do I add a device? for the full first-run walkthrough. The token is written straight to the file described in Running the device server as a service under “The device token file”; it is never displayed on screen, at first run or afterward. CodeHerder keeps no copy of it, so it can’t be shown to you again later — if the token file is lost or you need a new token, rotate it (below). Every restart after first run just reads the saved file and reconnects.

Not the same as your other credentials

A device token is one of four separate credentials, each with its own job:

• Your API key (CH_TOKEN) authenticates you to the ch CLI. See Credentials and profiles.
• A device token (this page) authenticates a machine running ch device-server to CodeHerder.
• An agent’s device key, minted by ch agent rotate-device-key, authenticates one agent running on one device — see “Rotating an agent’s device key” in Agents and the CLI.
• Workspace secrets store your own encrypted credentials (API keys, database passwords, and the like) for agents to use inside a task — see Secrets.

Rotating one of these has no effect on the others.

One live connection per device

A device holds exactly one live connection to CodeHerder at a time. If a second connection presents the same device token while the first is still active, CodeHerder closes the older one and lets the newer one take over — the device doesn’t run two connections at once, and it doesn’t stay caught between two.

When that happens, CodeHerder drops a message in the device owner’s inbox (check the Messages page or ch msg inbox) naming the older connection’s IP address and the newer one’s, plus the command to rotate the token if needed.

This isn’t always a sign of trouble. The same thing happens after an ordinary reconnect — following an unclean shutdown, a lost network, or restarting the device server twice in quick succession — because the old connection is still technically live until CodeHerder notices it’s gone. Before assuming a token has leaked, compare the two IP addresses in the message: if both look like machines and networks you recognize, it was almost certainly just a reconnect. If the newer IP is unfamiliar, treat it as a compromise and rotate the token right away.

Rotating a device token

If you suspect a device’s token has leaked — the alert above named an IP you don’t recognize, or the token file was exposed some other way — rotate it:

ch device rotate-token <device>

You can run this if you’re the device’s owner, or an owner or admin of the workspace the device was linked to first — being an owner or admin of a workspace the device was added to later doesn’t grant this. It’s a human-only command; agents can’t run it.

Rotating revokes every existing token for the device immediately — there’s no grace period where both the old and new token work — and closes the device’s live connection right away. The command then prints a brand-new token, shown once, along with the exact command to run on the device to save it. Copy that command as-is; it already has the token filled in.

The device stays offline until it has the new token. In most cases you don’t need to do anything else: ch device-server checks its token file every time it retries a connection, so once you’ve saved the new token on the device it reconnects on its own, typically within about a minute. If you’d rather not wait, restart ch device-server on the device and it reconnects immediately.

Why not just delete the token file and re-register?

Deleting the token file and letting ch device-server self-register again creates a brand-new device — a new identity, disconnected from the old one’s workspace links, agent assignments, and history. The old device is left behind, still showing whatever state it was in. Rotating keeps the same device and everything attached to it; only the credential changes.

Signs a device token has gone bad

If a device’s token stops being accepted — because it was rotated from elsewhere, or revoked — the device can no longer connect, so it shows Offline and stops picking up work. Its health snapshot won’t show a failing check for this: the snapshot is only sent right after a successful connection, so with the connection failing it simply stops updating and keeps showing whatever it last reported while the token still worked. The device server itself keeps retrying in the background and logs the rejection on that machine. If a device is Offline and you don’t see an obvious cause, rotating its token (above) and saving the new one on the device is the fix. See Managing your devices for how to read the health snapshot and its checks.

Related guides

• How do I add a device? — connect a machine for the first time
• Managing your devices — device health, readiness checks, and troubleshooting
• Credentials and profiles — your own API key, separate from any device’s token
• Agents and the CLI — rotating an agent’s per-device key, a different credential from this one