Secrets
Store a secret at the workspace or group level and bind it to an agent's launch config under an environment variable name you choose, using a Credential ref.
A secret is a variable with Secret turned on: an encrypted value such as an API key or access token. After you save it, CodeHerder and everyone in your workspace see only its name, never its value.
A secret at workspace or group scope reaches sessions in one of two ways. An uppercase name such as STRIPE_KEY goes into the environment of every session in scope under its own name — see Variables. A Credential ref binds a secret to one launch config under an environment variable name you pick. This page covers Credential refs.
When to use a Credential ref
Use a Credential ref when you want to:
- Give the agent the secret under a different name than the secret’s own, for example a secret named
github-patthat the agent reads asGITHUB_TOKEN. - Keep a secret away from most sessions. A lowercase-named secret never goes into the environment by itself. It reaches only the launch configs that bind it.
- Bind a secret that a group holds and its workspaces share.
If you only need a value in every session’s environment under its own name, a plain secret variable with an uppercase name is simpler.
A device-side reference is a third option. It keeps the value on the device so CodeHerder never holds it. See Secrets on a device.
Who can manage secrets
A workspace or group secret needs a signed-in human who is a workspace owner or admin. Every other role is refused. Agents can never view or manage secrets. An agent’s session credentials can’t create, read, or change one. An agent can use a credential without ever holding or seeing it.
Anyone in the workspace can see a secret’s name in the list on Settings → Variables. Binding a secret to a launch config needs permission to edit that config — see Agents and the CLI.
Creating a secret
Run:
ch variable set <name> --secret --from-file <path|->
The value comes from a file or from standard input. There is no inline form, so the value never lands in your shell history:
ch variable set github-pat --secret --from-file token.txt # from a file
printf %s "$TOKEN" | ch variable set github-pat --secret --from-file - # stdin
A secret name can take two shapes:
- Uppercase, such as
STRIPE_KEY: uppercase letters, digits, and underscores, starting with a letter or underscore. CodeHerder also injects it into every session in scope. - Lowercase, such as
github-patorslack_webhook: lowercase letters, digits, hyphens, and underscores, up to 64 characters. It reaches a session only through a Credential ref.
A name is unique within its scope. The web app creates uppercase names only. Create a lowercase secret from the CLI.
The value is write-only. CodeHerder never shows it again in the web app or the CLI. Keep a copy where you generated it if you might need it later.
Finding a secret’s id
A Credential ref points at the secret’s id. Print it with:
ch variable show <name>
The output includes the id and the version. Commands take the exact name. ch variable list shows every variable in scope, secrets included, but not their ids. Neither command prints a value. You need CH_WORKSPACE_ID set so CodeHerder knows which workspace to look in — see Agents and the CLI.
Binding a secret to an agent
In the web app, open the agent’s detail page and edit the launch config. In the Credential refs field:
- Enter the environment variable name the agent’s process sees, for example
GITHUB_TOKEN. Use uppercase letters, digits, and underscores, starting with a letter or underscore. The name can’t start withCH_, which CodeHerder reserves. - Pick the secret. The picker lists secrets set on the agent’s workspace or on a group above it. It doesn’t list device or agent secrets.
- Save.
From the CLI:
ch agent config edit <agentId> --credential-ref GITHUB_TOKEN=<secretId>
--credential-ref replaces the config’s whole set of refs, the same way --env replaces the whole env set. To keep an existing ref, pass it again alongside the new one. Repeat the flag for more than one ref. To clear all refs, pass the flag with an empty value.
CodeHerder resolves the ref and puts the value into the process environment only when a session starts. The launch config never stores the value. CodeHerder redacts secret-shaped values from its own log lines and from the stored exit tail. The agent’s process sees a normal environment variable, so the agent can print or send the value. Redaction works by shape only and can miss a value. Bind a secret only to an agent you trust with it.
Device consent
A device must agree before a session on it receives a secret variable. This is the device acknowledgement.
- A lowercase secret that you bind with a Credential ref needs no device consent.
- An uppercase secret in scope needs device consent even when a Credential ref also binds it. The ref adds no approval step, but CodeHerder still injects the secret under its own name. A new uppercase workspace or group secret therefore stops every session in scope on a device that hasn’t agreed to it.
Consent for secret variables expires, by default 90 days after the owner last added a key with ch device secrets set. After that, sessions that need one refuse to start until the owner renews it with ch device secrets set <deviceId> --add <key>. See Secrets on a device.
Rotating a secret
Run the same command you used to create it:
ch variable set <name> --secret --from-file <path|->
The secret keeps its id and its version number goes up. Every launch config that binds it picks up the new value the next time a session starts. There is nothing else to update.
Deleting a secret
On Settings → Variables, find the row and click Delete. Or run ch variable unset <name>.
Deleting is irreversible. A launch config that still references the deleted secret fails to start a session. Update or remove the Credential ref on every agent that uses the secret first. Otherwise a task that reaches that stage errors out.
The Legacy chip
A secret whose name is lowercase carries a Legacy chip on Settings → Variables. The web app can’t edit or override these rows. You can only delete them there. Rotate one from the CLI with ch variable set <name> --secret --from-file <path|->.
Availability
Secrets need encryption support configured on your deployment. If creating or rotating one fails with an error saying the feature isn’t available, ask your workspace admin.
Related guides
- Variables — set a plain or secret value at group, workspace, device, or agent scope.
- Secrets on a device — keep a credential on the device only, and manage the device consent that secret variables need.
- Agents and the CLI — launch configs, including where Credential refs live.
- Managing your devices — device state and troubleshooting.
- Integrations — connect the workspace itself to an external service such as GitHub or GitLab.
Last updated