OneCLI Keeps Secrets Out of Agents

OneCLI is an Apache-2.0 open-source credential gateway from creators Jonathan and Guy that sits between AI agents and the services they call. It deals with the boring but dangerous moment when an agent gets a real API key and may log it, save it, or be tricked into handing it over. The answer is a network boundary: store the real secret once, give the agent a useless placeholder, and let the gateway inject the real credential only on the outbound request. For claude code teams, that boundary is the part to copy into the workflow, even if you never run OneCLI itself.

Follow the key, not the agent

OneCLI is a credential gateway for AI agents: the agent makes an ordinary HTTP request with a placeholder key, and the gateway swaps in the real credential after the request leaves the agent process.

That sounds small. It is not. Most agent security advice starts with the agent: prompts, permissions, sandboxes, reviews, logs. OneCLI starts with the credential and asks a sharper question: where does the real key actually exist?

In the project README, the model is simple. Store the real API credential in OneCLI. Give the agent something like FAKE_KEY. Route the agent’s request through the gateway. The gateway matches the request, decrypts the stored credential, injects it into the outbound call, and keeps the real value out of the agent’s context.

As of July 2026, the public repository showed 2,664 GitHub stars, an Apache-2.0 license, and a codebase centered mainly on TypeScript, with a Rust gateway described in the project architecture. The repo topics also make the intended world obvious: AI agents, CLI, MCP, Node.js, Rust, Postgres, and related agent plumbing.

The interesting bit is not that OneCLI is another place to store secrets. The interesting bit is that it treats an agent as an untrusted middle layer, even when the agent is useful and mostly well-behaved.

The trap is assuming a traditional vault solves this by itself. A normal vault protects the key until retrieval. Once the key is handed to an agent, the key can move into logs, shell history, generated files, crash reports, tool calls, or a copied prompt. OneCLI’s bet is that the safer handoff is no handoff at all.

Watch the leak happen in a normal coding session

Here is the workflow that makes this project feel timely.

A developer asks Claude Code, Anthropic’s coding agent, to add a GitHub integration to a service. The agent needs to call an API, run a local test, maybe inspect a failing response, and write a fixture. Someone puts GITHUB_TOKEN in the environment because that is how the old script worked.

Nothing obviously malicious happens. The agent adds a debug log while chasing a 401. It writes a reproduction command into a markdown note. It creates a test fixture with headers copied from a live request. Then the branch goes up for review, and the real token has quietly crossed from secret storage into repo-shaped exhaust.

This is why OneCLI’s placeholder-key idea is useful for a Claude Code workflow. The agent can still make the call. The test can still run. But the value available inside the session is not the value an attacker can use.

Hacker News readers noticed the same boundary question quickly. If the agent controls the environment where the gateway runs, the protection gets weaker. A fake token is only fake if the agent cannot also rewrite the thing that turns fake into real.

That is the practical lesson. Do not draw the boundary around the prompt. Draw it around the credential path.

The trap to avoid is comfort theatre. A prompt that says do not reveal secrets is a reminder, not a control. A gateway, a separate process, a narrow network route, and redacted logs are controls.

Put a gateway boundary in Claude Code

The minimal pattern for Claude Code users is simple: the agent gets placeholders, the gateway gets real credentials, and the repo records which routes are allowed.

This matters for claude code teams because agent work is often parallel and messy. One session is fixing tests. Another is writing migration code. A third is checking API behavior. If all three sessions can see real credentials, every generated file and every debug path becomes a secret-handling surface.

Keep the durable convention small. A short repo note can say that agents must not receive real API keys, that service calls go through the credential gateway, and that direct egress to the same service is not allowed during agent tasks. Put broader working agreements in the related training topic, but keep the repo rule close to the code that needs it.

A clean boundary also pairs well with sandboxes. If a coding agent release changes how sandboxing behaves, the credential rule should still hold: no real key in the agent process. That is the same habit behind our note on claude-code 2.1.216 Loosens Sandboxes: when execution gets easier, boundary evidence matters more.

The trap is routing through a gateway while leaving the old .env path alive. Agents are very good at discovering working commands. If curl https://api.service.test -H Authorization: Bearer $REAL_KEY still works from the session, the gateway is a preference, not a boundary.

Copy this starter boundary checklist

Use this as a small review artifact before giving an agent access to a real external service. It is not OneCLI configuration. It is the permission note you want beside any credential gateway experiment.

Agent credential boundary

Task:
- Service the agent needs to call:
- Placeholder value exposed to the agent:
- Gateway or proxy process that holds the real credential:

Rules:
- No real API keys in prompts, environment files, fixtures, logs, screenshots, or pasted terminal output.
- Agent requests to this service must go through the gateway.
- Direct outbound calls to the same service are blocked or treated as a review failure.
- Debug logs must redact Authorization, Cookie, x-api-key, and query-token values.
- The PR notes which external service was called and why.

Before merge:
- Search the diff for token-shaped strings and copied headers.
- Rotate the real credential if it appeared outside the gateway.
- Remove temporary bypass commands from scripts and docs.

Here is the risk table I would keep next to it.

The checklist is intentionally plain. Fancy policy fails when the task is on fire. A short note that reviewers can enforce is better than a beautiful rule nobody reads.

Common questions

• Does OneCLI replace my secrets manager?

  No, OneCLI is better understood as an agent-facing credential gateway, not a blanket replacement for every vault. The project includes a built-in vault, but the bigger idea is request-time injection. If your existing setup already has rotation and audit, the question is whether agents still receive raw secrets after retrieval.

• How should claude code teams use this idea?

  Claude code teams should start by keeping real service credentials out of agent sessions and routing only the needed API calls through a gateway or proxy. The concrete artifact is a one-page boundary note: placeholder value, allowed service, gateway path, blocked bypass, and review receipt. That is enough to catch most accidental leaks.

• Is a fake key safe if it leaks?

  A fake key is safe only if it has no value outside the gateway path. If the placeholder can be exchanged by any caller, or if the gateway trusts only the token string with no route, process, or network checks, it becomes a bearer secret by another name. Treat placeholders as low-value, not magic.

• Can the agent bypass the gateway?

  Yes, it can if the environment still allows direct calls with real credentials or lets the agent modify the gateway configuration. This is the uncomfortable part of the design. The gateway boundary needs ordinary engineering controls around it: narrow egress, read-only config during tasks, redacted logs, and reviewable service receipts.

• Where does this fit in a Claude Code workflow?

  It fits before the prompt. Configure the task so Claude Code sees placeholders and approved routes, then ask it to work normally. If a service call is needed, the gateway handles the credential swap. Afterward, review the diff and logs for copied headers, token-shaped strings, and accidental bypass commands.

Best ways to use this research

• Best for: evaluating whether an AI coding session ever needs to see real API keys, especially when the task involves external services.
• Best first artifact: copy the starter boundary checklist into the issue or PR description for one low-risk integration task.
• Best comparison angle: compare secret retrieval with request-time credential injection. The first protects storage; the second reduces what the agent can leak after retrieval.
• Best Claude Code convention: make no real secrets in agent sessions a repo rule, and make gateway-only service calls part of the review evidence.

Further reading

• Claude Code — getting started
• Claude Code — skills
• onecli — source

Next step

Pick one service your agent calls today and replace the real key in the session with a placeholder. If the task still works through a gateway and the diff has no credential exhaust, you have a boundary worth keeping.

One methodology lens

One useful way to read this through our methodology is the Plan step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.