cc-gateway

Quick Start

One command. Requires Node.js 22+ and an existing Claude Code login on this machine.

git clone https://github.com/motiful/cc-gateway.git
cd cc-gateway
npm install
bash scripts/quick-setup.sh

This will:

1. Extract your OAuth credentials from macOS Keychain (access token + refresh token)
2. Generate a canonical device identity and client token
3. Write config.yaml
4. Generate a client launcher at ./clients/cc-<hostname>
5. Start the gateway on http://localhost:8443

Use it

In another terminal:

./clients/cc-<hostname>

That's it. Claude Code launches, traffic routes through the gateway. No env vars to set, no files to edit.

Behind a proxy?

HTTPS_PROXY=http://127.0.0.1:7890 bash scripts/quick-setup.sh

The gateway will route all outbound traffic (API calls + token refresh) through your proxy.

Add Clients

Each person gets their own launcher script with a unique token. The admin generates it:

bash scripts/add-client.sh alice
bash scripts/add-client.sh bob

This creates ./clients/cc-alice and ./clients/cc-bob. Send each file to the respective person.

Client setup (what you tell them)

chmod +x cc-alice
./cc-alice install        # installs as 'ccg' command
ccg                       # start Claude Code through gateway

That's it. All Claude arguments work: ccg --print "hello", ccg --resume, etc.

Optional: make claude go through gateway too

ccg hijack                # alias claude → ccg (new terminals auto-apply)
claude                    # now goes through gateway
ccg release               # undo — restore native claude

All commands

ccg                       Start Claude Code through gateway
ccg install               Install as 'ccg' system command
ccg uninstall             Remove 'ccg' and clean up
ccg hijack                Make 'claude' also go through gateway
ccg release               Restore 'claude' to native
ccg native [args]         Run native claude once (bypass gateway)
ccg status                Show gateway connection and hijack status
ccg help                  Show help

ccg and claude coexist by default. Hijack is opt-in and reversible. Supports zsh, bash, and fish.

What Gets Rewritten

| Layer | Field | Action | |-------|-------|--------| | Identity | device_id in metadata + events | → canonical ID | | | email | → canonical email | | Environment | env object (40+ fields) | → entire object replaced | | Process | constrainedMemory (physical RAM) | → canonical value | | | rss, heapTotal, heapUsed | → randomized in realistic range | | Headers | User-Agent | → canonical CC version | | | x-api-key | → real OAuth token (injected by gateway) | | | x-anthropic-billing-header | → stripped | | Prompt text | Platform, Shell, OS Version | → canonical values | | | Working directory | → canonical path | | | /Users/xxx/, /home/xxx/ | → canonical home prefix | | Billing | x-anthropic-billing-header system block | → stripped entirely | | Leak fields | baseUrl (ANTHROPIC_BASE_URL) | → stripped | | | gateway (provider detection) | → stripped |

Deployment

Local (development)

npm run dev    # tsx watch, auto-reload

Docker (production)

bash scripts/admin-setup.sh

This interactive script:

1. Extracts OAuth credentials
2. Generates config + first client launcher
3. Builds and starts the Docker container
4. Asks for the gateway address clients should connect to

After setup, add more clients with:

bash scripts/add-client.sh <name>
# Restart to pick up new tokens:
docker compose restart

Multi-machine deployment

Mac-A ──┐
Mac-B ──┼──→ gateway-server:8443 ──→ api.anthropic.com
Mac-C ──┘

Important: All machines — including the admin — should use the gateway. Direct connections from the admin machine would create a second device fingerprint visible to Anthropic.

For remote deployment, generate TLS certificates:

mkdir certs
openssl req -x509 -newkey rsa:2048 \
  -keyout certs/key.pem -out certs/cert.pem \
  -days 365 -nodes -subj "/CN=cc-gateway"

Uncomment the tls section in config.yaml, then generate client launchers pointing to the server address:

bash scripts/add-client.sh alice "" <gateway-ip>:8443 https

Alternative: Tailscale (zero config networking)

If all devices have Tailscale installed, run the gateway on any machine in the mesh. No TLS needed (Tailscale encrypts the tunnel), no public IP needed, no port forwarding.

Architecture

Client machines                        CC Gateway                    Anthropic
┌────────────┐                    ┌──────────────────┐
│ ./cc-alice  │── ANTHROPIC_ ────│  Auth: x-api-key  │
│  (launcher) │   BASE_URL       │  OAuth: auto-     │
│  + env vars │                  │    refresh        │──── single ────▶ api.anthropic.com
│             │                  │  Rewrite: all     │     identity
│             │                  │    identity       │
└────────────┘                    │  Strip: billing   │
                                  │    header         │
                                  │  Stream: SSE      │
                                  │    passthrough    │
                                  └──────────────────┘
                                         │
                                   platform.claude.com
                                   (token refresh only,
                                    from gateway IP)

Defense in depth:

| Layer | Mechanism | What it prevents | |-------|-----------|-----------------| | Launcher env vars | ANTHROPIC_BASE_URL + DISABLE_NONESSENTIAL + ATTRIBUTION_HEADER=false | CC voluntarily routes to gateway, disables side channels, skips billing hash | | Clash (optional) | Domain-based REJECT rules | Any accidental or future direct connections to Anthropic | | Gateway | Body + header + prompt rewriting | All 40+ fingerprint dimensions normalized to one device |

OAuth Lifecycle

The gateway manages the full OAuth token lifecycle:

1. Startup — uses the existing access token from your keychain. Zero network calls.
2. Auto-refresh — 5 minutes before expiry, the gateway silently refreshes via platform.claude.com.
3. Continuous — refresh tokens rotate automatically. The gateway runs indefinitely without admin intervention.
4. Failure recovery — if a refresh fails, retries every 30 seconds. Only a refresh token expiry (rare, mon