CLI Reference#

Complete reference for the acp-proxy command.

#Usage

acp-proxy [options] <agent-command> [-- <agent-args>]

Arguments:

• <agent-command> - The ACP agent executable to run
• [agent-args] - Arguments passed to the agent (after --)

#Options

#Environment Variables

#ACP_AUTH_TOKEN

Set a custom authentication token instead of auto-generating one:

export ACP_AUTH_TOKEN="my-secret-token"
acp-proxy --host 0.0.0.0 claude-code-acp

When not set, a random token is generated and printed to the console.

#Agent Environment

The proxy inherits and passes through all environment variables to the agent. Set API keys before starting:

# For Claude Code
export ANTHROPIC_API_KEY="sk-ant-..."

# For OpenAI Codex
export OPENAI_API_KEY="sk-..."

# For Gemini CLI
export GOOGLE_API_KEY="..."

acp-proxy --no-auth claude-code-acp

#Examples

#Basic Local Usage

acp-proxy --no-auth claude-code-acp

Output:

  ACP Proxy Server

  Open in browser:
    Local:   http://localhost:9315/app

  Agent: claude-code-acp
  CWD:   /home/user/project

  Press Ctrl+C to stop

#Custom Port

acp-proxy --port 8080 --no-auth claude-code-acp

#Network Access with HTTPS

acp-proxy --https --host 0.0.0.0 claude-code-acp

Output includes:

• URLs with embedded auth token
• QR code for mobile connection

#Server Deployment with Public URL

When deploying behind a reverse proxy with a domain name:

acp-proxy --host 0.0.0.0 --public-url wss://example.com/ws claude-code-acp

The --public-url overrides the QR code URL, so mobile devices can connect via your domain instead of the local IP.

#Agent with Arguments

Use -- to separate proxy options from agent arguments:

# Gemini CLI with experimental ACP flag
acp-proxy --no-auth gemini -- --experimental-acp

# Qwen Code with ACP mode
acp-proxy --no-auth qwen -- --acp

#Debug Mode

acp-proxy --debug --no-auth claude-code-acp

Debug logs are written to .acp-proxy/ in the current working directory:

• Format: .acp-proxy/acp-proxy-YYYY-MM-DD_HH-MM-SS.log
• Example: .acp-proxy/acp-proxy-2026-02-16_14-30-45.log

#HTTPS Configuration

When --https is enabled:

1. Self-signed certificate is generated automatically
2. Certificate is stored in ~/.acp-proxy/ (persisted and reused)
3. Browser will show a security warning - this is expected

#Why HTTPS?

Required for:

• Camera access on mobile (for QR scanning)
• Service Worker registration on non-localhost origins
• Secure WebSocket (wss://) connections

#Termux Mode

The --termux flag is designed for running on Android:

acp-proxy --termux claude-code-acp

Behavior:

1. Starts the proxy server
2. Waits for server to be ready
3. Launches the PWA URL using Termux's termux-open-url command

#Termux Setup

# Install Node.js
pkg install nodejs

# Install Chrome ACP
npm install -g @chrome-acp/proxy-server

# Install your agent
npm install -g @anthropic-ai/claude-code @zed-industries/claude-code-acp

# Run
acp-proxy --termux claude-code-acp

#Working Directory

The agent runs in the current working directory. This determines:

• Which files the agent can access
• The project context for coding agents
• The base path for file operations

cd /path/to/your/project
acp-proxy --no-auth claude-code-acp

#Authentication

#With Authentication (default)

When authentication is enabled (no --no-auth flag):

1. Server generates random token (or uses ACP_AUTH_TOKEN)
2. Token is embedded in printed URLs
3. Clients must provide token to connect

Token format in URL:

http://192.168.1.100:9315/app?token=abc123...

#Without Authentication

acp-proxy --no-auth claude-code-acp

#Exit Codes