All pages
Docs · Right-sidebar surfaces
Access keys (the Keys tab)
Availability: macOS · Linux · Windows (access_key_* tools; no pane yet) · cloud workspace (key_* at the edge, injected into the box).
The Keys tab (right sidebar → More ▾) is a vault for integration credentials — API keys, tokens, webhook secrets — that you or the agent spend when talking to outside services. TRMNLY stores metadata (name, env var, service, scope) as ordinary JSON, and the secret value separately.
Where the value is actually kept, which is not the same everywhere
This is the one thing about this feature worth reading twice.
| Host | Secret values live in | What that protects against |
|---|---|---|
| macOS | The login Keychain | Another user, another app without your code identity, and a stolen disk image |
| Linux / Windows | 0600 files under $XDG_STATE_HOME/trmnly/secrets |
Another user, and nothing else |
On a non-macOS host the values are plaintext on disk. Any process running as
you can read them, and so can any backup of that directory. That is the
platform's honest position today rather than a bug: the seam
(AccessKeySecrets) takes a real backend — libsecret, or an age-encrypted
file — without a single call site changing, and one has not been written yet.
The Keys pane reports the real location rather than implying parity, and
AccessKeySecrets.isProtected is the flag it reads. If you are storing
something whose disclosure matters and you are not on macOS, put it in your
shell's own secret manager and reference it with {{key:}} instead.
Not to be confused with Settings → API Keys, which holds the model provider keys (Anthropic, OpenAI, …) that power the agent itself. The Keys tab is for everything else: your Stripe test key, a GitHub PAT, a staging-server token.
That distinction catches people out, so TRMNLY now says it out loud. Put
a key here with an env var like ANTHROPIC_API_KEY while Settings → API
Keys has no Anthropic key, and the row tells you the agent reads its
Anthropic key from Settings, not from here — with a context-menu item
that takes you there. The Settings row, from the other side, offers to
copy this key across in one click. Once the provider is configured the
note goes away: the vault entry is then doing its real job of feeding
your shells and agent tools, and there's nothing to warn about.
What a key carries
- Name — how you and the agent refer to it (
OpenAI,Stripe test). - Env var — the conventional variable (
OPENAI_API_KEY). Setting one exports the key into the environment of every command the agent runs, which is the preferred way to spend it. - Service URL / notes — where it's for.
- Project scope — "All projects" or pinned to specific ones; a key scoped elsewhere is invisible to that project's agent.
- Expiry / rotation badges — "expired" and "rotate" flags in the list.
An importer pulls existing .env files straight into the vault.
The filter button in the Keys toolbar picks what the list shows: All Keys, Grouped by Project (a section per project, then the keys open to all projects, then any scoped only to projects you've since removed), Current Project (follows the project you switch to), or one named project. A single-project view includes keys scoped to "All projects", because that project's agent can use them. The choice is remembered.
How the agent spends a key (without seeing it)
Three paths, in order of preference:
- Environment. A key with an env var is already
$NAMEin everybash/spawn_and_readthe agent runs. Nothing to fetch. - Placeholders. Where an env var can't reach — an HTTP header, a
browser form fill — the agent writes
{{key:NAME}}in the tool argument and TRMNLY substitutes the real value host-side at execution time. The secret never enters the conversation. access_key_get. The escape hatch: returns the plaintext, which then lives in the transcript permanently. The agent is instructed to avoid it unless the value itself must be written somewhere (e.g. into a config file you asked for).
A command that references a key this way passes the secret check:
curl -H "x-api-key: $MY_KEY" …, API_KEY=$MY_KEY npm run deploy, or
Authorization: Bearer {{key:Stripe}} all run. A key's value pasted
literally into a command is still refused, so the reference is always the
way to go.
| Tool | Use |
|---|---|
access_key_list |
Metadata only — names, env vars, scopes; never values |
access_key_get |
Fetch one plaintext value (see the gates below) |
access_key_set |
Create or update a key; value goes to the Keychain |
access_key_delete |
Remove a key |
Gates on reading values
access_key_get fails when the key doesn't exist, is hidden from
agents, is scoped to a different project, or its grant has expired:
- Per-key agent access — each key has an "agents may fetch" toggle.
- Time-boxed grants — allow fetches for 15 Minutes / 1 Hour / 8 Hours / Until I Turn It Off; after that, reads fail again.
- Per-client grants — external MCP clients get their own key-fetch grants, revocable in one click ("Revoke Key-Fetch Grants").
Env injection and {{key:}} placeholders keep working regardless —
they spend the credential without disclosing it.
Pushing keys to the cloud workspace
The Keys tab starts with an Agents card: whether Claude Code and Codex
inside the workspace are signed in, and one field each to sign them in. Claude
takes the token claude setup-token prints, which also runs scheduled jobs and
the Agent tab. Codex takes an OpenAI API key, stored as OPENAI_API_KEY.
The cloud workspace has its own vault (the web Keys page, key_set /
key_list / key_delete on /api/mcp), and the box reads it into its
environment on every start. A change reaches a box that is already running
straight away, and panes opened after it see the new value. access_key_push_cloud copies keys from this
Mac's vault into it, under each key's env var name, so work handed to
the cloud has the same credentials without anyone pasting a value:
- Called with nothing it pushes every eligible key;
keysnarrows it to names, env vars, or ids;dry_run: truelists what would go. - Eligible means what the agent could already spend here: opened to agents, grant unexpired, project and client scope admitting the caller, and a valid env var name that isn't reserved. Expired keys, keys with no value, values with a newline, and values over 8 KB are skipped — each with its reason.
- Values never appear in the result. It is not a way to read a key, and the cloud never returns one either.
- The box picks the keys up on its next start or attach; a running box sees them after it restarts.
prune: true (or --prune) also removes cloud keys whose env var name no
eligible key on this Mac carries — including keys set from the web — so
the cloud vault mirrors the Mac's. It compares against every eligible key,
never only the ones named in the call.
Three ways in, one implementation: the tool, the Keys tab's cloud button
(the toolbar icon, or Push to Cloud Workspace… on a key's menu — the
sheet previews what would travel before anything is sent), and from a
pane trmnly keys push [name ...] [--dry-run] [--prune], with trmnly keys list for what's stored. All need the Mac signed in to trmnly.dev
(Settings → Account, or AI Agent → Remote Control).