CodeHerderSearch⌘KRequest access →

Device tokens

What a device token is, and how to rotate it or revoke an extra one from the CLI.

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 a device token is, what happens if a device gets displaced by an unexpected second connection, and the two ways to remove a token: rotating it or revoking it.

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 “What the device server needs at startup.” It’s never displayed on screen, at first run or afterward. CodeHerder keeps no copy of it, so it can’t be shown to you 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.

CodeHerder logs every token mint and every revoke. The entry goes in the activity feed of the device’s main workspace. The main workspace is the oldest workspace the device is still linked to. If you register a device by running ch device-server yourself, the first token is minted before the device has any workspace. That entry goes in the feed of the owner’s home workspace instead.

Who can do what

Action Who can do it
Rotate a token The device’s owner, and only while that owner has admin rank or higher in the device’s main workspace.
Revoke a token The device’s owner (with admin rank in the main workspace), or any admin or owner of the main workspace.
Archive the device An admin or owner of the main workspace, or the device’s owner with admin rank there. If the device has no workspace links, its owner can archive it. See Managing your devices.

All of these are human-only. Agents cannot run them, and a session you started on a device cannot run them either. Run them from your own login.

A workspace admin who does not own the device cannot rotate its token. The server refuses with “only the device’s owner can mint or rotate its token”. In that case, ask the owner to rotate. Or revoke the token yourself, which cuts the device off. Then the owner must issue a new token.

Archiving a device (see Managing your devices) revokes every token it holds and disconnects it. Restoring the device does not bring those tokens back, so a restored device needs a fresh one. Rotate one (below), same as any other lost or compromised token. A microVM pool cannot be restored. Create the pool again.

MicroVM pools

A microVM pool holds no device token of its own. Each microVM it launches gets its own launch token, good for that one launch. So rotate and revoke do not apply to a pool. CodeHerder refuses both, with the message “a microVM pool holds no device token; its VMs hold their own launch tokens”. Archiving a pool is allowed.

To cut a pool off, use one of these instead:

  • ch device disable <pool> stops new launches. MicroVMs that already run keep running.
  • ch device archive <pool> stops launching and terminates the live microVMs.

Not the same as your other credentials

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

  • An API key (CH_TOKEN) authenticates a member — human or agent — to the ch CLI or the API directly. See Credentials and profiles.
  • A device token (this page) authenticates a machine running ch device-server to CodeHerder.
  • 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 authenticates as the same device while the first is still active, CodeHerder closes the older one and lets the newer one take over. The device never runs two connections at once, and it never stays caught between two.

When that happens, CodeHerder drops a message in the device owner’s inbox. Check the Messages page, or ch msg inbox, in the device’s main workspace. That is the only place the alert goes, even if the device is linked to other workspaces too. If the device has no workspace links, CodeHerder sends no message. The message names the device’s id and both connections’ IP addresses, plus the command to rotate the token if you need it. CodeHerder sends this message on every takeover, whether or not anything looks wrong.

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. It also happens if you run a second ch device-server on a different machine using a copied token file: CodeHerder has no way to tell that apart from a real takeover. A second ch device-server that uses the same device folder on one machine refuses to start, so this mix-up needs two separate device folders, such as two machines, two home folders, or two containers.

On a microVM pool, each microVM holds its own connection. The message names the pool’s id. The rotate command it prints does not work on a pool. If the new IP is unfamiliar, disable or archive the pool instead.

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.

Rotate, or revoke an extra token

Through the CLI, a device normally holds exactly one live token: registration mints it, and rotating replaces it with a new one. That covers almost every case. If you suspect a device’s token has leaked, rotate it.

A device only ends up with more than one live token if someone minted an extra one for it directly, separately from the normal registration flow. If that’s your situation, and you know which token you want gone without disturbing the other, revoke it by id instead of rotating.

  • Rotate when you’re not sure how many tokens the device holds, or you just want the device’s credential replaced. Rotating revokes every token the device holds and leaves the device offline until it’s given the new one.
  • Revoke when the device holds more than one live token and you want to remove one of them by id, without knocking out the token still in use. Revoking removes exactly that one token and leaves the rest alone.

Revoking the device’s only live token has the same effect as rotating, minus the replacement. The device goes offline, because it no longer has a credential to connect with. Only rotate or register again gives it a new one.

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>

Only the device’s owner can run this, and only while the owner has admin rank or higher in the device’s main workspace. An admin or owner of that workspace cannot rotate a token for someone else’s device. They can revoke it instead (see below).

Rotate also fails in three cases:

  • The device is linked to no workspace. Nobody can rotate its token.
  • The device is archived. Restore it first (see Managing your devices).
  • The device is a microVM pool. See MicroVM pools above.

Run the command from your own login. It is human-only.

Rotating revokes every existing token for the device immediately, with 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 save it on the device:

umask 077 && printf '%s\n%s\n' <deviceId> '<token>' > ~/.codeherder/device.token

That command writes to the default token path. If the device runs with a custom --token-file, change the path in the printed command to match before you run it there.

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. Restarting ch device-server isn’t required; it just makes the reconnect happen immediately instead of on the next retry.

Revoking an extra token

If a device holds more than one live token and you only want to remove one of them, revoke it by id:

ch device revoke-token <device> <tokenId>

Revoking is open to more people than rotating. You can revoke if you are the device’s owner with admin rank in its main workspace, or if you are an admin or owner of that workspace. Revoke also works on an archived device. It fails on a device with no workspace links. It is human-only, same as rotating. It fails on a microVM pool too, because a revoke would close the connection of every microVM in the pool. See MicroVM pools.

Revoking always closes the device’s live connection, even when another token is still live. CodeHerder can’t close just one token’s share of a connection, only the whole thing. If another live token remains, the device reconnects on that one right away, so you won’t see it go offline the way a rotate does. If the token you revoked was the device’s only one, it stays offline instead, just like after a rotate, but with no replacement token printed.

It’s safe to run more than once. Revoking a token that’s already revoked still succeeds and does nothing further — no second disconnect, no second log entry.

There’s no command that lists a device’s tokens, and no token screen in the app. A token id shows up in two places: the tokenId field in ch device rotate-token --json’s output, and the device’s activity history, where each logged mint or revoke carries the token id:

ch activity workspace <workspace> --type device.token_minted --subject-id <deviceId> --json

Two things to get right here: --subject-id wants the device’s full id, not its hostname (ch device show <device> prints it), and the events live in the device’s main workspace feed, so point ch activity workspace at that workspace. For a first token minted before the device was linked, use the owner’s home workspace. You also need --json — the plain-text table doesn’t show tokenId, only the JSON payload does.

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 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 its last remaining live token was revoked — the device can no longer connect, so it shows Offline and stops picking up work. (Revoking one token out of several doesn’t do this: the device just reconnects on another one it still holds.)

Its health snapshot won’t show a failing check for this. The device only pushes a snapshot while it has a live connection — on connect and when something changes — so once the connection is gone, the snapshot 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 locally 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. This does not apply to a microVM pool, which holds no token. See Managing your devices for how to read the health snapshot and its checks.

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