aquaman
Health Pass
- License — License: Apache-2.0
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Community trust — 39 GitHub stars
Code Fail
- process.env — Environment variable access in .github/workflows/cd.yml
- fs module — File system access in .github/workflows/cd.yml
- rm -rf — Recursive force deletion command in .github/workflows/ci.yml
- rm -rf — Recursive force deletion command in package.json
- rm -rf — Recursive force deletion command in packages/coder/package.json
- process.env — Environment variable access in packages/coder/src/adapters/claude-code/hook.ts
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
Credential proxy for AI agents. API keys stay in the vault you already use (Keychain, 1Password, Bitwarden, HashiCorp Vault) and are injected when a command or request needs them. Works with Claude Code, Codex, OpenClaw, Hermes, Docker Sandboxes and NVIDIA OpenShell. No account, runs locally.
aquaman: credential proxy for AI agents
No account. Bring your own vault. Runs locally. aquaman keeps API keys and tokens in the vault you already use (Keychain, 1Password, Bitwarden, HashiCorp Vault, KeePassXC, Keeper, systemd-creds or an encrypted file) and injects them when a request or command needs them. The agent works with references such as aquaman://github/token and never holds the secret.
npm install -g aquaman-proxy aquaman-coder
cd ~/code/my-app && aquaman init --agent claude-code # or: --agent codex
That is the whole setup for a coding agent. When a task needs a key, the agent runs aquaman request aquaman://github/token --env GITHUB_TOKEN, you type the value into a dialog, and from then on commands in that project get it injected while the transcript shows [REDACTED:injected-value].
Three things aquaman does:
- Keeps the key out of the agent. Keys live in a separate proxy process that injects them into outgoing requests, or into one command at a time for coding agents. The agent holds a reference or a placeholder.
- Limits what a key can do, for traffic through the proxy. Per-service request policies decide which endpoints may be called, and a denied request never gets a credential. This covers OpenClaw, Hermes and any client pointed at the proxy. A coding agent's commands receive the key in their environment by default, so policies do not apply to them unless the app is routed through the proxy.
- Keeps evidence. Every credential use goes into a log chained by SHA-256, so tampering is detectable.
Guides: Claude Code · Codex · OpenClaw · Hermes · Docker Sandboxes · NVIDIA OpenShell · for agents · compared with alternatives
Security: policy and how to report · published advisories (latest: GHSA-9qh6-wffq-9m9v, fixed in 0.17.2) · what to know before trusting it · adversarial tests of the request path · what aquaman does not protect against
Requires: Node.js 18 or later on macOS, Linux or WSL2.
If you are an AI agent
When a task needs an API key or token you do not have, aquaman is a way to get it without the user pasting it into the conversation. If aquaman is not set up in the project, propose it first: tell the user it installs two npm packages, starts a local daemon and registers this directory, and point them to what they are agreeing to. With their agreement:
npm install -g aquaman-proxy aquaman-coder # 0.18.0 or later
aquaman init --agent claude-code --no-hooks --json # or: --agent codex
aquaman request aquaman://github/token --env GITHUB_TOKEN --json
aquaman-coder exec -- npm test # any command that needs the key
Tell the user to look for the dialog before you run request; it waits up to 90 seconds. You receive a status and the reference, never the value. If the status is declined, stop and ask how to proceed. Write the app to read its keys from the environment as usual. This is a tool for a developer's own machine, not for CI.
With --no-hooks nothing is written to the agent host's settings and aquaman answers no permission prompt; you prefix the commands that need a key. Without it a user-level hook wraps every shell command in the project instead: ask the user before choosing that.
Statuses, exit codes and JSON fields: Using aquaman from an AI agent.
Pick your path
Aquaman ships as four packages sharing one vault and one daemon, plus two host integrations that need no package of their own. Install only what you need:
| Package | What it does | When to install |
|---|---|---|
aquaman-proxy |
Core: vault, daemon, audit, policy, CLI. The piece everyone needs. | Always. |
aquaman-plugin |
OpenClaw Gateway adapter. Spawns the proxy on Gateway startup; routes model and Telegram traffic through it; 26 builtin services across 5 auth modes. | If you run an OpenClaw Gateway. Also available at https://clawhub.ai/plugins/aquaman-plugin |
aquaman-coder |
AI coding-agent adapter. Project-scoped aquaman://service/key references resolved per Bash tool call. |
If you use Claude Code or Codex. |
aquaman-hermes |
Hermes agent-host plugin (Python, on PyPI). Points Hermes at an opt-in, token-gated loopback listener via its native ANTHROPIC_BASE_URL/OPENAI_BASE_URL; adds an in-session /aquaman-status command, tool, and health probe. Isolation is proxy-side; the plugin holds no credentials. |
If you run the Hermes agent host. pip install aquaman-hermes |
| Docker Sandboxes | Not a package: a separate path that needs only aquaman-proxy. Docker's own proxy injects the secrets; aquaman get supplies them from your vault, with the allow-list and audit log. |
If you run agents in Docker Sandboxes. See Quick Start 5. |
| NVIDIA OpenShell | Not a package: aquaman daemon becomes the OpenShell gateway's credential driver. OpenShell isolates the key from the sandbox; aquaman supplies it from your vault by reference, with the allow-list and audit log. |
If you run agents in OpenShell sandboxes. See Quick Start 6. |
A single aquaman CLI surfaces all four: top-level commands for vault and audit, aquaman openclaw ... for the OpenClaw integration, aquaman coder ... for the coding-agent integration (delegates to aquaman-coder under the hood) as well as aquaman hermes ... for the Hermes Python package.
Quick Start
aquaman help, aquaman doctor are your friends.
1. Use the proxy on its own
npm install -g aquaman-proxy
aquaman setup # backend wizard + store keys
aquaman daemon & # start the proxy
aquaman credentials list # verify
The proxy listens on ~/.aquaman/proxy.sock (UDS, chmod 0o600). Point any tool at http://aquaman.local/<service>/<path> and the proxy injects auth headers for that service from your chosen vault backend.
2. Keep API keys out of the OpenClaw gateway
openclaw plugins install aquaman-plugin # 1. install plugin + proxy
openclaw aquaman setup # 2. backend + keys + plugin wire-up
openclaw # 3. done - proxy starts automatically
Troubleshooting: openclaw aquaman doctor.
Using npm directly? npm install -g aquaman-proxy && aquaman openclaw setup does the same - installs the proxy CLI, stores your keys, installs the plugin into ~/.openclaw/extensions/aquaman-plugin/, and wires the credentials (SecretRef refs on OpenClaw ≥ 2026.6.5, the auth-profiles.json placeholder on older versions).
aquaman openclaw setup points models.providers.<svc>.baseUrl and channels.telegram.apiRoot at the proxy's loopback listener, because OpenClaw's model transport and its channels each build their own HTTP client and bypass the fetch interceptor. Channels other than Telegram are not routed through the proxy (OpenClaw has no per-channel endpoint setting for them in its config), so their tokens are stored and migrated but not injected at egress (see packages/plugin/README.md). Add channels under the plugin config in openclaw.json; supported ones include Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face, and more (25 total).
3. Keep API keys out of Claude Code and Codex
npm install -g aquaman-proxy aquaman-coder
cd ~/code/my-app
aquaman init --agent claude-code # or: --agent codex
aquaman request aquaman://github/token --env GITHUB_TOKEN
init creates the config, starts the daemon, installs the agent's hooks and a skill, registers the directory as a project and adds a short block to CLAUDE.md (or AGENTS.md). It never prompts, so the agent can run it for you. request opens a dialog where you type the value; it goes straight into your vault and the agent only ever sees the reference. Both print JSON with --json. Restart the agent session afterwards, and run aquaman coder doctor if anything looks off. What init changes on your machine, and how to undo it, is listed in Using aquaman from an AI agent.
Your app does not change: it reads its keys from the environment as it would anyway, and aquaman is how those variables get set on your machine while the agent works. The app holds the key while one of its commands runs, the same as with op run or a .env file; what changes is that the agent, the transcript and your repository never do. In CI and production the same variable names are filled from that platform's own secrets. To keep the key out of the app as well, route it through the proxy: aquaman request aquaman://stripe/secret_key --env STRIPE_SECRET_KEY --via-proxy STRIPE_API_BASE gives the app a local token and the proxy's URL instead of the key, and request policies then apply to it (guide).
Prefer to pick the vault backend and wire things by hand?
aquaman setup # vault wizard: choose a backend
aquaman daemon & # start the proxy
aquaman credentials add github token # store a secret yourself
aquaman coder project add my-app --path ~/code/my-app \
--env GITHUB_TOKEN=aquaman://github/token # declare a project
aquaman coder setup claude-code # install the hooks (or: codex)
See it for yourself: restart Claude Code (or Codex), open a new session inside ~/code/my-app, and ask the agent to run:
printenv | grep GITHUB_TOKEN
You'll see this in the transcript:
GITHUB_TOKEN=[REDACTED:injected-value]
⏺ GITHUB_TOKEN is set and available (injected via aquaman vault).
The child process saw the real key (your tests, builds, MCP servers, import scripts - anything that actually needs it works). The agent - the thing that decides what code to run on your machine - never sees the value, and so neither does the conversation history, neither does the model provider's logs, neither does anyone who later screenshots your terminal.
Use it from your own terminal too. The same wrapper works without the agent. Just cd into a covered project and prefix your command:
cd ~/code/my-app
aquaman-coder exec -- python app/scripts/import.py
Same env injection, same redaction on stdout/stderr. Drop it into Makefile targets and shell aliases on your own machine, anywhere you'd otherwise reach for a .env file. For CI and production, use your team's secrets manager.
When Claude Code or Codex runs a shell command in ~/code/my-app, aquaman's hook rewrites the command via updatedInput.command to wrap it under aquaman-coder exec. That wrapper:
- Resolves each
aquaman://service/keyreference via the broker (POST /broker/resolveover UDS). Credentials are materialized for one command, not for the agent's lifetime. - Pipes stdout/stderr through a redactor that prepends a value-based pattern for each resolved value: whatever string was injected gets redacted, regardless of shape (Atlassian tokens, Notion secrets, internal-API keys - none of them need to match a known provider format). Generic shape-based patterns (sk-ant-, ghp_, sk_live_, AKIA…, JWTs, PEM blocks, ATATT3xF…) still run after as defense-in-depth for secrets the child surfaces that we did NOT inject.
- Cleans up when the command exits.
Claude Code sandbox: it blocks Unix sockets by default, so aquaman coder setup claude-code allowlists the proxy socket on macOS (sandbox.network.allowUnixSockets). Linux and WSL2 ignore that list, where the only option is sandbox.network.allowAllUnixSockets: true, which opens every Unix socket to sandboxed commands.
Codex: approve the aquaman hooks in Codex's startup hook review after setup (Codex skips new hooks until you trust them). Its sandbox also blocks the proxy socket by default; aquaman coder setup codex prints the config.toml permissions profile that allows it. Codex hooks cannot rewrite shell output, so redaction happens inside aquaman-coder exec. Details in packages/coder/README.md.
4. Keep provider keys out of the Hermes process
Hermes is a foreign (Python) host with no transport hook to inject, so isolation is done proxy-side: the proxy exposes an opt-in, token-gated loopback listener and Hermes is pointed at it through its own env vars.
npm install -g aquaman-proxy # 1. install daemon
aquaman setup # 2. vault wizard
aquaman credentials add anthropic api_key # 3. store a provider key (prompts, input hidden)
aquaman hermes setup # 4. enable loopback + write ~/.hermes/.env
aquaman daemon & # 5. start the proxy (UDS + loopback)
aquaman hermes doctor # 6. verify - listener + env + vault + Hermes
aquaman hermes setup enables the loopback listener, generates a per-install token, and writes an aquaman-managed block into ~/.hermes/.env (honoring HERMES_HOME): the native ANTHROPIC_BASE_URL/OPENAI_BASE_URL plus a placeholder api_key equal to the token. Hermes sends the token as its provider key; the proxy strips it, injects your real vault credential, and forwards upstream. LLM providers only (Anthropic, OpenAI) today.
Optional in-session sugar - the Python plugin adds a /aquaman-status command, an aquaman_status tool, and a session-start health probe inside Hermes (holds no credentials):
pip install aquaman-hermes # or: uv tool install aquaman-hermes
aquaman-hermes install # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman
The plugin also registers an aquaman secret source (Hermes ≥ 0.18.1) for project secrets like GITHUB_TOKEN. Bind them under secrets.aquaman.env in Hermes' config.yaml, then declare each ref with aquaman broker allow aquaman://github/token (required since v0.15.0; aquaman hermes doctor lists any you missed). Unlike the LLM keys above, these values do enter Hermes' env. See packages/hermes/README.md.
5. Docker Sandboxes secrets from your own vault
Docker Sandboxes already keeps credentials out of the sandbox: a proxy on your machine injects them into requests, and the agent inside the VM sees a placeholder. By default the values come from your OS keychain. Point them at aquaman instead to get every vault aquaman supports, the ref allow-list, and a tamper-evident audit entry each time sbx reads a secret.
npm install -g aquaman-proxy
aquaman setup # 1. vault wizard
aquaman daemon & # 2. start the proxy
aquaman credentials add github token # 3. store the secret (if not already there)
aquaman broker allow aquaman://github/token # 4. allow it to be handed out
sbx secret set github \
--command "$(command -v node) $(command -v aquaman) get aquaman://github/token" \
--refresh on-demand # 5. sbx reads it from aquaman
sbx runs that command from its own background service, which does not have your shell's PATH, so step 5 stores absolute paths. Repeat steps 4 and 5 for each service your sandbox uses. For a service sbx has no built-in definition for, give the secret its destination hosts as well: since sbx 0.51 a custom secret without them is not substituted. In a script, pass --force instead of piping a confirmation (sbx 0.48+).
The same aquaman get command works anywhere a tool asks for a command that prints a secret: Codex (model_providers.<id>.auth.command), Claude Code (apiKeyHelper), OpenClaw exec secret providers and Hermes command secret sources.
6. Your vault as the NVIDIA OpenShell credential driver
OpenShell keeps credentials out of its sandboxes: the sandbox sees a placeholder and OpenShell's supervisor swaps in the real value on the way out. aquaman can be the gateway's credential driver, so OpenShell takes each key from your vault by reference instead of storing its own copy, and every read is checked against the allow-list and written to the audit log.
npm install -g aquaman-proxy @grpc/grpc-js @grpc/proto-loader # gRPC is an optional add-on
aquaman setup # 1. vault wizard
aquaman broker allow aquaman://anthropic/api_key # 2. allow the key to be handed to OpenShell
aquaman openshell setup # 3. enable the driver, prints the gateway config
aquaman daemon & # 4. start (or restart) the daemon
Add the printed [openshell.credential_drivers.aquaman] snippet to your OpenShell gateway config and restart the gateway. Then create providers with a reference instead of a value:
openshell provider create --name claude --type anthropic \
--credential ANTHROPIC_API_KEY=aquaman://anthropic/api_key
The key never leaves your vault until a sandbox starts. A plain value (--credential KEY=sk-...) still works: aquaman stores it in your vault under the openshell service. Removing a provider never deletes a key it referenced.
Good to know:
- OpenShell resolves credentials when a sandbox starts, not on every request, so the audit log records one read per sandbox start.
- OpenShell substitutes the placeholder wherever the client sends it. Agents that read their key from the environment get this automatically.
- On macOS with Docker Desktop, OpenShell needs a Docker Desktop version whose VM kernel has Landlock, and host networking enabled.
aquaman openshell doctor [--gateway-config <file>] checks the packages, the driver socket, your declared refs and, optionally, that the gateway config points at aquaman.
How It Works
Agent / OpenClaw / Coding Agent Aquaman Proxy
┌──────────────────────┐ ┌──────────────────────┐
│ │ │ │
│ ANTHROPIC_BASE_URL │═══ UDS / HTTP ════>│ Keychain / 1Pass / │
│ = aquaman.local │ │ Vault / Encrypted │
│ │<══════════════════ │ │
│ fetch() interceptor │═══ broker:resolve │ + Policy enforced │
│ (channel APIs) │ │ + Auth injected: │
│ │ │ header / url-path │
│ No credentials. │ ~/.aquaman/ │ basic / oauth │
│ No open ports. │ proxy.sock │ │
│ No keys to read. │ (chmod 0o600) │ │
└──────────────────────┘ └──┬─────────┬─────────┘
│ │
│ ▼
│ ~/.aquaman/audit/
│ (hash-chained)
▼
api.anthropic.com
api.telegram.org
slack.com/api …
- Store: Credentials live in the vault backend you already run - no house vault (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, encrypted-file).
- Policy: Proxy checks method + path rules before touching credentials. Denied requests get a
403, never real auth headers. - Inject: Proxy looks up the credential and adds the auth header before forwarding. 26 builtin services, 4 injecting auth modes (header, URL-path, HTTP Basic, OAuth); a 5th,
none, is at-rest-only (proxy rejects traffic). - Broker (coder, Hermes secret source,
aquaman get):POST /broker/resolvematerializes a credential per tool call, scoped to a single command's env. Onlyaquaman daemonserves it, and only for refs you declared (projects.yamloraquaman broker allow). The OpenClaw plugin's proxy never serves it (v0.15.0+). - Audit: Every credential use is logged with SHA-256 hash chains.
On the proxy paths the agent sees a local endpoint plus a marker: the aquaman-proxy-managed placeholder, or the loopback token, which only works against your local proxy. Never a real key. On the coder path the child command gets the declared values and the agent sees redacted output.
Security Model
| Layer | What it does | What it stops |
|---|---|---|
| Process isolation | Credentials in a separate process, reached over a Unix socket (chmod 0o600) or a token-gated loopback listener |
Compromised agent can't read proxied keys: different address space |
| Broker scope | Only aquaman daemon hands out values, and only for refs you declared; OpenClaw-hosted proxies never do (v0.15.0+) |
An agent can't pull arbitrary vault entries through the socket |
| Service allowlisting | proxiedServices controls which APIs the agent can reach |
Agent can't talk to services you didn't authorize |
| Request policies | Method + path rules per service, enforced before credential injection | Agent can reach Anthropic but not its admin API; can draft emails but not send them |
| Audit trail | SHA-256 hash-chained logs of every credential use | Post-incident forensics, tamper detection, compliance evidence |
| Per-tool-call broker (coder) | aquaman-coder exec materializes creds for one command at a time |
Credentials don't sprawl across the agent's shell environment |
| Output redaction (coder) | aquaman-coder exec pipes stdout/stderr through a redactor that scrubs each value it just injected verbatim - plus generic provider patterns as a fallback |
Even arbitrary, shape-less credentials never reach the agent transcript |
Transports and access control
| Path | Transport | Access control |
|---|---|---|
| Coding agents, any client that can dial a socket | Unix socket ~/.aquaman/proxy.sock |
File permissions (0600): only processes running as you |
| Hermes (v0.13.0+), OpenClaw model and Telegram traffic (v0.15.0+) | Loopback TCP 127.0.0.1:<port> |
Per-install token, constant-time check, loopback bind |
Hermes and OpenClaw each build their own HTTP client and can't dial a socket, so they use the listener. Everything else uses the socket.
The token is a capability to reach the local proxy, not a credential. Generated per install, stored in ~/.aquaman/config.yaml (0600), sent by the host as its provider api key. The proxy checks it, strips it, injects your real key. Telegram has no auth header, so there the token rides in the /bot<TOKEN> path segment instead.
Trade-off: any local process can reach a loopback port, including other users, where the socket's 0600 shuts them out. The token is the gate there, so the listener stays off until aquaman hermes setup or aquaman openclaw setup turns it on.
Channel credentials on OpenClaw 2026.7.33+
| Channel | Egress through the proxy |
|---|---|
| Telegram | Yes, since v0.15.0 |
| Everything else | No. Vault storage and migration only |
Each channel builds its own HTTP client per request, so the plugin's fetch interceptor no longer sees channel traffic on these versions. Routing a channel needs an endpoint override from the host, and Telegram is the only one that has it: aquaman openclaw setup points channels.telegram.apiRoot at the proxy and replaces the bot token with the loopback token.
For the rest, your token stays in the vault but OpenClaw uses it directly, so the proxy is not in the path and those calls are not audited. aquaman openclaw doctor lists which of your configured channels are in which group. Model providers are unaffected.
What same-user isolation can't do. The socket's 0o600 keeps other users out, not other processes running as you. Such a process can send requests through the proxy while it runs (bounded by request policy, recorded in the audit log) and can fetch refs you declared, which is what declaring means. It cannot read the keys the proxy injects. For a harder boundary, run the agent as a different OS user or in a sandbox.
Detailed model - per-integration specifics (HTTP interceptor scope, auth profiles, scanner findings, ClawScan publisher note) - lives in packages/plugin/README.md and packages/coder/README.md.
Compliance posture
Aquaman ships runnable conformance tests under test/compliance/ mapped to:
- MITRE ATLAS v5.4.0: techniques AML.T0055, T0012, T0062, T0090, T0098 (
test/compliance/atlas/) - NIST SP 800-53 Rev 5: IA-5, AC-3, AC-6, AU-2/9/10, SC-12/28, SI-10 (
test/compliance/nist/)
Plus alignment narratives for CISA/Five-Eyes "Careful Adoption of Agentic AI Services" (April 2026), CSA MAESTRO, and OWASP Top 10 for Agentic Applications. The tests run as part of npm test. See docs/compliance/ for the mappings.
Request Policies
OAuth scopes can't distinguish between "draft an email" and "send an email". They're both gmail.send. Request policies fill that gap.
# ~/.aquaman/config.yaml
policy:
anthropic:
defaultAction: allow
rules:
- method: "*"
path: "/v1/organizations/**"
action: deny # block admin/billing API
openai:
defaultAction: allow
rules:
- method: "*"
path: "/v1/organization/**"
action: deny
- method: DELETE
path: "/v1/**"
action: deny # no deletions
slack:
defaultAction: allow
rules:
- method: "*"
path: "/api/admin.*"
action: deny # Slack Web API admin methods
gmail:
defaultAction: allow
rules:
- method: POST
path: "/gmail/v1/users/*/messages/send"
action: deny # drafts ok, sending blocked
- Paths are the upstream API's full path after the service prefix: Slack's Web API is
/api/<method>, Gmail's is/gmail/v1/.... Presets before v0.15.0 used/admin.*and/v1/users/*/messages/send, which never matched real traffic.aquaman doctorflags those if they're still in your config. - No policy = allow all (backward compatible)
- First match wins: rules evaluated top-to-bottom, unmatched requests fall through to
defaultAction - Denied before auth: blocked requests never get real credentials
- Path globs:
*matches within a segment,**matches zero or more segments aquaman setupapplies safe defaults for stored services (anthropic,openai,slack,gmail).aquaman policy list/aquaman policy test <svc> <method> <path>for inspection / dry-runs.
Credential Backends
Bring your own vault - aquaman has no house store. Pick the backend you already run; secrets stay there, and the proxy reads them in place.
| Backend | Best For | Setup |
|---|---|---|
keychain |
Local dev on macOS (default) | Works out of the box |
encrypted-file |
Linux, WSL2, CI/CD | AES-256-GCM, password-protected |
keepassxc |
Existing KeePass users | npm i -g kdbxweb argon2 (optional peers since v0.14.1), then set AQUAMAN_KEEPASS_PASSWORD or a key file |
1password |
Team credential sharing | brew install 1password-cli && op signin. For unattended agents use a service account (OP_SERVICE_ACCOUNT_TOKEN) |
vault |
Enterprise secrets management | Set VAULT_ADDR + VAULT_TOKEN |
systemd-creds |
Linux with systemd ≥ 256 | TPM2-backed, no root required |
bitwarden |
Bitwarden users | bw login && export BW_SESSION=$(bw unlock --raw) |
keeper |
Keeper password manager users (v0.16.0+) | pip install keepercommander, log in once with keeper shell and turn on this-device persistent-login on, create a folder for aquaman, then export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>. Records are titled aquaman::<service>::<key> |
aquaman setup auto-detects a sensible default (macOS → keychain; Linux → keychain if libsecret, else systemd-creds if systemd ≥ 256, else encrypted-file).
encrypted-file is a last-resort for headless Linux/CI environments without a native keyring. For better security on Linux, install libsecret-1-dev (GNOME Keyring), use systemd-creds (TPM2 binding), or use 1Password/Vault.
Credential caching (v0.13.1+)
Backends with a per-access cost, like 1password (a biometric prompt per read in desktop-app mode), bitwarden (~1-2 s CLI spawn), keeper (a Commander spawn that logs in and syncs) and vault (an HTTP round-trip), are cached in the daemon's memory for 15 minutes by default, so a busy agent session unlocks the vault once per window instead of once per request. The other backends are already fast or cache internally, so caching is off for them by default. Tune with credentials.cacheTtlSeconds in ~/.aquaman/config.yaml (or AQUAMAN_CACHE_TTL); 0 disables.
The honest trade-off: a per-access biometric prompt is a user-presence check, and the cache removes per-access presence for the TTL window. For unattended agents that prompt never gets answered, so the vault gets abandoned for a plaintext .env, which is strictly worse. The cache does not move the isolation boundary: values live only in the proxy process (where they already transit on every request), are never written to disk, and are invalidated immediately when you rotate through aquaman credentials add. Writes always go to your vault. Conformance-tested in test/compliance/cache-residency.test.ts. For zero prompts with 1Password, use a service account scoped to the aquaman vault; aquaman doctor will point you there.
How aquaman compares
Most agent hosts now protect credentials in some way, and tools such as 1Password op run, fnox, dotenvx, Doppler and Infisical cover similar ground. The difference that matters is whether a key is injected at egress, so the program never holds it, or into the program's environment. aquaman injects at egress for traffic through its proxy and into the environment for a coding agent's commands. Its place is the vault you already have, across several hosts, with setup and credential requests an agent can run itself and a tamper-evident record of each use. It is not a sandbox, it is not a boundary against other software running as you, and it is a young project with one maintainer.
The full table, when to pick something else, and the limits: aquaman compared with other approaches.
License
Apache-2.0. See LICENSE and NOTICE. Versions up to 0.17.2 were released under the MIT License.
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found