Logo

How AI Agents Should Handle Secrets

AI coding agents touch API keys, database URLs, and .env files every day. Here are practical rules for keeping those secrets out of transcripts, logs, and context windows.

How AI Agents Should Handle Secrets

Coding agents now do real operational work. They provision databases, rotate keys, configure CI, and debug production. All of that involves secrets. Most agent setups still handle them the way people did in 2010: paste it into the chat and hope for the best.

This post covers where secrets leak in agent workflows, and a few simple rules that prevent most of it.


Where secrets leak in agent workflows

1. The transcript

Anything you paste into an agent conversation becomes part of the transcript. Depending on your tools, that transcript may be saved to disk, synced to the cloud, shared with teammates, or attached to a bug report. A key pasted "just this once" lasts as long as the conversation does, which is often forever.

2. Tool output

When an agent runs cat .env, env, or kubectl get secret -o yaml, the output goes into its context. It's also displayed in your terminal, and often written to session logs. The agent didn't need to see the secret to use it, but now it has.

3. Agent-generated credentials

Agents increasingly create credentials: a new API token, a database password, a signing key. The natural instinct is to print it so you can save it. That puts a freshly minted secret into the least secure place possible.

4. Handoffs between agents

Multi-agent setups pass work between processes, threads, and sometimes different vendors. If one agent needs to hand a credential to another, the easiest path is to put it in the task description, where every orchestrator log and summary will copy it.


Six rules for agents

These rules work whether you're writing an agent, configuring one, or just using one.

Rule 1: Reference secrets, don't read them

Most of the time, an agent only needs a secret to exist in the right place, not to know its value. Prefer commands that use secrets without printing them: source .env && ./deploy, not cat .env. Tell your agent this explicitly in your project instructions.

Rule 2: Never print a secret you generated

When an agent creates a credential, it should store it in the destination (a secrets manager, an environment variable, a config file in .gitignore) and only report where it put it. If a human needs the value, use a single-use link.

When a secret has to move between parties, whether human to agent, agent to human, or agent to agent, wrap it in a link that works once. With Dropzone, that's one tool call (create_drop) or one curl. The link can appear in a transcript safely: once the recipient opens it, it's useless to anyone who finds it later.

Single-use links only work if agents don't open them on a whim. An agent should open a link only when the contents are meant for it and it actually needs them now. It should open it once, and save what it needs. It should never open a link it created for someone else. That's why Dropzone marks the open_drop tool as destructive, and why fetching a Dropzone page as HTML doesn't consume it.

Rule 5: Keep secrets out of task descriptions

If you orchestrate agents, pass references, not values. "The staging DB URL is at this Dropzone link" ages much better than the URL itself in a task prompt that gets logged, retried, and summarized.

Rule 6: Write the rules down

Agents follow project instructions. Put your secret-handling rules in AGENTS.md, CLAUDE.md, or your agent's system prompt. A few lines are enough:

## Secrets
- Never paste secrets, API keys, or .env contents into chat or logs.
- To share a secret with a human or another agent, create a single-use
  Dropzone link (MCP tool `create_drop`, or see https://dropzone.sh/llms.txt).
- Only open a Dropzone link when its contents are meant for you, and only once.

Vaults and secrets managers are the right home for long-lived credentials. But many secret movements are one-off handoffs: onboarding a contractor, sharing a staging key, giving an agent access for one task. Setting up a vault policy for each of those is so much friction that people skip it and paste the secret instead.

Single-use links fill that gap. They need no setup on the receiving end, so any agent that can make an HTTP request can use one. And they fail safe: a leaked transcript containing a used link reveals nothing.

Dropzone's agent tools are free and need no account. See the agents page to set them up, or point your agent at /llms.txt.