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:

  1. Environment. A key with an env var is already $NAME in every bash / spawn_and_read the agent runs. Nothing to fetch.
  2. 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.
  3. 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; keys narrows it to names, env vars, or ids; dry_run: true lists 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).