Secrets on a device
Reference a credential that lives only on a device's own secret store, and get the device owner's acknowledgement it needs before an agent can run.
A device-side secret reference is another way to give an agent a credential, alongside the workspace and group Secrets. Instead of storing the value in CodeHerder, you leave it on the device itself and put only a reference to it in the agent’s launch config.
When to use this instead of a workspace secret
| aspect | Workspace or group secret + Credential ref | Device-side reference |
|---|---|---|
| Where the value lives | Encrypted in CodeHerder | Only on the device, in its own secret store |
| Setup | Once, works on every device the agent runs on | Once per device |
| Best for | A credential you’re fine handing to CodeHerder | A credential you don’t want CodeHerder to hold at all |
See Secrets for the Credential ref path. The rest of this page covers the device-side one.
How it works
In an agent’s launch config, an environment variable can hold a value of the form @secret:<key> instead of a literal value — for example, MY_SERVICE_TOKEN=@secret:my_service. CodeHerder stores that string as-is; it is a reference, not a credential. The device resolves it to the real value only at the moment a session starts, reading it from its own secret store. The value itself never reaches CodeHerder — not in the config, not in logs, not anywhere.
The reference can live in any of the agent’s launch configs (see Running more than one launch config in Agents and the CLI) — at spawn time CodeHerder checks whichever config is actually running against the device’s acknowledged-secrets list, not just the top one.
Step 1 — put the value on the device
Run this on the device itself, not from your own machine:
macOS:
security add-generic-password -U -s codeherder-device -a my_service -w
Leaving off a trailing value after -w makes security prompt for it (twice, to confirm) instead of taking it as an argument, so it never lands in your shell history. -U lets you re-run the command later to update the value.
Linux:
printf %s "$TOKEN" | secret-tool store --label codeherder service codeherder-device key my_service
Headless devices or CI: set an environment variable on the device server’s own process — CH_SECRET_<KEY> with the key upper-cased, for example CH_SECRET_MY_SERVICE. CodeHerder checks this before the operating system’s secret store. This is the simplest path on a machine with no interactive keychain, at the cost of the value sitting in the device server’s own environment instead of a dedicated secret store. Use a key made of letters, digits, and underscores so its upper-cased form is a valid environment variable name.
The operating system’s secret store works on macOS and Linux only. On any other platform, use the CH_SECRET_<KEY> variable. Without it, a session that needs the reference fails to start.
Step 2 — reference it in the launch config
Web app: open the agent’s detail page, find the Launch configs panel, and edit the config’s Env field — one KEY=value per line, using @secret:<key> as the value:
MY_SERVICE_TOKEN=@secret:my_service
CLI:
ch agent config edit <agentId> --env MY_SERVICE_TOKEN=@secret:my_service
This command edits the agent’s top launch config. To put a reference in another config, use the web app.
--env is repeatable if the config needs more than one reference. It replaces the config’s whole env set on any call where you pass it. List every env var you want the config to keep, not just the new reference. Every other launch-config field stays as it is unless you pass its own flag (see What each edit actually changes in Agents and the CLI).
CodeHerder refuses to save a config that references a key starting with ch_session_, ch_devsession_ or ch_token_. CodeHerder reserves those names. Acknowledging such a key does not help.
Step 3 — get the reference acknowledged
Every key any of the device’s agents’ launch configs reference with @secret: must be explicitly acknowledged before a session referencing it can start. This is a deliberate checkpoint: it stops a config edit from quietly reaching into a device’s secret store for a credential nobody agreed to hand over. The acknowledgement lives on the device, not on any one agent — set it once and every agent that runs there shares it.
The same list gates one more thing: a secret variable with an uppercase key is injected into a session on this device only once its key is on this same acknowledged list — even though it isn’t an @secret: reference at all, and even when a Credential ref also binds it. Add its key alongside your @secret: keys the same way.
Consent for secret variables expires. By default it lasts 90 days. The clock restarts when you add a key to the list, or when you use --add, even for a key already on the list. A call that only removes keys keeps the current expiry. After the expiry, a session that needs a secret variable refuses to start until the owner renews consent. @secret: references don’t expire.
Only the device’s owner or a workspace owner can give this acknowledgement. A workspace admin is not enough. On a personal device, only its owner can. A person must run the command: an agent or a session credential is refused.
To acknowledge a key, or to renew consent, add it:
ch device secrets set <deviceId> --add my_service
--add and --remove change the list without replacing it, so two people can acknowledge at the same time. Both are repeatable:
ch device secrets set <deviceId> --add my_service --remove old_key
To replace the whole list, use --secret once per key. This is a whole-set replace, not a diff. The list becomes exactly the keys you pass, so include every key you still want. Omit every flag to clear the list. You cannot combine --secret with --add or --remove.
ch device secrets set <deviceId> --secret my_service --secret other_key
See the current list with:
ch device secrets list <deviceId>
list also prints the consent expiry date when there is one. You edit the list from the CLI only. The web app does not have an editor for it.
Only the device’s owner and workspace admins see this list. Everyone else gets a notice instead — see Who sees host details.
Adding a reference later: if you edit a config to add a new @secret: reference, the next session refuses to start until you add its key with ch device secrets set <deviceId> --add <key>.
Expiry warnings: when the list holds a secret variable key, the device page in the web app shows a notice as expiry nears and after it passes. The notice includes the command to renew. By default, CodeHerder also emails the device owner and the admins of the workspaces linked to the device, about 14 days before expiry and again when consent lapses.
Session credentials and your keychain
CodeHerder gives each session its own short-lived credential. It passes that credential to the session in the session’s environment. It never writes it to your keychain or secret store, in any mode: not for a container session, not for a process session, not for a task or a dev session.
Earlier releases did write a copy, in the keychain under the service codeherder-device, with an account named ch_session_<id> or ch_devsession_<id>. Nothing ever read that copy, and some copies were never deleted. On macOS they could also raise keychain prompts. If you see several of these items, they are leftovers from those releases.
What the cleanup does
On macOS, the device server removes those leftovers by itself. The cleanup:
- runs in the background, a few minutes after the device server connects, and never delays a session from starting;
- lists the login keychain’s item attributes only. It never reads a value;
- deletes an item only when all of these hold: the service is exactly
codeherder-device, the account is exactlych_session_orch_devsession_followed by a lower-case id, CodeHerder reports that session ended on this device, and no session on the device still uses it; - keeps every other item. This includes your own
@secret:keys,ch_token_items, provider logins, device credentials, items of other apps and any account it cannot match exactly; - skips the pass when the keychain is locked or unavailable, and tries again later. It stops trying for the life of the process after a few attempts. It is designed not to wait for you to unlock and not to show a prompt. Each keychain command has a short time limit. If macOS does show an unlock prompt, you can cancel it: the cleanup skips that pass;
- records only counts and a reason in the device log: how many it found, deleted and kept. It never records an account name or a value.
A session that is still running, or stopped and resumable, keeps its item until CodeHerder reports it ended. Running the cleanup twice is safe.
The setting
CH_SPAWN_SECRET_KEYRING on the device server’s environment controls the cleanup:
| value | what the device does |
|---|---|
auto (default) |
Never writes a session credential. On macOS, runs the cleanup above. Does nothing on other systems. |
off |
Makes no keyring call for a CodeHerder session slot. No cleanup runs. Your own @secret: references still resolve. |
No other value changes the behaviour: anything that is not off means auto. To migrate, update the device server. You do not need to set anything. The next device server start cleans up what it can prove ended.
Linux: the device server does not clean up Secret Service items. To remove a leftover by hand, list the ones you have with secret-tool search --all service codeherder-device and clear one with secret-tool clear service codeherder-device key ch_session_<id>. The search output includes secret values, so do not paste it anywhere.
Remove one item by hand (macOS): only for an item you have confirmed is a leftover:
security delete-generic-password -s codeherder-device -a ch_session_<id>
Never delete an account that does not start with ch_session_ or ch_devsession_. Those names hold your own keys.
When it goes wrong
- Session doesn’t start, and the device needs acknowledgement: run
ch device secrets set <deviceId> --add <key>for each key the message names. This covers both an unacknowledged@secret:reference and an unacknowledged secret variable key. - Session doesn’t start, and the device’s consent for secret variables has expired:
ch device secrets list <deviceId>shows the expiry. Runch device secrets set <deviceId> --add <key>for each secret variable key. This renews the consent. Running--secretagain with keys already on the list does not renew it. - Session doesn’t start, and a key can’t be found on the device: the failure reports that a secret reference couldn’t be resolved on that device, but it does not say which key. Check which
@secret:<key>references the spawning launch config uses, confirm each one is stored on that device (Step 1), and try again.
Related guides
- Variables — set a secret variable at group, workspace, device, or agent scope; also gated by this same acknowledged-secrets list
- Secrets — the alternative where CodeHerder holds the encrypted value and a Credential ref binds it.
- Agents and the CLI — launch configs, multiple configs and ordering, and where an agent runs.
- Managing your devices — device state and troubleshooting.
Last updated