agent-proxy

agent-proxy is a Linux-first API gateway for installed and authenticated AI
command-line tools. It exposes familiar OpenAI and Anthropic HTTP endpoints
while routing requests to Claude Code, Codex, Google Antigravity, or Grok Build.

Project origin

This project is a focused refactor of
starhunt/star-cliproxy. The original
project supplied the initial provider, routing, dashboard, and compatibility
work. This fork narrows that foundation to a maintainable English-only Linux
server and credits the upstream project for that work.

Status

Status updated: 2026-07-26

Phase 3 is complete for the Codex-only production profile. The Responses
adapter, unmodified Codex live matrix, pinned Open WebUI matrix, and supported
topologies pass. Claude and Grok remain implemented and offline-tested, but
their live tests are explicitly waived and both providers are disabled because
this installation has no usable subscription login for them.

See SPEC.md for the product contract and
ROADMAP.md for implementation phases.

Built-in CLI backends

The server invokes these tools as child processes under its service account.
Provider credentials stay in the CLI-owned service-account state; agent-proxy
does not return or store provider tokens in its database. Each operator is
responsible for complying with the terms and usage limits of every configured
provider.

API surface

The server also retains optional generic CLI and OpenAI-compatible HTTP
adapters. They are extension points, not first-class backends.

The Responses subset supports text and image input items, instructions,
function tools, typed streaming events, cancellation, and bounded
previous_response_id continuation. Continuation is kept in memory, scoped to
the API key or X-Agent-Proxy-Session-Id, and expires according to the
responses configuration. See
docs/responses-api.md for the exact contract and
limitations.

Custom HTTP providers reject localhost, LAN, link-local, and other reserved
network targets by default. Enable allow_private_network only when connecting
to an operator-controlled local service such as Ollama. HTTP provider timeouts
must be between 1 and 600 seconds, and redirects are rejected.

Requirements

• Linux
• Node.js 24 or newer
• npm
• At least one supported CLI installed and authenticated for the service user
• A writable directory for SQLite data and logs

Quick start

npm ci
cp .env.example .env
cp config.example.yaml config.yaml

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
node -e "console.log('sk-proxy-' + require('crypto').randomBytes(24).toString('hex'))"

npm run build
npm start --workspace=packages/server

Put the first generated value in ADMIN_TOKEN and the second in
PROXY_API_KEY. The defaults bind to 127.0.0.1:8300.

For development:

./start.sh start
./start.sh status
./start.sh stop

The dashboard development server listens on 127.0.0.1:5300.

The dashboard's Provider Login page checks subscription authentication for
the service account and starts or refreshes the official Claude, Codex, and
Grok CLI login flows. It displays only verification URLs and one-time codes;
provider tokens and account identifiers are never returned by the admin API.
Desktop-user CLI sessions are separate from the hardened service account, so a
provider may need one service-account device login even when the desktop CLI
is already signed in.

Containers

The Dockerfile provides server and dashboard targets:

docker build --target server --tag agent-proxy-server .
docker build --target dashboard --tag agent-proxy-dashboard .

The server image binds to 0.0.0.0:8300 and accepts these deployment
overrides:

• AGENT_PROXY_HOST
• AGENT_PROXY_PORT
• AGENT_PROXY_DATABASE_PATH
• ADMIN_TOKEN

Mount an operator-owned config.yaml, persistent data directory, supported CLI
binaries, and the authenticated service-user state required by those CLIs.

Set AGENT_PROXY_UPSTREAM on the dashboard container to the server URL visible
from its container network. Its standalone-safe default is
http://127.0.0.1:8300.

See Open WebUI compatibility for the
pinned release, loopback-only native/Docker/Podman topologies, background-task
settings, and the live validation commands.

Client examples

Claude Code can use an Anthropic-compatible gateway:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8300
export ANTHROPIC_AUTH_TOKEN=sk-proxy-replace-me
claude

Codex can use a custom Responses provider in ~/.codex/config.toml:

model = "gpt-5.6-sol"
model_provider = "agent_proxy"

[model_providers.agent_proxy]
name = "agent-proxy"
base_url = "http://127.0.0.1:8300/v1"
env_key = "AGENT_PROXY_API_KEY"
wire_api = "responses"

export AGENT_PROXY_API_KEY=sk-proxy-replace-me
codex

Grok Build supports custom models in ~/.grok/config.toml:

[model.agent-proxy]
model = "grok-build"
base_url = "http://127.0.0.1:8300/v1"
name = "agent-proxy"
env_key = "AGENT_PROXY_API_KEY"

[models]
default = "agent-proxy"

These client examples define the intended compatibility target. The Responses
wire contract is covered by OpenAI SDK and provider-adapter tests. Native Codex
passes. Claude and Grok require their own live acceptance before either is
enabled in a future production profile.

Configuration

• config.yaml controls listeners, built-in providers, model mappings, rate
  limits, cache behavior, and validation limits.
• .env provides ADMIN_TOKEN and the initial PROXY_API_KEY.
• SQLite stores model mappings, keys, provider overrides, and request metadata.
• The dashboard can change supported runtime settings through /admin/*.

Never expose the API directly to the public internet without TLS, firewall
rules, strong tokens, and an upstream reverse proxy.

Validation

npm run typecheck
npm test
npm run build
bash -n start.sh

See CONTRIBUTING.md for the complete contributor workflow
and SECURITY.md for private vulnerability reporting.

Production systemd installation, upgrades, rollback, backup, restore, and
uninstall are documented in the
Linux service operations runbook.

References

• OpenAI Responses streaming reference
• Claude Code LLM gateway configuration
• Grok Build custom model configuration

License

This project is licensed under the MIT License; see LICENSE.
Upstream attribution and notice obligations must still be confirmed before the
stable release.