proxyagent 0.3.0

Run any agent (Claude, Codex, custom) on any machine — with no API key on the machine. A secure, self-hosted proxy for models and tools.

proxyagent

Run any agent — Claude, Codex, custom — on any machine, with no API key on the machine.

A secure, self-hosted proxy for models and tools. Your keys live in one hardened place; every machine holds only a scoped, revocable token.

---

Agents need model access (and tool access) to do anything. Today that means scattering real API keys across every machine an agent runs on — a security nightmare. proxyagent fixes it: stand up one proxy that holds the real credentials, and point every agent at it. The machine gets a throwaway token; the real key never leaves the proxy.

   remote machine                     proxy (you host)            upstream
 ┌────────────────┐  token only   ┌──────────────────┐  real key  ┌───────────┐
 │ claude / codex │ ───────────►  │  proxyagent serve │ ─────────► │ Anthropic │
 │  (no real key) │ ◄───────────  │  scope·log·tools  │ ◄───────── │  OpenAI   │
 └────────────────┘   stream      └──────────────────┘            └───────────┘

How it works

Every harness honours *_BASE_URL, so the shim is trivial: point the base URL at the proxy and use the machine token as the "api key." The proxy authenticates the token, checks its scope, swaps in the real key, forwards upstream, and logs the call. The machine never sees a real credential.

Try it with zero keys (local)

pip install proxyagent && proxyagent serve        # prints an admin token
proxyagent token new local --admin pa_admin_…     # mint a token
# call the built-in `mock` model — full pipeline (auth, scope, usage, cost, log), no real key:
curl -s localhost:8080/anthropic/v1/messages -H "x-api-key: pa_…" \
  -d '{"model":"mock","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'

Quickstart

1. Run the proxy (on a box you control — it holds the real keys):

pip install proxyagent
export ANTHROPIC_API_KEY=sk-ant-…      # and/or OPENAI_API_KEY=sk-…
proxyagent serve                        # prints an admin token + a dashboard at :8080

2. Mint a machine token (scoped + revocable):

proxyagent token new macbook-01 --scope "anthropic:claude-*" --admin pa_admin_…

3. Run any agent on any machine — no real key there:

PROXYAGENT_TOKEN=pa_… proxyagent run claude-code \
  --goal "build a SwiftUI todo app" --proxy https://proxy.you.com
# or:  proxyagent run codex --goal "fix the failing tests" --token pa_…

Or use any harness directly — just set the env and the proxy does the rest:

export ANTHROPIC_BASE_URL=https://proxy.you.com/anthropic
export ANTHROPIC_API_KEY=pa_…          # the machine token, not the real key
claude -p "ship it"

The dashboard

proxyagent serve ships a dashboard at / — mint/revoke tokens, watch live usage and a full request audit log, see configured providers + proxied tools. Paste the admin token to open it.

Proxied tools — the same trick, for tools

The proxy can also hold your tool keys and hand agents governed tools — so an agent gets web search (and custom tools) without ever holding the tool's credential.

export TAVILY_API_KEY=tvly-…                                   # web_search uses this; agents never see it
export PROXYAGENT_TOOLS='[{"name":"crm","url":"https://hooks.you.com/crm","headers":{"Authorization":"Bearer …"}}]'
# then send requests with header  x-proxyagent-tools: on  → tool defs are injected;
# the proxy executes calls to managed tools server-side (keys stay here).

Credentials, storage & cost

By default provider keys come from the environment and stay local. Or add them once and they're stored encrypted (proxy_agent_keys) — locally in SQLite, or in Postgres if you point at one. Either way the machine never sees them.

export PROXYAGENT_SECRET_KEY=…                 # enables at-rest encryption (Fernet)
proxyagent provider add anthropic --key sk-ant-…          # stored, encrypted
proxyagent provider add openai --key sk-…  --kind api_key
# OAuth: store an access token →  proxyagent provider add anthropic --key <oauth-token> --kind oauth
proxyagent provider ls

# Postgres-backed (shared, multi-instance): tables proxy_agent_keys / _tokens / _calls
export PROXYAGENT_DATABASE_URL=postgresql://user:pass@host/db    # pip install 'proxyagent[postgres]'

Every call is traced in proxy_agent_calls with token usage, latency, and computed cost (per-model pricing, override via PROXYAGENT_PRICING). See it live:

proxyagent usage          # totals: requests · tokens · $ cost
proxyagent logs           # per-request trace incl. cost

Security model

• Real keys never leave the proxy — read from env, never persisted, never logged, never returned.
• Machine tokens are stored hashed (SHA-256); plaintext shown once. A stolen DB yields nothing usable.
• Scoped (provider:model globs), expiring (TTL), revocable, rate-limited.
• Constant-time token comparison; sensitive headers redacted from logs.
• Admin API + dashboard gated by a separate admin token. Run it behind TLS.

SDK

import proxyagent

# host the proxy (embed in your own service):
app = proxyagent.create_app()              # ASGI app

# mint tokens programmatically:
admin = proxyagent.Admin("https://proxy.you.com", "pa_admin_…")
token = admin.mint("ci-runner", scope=["anthropic:claude-*"], ttl_seconds=3600)

# run a harness on this machine, no key here:
proxyagent.run("claude-code", goal="build the app",
               proxy="https://proxy.you.com", token=token)

Supported providers

anthropic · openai · gemini · groq · openrouter · mistral · deepseek · xai · together — Anthropic uses its Messages API; the rest are OpenAI-compatible. Point a harness/agent at https://proxy.you.com/<provider>/v1 and it routes there. Add or override any endpoint with PROXYAGENT_<NAME>_ENDPOINT.

Model remap — rename or reroute models

Rewrite the requested model before forwarding — rename it, or reroute it to a totally different provider:

proxyagent alias set gpt-4o anthropic:claude-sonnet-4-5   # send "gpt-4o" calls to Claude
proxyagent alias set '*' mock                             # force EVERYTHING offline (no keys)
proxyagent alias ls

The '*' → mock trick is the offline harness unlock: point claude-code at the proxy, map everything to mock, and it runs end-to-end with zero keys and zero spend — perfect for local dev, demos, and CI.

Supported harnesses

claude-code, codex, and any custom command (--command "my-agent {goal}"). Adding one is a few lines — it just needs to respect *_BASE_URL.

License

Apache-2.0