Managing credentials
Local and organization credential stores, setup, sync, and trust boundaries.
Devboxes rejects dispatch until a credential can serve its model provider. Credentials come from your runner or the organization's encrypted store.
Choose where the credential lives
| Store | Serves | Add credentials with |
|---|---|---|
| Local device store | This runner machine | devboxes credentials setup |
| Local auth-file reference | This runner machine | devboxes credentials setup --provider |
| Organization store | Every local and dashboard-managed runner | Model providers or credentials sync |
The device credential store holds subscriptions and API keys entered here. It is age-encrypted; Devboxes returns its machine-specific passphrase only to the registered runner.
An auth-file reference records a provider and local path. The runner reads it on demand; it does not copy the key into config.
Configure local credentials
devboxes credentials setup
devboxes credentials setup --connect openai
devboxes credentials setup --connect opencode
devboxes credentials setup --connect opencode-go
devboxes credentials setup --api-key anthropic < key.txt
devboxes credentials setup --provider openai
devboxes credentials setup --all
devboxes credentials status [--json]
devboxes credentials remove --provider openai
devboxes credentials remove --allInteractive setup shows organization and local state, then offers subscription
connections, API-key entry, discovered auth files, and sync. Piped --api-key
input stays out of the process list.
OpenCode Zen (opencode) and OpenCode Go (opencode-go) are separate
providers. Their credentials are stored, advertised, and served under those
exact ids.
A foreign CLI's subscription tokens stay with it. Save its API-key reference
or use --connect <provider> for a Devboxes-owned subscription. Restart
devboxes listen after local credential changes.
Share credentials with the organization
devboxes credentials sync
devboxes credentials sync --provider openai,anthropicSync copies device-store subscriptions and API keys, plus API keys read from saved references, into organization storage. It skips subscription tokens owned by another CLI. Every sync requires fresh runner browser approval because it exports local secrets.
Connecting a provider makes its non-deprecated models from the API's bundled Models.dev snapshot dispatchable.
Organization credentials use AES-256-GCM at rest and serve every runner. Add an API key or subscription under Manage → Credentials → Model providers. Repeating a provider sync updates that credential.
A credential marked Reconnect needed or Invalid no longer makes its provider dispatchable or qualifies new claims. Reconnect or replace it, or serve the provider locally, before dispatching again. A task already running can still fail its credential fetch.
Sync expands access from one machine to the whole organization. Anyone who can dispatch a run can execute code in a container that receives its selected credential.
Inspect and recover
credentials status lists provider, kind, account label, and auth-file
references without secret values. doctor --live refreshes every stored
subscription against its vendor; stored API keys are listed but not
vendor-verified.
Deleting a runner revokes its API key and removes the device-store passphrase;
the ciphertext cannot be decrypted again. Reconnect with devboxes connect,
delete the unreadable store when instructed, then run credentials setup.
Disconnecting an organization credential is blocked while a queued or running run has already received that exact credential. Finish or cancel those runs, then disconnect it again.
Secret exposure
- API responses and status commands never return key or token material.
- Provider keys enter task containers only through memory-backed storage.
- Removing a runner prevents future passphrase retrieval; it cannot retract plaintext already exposed to a process you control.
See the full Security model and ordered credential recovery steps.
Next: Roles & access — who can dispatch work and manage credentials.