Portunus

Portunus

A secret broker that finds secrets by metadata and injects them — without them ever touching your LLM. Free & open source.

Built by Mathew Dostal — fractional CTO, Dostal Technology.

Choose your vault. Give your AI agents safe tooling to use it — without secrets ever touching

the LLM.

portunus is a thin broker between your AI agents and the secret vault you already run. It doesn't store your secrets or reinvent vault security — it resolves them by metadata and injects them at the boundary, so an agent can use a secret (call an API, deploy, sign) without the raw value ever landing in the model's context, logs, or tool output.

*(Portunus — the Roman god of keys and doors. Fitting.)*

Get your agent using it in one command

curl -fsSL https://mdostal.github.io/portunus/install.sh | bash

Installs the CLI, wires the MCP server into whatever AI coding agent CLIs are already on the machine (Claude Code, Codex CLI today), and drops in the usage skills — so an agent gets the *boundary-only* usage conventions immediately, not just a raw tool list. Already have portunus installed? Just run portunus agent init — same thing, idempotent, safe to re-run any time (e.g. after installing a new harness). portunus agent status shows what's currently wired without changing anything.

Since this runs standalone often — a local key-value store on its own, not just a plugin — it keeps itself current too: portunus update check (read-only) / portunus update run (installs, with either an interactive confirm or --yes) walk the same "your own already-authenticated gh CLI, pinned to an exact release tag, never a silent unattended swap" posture as the desktop app's updater. A one-line stderr heads-up ("portunus vX.Y.Z is available…") shows up on its own, throttled to once a day, never installs anything by itself — opt out any time with PORTUNUS_NO_UPDATE_CHECK=1.

[portunus site →](https://mdostal.github.io/portunus/) — landing page, install snippets, and the component-model pitch in one place.

[Documentation →](https://mdostal.github.io/portunus/docs/) — quickstart, concepts, architecture, CLI/MCP reference, and Process & Design, the design record behind every feature, published from .pHive/ and rebuilt on every push to main.

The problem

AI agents need real secrets to do real work — deploy tokens, API keys, DB creds. But the moment a secret touches an LLM's context, a log line, or a tool result, it's leaked. Most teams already have a vault. What's missing is the layer that lets an agent use that vault safely.

That's portunus.

What works today

• The secret value never enters the LLM's context, logs, or tool output. Enforced by code — every boundary path (the resolver's three sinks, every MCP tool, every adapter's failure path) is covered by a test that asserts the value never appears in a return value, stdout/stderr, or the audit log, including on the failure path, not just the happy one.
• Resolve by metadata. Ask for anthropic / demo / prod by what it *is*, not by memorizing a key name. Fail-closed — an ambiguous match refuses and lists candidates, never returns the wrong secret.
• Inject at the boundary — env var, file (env/json/yaml), subprocess argv, or a 0600 tempfile. The agent gets a *reference* or a *path*, never the value.
• Bring your own vault — GCP Secret Manager (keyless, via Workload Identity Federation), a local-encrypted vault (Fernet: AES-128-CBC + HMAC-SHA256, zero cloud setup), and Chrome's own saved logins (macOS Keychain / Linux Secret Service-KWallet, read-only — see docs/backends.md) work today.
• One core, three doors — an MCP server (21 tools, metadata-only by default), a 35-command CLI, and a Next.js UI (plus a native macOS desktop shell around the UI).
• Tamper-evident, hash-chained audit log — keyed by secret *name*, never value. portunus verify proves the chain.
• Per-agent access control, opt-in. portunus roles set --principal scopes a policy to a specific identity (org/project/env/repo); portunus roles enforce on activates it. A scope with no configured policy always stays fully open — enforcement only ever narrows what a *specific* principal can reach, never a surprise lockout. See "Access control (Petitio)" below.

Roadmap (help wanted)

• More vault backends — HashiCorp Vault, AWS, Azure, 1Password, Doppler, Infisical *(fail-closed stubs today — request the one you need and it jumps the queue)*
• Native HTTP-client injection adapter *(today it's portunus resolve --exec curl ..., or a caller-supplied boundary callable via the library's resolve_call — works, but there's no built-in HttpHeaderAdapter/HttpBodyAdapter class yet, only EnvVarAdapter/FileAdapter)*
• More secret-rotation adapters *(eight real adapters ship today, all run via portunus rotation run: OAuth refresh tokens, GCP service-account keys, Google Cloud API keys, Resend API keys, Grafana Cloud access policy tokens, YouTrack/Hub permanent tokens, Vercel access tokens, and GitHub OAuth App tokens from an App you own. GitHub PATs are manual because GitHub has no reissue API. Stripe is still a stub that raises. portunus liveness check flags dead GitHub tokens. See docs/rotation.md for the per-subtype capability matrix)*
• Scope-aware list/tree — these two MCP tools still return full-vault metadata regardless of the caller's own access scope; only the actual resolve/inject path is gated today *(a real, named gap — not started; portunus-petitio-rbac design-discussion.md's self-grill)*
• Approval tokens (portunus approve) are scoped to a reference name only, not to the identity that requested it — a different concurrently-running agent can walk through the same approval window *(also a real, named gap, same source)*

Honest scope

Portunus guarantees that its own paths never leak the value. It can't stop a command *you* wrap from echoing its own argument — echo {{secret}} will print the secret, because that's the command's doing, not portunus's. That's the correct, defensible boundary, and it's documented in the code.

Built in the open

Solo-built and moving fast. The core is real and tested; the backends and rotation are where the growth is. Break it, tell me where it leaks, open issues, send PRs — poking a hole in the security model is a *gift*, open it as an issue.

Quick start

curl -fsSL https://mdostal.github.io/portunus/install.sh | bash   # or: pip install -e ".[test]" from a clone

store a secret -- stdin/file only, never an inline flag (would land in shell history)

echo -n "sk-ant-..." | portunus drop shared-anthropic dostal-shared-anthropic --stdin portunus state shared-anthropic enabled # lands dropped/fail-closed by default; this makes it injectable

resolve it only at the boundary -- the value never touches your shell history, a log, or an LLM turn

portunus resolve --exec curl -H "Authorization: Bearer {{secret:shared-anthropic}}" \ https://api.anthropic.com/v1/messages

See Install and Usage below for the full picture — registering an existing secret instead of dropping a new one, tag-based lookup, the MCP server, and the UI.

Architecture, vision & design decisions

• [docs/architecture.md](docs/architecture.md) — the adopter-facing reference: a component diagram, ARCA's backend-selection precedence as a decision tree, Petitio today-vs-the-designed- future, the full request/resolve sequence, and the rotation-provenance design — five diagrams, kept honest about what's real versus what's a stub.
• Long-term direction (from this project's own planning doc, .pHive/project-profile.yaml):

Portunus is a standalone, releasable, containable secret finder/manager — not just a

Dostal-harness plugin. [...] GCP Secret Manager is the store; Portunus is the

resolver+injector layer on top — that split is decided, not open. Long-term it should also

self-declare as an L2 Pantheon plugin [...] while still standing up its own harness

integration (skill/CLI) and UI when run standalone.

• Every design decision, with the reasoning, not just the outcome — .pHive/epics/ holds a research brief + design discussion (often with an adversarial "grill" pass) for every feature this project has shipped: why local+GCP are the only real ARCA backends today, why rotation first shipped as provenance-only, why the desktop app shells out to gh instead of embedding a token, and more. This is the actual paper trail, not a curated highlight reel.
• [CHANGELOG.md](CHANGELOG.md) — what shipped, release by release.
• Adapter pattern — a new ARCA backend implements one method (access(sm_name, project="") -> str, see SecretBackend in backend.py) and fails closed with a clear error until it's real; request one or see an existing stub (e.g. InfisicalBackend) as a template.

Component model

Portunus is the whole secret-broker system, not any single piece of it. Its components carry their own (Latin, theme-consistent) names:

| Petitio | The approval-gate wrapper — wraps every OSTIARIUS request so access is always gated (grant / gate / approve + lifecycle guard). Per-agent access control is real and opt-in: every call threads an Identity (requester) through check_injectable(), which evaluates it against roles.py's PolicyRecords (org/project/env/repo scope + principal) via roles.evaluate() — every resolve gets a would-allow/would-deny audit line regardless, but only actually *raises* NotAuthorized when portunus roles enforce on has been explicitly run for that vault (default: off; a scope with zero configured policies a