maxx

English | 简体中文

Multi-provider AI proxy with a built-in admin UI, routing, and usage tracking.

Docs · Docker · Desktop · API

Features

• Protocol Compatibility: Claude, OpenAI, Gemini, and Codex API formats
• AI Tool Friendly: Works with Claude Code, Codex CLI, and other coding agents
• Provider Types: Custom relay, Antigravity (Google), Kiro (AWS)
• Routing: Priority-based and weighted-random routing strategies
• Databases: SQLite (default), MySQL, PostgreSQL
• Usage & Billing: Request logs + nano-dollar pricing with multipliers
• Pricing Catalog: Versioned, tiered, and cache pricing support
• Admin UI: Multi-language Web UI with real-time WebSocket updates
• Profiling: Built-in pprof support
• Backup: Import/export configuration

Quick Start

Maxx supports three deployment methods:

Docker (Recommended for Server)

docker compose up -d

The service will run at http://localhost:9880.

📄 Full docker-compose.yml example

services:
  maxx:
    image: ghcr.io/awsl-project/maxx:latest
    container_name: maxx
    restart: unless-stopped
    ports:
      - "9880:9880"
    volumes:
      - maxx-data:/data
    environment:
      - MAXX_ADMIN_PASSWORD=your-password  # Optional: Enable admin authentication
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:9880/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  maxx-data:
    driver: local

Desktop App (Recommended for Personal Use)

Download from GitHub Releases:

🍺 macOS Homebrew Installation

# Install
brew install --cask awsl-project/awsl/maxx

# Upgrade
brew upgrade --cask awsl-project/awsl/maxx

Gatekeeper note: maxx is not notarized. On first launch, macOS Gatekeeper may block it. To allow it, run: xattr -d com.apple.quarantine /Applications/maxx.app

Or go to System Settings > Privacy & Security and click Open Anyway.

If macOS says the app is damaged: 1. Remove quarantine attributes: sudo xattr -rd com.apple.quarantine /Applications/maxx.app 2. Right-click maxx.app in Finder and choose Open once. 3. If it still fails, reinstall and retry: brew uninstall --cask awsl-project/awsl/maxx && brew install --cask awsl-project/awsl/maxx

Local Build

# Server mode
go run cmd/maxx/main.go

# With admin authentication
MAXX_ADMIN_PASSWORD=your-password go run cmd/maxx/main.go

# Desktop mode (Wails)
go install github.com/wailsapp/wails/v2/cmd/wails@latest
wails dev

Frontend requirements: Node.js 22.12.0+ within the 22.x line (see .node-version / .nvmrc) and pnpm 10.7.0 (locked via web/package.json).

Headless admin CLI (maxx-cli)

maxx-cli is a separate binary that talks to a running maxx server's admin HTTP API. It covers everything the web UI does — providers, API tokens, routes (with weights), routing strategies (with sticky session affinity), users, invite codes, and settings — and is designed for scripts, CI, and AI agents.

Supported install paths:

# From source (latest tagged release):
go install github.com/awsl-project/maxx/cmd/maxx-cli@latest

# From source (local checkout):
task install:cli      # uses Taskfile; installs to $GOBIN

# Inside the official Docker image: maxx-cli is on PATH at /usr/local/bin/maxx-cli
docker exec <container> maxx-cli --help

Standalone binary release assets and Homebrew/Scoop manifests for maxx-cli are not yet published; track #585 for the follow-up.

First-time usage:

maxx-cli login --server http://localhost:9880 --username admin
maxx-cli help reference       # full command tree, auto-generated
maxx-cli -o json provider list

For the full agent-friendly briefing run maxx-cli help reference, maxx-cli help formatting, and maxx-cli help auth-config.

Configure AI Coding Tools

Claude Code

Create a project in the maxx admin interface and generate an API key.

settings.json (Recommended)

Location: ~/.claude/settings.json or .claude/settings.json

{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your-api-key-here",
    "ANTHROPIC_BASE_URL": "http://localhost:9880"
  }
}

🔧 Shell Function (Alternative)

Add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

claude_maxx() {
    export ANTHROPIC_BASE_URL="http://localhost:9880"
    export ANTHROPIC_AUTH_TOKEN="your-api-key-here"
    claude "$@"
}

Then use claude_maxx instead of claude.

🔐 Token Authentication

When Token Authentication is Enabled: - Set ANTHROPIC_AUTH_TOKEN to a token created in the 'API Tokens' page (format: maxx_xxx) - Claude Code will automatically add the x-api-key header to requests - maxx will validate the token before processing requests

When Token Authentication is Disabled: - You can set ANTHROPIC_AUTH_TOKEN to any value (e.g., "dummy") or leave it empty - maxx will not validate the token - Suitable for internal networks or testing scenarios - ⚠️ Warning: Disabling token authentication reduces security

Codex CLI

config.toml

Add to ~/.codex/config.toml:

# Optional: Set as default provider
model_provider = "maxx"

[model_providers.maxx]
name = "maxx"
base_url = "http://localhost:9880"
wire_api = "responses"
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000

auth.json

Create or edit ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "maxx_your_token_here"
}

Usage:

# Use --provider flag to specify
codex --provider maxx

# Or use directly if set as default provider
codex

🔐 Token Authentication

When Token Authentication is Enabled: - Configure OPENAI_API_KEY in auth.json with a token created in the 'API Tokens' page (format: maxx_xxx) - Codex CLI will automatically add the Authorization: Bearer <token> header to requests - maxx will validate the token before processing requests

When Token Authentication is Disabled: - You can set OPENAI_API_KEY in auth.json to any value (e.g., "dummy") - maxx will not validate the token - Suitable for internal networks or testing scenarios - ⚠️ Warning: Disabling token authentication reduces security

API Endpoints

Configuration

Environment Variables

Headless Mode (API-only, no Web UI)

Run maxx as a pure API gateway without serving the admin Web UI — useful for server/production deployments where you configure everything through the Admin API and want a smaller attack surface.

Enable it with either the -no-ui flag or the MAXX_DISABLE_UI environment variable (the flag wins if both are set):

# Flag (local build)
maxx -no-ui

# Env var (Docker / compose)
docker run -e MAXX_DISABLE_UI=true -p 9880:9880 ghcr.io/awsl-project/maxx

In headless mode:

• / and all web UI routes return 404 (no static files are served).
• The API (/api/admin/*), proxy endpoints (/v1/messages, /v1/chat/completions, …), project proxy (/project/{slug}/...), /health, and /ws all keep working.
• Configure providers, routes, tokens, etc. via the Admin API. Set MAXX_ADMIN_PASSWORD to protect it.

Separately-hosted Frontend (point the UI at a remote backend)

You can host the Web UI on one origin (e.g. a CDN, a dev server, or a headless maxx's sibling) and have it talk to a backend on a different origin.

1. Allow the frontend's origin on the backend via CORS (otherwise the browser blocks cross-origin requests):

# Single origin
MAXX_CORS_ALLOW_ORIGINS=https://ui.example.com maxx

# Multiple origins (comma-separated), or "*" to allow any
MAXX_CORS_ALLOW_ORIGINS=https://ui.example.com,http://localhost:3000 maxx

⚠️ CORS is not a substitute for authentication. * lets any website read and call your API from a browser, including the admin API. Only use * for trusted/local setups, and always set MAXX_ADMIN_PASSWORD so the admin API requires a token. Prefer listing explicit origins over *. maxx logs a warning at startup if * is combined with an unauthenticated admin API.

2. Point the UI at the backend. Open the Web UI and either:

• On the login screen, expand Connection settings and enter the backend URL (e.g. https://api.example.com); or
• After login, go to Settings → Backend address.

The value is stored in the browser (localStorage), so each user/browser can target a different backend. Leave it empty to use the same origin that served the page (the default). Build-time default: set VITE_BACKEND_URL when building the frontend.

System Settings

Configurable via Admin UI: