ROTOXY

One gateway for authorized AI workspaces, model accounts, search tools and local workers. ROTOXY combines Token2OAuth's OAuth/MCP gateway with Snooze's durable jobs and monitoring. Existing token2oauth commands, configuration paths and client URLs remain compatible.

• Workspace providers: pooled LightSprint access, pinned sessions, distributed job tools and a persistent supervisor.

• Models & APIs: an encrypted Ollama Cloud key pool, scoped model tokens, and explicitly permitted Exa, Firecrawl and Tavily search/extraction tools.

• Private workers: a durable Oracle queue with health, assignments, model names and reported throughput.

• Codex profiles: isolated official CLI sign-in, model discovery and reported AI quota windows. Automatic subscription pooling/dispatch is not enabled.

The dashboard distinguishes reported values, historical snapshots and unknown metrics. Monitoring survives a closed chat while the service host remains online. Automatic recovery capabilities and client limitations are described in the consolidation checkpoint and the actionable supervision update.

Architecture

                              OAuth authorization code + PKCE
┌─────────────┐             ┌──────────────────────────────┐
│ ChatGPT Web │────────────▶│         Token2OAuth          │
│             │◀────────────│  OAuth AS + MCP resource     │
└─────────────┘             │                              │
                            │  adaptive credential pool    │
                            │  A  healthy                  │
                            │  B  cooldown (429)           │
                            │  C  healthy                  │
                            │  D  exhausted                │
                            │  E  healthy                  │
                            └──────────────┬───────────────┘
                                           │ Bearer upstream-token
                                           ▼
                                ┌──────────────────────┐
                                │ Upstream MCP server  │
                                └──────────────────────┘

Highlights

• One MCP connection, many upstream credentials

• OAuth authorization code flow with PKCE S256

• Protected-resource and authorization-server metadata

• Dynamic Client Registration (DCR)

• Resource-bound short-lived gateway access tokens

• Rotating refresh tokens

• AES-256-GCM encryption for upstream bearer credentials at rest

• No upstream bearer token is returned to downstream clients or rendered back into the admin UI

• Streamable HTTP/SSE-friendly MCP proxy

• MCP session affinity using Mcp-Session-Id

• Smart 401 / 402 / 429 / 5xx handling and Retry-After support

• Configurable quota/error body matching and cooldown recovery

• Six pool strategies

• Polished browser admin console

• Headless CLI

• Idempotent installer

• Tailscale detection and optional automatic installation

• Tailscale path mounting without resetting existing routes

• systemd user service, Docker, tests, and GitHub Actions

Related MCP server: MCP Credentials Broker

Quick install

Install Node.js 22+, Git, npm and an authenticated Tailscale client first, then run:

curl -fsSL https://raw.githubusercontent.com/p5n-n3t/token2oauth/main/install-rotoxy.sh | bash
rotoxy up

The manual installer prepares the gateway and foreground Funnel units without enabling boot startup or publishing routes. rotoxy up starts the configured services and publishes one root route to port 2030. rotoxy down withdraws that route and stops the services. Existing conflicting routes cause a refusal and must be migrated explicitly; global resets are never used. Oracle and monitoring units are started when separately installed and configured.

The canonical repository retains the token2oauth name during migration; product branding is ROTOXY. See manual lifecycle and legacy migration.

Compatibility installer switches

--prefix PATH
--port N
--path PATH
--mode funnel|serve|none
--public-base-url URL
--upstream-url URL
--branch NAME
--repo URL
--no-tailscale
--no-service
--force-root
--yes
--dry-run

Examples:

./install.sh --port 2030 --path /token2oauth

./install.sh --mode serve --path /token2oauth

./install.sh --mode none \
  --public-base-url https://mcp.example.com/token2oauth

./install.sh \
  --upstream-url https://provider.example.com/mcp

First run

1. Open the admin console

The installer prints the Gateway, MCP, and Admin URLs. On first initialization it also generates an admin password. Only its scrypt hash is persisted.

2. Configure the real upstream MCP URL

Use the web Admin console, or:

token2oauth config set upstreamUrl https://provider.example.com/mcp

3. Add your authorized provider accounts

token2oauth account add --label "Pro account 1"
token2oauth account add --label "Pro account 2" --weight 1.5
token2oauth account add --label "Pro account 3" --priority 50

3a. Test every credential

New accounts begin as unknown until the proxy uses them. To verify every token before attaching ChatGPT, run a direct authenticated MCP initialize probe. It runs sequentially and records only the resulting status, never the token itself:

token2oauth account probe

The admin console provides Test credential and Test all enabled credentials controls with the same behavior.

The interactive CLI disables terminal echo while the token is entered.

For automation:

printf '%s' "$PROVIDER_TOKEN" |
  token2oauth account add --label "CI account" --token-stdin

token2oauth account add \
  --label "Environment account" \
  --token-env PROVIDER_TOKEN

4. Add one URL to ChatGPT

Add only:

https://your-node.your-tailnet.ts.net/token2oauth/mcp

Token2OAuth advertises OAuth metadata. ChatGPT performs OAuth with Token2OAuth; upstream bearer tokens stay on your host.

See ChatGPT OAuth.

Smart pooling

The default strategy is adaptive-sticky.

For a new MCP session, Token2OAuth favors an enabled credential with low normalized usage, low error rate, no cooldown, and low current concurrency. Once the upstream establishes an MCP session, Token2OAuth pins that session to the same upstream credential.

This distributes load without randomly switching accounts in the middle of a stateful MCP session.

There is intentionally no fake "remaining credits" counter. If a provider publishes a real usage endpoint, a provider adapter can add proactive checks. Otherwise provider responses are more reliable than guessing.

See Pooling and failover.

Pool strategies

token2oauth pool strategy adaptive-sticky
token2oauth pool strategy round-robin
token2oauth pool strategy least-used
token2oauth pool strategy weighted-random
token2oauth pool strategy random
token2oauth pool strategy priority

• adaptive-sticky — recommended; affinity + usage/error/concurrency score

• round-robin — deterministic rotation among eligible accounts

• least-used — request count normalized by weight

• weighted-random — probabilistic distribution using account weights

• random — uniform random eligible credential

• priority — lowest numeric priority first

CLI

token2oauth init
token2oauth serve

token2oauth account add
token2oauth account list
token2oauth account enable ID
token2oauth account disable ID
token2oauth account remove ID
token2oauth account reset-health [ID]

token2oauth pool status
token2oauth pool strategy STRATEGY

token2oauth config list
token2oauth config get KEY
token2oauth config set KEY VALUE

token2oauth oauth clients
token2oauth oauth revoke-client CLIENT_ID

token2oauth admin reset-password [--generate] [--revoke-connections]

token2oauth tools refresh [ACCOUNT_ID]
token2oauth tools list
token2oauth tools deny NAME
token2oauth tools allow NAME
token2oauth tools policy show
token2oauth tools policy set FILE.json

token2oauth lifecycle status
token2oauth lifecycle up [--mode funnel|serve] [--execute]
token2oauth lifecycle down [--keep-service|--keep-route] [--execute]

token2oauth tailscale status
token2oauth tailscale expose [--execute]    # alias of lifecycle up; /token2oauth only

token2oauth doctor [--live] [--public] [--repairs] [--json]
token2oauth pools preview

For the unified foreground stack use rotoxy up|down|status. The older lifecycle up|down and tailscale expose commands refuse changes when a foreground stack exists; otherwise they are dry runs that print the exact commands unless --execute is given. They only ever add or remove the /token2oauth mount, re-read tailscale serve status --json before and after each write, and stop if any other route changed.

Admin console

• Pool — upstream URL, strategy (with live help for each choice), failover/cooldown/timeout settings and per-credential health probes.

• Tools — per-account tool inventory from tools/list, enable/disable toggles enforced by the gateway for every MCP client, and "replay-safe" marks for read-only tools.

• Diagnostics — doctor report, read-only service/Funnel check, request analytics by account and tool, recent events in plain language, and quota data only when a provider actually reports it.

• Security — regenerate the admin password (shown once) and optionally disconnect every MCP client.

Every admin form is CSRF-protected and the admin cookie is scoped to the gateway path.

Every command supports --help through Commander.

LightSprint

Token2OAuth is provider-agnostic. For LightSprint or another service, configure the actual remote MCP endpoint that accepts the account's bearer credential, then add each authorized account token to the pool.

Example labels:

LightSprint Pro #1
LightSprint Pro #2
LightSprint Pro #3
LightSprint Pro #4
LightSprint Pro #5

The public LightSprint CLI/plugin demonstrates Bearer-token API calls, token refresh and explicit handling of HTTP 429. Token2OAuth therefore treats 429/Retry-After as a strong cooldown signal by default, while also supporting configurable credit/quota patterns. It does not assume an undocumented balance endpoint.

Tailscale

Token2OAuth never calls tailscale funnel reset or tailscale serve reset.

The generated route is equivalent to:

tailscale funnel --bg \
  --https=443 \
  --set-path=/token2oauth \
  http://127.0.0.1:2030

See Tailscale deployment.

Docker

Tailscale normally stays on the host:

docker compose up -d --build
tailscale funnel --bg --https=443 --set-path=/token2oauth http://127.0.0.1:2030

Persist the data volume. It contains encrypted account envelopes, OAuth client state, and the local master key.

Security

Upstream tokens are encrypted with AES-256-GCM using a random 256-bit key stored separately in ~/.config/token2oauth/master.key. The admin UI never reveals a stored bearer token. Gateway OAuth access tokens are short-lived and audience-bound; refresh tokens are stored as hashes and rotated.

Read SECURITY.md before putting the gateway on a public hostname.

Development

git clone https://github.com/p5n-n3t/token2oauth.git
cd token2oauth
npm install
npm test
npm run dev

The test suite includes RFC 7636 PKCE verification, encryption round-trip, failure classification, a full DCR/authorization/token flow, live 429→healthy credential failover, and refresh-token rotation.

Documentation

• Architecture

• ChatGPT / OpenAI OAuth

• Pooling and failover

• Configuration

• Tailscale deployment

• Security policy

• Contributing

License

MIT