README
¶
Cloak
Hand your AI agent a fake credential; keep the real one out of its context.
The moment an agent holds a real DSN or API key, that secret is in its context
window, logs, and traces — the places nobody rotates secrets out of. Cloak is a
tiny local proxy: it hands the agent a fake credential pointing at
localhost and swaps in the real one on egress, over verified TLS, loaded from
your OS keychain. The agent never sees it.
Works today for PostgreSQL and HTTP APIs (OpenAI, Anthropic, and anything taking a bearer token or API-key header).
Install
macOS (Homebrew):
brew install hoophq/tap/cloak
macOS / Linux (script):
curl -fsSL https://raw.githubusercontent.com/hoophq/cloak/main/install.sh | sh
Signed binaries on releases; or
go install github.com/hoophq/cloak@latest (Go 1.26+).
Setup — point cloak at your .env
$ cloak import .env
→ DATABASE_URL (line 1): upstream "database-url" on 127.0.0.1:5433, credential moves to the OS keychain
→ OPENAI_API_KEY (line 2): upstream "openai-api-key" on 127.0.0.1:5434, credential moves to the OS keychain
Rewrite .env? [y/N] y
✓ imported 2 credential(s); .env rewritten (original backed up)
The real secrets move to your keychain; the .env is rewritten to fakes — a
loopback DSN and a cloak-… key that only resolve through cloak. It recognizes
Postgres DSNs and common LLM providers (OpenAI, Anthropic) on sight. Undo with
cloak import --undo .env.
Need something import doesn't recognize (a custom host, an odd env name)? Register it by hand — same keychain, same fakes:
$ cloak add openai --type http --host api.openai.com --auth bearer \
--env OPENAI_API_KEY --env-url OPENAI_BASE_URL
Use it — set up once, then forget it
Agents (Claude Code)
$ cloak init # wire cloak into Claude Code, once
$ claude # a 🔒 banner confirms it's on
Ask the agent to print $OPENAI_API_KEY and it sees cloak-…, never your real
key — while its requests still reach OpenAI with the real one swapped in.
Your own application
$ cloak start # run cloak as a background service, once
$ python app.py # run your app normally — no prefix, no wrapper
Your app loads the rewritten .env and talks to localhost; cloak swaps in the
real credentials on the way out. cloak status shows what's live, cloak stop
tears it down. Just need a one-off? cloak run -- python app.py serves a single
command, then exits.
Add a credential later and cloak resyncs itself — the running daemon and Claude
Code both pick it up, no cloak init re-run needed.
LangChain or another framework? It delegates to the same SDKs — see the integration guide.
What it protects — and what it doesn't
Cloak keeps the real credential out of the agent's context, logs, and traces; a leaked fake is worthless off-box and dies with the session. It does not stop a prompt-injected agent from misusing the live access while the proxy runs — it protects the credential, not the access. Pair it with your agent's sandboxing. The threat model is honest about the limits.
Docs
- Integration guide — Claude Code, MCP servers, agentic backends, CI.
- Threat model — what it protects, what it doesn't, and why.
- FAQ — why not env vars or a secrets manager.
Other commands: cloak list, cloak rm <name>, cloak status · cloak --help.
Development
make build # build the binary
make test # unit tests
make e2e # full broker path against real PostgreSQL (Docker)
License
MIT
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package cmd implements the cloak CLI.
|
Package cmd implements the cloak CLI. |
|
internal
|
|
|
claudecfg
Package claudecfg installs and removes cloak's entries in a Claude Code settings.json — an `env` block that hands the agent fake credentials and SessionStart/SessionEnd hooks that drive the proxy — without disturbing any other setting the user has.
|
Package claudecfg installs and removes cloak's entries in a Claude Code settings.json — an `env` block that hands the agent fake credentials and SessionStart/SessionEnd hooks that drive the proxy — without disturbing any other setting the user has. |
|
config
Package config holds the on-disk registry of upstreams.
|
Package config holds the on-disk registry of upstreams. |
|
connector
Package connector defines the interface protocol connectors implement.
|
Package connector defines the interface protocol connectors implement. |
|
connector/httpapi
Package httpapi brokers HTTP APIs: the agent calls a loopback base URL with a fake per-session key, and the real credential is injected into the configured header on the way out over verified TLS.
|
Package httpapi brokers HTTP APIs: the agent calls a loopback base URL with a fake per-session key, and the real credential is injected into the configured header on the way out over verified TLS. |
|
connector/postgres
Package postgres brokers PostgreSQL connections: it accepts the fake session credential from the agent, authenticates upstream with the real one, then splices bytes transparently for the rest of the session.
|
Package postgres brokers PostgreSQL connections: it accepts the fake session credential from the agent, authenticates upstream with the real one, then splices bytes transparently for the rest of the session. |
|
envimport
Package envimport scans .env files for credential-shaped values, imports the ones cloak can proxy, and rewrites the file so nothing sensitive is left for an agent to read.
|
Package envimport scans .env files for credential-shaped values, imports the ones cloak can proxy, and rewrites the file so nothing sensitive is left for an agent to read. |
|
native
Package native backs cloak's wrapper-free Claude Code integration: a stable per-machine fake token, a session-scoped background proxy (the daemon), and the session bookkeeping that starts it when a Claude session opens and stops it when the last one closes.
|
Package native backs cloak's wrapper-free Claude Code integration: a stable per-machine fake token, a session-scoped background proxy (the daemon), and the session bookkeeping that starts it when a Claude session opens and stops it when the last one closes. |
|
pgwire
Package pgwire is a minimal codec for the PostgreSQL v3 wire protocol — just the subset needed to broker a connection handshake.
|
Package pgwire is a minimal codec for the PostgreSQL v3 wire protocol — just the subset needed to broker a connection handshake. |
|
proxy
Package proxy binds the local listeners and dispatches accepted connections to protocol connectors.
|
Package proxy binds the local listeners and dispatches accepted connections to protocol connectors. |
|
secret
Package secret stores real credentials.
|
Package secret stores real credentials. |
|
token
Package token generates the fake per-session credentials handed to agents.
|
Package token generates the fake per-session credentials handed to agents. |