AgentProxy docs — install, quickstart & configuration

Getting started

Install

All paths share one set of GoReleaser-built release artifacts (per-platform archives + a checksums.txt). Each install path verifies the SHA256 before installing — no Go toolchain required. Source, releases and issues live on GitHub (open source); you can also go install github.com/deemwar-products/agentproxy/cmd/agentproxy@latest.

brew install deemwar-products/agent-proxy/agentproxy

Homebrew. The formula installs the same signed release archive as every other path.

Or with npm, on any of the three:

npm install -g @deemwario/agent-proxy

The installer places the binary and agent wrapper commands (claudeproxy, codexproxy, copilotproxy, opencodeproxy, devinproxy) on your PATH. To remove everything: ./uninstall.sh (macOS/Linux) or uninstall.bat (Windows).

Getting started

Quickstart

From an installed binary to a routed agent run. Everything here happens locally — AgentProxy is free and open source, with no account and no license key.

Bring up the proxy and trust its local CA

agentproxy setup --open

Idempotent — re-running prints "already trusted ✓". Starts the proxy (:7717) and opens the dashboard (:7718).

Point an agent at the proxy

agentproxy run claude 'summarise this codebase'

agentproxy run codex 'fix the failing test'

agentproxy run -- npm test

Dedicated wrappers (claudeproxy, codexproxy, copilotproxy, opencodeproxy, devinproxy) also work, or enable transparent mode (agentproxy shell enable) so plain claude/codex route through the proxy in every new shell with no wrapper at all. Each agent's own CLI must already be installed and authenticated — AgentProxy routes it, it doesn't install it.

Next: agentproxy dashboard serves a live cost and masking view on 127.0.0.1:7718. Nothing is uploaded.

Reference

Configuration

AgentProxy reads a YAML config (default ./config/agentproxy.yaml, or ~/.agentproxy/agentproxy.yaml for an installed binary). Keys you'll actually touch:

Key	What it controls
proxy.host / proxy.port	Listen address for the MITM proxy (default `127.0.0.1:7717`)
detection.intercepted_domains	Which upstream hosts get MITM'd and scanned; everything else passes through untouched
detection.pattern_file	Secret-detection regex patterns (API keys, JWTs, connection strings, etc.)
pii.enabled	Optional PII scanning (email, phone, SSN, credit card, IP) — off by default
logging.log_originals	Debug-only; originals are never persisted to disk by default
upstream_proxy.*	Corporate upstream proxy (auto-detected from `HTTP_PROXY`/`HTTPS_PROXY`, or a PAC file)
budgets.file	Opt-in spend budgets — soft alerts by default, or hard-enforced (429) per limit
governance.allowed_models / risky_patterns	Warn-only policy guardrails surfaced in the dashboard and `logs/governance.jsonl`
looper.enabled	Same-provider "easy/hard" model routing to cut cost — never crosses providers

Secrets referenced from your own config (e.g. ${OPENAI_API_KEY}) are read from your shell environment at runtime — never written to the config file itself. Inspect what's active any time: agentproxy config.

Reference

Providers & masking

Out of the box, these upstream hosts are intercepted and scanned (add more under detection.intercepted_domains):

api.anthropic.com — Claude
api.openai.com, chatgpt.com — OpenAI / Codex
api.githubcopilot.com and related hosts — GitHub Copilot
opencode.ai, openrouter.ai — opencode
api.devin.ai, server.codeium.com — Devin

Masking is body-shape-agnostic — it scans any JSON/text body regardless of the agent's wire format — and is SSE- and WebSocket-delta-aware, so a secret split across streamed chunks or frames is still masked and correctly restored end-to-end.

Running it

Dashboard

A local dashboard runs alongside the proxy at http://127.0.0.1:7718, backed entirely by an in-memory event store (TTL ring, default 10 minutes) — nothing sensitive is written to disk. Open it with:

agentproxy dashboard

It shows live request/response traffic per session, token counts, model, and cost — and, when looper or governance are configured, routing decisions and policy flags too.

Answers

FAQ

What does it cost?: Nothing. AgentProxy is free and open source — every feature, no account, no license key, no trial clock. If you need deployment help, an SLA or custom masking patterns, talk to us about enterprise support.
Does anything leave my machine?: No. The proxy runs on your machines and talks only to your agents’ own providers. Prompts, API keys and traffic stay local; there is no telemetry and nothing phones home.
Do I need to sign up for anything?: No. Install it, run agentproxy setup, and point your agent at it.

Answers

Troubleshooting

HTTPS requests aren't being masked: The proxy can't decrypt HTTPS until its CA is trusted. Run agentproxy ca-setup (prints manual trust steps) or task ca-setup for OS-store trust.
A tool I run isn't being routed: Wrappers/agentproxy run scope HTTP_PROXY/HTTPS_PROXY to that process only. Use agentproxy shell enable for every new shell instead, or check detection.intercepted_domains includes the host you expect.
Copilot CLI isn't found: copilotproxy requires the standalone Copilot CLI or gh extension install github/gh-copilot — it's not bundled with gh. The wrapper prints the exact install command if it's missing.
I want to remove transparent mode: Run agentproxy shell disable — it restores your shell profile byte-for-byte.
Full uninstall: ./uninstall.sh (or --keep-trust to leave OS CA trust in place) — uninstall.bat on Windows.

← Back to agentproxy.deemwar.com