All pages

Autonomy you can trust · Lesson 1.3 · 10 min

Secrets without leaks

Let the agent use credentials it never sees.

After this lesson you can give the agent a credential it can use but never read, scope and time-box that access, and spot the places a secret can still escape into a transcript or a log.

Time: 10 minutes · Works on: macOS app. The access_key_* tools also run on Linux and Windows, where values are stored less securely.

The transcript is forever

Anything the agent reads becomes part of its conversation. That conversation is sent to the model provider, kept in your chat history, and may be exported, shared, archived or synced. You can't take a value back out once it's in. So the rule for credentials is simple:

The agent spends secrets. It doesn't read them.

An agent almost never needs to know a key's value. It needs a command or a request that carries the value, and that can be arranged without the value passing through the model. The few times it really must write the plaintext somewhere, such as a config file you asked for, that should be a decision you make once, on purpose, and not a habit.

Three more habits follow from this:

  • Scope narrowly. A key the agent in project A can use should not be visible to the agent in project B.
  • Grant for a while, not for ever. When a task really does need more access, give it for the length of the task.
  • Watch the side doors. Most leaks don't come from asking for a key. They come from output: cat .env, printenv, a verbose curl -v that echoes an Authorization header, a stack trace that prints a connection string.

A worked example

You want the agent to test a Stripe webhook handler against Stripe's test mode.

  • The wrong way is to paste the test key into the chat. It's now in the transcript and sent to the model with every turn after.
  • The better way is to store it in the vault as Stripe test with the env var STRIPE_API_KEY, scoped to this one project. The agent writes curl -u "$STRIPE_API_KEY:" https://api.stripe.com/... and the shell fills in the value. The model only ever sees the variable's name.
  • For the browser step, where there is no shell, the agent fills a form field with the placeholder {{key:Stripe test}}, and TRMNLY swaps in the value at the moment the tool runs.
  • If the agent then runs printenv to debug something, the value would come back in the output. TRMNLY knows the stored value, so it redacts it from the result before the model sees it. You still treat that as a near miss and ask why the agent needed printenv.

Do it in TRMNLY

  1. Know the two stores. Model provider keys for the agent itself go in Settings → API Keys. Everything the agent or your shells spend, such as service tokens, webhook secrets and test keys, goes in the Keys tab. Show the right sidebar with ⌘⇧\, open the More menu and choose Keys. On macOS the values are kept in your login Keychain.
  2. Add the key with an env var. Click +, give it a Name such as Stripe test and an Env var such as STRIPE_API_KEY, and paste the value. Under projects, pick only the projects that need it instead of All projects. Another project's agent can't spend or fetch a key that isn't scoped to it. If the keys already live in a .env file, the import button, Import keys from a .env file, pulls them in.
  3. Spend it through the environment. A key with an env var is exported into every command the agent runs. Ask the agent to check it's there without showing it: echo ${#STRIPE_API_KEY} prints a length, not the value.
  4. Use a placeholder where a shell can't reach. For an HTTP header or a browser form field, the agent writes {{key:Stripe test}}. The name can be the key's name, its env var or its id. The approval card and the audit log see the placeholder, not the value. Placeholders work only in TRMNLY's built-in tools. An external tool, from an MCP server or a plugin, refuses a placeholder rather than receive it as text, so pass those a credential another way.
  5. Keep the escape hatch closed. access_key_get returns the plaintext, which then stays in the conversation. It always needs approval on Approve. When a card for it appears, deny it unless the value really must be written somewhere, and never turn it into an Always… rule.
  6. Decide whether agents may use the key at all. In the key's editor, Agents may fetch this key is on by default. Turned off, the row reads Hidden from agents, and agents can't use the key in any way: it isn't exported into their commands, and placeholders naming it fail. Use it for keys that only your own shells should spend.
  7. Time-box a grant. Right-click the key and choose Allow Agents For…, then 15 Minutes, 1 Hour, 8 Hours or Until I Turn It Off. When the time is up, agent access ends again. Hide from Agents in the same menu ends it immediately. External MCP clients such as Claude Code get their own grants through Let MCP Client Fetch Keys…, and Revoke Key-Fetch Grants removes them all.
  8. Check the redaction layer. Open the Safety panel from the shield icon and look at the Detectors tab. Tool results are scanned for known credential shapes and for the exact values stored in your vault, and a redacted result ends with a line saying how many credentials were removed. The gitleaks and trufflehog detectors are off by default and run only when installed. Redaction is a backstop, not a plan: a secret that isn't in your vault and doesn't look like a known key format gets through.
  9. Be deliberate about a project .env. In Project Settings…, the .env / .envrc field loads a file's KEY=VALUE lines into every shell in the project and into the agent's commands. Where a name is in both, the project file wins over the vault. Values that live only in that file aren't in the vault, so they aren't matched exactly by the redaction layer. Import the sensitive ones into the Keys tab. Lines that would rewire the shell or the loader, such as PATH or DYLD_*, are skipped.
  10. Remember what your logs keep. If terminal history is on, anything a command printed is recorded, secrets included. The Keys tab's own redaction works on what the agent reads, not on what your panes print. Keep commands that echo secrets out of long-lived panes, and treat the history folder accordingly.
  11. Know the remote limit. A paired phone or the web remote can never read or set vault keys, whatever its scopes. Credentials stay on the Mac.

Check yourself

  • A key you added is scoped to one project. In another project, the agent's echo ${#STRIPE_API_KEY} prints 0, because the key isn't exported there.
  • The agent used the key in a command, and the value never appeared in the chat.
  • You denied an access_key_get card and the run carried on through the env var.
  • You can name two ways a secret can reach a transcript or a log even though the agent never asked for it.

Go further