Skip to main content
NanoClaw’s credential invariant: agent containers never hold raw API keys. Secrets live in the OneCLI Agent Vault on the host, and the vault’s gateway injects them into outbound HTTPS requests in flight. An agent that is prompt-injected, jailbroken, or just curious can dump its entire environment and filesystem and find nothing worth stealing.

​
How the vault works

Every container is launched with HTTPS_PROXY pointing at the vault’s gateway. When the agent calls a real API URL — api.anthropic.com, api.github.com, gmail.googleapis.com — the gateway intercepts the request, matches the host against its stored secrets, and rewrites the auth header with the real token before the request leaves for the internet. Standard HTTP clients (curl, fetch, requests, axios, git) honor HTTPS_PROXY automatically, so the agent just makes normal requests with no auth headers at all. If the target service isn’t connected yet, the gateway returns an error with a connect_url the agent surfaces to you, instead of a silent failure. NanoClaw talks to the vault through two values in .env: ONECLI_URL (where the gateway lives) and ONECLI_API_KEY (the host’s own credential for the vault API).

​
Credential stubs

Some tools insist on finding a credential locally before they’ll start — MCP servers especially. For these, the container gets stub files whose secret values are the placeholder string "onecli-managed". The Gmail tool is the worked example: the Gmail MCP server reads ~/.gmail-mcp/credentials.json containing "access_token": "onecli-managed", happily starts, and sends Authorization: Bearer onecli-managed — which the gateway rewrites to the real OAuth token on its way to gmail.googleapis.com. Files containing onecli-managed are managed by OneCLI; agents are instructed never to modify or delete them.

​
Setting it up

The setup wizard handles the vault as one of its steps, with three paths:
  • Fresh install (default) — runs the OneCLI installer (a Docker Compose stack plus the onecli CLI), points the CLI at the new instance, and writes ONECLI_URL to .env.
  • Reuse existing — if setup detects a working onecli on the host, it asks before reinstalling. Choosing reuse leaves the running gateway untouched (re-running the installer would rebind the listener and break other apps using it) and just records its URL.
  • Remote vault — set NANOCLAW_ONECLI_API_HOST before running setup to point at a OneCLI instance on another machine. Setup installs only the CLI, health-checks the remote URL, and writes ONECLI_URL. Pass the remote vault’s API token via NANOCLAW_ONECLI_API_TOKEN so setup can authenticate the CLI and write ONECLI_API_KEY.
On an existing install (for example after /update-nanoclaw brings in OneCLI as a breaking change), run the /init-onecli skill instead. It installs the vault, migrates any credentials it finds in .env (Anthropic keys, OPENAI_API_KEY, and similar container-facing secrets) into the vault, and removes the raw values from .env. Channel tokens like TELEGRAM_BOT_TOKEN stay in .env — the host process uses those, not the containers.

​
Anthropic credentials

The wizard’s auth step offers three ways to connect Claude, all of which end up as a vault secret rather than an env var:
Setup runs claude setup-token under a PTY so the browser OAuth flow works, captures the resulting sk-ant-oat… token, and registers it:
onecli secrets create \
  --name Anthropic \
  --type anthropic \
  --value "$token" \
  --host-pattern api.anthropic.com

​
Adding a credential for a new service

Register a secret with a name and a host pattern — the host the gateway should inject it for: 
onecli secrets create \
  --name GitHub \
  --type api_key \
  --value "$TOKEN" \
  --host-pattern api.github.com
Then grant it to the agent groups that should use it. Note that set-secrets replaces the agent’s whole list, so read and merge first: 
AGENT_ID=$(onecli agents list | jq -r '.data[] | select(.identifier=="<agentGroupId>") | .id')
CURRENT=$(onecli agents secrets --id "$AGENT_ID" | jq -r '[.data[]] | join(",")')
MERGED=$(printf '%s' "$CURRENT,<new-secret-id>" | tr ',' '\n' | sort -u | paste -sd ',' -)
onecli agents set-secrets --id "$AGENT_ID" --secret-ids "$MERGED"
<agentGroupId> is the agentGroupId field in the group’s container.json. The same model powers setup/register-claude-token.sh, which accepts SECRET_NAME and HOST_PATTERN overrides if you want the subscription flow against a different secret name or host.

​
Approving credential use

Secrets can be configured in OneCLI to require manual approval per request. When the gateway intercepts a request that needs one, it holds the HTTP connection open and asks NanoClaw, which delivers a Credentials Request card to an admin DM showing the agent name, the METHOD host/path, and a body preview, with Approve / Reject buttons.
  • Who gets the card: admins of the originating agent group first, then global admins, then owners — the first one with a reachable DM. No eligible approver means auto-deny.
  • Approving or rejecting: tap the button on the card. The decision is returned to the gateway, which either injects the credential and lets the request through or fails it.
  • Expiry: unanswered cards expire on the gateway’s TTL and the request is denied. Cards left over from a previous process are marked “Expired (host restarted)” at startup.
Inspect in-flight approvals with the ncl CLI: ncl approvals list --status pending. The CLI is read-only for approvals — decisions happen on the card.

​
Opting out: the native credential proxy

If you don’t want the vault — a single-user install where .env simplicity beats per-agent policies — the /use-native-credential-proxy skill adds an explicit opt-out. With NANOCLAW_NATIVE_CREDENTIALS=true, NanoClaw reads ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, or ANTHROPIC_AUTH_TOKEN (plus optional ANTHROPIC_BASE_URL) straight from .env and threads them into the container’s environment as standard SDK variables.
This deliberately inverts the v2 invariant: the raw credential enters the container. You lose injection-at-the-boundary, per-agent secret grants, and approval cards. Use it only if you accept that tradeoff.
The skill is additive — with the flag unset, it’s a no-op and the vault path is unchanged. It only covers Anthropic credentials; other service secrets still need the vault or manual handling.

​
Egress lockdown

For defense in depth, NANOCLAW_EGRESS_LOCKDOWN=true places agents on an internal Docker network where the vault’s gateway is the only reachable egress hop — agents physically cannot bypass the proxy. See Hardening for the full setup.
Last modified on June 10, 2026