Agent Wire Proxy

A lightweight compatibility proxy that lets OpenAI Responses, OpenAI Chat Completions, and Anthropic Messages clients share Qwen/vLLM backends.

[!IMPORTANT] Agent Wire Proxy is an alpha-stage compatibility layer. Review the compatibility contract before relying on it in a production path, and put authentication and TLS in front of non-localhost deployments.

It is useful when:

• Codex expects /v1/responses, but a backend only exposes Chat Completions.
• Claude Code needs an Anthropic Messages-compatible gateway.
• several model IDs must route through one local proxy port.
• streaming text, tool calls, usage, and timing must survive protocol conversion.

Requirements

• Python 3.11+
• one or more OpenAI-compatible model backends
• Codex or Claude Code only when using the optional TUI launcher

Install

Install the published package from PyPI:

python3 -m pip install agent-wire-proxy

Or install from a repository checkout for development:

python3 -m venv .venv
.venv/bin/python -m pip install -e .

For development:

.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest
.venv/bin/python -m ruff check .

Configure models

Routes live in config/models.toml:

[proxy]
default_model = "Qwen3.5-397B-FP8"

[[models]]
id = "Qwen3.5-397B-FP8"
target = "http://127.0.0.1:8000"
upstream_api = "responses"
aliases = ["claude-qwen3-5-397b"]

[[models]]
id = "qwen3.5-122b-a10b"
target = "http://127.0.0.1:8001"
upstream_api = "chat_completions"
aliases = ["claude-qwen3-5-122b"]

For machine-specific routes, copy it to the Git-ignored config/models.local.toml; the helper scripts prefer that file when it exists.

Use api_key_env = "UPSTREAM_API_KEY" for an authenticated upstream. Put the value in an ignored .env file:

cp .env.example .env

Run the proxy

The lifecycle helper runs the proxy in the background on http://127.0.0.1:18009:

scripts/agent_wire_proxy.command start
scripts/agent_wire_proxy.command status
scripts/agent_wire_proxy.command restart
scripts/agent_wire_proxy.command stop

It reads config/models.toml and .env, and writes runtime files under logs/. Override LISTEN, CONFIG, ENV_FILE, LOG_PATH, PID_PATH, or STDOUT_PATH when needed.

You can also run the installed CLI in the foreground:

agent-wire-proxy \
  --listen 127.0.0.1:18009 \
  --config config/models.toml \
  --env-file .env

The installed package also exposes a reentrant API. Each returned server owns its routing state, so multiple differently configured proxies can run in the same process:

from agent_wire_proxy import serve

proxy = serve(
    config="config/models.toml",
    listen=("127.0.0.1", 0),
    block=False,
)
print(proxy.server_port)

# Later:
proxy.shutdown()
proxy.server_close()

Check health and model discovery:

curl -fsS http://127.0.0.1:18009/health
curl -fsS http://127.0.0.1:18009/v1/models

Launch Codex or Claude Code

Choose an agent and configured model interactively:

agent-wire-tui

Or select them directly:

# Codex + Qwen 397B
agent-wire-tui --agent codex --model Qwen3.5-397B-FP8

# Claude Code + Qwen 397B
agent-wire-tui --agent claude --model claude-qwen3-5-397b

The launcher injects temporary client settings. It does not modify the user's Codex configuration. It is also available as launch(agent="codex", model="Qwen3.5-397B-FP8") from Python. Run agent-wire-tui --help for all options. The legacy scripts/agent_wire_tui.command wrapper uses the installed CLI when available and otherwise runs from the source checkout.

Unless --config is supplied, the launcher checks AGENT_WIRE_PROXY_CONFIG, then config/models.local.toml and config/models.toml under the current directory, then $XDG_CONFIG_HOME/agent-wire-proxy/models.toml (or the equivalent under ~/.config), and finally the packaged default configuration.

Supported endpoints

The proxy supports streaming text, reasoning, and tool-call conversion between these protocols. It can also write content-free benchmark route receipts; see docs/cli.md for configuration and operational details.

The APIs are not a symmetric provider gateway: upstreams must expose OpenAI Responses or Chat Completions. See docs/compatibility.md for the supported matrix, behavior classes, and repair contract.

For opt-in endpoint checks and LiteLLM comparisons, see docs/compatibility-testing.md.

Security

• Client authentication is optional. Set AGENT_WIRE_PROXY_CLIENT_API_KEY and still prefer a localhost binding or authenticated TLS reverse proxy.
• Keep upstream credentials in environment variables or an ignored .env.
• Request and response content is omitted from logs by default. Treat logs produced with --log-content as sensitive.
• Configure NO_PROXY/no_proxy yourself when an upstream must bypass an HTTP proxy.

License

MIT