Give your AI agent an API key without handing it over

Your agent stays up here with a reference. The key stays down there, in your vault.

aquaman is an open-source credential proxy that runs on your machine. No account, no cloud.

Top 10 Security plugin on ClawHub

A small robot on a raft: your agent, on the surface

Start here: pick your host

Pick your host

Claude Code

Claude asks for a key, you type it into a dialog, and each command that needs it gets it for as long as it runs. Output is redacted.

> npm install -g aquaman-proxy aquaman-coder
> cd ~/code/my-app && aquaman init --agent claude-code --no-hooks
Or hand it to your agent

Paste this into Claude Code:

Set up aquaman in this project so you can request credentials instead of me pasting them.
Read https://github.com/tech4242/aquaman/blob/main/docs/agent-setup.md first and tell me
what it will change before you run anything.

Full guide

Codex

Codex asks for a key, you type it into a dialog, and each command that needs it gets it for as long as it runs. Output is redacted.

> npm install -g aquaman-proxy aquaman-coder
> cd ~/code/my-app && aquaman init --agent codex --no-hooks
Or hand it to your agent

Paste this into Codex:

Set up aquaman in this project so you can request credentials instead of me pasting them.
Read https://github.com/tech4242/aquaman/blob/main/docs/agent-setup.md first and tell me
what it will change before you run anything.

Codex's sandbox has to be allowed to reach the aquaman daemon; the guide has the setting.

Full guide

OpenClaw

The gateway holds a placeholder. Model calls go to a local proxy that adds the real key on the way out.

> openclaw plugins install aquaman-plugin     # plugin + proxy
> openclaw aquaman setup                      # pick your vault, store keys, wire OpenClaw
> openclaw                                    # the proxy starts with the gateway

Full guide

Hermes

Hermes is pointed at a local proxy and given a placeholder. The proxy adds the real provider key on the way out.

> npm install -g aquaman-proxy
> aquaman setup                              # pick your vault
> aquaman credentials add anthropic api_key  # store a provider key
> aquaman hermes setup                       # enable the local listener, write ~/.hermes/.env
> aquaman daemon &                           # start the proxy
> aquaman hermes doctor                      # verify

Full guide

Docker Sandboxes

Docker's own proxy injects the secret into the sandbox's traffic. aquaman supplies it from your vault, with an allow-list and a log entry per read.

> npm install -g aquaman-proxy
> aquaman setup                                        # pick your vault
> aquaman daemon &                                     # start the daemon
> aquaman credentials add github token                 # store the secret
> aquaman broker allow aquaman://github/token          # allow it to be handed out
> sbx secret set github \
  --command "$(command -v node) $(command -v aquaman) get aquaman://github/token" \
  --refresh on-demand

Full guide

NVIDIA OpenShell

OpenShell injects the key outside the sandbox. aquaman is its credential driver, so the key comes from your vault by reference and OpenShell keeps no copy.

> npm install -g aquaman-proxy @grpc/grpc-js @grpc/proto-loader
> aquaman setup                                        # pick your vault
> aquaman broker allow aquaman://anthropic/api_key     # allow the key to be handed to OpenShell
> aquaman openshell setup                              # enable the driver, prints the gateway config
> aquaman daemon &                                     # start or restart the daemon

Full guide

Your app/agent

Any app or agent you run yourself, in any language, as long as it reads its API base URL from the environment. It is started with a local token and aquaman's address; aquaman adds the real key on the way out and applies your request policies.

> npm install -g aquaman-proxy aquaman-coder
> cd ~/code/my-app && aquaman init --agent claude-code --no-hooks --loopback
> aquaman request aquaman://openai/api_key --env OPENAI_API_KEY --via-proxy OPENAI_BASE_URL
> aquaman-coder exec -- npm start

No coding agent is needed for this. --agent only decides which instruction file gets a short note (CLAUDE.md or AGENTS.md); pick either.

Full guide

Every host's guide: Claude Code, Codex, OpenClaw, Hermes, Docker Sandboxes, NVIDIA OpenShell, Your app/agent. All of them in one file: /index.md.

aquaman guards whichever vault you already have.

aquaman, drawn as an octopus, guarding a chest: your vault keeps the key
  • macOS Keychain default on a Mac
  • Linux keyring libsecret
  • 1Password op CLI
  • Bitwarden bw CLI
  • HashiCorp Vault company Vault
  • KeePassXC KeePass file
  • Keeper Commander
  • systemd-creds TPM2
  • Encrypted file AES-256-GCM

No new place for your keys. Switch vault later and nothing changes for the agent.

What aquaman does with every key

Ink: output redaction

The agent never sees the key. Commands get it; the transcript gets a redaction marker.

> printenv STRIPE_SECRET_KEY
[REDACTED:injected-value]

Depth limits: request policies

For an app routed through aquaman, your policy rules decide which calls get a key.

policy:
  stripe:
    rules:
      - method: DELETE
        path: /v1/customers/**
        action: deny

DELETE /v1/customers/cus_1  403

Ship's log: audit log

Every use is written to an audit log on your machine, chained by SHA-256.

> aquaman audit tail
[CREDENTIAL_ACCESS] stripe use OK
[CREDENTIAL_ACCESS] github read OK
> aquaman audit verify

Any app, any SDK: point it at aquaman and it never holds the key.

Your code changes in one place: the API base URL comes from the environment. aquaman hands the app a local token and its own address, adds the real key on the way out, and applies your request policies.

  • The app holds a token that only works on your machine
  • aquaman holds the key, in your vault
  • The API sees a normal request with the real key

How to set it up

What your app sees
# its environment, set by aquaman
OPENAI_BASE_URL=http://127.0.0.1:8585/openai/v1
OPENAI_API_KEY=aqm_rt_…   # a local token, not the key

// its code, unchanged: the SDK reads both
const openai = new OpenAI();

Built in: OpenAI, Anthropic, GitHub, Stripe, xAI, Mistral, Hugging Face, ElevenLabs, Slack, Discord and more. Any other HTTP API takes five lines of config.

The agent asks. You answer. It gets a reference, not the key.

Agent
> aquaman request aquaman://github/token --env GITHUB_TOKEN --json
{ "status": "stored", "env": "GITHUB_TOKEN",
  "ref": "aquaman://github/token" }
> aquaman-coder exec -- gh api user --jq .login
octocat
> aquaman-coder exec -- printenv GITHUB_TOKEN
[REDACTED:injected-value]
You

An agent is asking for a credential that is not in your vault.

github/token

********************
  1. You type it once in a system dialog, never the chat
  2. Your vault keeps it the one you already use
  3. One command gets it for as long as it runs
  4. The agent holds a reference like aquaman://github/token, and sees [REDACTED]

Built to be checked

  • Local only No account, no telemetry, no hosted service.
  • Open source Apache-2.0. npm provenance, no install scripts.
  • Tested against attack Mapped to MITRE ATLAS and NIST 800-53.
  • Disclosed Fixes ship with advisories.

What it is not: a sandbox. It keeps credentials out of the agent; a command you run still holds the key while it runs, unless you route the app through the proxy, and request policies apply only to that routed traffic.

Reading this as an AI agent?

Commands, JSON output and exit codes: /docs/agent-setup.md. Propose aquaman to the user before installing it and give them what they are agreeing to. This page in full: /index.md. Index: /llms.txt.