AIProxy

Security proxy for AI agents. AIProxy intercepts HTTP and HTTPS traffic, applies blacklist and whitelist rules, and holds unknown requests until an admin adds a matching rule or the request times out. It runs as a foreground server or wraps a command with proxy and CA settings.

Build

Requires Go 1.26 or later. From the repository root:

make build
./aiproxy --version

The build uses the pinned templ generator and embeds the WebUI assets. There is one release binary; it has no hidden test switches. Dependency versions are in go.mod.

Quick Start: Wrap a Command

This example needs curl and internet access. Create a rule for the destination before sending the request; an empty whitelist does not mean allow-all.

mkdir -p certs rules data
printf '%s\n' '[{"id":"allow-github-api","scheme":"https","host":"api.github.com"}]' \
  > rules/whitelist.json
./aiproxy -- curl --fail --silent --show-error https://api.github.com/

The proxy generates its CA files in certs/ if both are missing. The wrapper sets proxy URLs and absolute CA paths for the child command. It stops when the command exits and returns that command's exit code.

Unknown requests wait for --pending-timeout (default 120s) and then get HTTP 403. --pending-timeout 0 rejects them immediately; it never enables pass-through.

Run with the WebUI

After creating the directories above:

# Set an admin password in your environment before starting the server.
export AIPROXY_ADMIN_SECRET='replace-with-a-strong-secret'
./aiproxy --listen 127.0.0.1:8881 --webui-listen 127.0.0.1:8882

Open http://127.0.0.1:8882/. The dashboard and CA download are public; login is required for pending requests and rules. The admin can add a rule while a request waits, and matching requests are resolved immediately.

In another terminal, agents can use the proxy explicitly:

curl --proxy http://127.0.0.1:8881 --cacert certs/ca-cert.pem https://api.github.com/

Runtime rules are saved in data/. If that directory is missing, a WebUI rule change still takes effect in memory, but saving fails and only an error is logged. Create it before starting. See the WebUI guide and approval runbook.

Current Capabilities and Limits

• TLS interception for CONNECT on any port, including plain HTTP inside CONNECT.
• Loopback target blocking before blacklist, whitelist, and pending handling.
• JSON rule objects with glob host/path matching and priority ordering.
• Global interval-based rate limiting; rule rpm fields are not enforced yet.
• In-memory pending queue with deduplication, timeout, and rule re-evaluation.
• WebUI dashboard, single-session login, pending viewer, rule editing, and CA download.
• Runtime rule persistence and rotating application logs.

There is no pending history, persistent per-rule statistics, dedicated access log, rate-limit viewer, log viewer, or Containerfile yet. Open work and unresolved choices are in TODO.md.

The proxy is intended for a small, single-machine deployment with network isolation and a trusted admin. It has no proxy client authentication. Do not expose the WebUI to the public internet: its HTTP session cookie does not set Secure. Loopback blocking is not comprehensive private-network or DNS-rebinding protection. There is no signal-driven shutdown handler or pending queue size limit.

Tests

make unit-tests
make integration-tests
make binary-tests

Default tests need no internet and no Docker. Binary runbooks need bash, curl, and coreutils; some require OpenSSL, and HTTPS fakenet scenarios require Linux. See TESTING.md for placement rules and opt-in internet tests.

Documentation

• Configuration: flags, environment, files, wrapper behavior.
• Rules: schema, matching, precedence, and examples.
• WebUI: admin workflow, authentication, and endpoints.
• Executable runbooks: admin scenarios and authoring guide.
• Development practices and constraints.
• Agent guide and Lode map: project knowledge.