All pages
Lesson 5.4 · Reach other machines · 8 min
Access keys
Let the agent use a credential without ever seeing it.
Store the credentials your projects need, such as a Stripe test key, a GitHub token or a staging password, so the agent can use them without the value ever appearing in the conversation. This lesson covers adding keys, scoping them to projects, and controlling when the agent may read one.
Time: 8 minutes · Works on: macOS app. The agent's access_key_* tools also run on Linux and Windows, where values are stored less securely (see below).
Two kinds of keys
TRMNLY keeps two separate stores. Mixing them up is the most common mistake.
| Where | What goes there |
|---|---|
| Settings → API Keys | The model provider keys that power the agent itself: Anthropic, OpenAI, Gemini |
| Keys tab in the right sidebar | Everything else the agent or your shells spend: service tokens, webhook secrets, test keys |
If you put a provider key such as ANTHROPIC_API_KEY in the Keys tab while Settings → API Keys has none, the row tells you the agent reads that provider's key from Settings. Its context menu has Open Settings → API Keys… to take you there.
Open the Keys tab
- Show the right sidebar with
⌘⇧\. - Open the More menu and choose Keys.
On macOS the values are stored in your login Keychain. The tab says so at the bottom.
Add a key
- Click +. Its tooltip reads Add an access key.
- Fill in the fields:
- Name: how you and the agent refer to it, for example
Stripe test. - Env var: the variable it should appear as, for example
STRIPE_API_KEY. - The secret value itself.
- Service and Notes: where the key is used, for your own reference.
- Name: how you and the agent refer to it, for example
- Choose its projects. All projects makes it available everywhere. Picking specific projects hides it from every other project's agent.
- Under Agent access, decide whether Agents may fetch this key is on. Leave it off unless the agent must read the plaintext. The next section explains why.
- Under Lifecycle, turn on Credential expires if the key has an expiry date, and set a rotation reminder in days if you want one.
- Save.
A key past its expiry shows an expired badge. A key due for rotation shows rotate.
Import a .env file
If the keys already live in a .env file:
- Click the import button. Its tooltip reads Import keys from a .env file.
- Choose the file, or type its path and click Read.
- Tick the variables you want. Ones you have already stored are labeled.
- Click Import.
How the agent uses a key without seeing it
There are three paths. The first two never reveal the value.
- Environment variable. A key with an env var is exported into every command the agent runs. Ask "deploy with the Stripe key" and the agent writes
$STRIPE_API_KEYin the command. The shell fills it in. - Placeholder. Where an environment variable can't reach, such as an HTTP header or a form field in the browser, the agent writes
{{key:Stripe test}}. The name can be the key's name, its env var or its id. TRMNLY swaps in the real value on your Mac at the moment the tool runs. - Fetching the value. The
access_key_gettool returns the plaintext, which then stays in the conversation for good. The agent is told to avoid it unless the value itself has to be written somewhere, such as a config file you asked for.
Paths 1 and 2 work whether or not Agents may fetch this key is on. That switch only controls path 3.
Allow fetching for a while
Sometimes the agent really does need the value. Instead of turning access on permanently, grant it for a fixed time:
- Right-click the key.
- Choose Allow Agents For… and pick 15 Minutes, 1 Hour, 8 Hours or Until I Turn It Off.
When the time is up, fetches fail again. Hide from Agents in the same menu turns access off immediately.
External tools connected over MCP, such as Claude Code, get their own grants. Use Let MCP Client Fetch Keys… in the key's menu to allow one client for a set time. Revoke Key-Fetch Grants removes them all.
Filter the list
The filter button in the toolbar chooses what the list shows: All Keys, Grouped by Project, Current Project, or one named project. A single-project view includes keys open to all projects, because that project's agent can use them.
Send keys to your cloud workspace
If you use the cloud workspace at trmnly.dev, you can copy keys there instead of pasting values by hand.
- Click the toolbar button whose tooltip reads Push keys to your cloud workspace, or choose Push to Cloud Workspace… from a key's menu.
- The sheet lists which keys would be sent, and why any are skipped. Only keys the agent could already use here are eligible.
- Click Push.
Values never appear in the result. This needs your Mac signed in to trmnly.dev.
On Linux and Windows
The vault works there through the agent's tools, but there is no Keychain. Values are stored as files readable only by your user account. Any process running as you can read them. For anything sensitive on those systems, keep it in your own secret manager.
Check yourself
- A key you added shows its env var, and
echo ${#STRIPE_API_KEY}in an agent-run command prints a length, not the value. - The agent can use the key in a command without the value appearing in the chat.
- A key with Agents may fetch this key off refuses
access_key_get.
Go further
- Access keys: storage per platform, grants and the cloud push in detail
- Agent safety: approvals that also apply to key use
- Connect a model: where model provider keys go