Proxy & Router Support — SCORPIOX CODE

Overview

scorpiox code supports routing all AI provider API traffic through custom endpoints. Every provider — Claude, OpenAI, Gemini — can have its base URL overridden to point at your own infrastructure. The Claude Code provider additionally has a dedicated proxy mode with strict-fail semantics.

Per-Provider Routing

Override OPENAI_BASE_URL, GEMINI_BASE_URL, or CLAUDE_CODE_PROXY_URL to route each provider through different endpoints.

Strict Fail Mode

When CLAUDE_CODE_PROXY_STRICT=1, requests fail immediately if the proxy is unreachable — no silent fallback to direct API.

Token Server

scorpiox-server-fetchtoken distributes API keys to agents via TCP, with IP whitelist and multi-key rotation support.

Traffic Capture

scorpiox-traffic captures HTTP/HTTPS conversations in HAR, JSONL, or raw format for debugging and auditing.

Claude Code Proxy Mode

The Claude Code provider in scorpiox code has a built-in proxy subsystem implemented in sx_provider_claude_code.c. When enabled, all API requests to Anthropic are routed through the configured proxy hostname instead of the default API endpoint.

            scorpiox-env.txt
# Enable Claude Code proxy routing
CLAUDE_CODE_PROXY_ENABLED=1

# Proxy hostname (your reverse proxy)
CLAUDE_CODE_PROXY_URL=anthropic.scorpiox.net

# Strict mode: fail if proxy is unreachable
CLAUDE_CODE_PROXY_STRICT=1
        

How It Works

When CLAUDE_CODE_PROXY_ENABLED=1, the C HTTP client replaces the default Anthropic API hostname with the value of CLAUDE_CODE_PROXY_URL. The request path, headers, and body remain identical — your proxy only needs to forward traffic to api.anthropic.com.

The default proxy hostname is anthropic.scorpiox.net. Set CLAUDE_CODE_PROXY_URL to your own domain to use a self-hosted reverse proxy.

Strict vs. Lenient Mode

Setting	Behavior
PROXY_STRICT=0	If proxy is unreachable, fall back to direct API call (default)
PROXY_STRICT=1	If proxy is unreachable, the request fails with an error — no fallback

Use strict mode in production to ensure all traffic goes through your compliance/audit proxy. Lenient mode is useful during development when your proxy may be down.

Provider Base URL Overrides

Every AI provider in scorpiox code supports a base URL override. This lets you point API requests at any compatible endpoint: a corporate proxy, a local cache, a regional mirror, or a custom gateway.

            scorpiox-env.txt
# OpenAI — route through corporate proxy
OPENAI_BASE_URL=https://openai-proxy.internal.corp:8443/v1

# Gemini — custom gateway
GEMINI_BASE_URL=https://gemini.your-org.com/v1beta

# Generic router for Claude API (alternative to proxy mode)
ROUTER_URL=https://llm-router.your-org.com

# WASM builds — API proxy for browser-side requests
WASM_API_PROXY=https://wasm-proxy.your-org.com
        

Key	Provider	Default
OPENAI_BASE_URL	OpenAI / GPT	api.openai.com
GEMINI_BASE_URL	Google Gemini	generativelanguage.googleapis.com
CLAUDE_CODE_PROXY_URL	Claude Code	anthropic.scorpiox.net
ROUTER_URL	Claude (generic router)	empty — direct
WASM_API_PROXY	WASM builds	empty — direct

Base URL overrides work with any API-compatible endpoint. If your proxy adds authentication headers, set the corresponding API key to a dummy value — the proxy handles auth upstream.

Router & Load Balancer

The ROUTER_URL config key points scorpiox code at a centralized router or load balancer. This is used by the Claude provider (sx_claude.c) to distribute requests across multiple API keys or backends.

            scorpiox-env.txt
# Point at your LLM router
ROUTER_URL=https://llm-router.internal:8080
        

Typical Router Architecture

            diagram
┌─────────────────┐      ┌─────────────────┐      ┌──────────────┐
│  scorpiox code  │─────▶│   LLM Router    │─────▶│  Claude API  │
│   (C client)    │      │  (load balance) │      │  OpenAI API  │
│                 │      │  (key rotation) │      │  Gemini API  │
└─────────────────┘      └─────────────────┘      └──────────────┘
                               │
                          ┌────┴────┐
                          │  audit  │
                          │  log    │
                          └─────────┘
        

The router sits between scorpiox code and the upstream provider APIs. It can:

Key Rotation

Distribute requests across multiple API keys to spread rate limits and billing.

Audit Logging

Log every prompt and completion for compliance, cost tracking, or debugging.

Rate Limiting

Enforce per-user or per-team token budgets before requests reach the provider.

Centralized Token Server

scorpiox-server-fetchtoken is a TCP server that bridges local agents to upstream HTTP token endpoints. It distributes API keys to scorpiox code instances without embedding secrets in config files or environment variables.

            scorpiox-env.txt
# Token server config
FETCHTOKEN_LISTEN_PORT=9800
FETCHTOKEN_UPSTREAM_BASE=https://tokens.your-org.com

# Security
FETCHTOKEN_API_KEY_REQUIRED=1
FETCHTOKEN_API_KEYS=key1:team-a,key2:team-b,key3:team-c
FETCHTOKEN_IP_WHITELIST=10.0.0.0/8,172.16.0.0/12

# Logging
FETCHTOKEN_ACCESS_LOG=1
        

Key	Type	Default	Description
FETCHTOKEN_LISTEN_PORT	string	9800	TCP port for the local listener
FETCHTOKEN_UPSTREAM_BASE	string	empty	Upstream base URL for token proxy
FETCHTOKEN_API_KEY	string	empty	Single API key
FETCHTOKEN_API_KEYS	string	empty	Multiple keys (comma-separated, with labels)
FETCHTOKEN_API_KEY_REQUIRED	boolean	false	Require API key for access
FETCHTOKEN_IP_WHITELIST	string	empty	CIDR-based IP whitelist
FETCHTOKEN_ACCESS_LOG	boolean	false	Enable access logging

Protocol Support

The fetchtoken server supports two wire protocols:

Legacy Protocol

Simple type-based request. Client sends a provider type (claude, codex, gemini) and receives a token back.

SXV1 Protocol

Authenticated requests with API key and structured payloads. Supports multi-type dispatch and key labels.

Traffic Capture & Inspection

scorpiox-traffic is an HTTP/HTTPS traffic capture CLI built in C. It launches an embedded MITM proxy, sets HTTP_PROXY/HTTPS_PROXY for a child process, and records all conversations.

            shell
# Capture all HTTP traffic from scorpiox code
scorpiox-traffic --format har -- scorpiox "Explain this codebase"

# Output as conversation JSONL
scorpiox-traffic --format conversation.jsonl -- curl https://api.anthropic.com/v1/messages

# Summary only
scorpiox-traffic --format summary.json -- scorpiox "Fix the bug"
        

Format	Description
raw	Full request/response bodies as files
summary.json	Metadata only — URLs, status codes, timing
conversation.jsonl	Structured prompt/completion pairs
har	HTTP Archive format (Chrome DevTools compatible)

Default capture port is 8899. Override with TRAFFIC_PORT in scorpiox-env.txt. Sessions are stored in ~/.scorpiox/traffic/.

Configuration Reference

Complete list of proxy-related configuration keys in scorpiox-env.txt:

Key	Type	Default	Description
CLAUDE_CODE_PROXY_ENABLED	boolean	0	Enable proxy routing for Claude Code requests
CLAUDE_CODE_PROXY_STRICT	boolean	0	Strict proxy mode — fail if proxy unreachable
CLAUDE_CODE_PROXY_URL	string	anthropic.scorpiox.net	Proxy hostname for Claude Code requests
OPENAI_BASE_URL	string	empty	Custom base URL for OpenAI API
GEMINI_BASE_URL	string	empty	Custom base URL for Gemini API
ROUTER_URL	string	empty	URL for the scorpiox router/load-balancer
WASM_API_PROXY	string	empty	API proxy URL for WASM builds
CURL_CA_BUNDLE	string	empty	Path to CA certificate bundle for TLS
TRAFFIC_PORT	string	8899	Port for scorpiox-traffic MITM proxy
FETCHTOKEN_LISTEN_PORT	string	9800	Port for the local fetchtoken server

Deployment Examples

Nginx Reverse Proxy for Claude

            nginx.conf
# Reverse proxy for Claude API
server {
    listen 443 ssl;
    server_name anthropic.your-org.com;

    ssl_certificate     /etc/ssl/certs/anthropic.pem;
    ssl_certificate_key /etc/ssl/private/anthropic.key;

    location / {
        proxy_pass https://api.anthropic.com;
        proxy_set_header Host api.anthropic.com;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_ssl_server_name on;

        # Log for audit
        access_log /var/log/nginx/anthropic_audit.log;
    }
}
        

            scorpiox-env.txt
# Point scorpiox code at your Nginx proxy
CLAUDE_CODE_PROXY_ENABLED=1
CLAUDE_CODE_PROXY_URL=anthropic.your-org.com
CLAUDE_CODE_PROXY_STRICT=1
        

Corporate Environment with Token Server

            scorpiox-env.txt
# Agent connects to internal token server (no API key in env)
FETCHTOKEN_LISTEN_PORT=9800

# All providers route through corporate proxy
OPENAI_BASE_URL=https://llm-gateway.corp.internal/openai/v1
GEMINI_BASE_URL=https://llm-gateway.corp.internal/gemini/v1beta
CLAUDE_CODE_PROXY_ENABLED=1
CLAUDE_CODE_PROXY_URL=llm-gateway.corp.internal
CLAUDE_CODE_PROXY_STRICT=1

# TLS verification
CURL_CA_BUNDLE=/etc/ssl/certs/corp-ca-bundle.pem
        

Debug with Traffic Capture

            shell
# Capture all API calls in HAR format
scorpiox-traffic --format har --session debug-session --     scorpiox "Refactor the database layer"

# Inspect the captured session
ls ~/.scorpiox/traffic/debug-session/
# → summary.json  requests/  responses/
        