# token-proxy

> Multi-provider API token proxy: auth gateway + key rotation for Claude Code and other AI clients

Latest version **0.3.0** (published 2026-08-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install token-proxy
pnpm add token-proxy
yarn add token-proxy
bun add token-proxy
```

Provides the command `token-proxy`.

## Health

**Score 60/100 (C)** — status: active.

Positive: esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-08-13 |
| First published | 2026-08-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 1 |
| Unpacked size | 574.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | dev800 |
| Keywords | claude, anthropic, openai, proxy, gateway, llm, token, opencode |

## Links

- npm: https://www.npmjs.com/package/token-proxy
- Repository: https://github.com/pagesuper/token-proxy
- Homepage: https://github.com/pagesuper/token-proxy#readme
- Issues: https://github.com/pagesuper/token-proxy/issues
- npm.io page: https://npm.io/package/token-proxy

## Dependencies (1)

- [fastify](https://npm.io/package/fastify.md) ^5.11.3

## Alternatives

- [flatbuffers](https://npm.io/package/flatbuffers.md) — 6.0M weekly downloads
- [jwt-simple](https://npm.io/package/jwt-simple.md) — 259.5K weekly downloads
- [@exodus/patch-broken-hermes-typed-arrays](https://npm.io/package/@exodus/patch-broken-hermes-typed-arrays.md) — 28.5K weekly downloads
- [@native-to-anchor/buffer-layout](https://npm.io/package/@native-to-anchor/buffer-layout.md) — 12.2K weekly downloads
- [binary-parser-encoder](https://npm.io/package/binary-parser-encoder.md) — 5.3K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2026-08-13
- 0.2.0 — 2026-08-13
- 0.1.0 — 2026-08-12

## README

# token-proxy

Multi-provider API token proxy: an authentication gateway with key rotation and request logging, providing unified access for AI clients such as Claude Code.

[中文文档](./README.zh-CN.md)

## Why

Claude Code only sends `Authorization: Bearer <token>` to custom endpoints, but some upstreams (e.g. opencode go) only accept `x-api-key` and enforce risk controls on the Claude Code User-Agent. token-proxy acts as a middle layer that:

- **Authentication** — multi-user (username + key) with three auth methods, ready for teams
- **Header conversion** — Bearer → the header the upstream requires (`x-api-key`, etc.)
- **User-Agent spoofing** — bypass upstream risk controls on AI-client user agents
- **Key rotation** — multiple upstream keys rotated round-robin to spread quotas
- **Multiple upstreams** — adapter-based support for anthropic / openai-compatible endpoints, fully configurable
- **Full logging** — complete request/response details stored in SQLite, with token usage & cost per request

## Features

- **SQLite-backed management** (users / backends / key pools / routes / models / aliases / admins) — single `token-proxy.<env>.db`, WAL mode, high performance
- **Zero-DB hot path** — auth/routing/backends/models are served from an in-memory snapshot that hot-reloads within ~1s of any admin change (no restart)
- **Usage & cost tracking** — input/output tokens and cost parsed from streaming and non-streaming responses, with per-model pricing
- **Model management** — catalog, pricing, aliases (client names rewritten to real model names), enable/disable, and per-model backend routing
- **Auto model sync** — the catalog auto-syncs from OpenCode Zen / Go every 12 hours (or on demand via a one-click button in the console), keeping models per backend with official pricing when available
- **Request log archiving** — expired logs are gzip-archived instead of deleted (downloadable `.db.gz` / `.db`, selectable time range, super-admin only), keeping history without growing the main database
- **Web admin console** (`/admin`) — dashboard, users, backends, routes, models, request logs, settings, audit log, and maintenance; fully internationalized (English primary, 中文 available)
- **Environment isolation** — dev / test / prod each with its own config file, port and database, selected via `.env`
- **pm2 cluster** — production deployment with 2 instances by default

## Architecture

```
Client (Claude Code / codex / ...)
   │  auth: Bearer user[@backend]:key (Basic / x-api-key also supported)
   ▼
token-proxy (Fastify, prod :3501)
   │  ① parse auth {user, key, upstream}
   │  ② pick adapter by route (anthropic / openai / anthropic-to-openai)
   │  ③ header conversion + UA spoofing + key round-robin + model resolution
   ▼
Upstream (opencode go / DeepSeek / OpenAI-compatible...)

Data:
  config        config.<env>.json (project root / XDG config)
  database      token-proxy.<env>.db (WAL, users/backends/routes/models/logs)
  text logs     logs/token-proxy.YYYY-MM-DD.log (per day)
  admin console http://<host>:<port>/admin
```

## Quick start

### Requirements

- Node.js >= 24 (`volta install node@24.16.0` recommended)

### Install & run

**Option 1 — CLI global install**

```bash
npm install -g token-proxy
token-proxy init          # create config (prints the initial admin password once)
token-proxy set-password  # set the super-admin password (scrypt hash)
token-proxy start         # start in the background
token-proxy logs          # tail request logs
token-proxy status        # show status
token-proxy stop          # stop
```

**Option 2 — from source**

```bash
npm install
npm run dev               # dev with hot reload (port 3502)
npm test                  # run all tests

# production with pm2 (cluster, 2 instances, port 3501)
pm2 start ecosystem.config.cjs
pm2 logs token-proxy
```

### Environments

The run environment comes from `.env` (`TOKEN_PROXY_ENV`, default `dev`), copied from [`.env.example`](./.env.example). Each environment is isolated:

| Env   | Config file        | Database               | Default port |
|-------|--------------------|------------------------|--------------|
| prod  | `config.prod.json` | `token-proxy.prod.db`  | 3501         |
| dev   | `config.dev.json`  | `token-proxy.dev.db`   | 3502         |
| test  | `config.test.json` | `token-proxy.test.db`  | 3503         |

Config files live in the project root (source mode) or `~/.config/token-proxy/` (CLI global mode). First boot migrates any legacy `config.json` users/backends/routes into the database.

### Client setup (Claude Code)

```bash
export ANTHROPIC_BASE_URL="http://<host>:<port>/v1"
export ANTHROPIC_AUTH_TOKEN="username:your-api-key"
```

Token format: `username[@backend]:key` — the optional `@backend` overrides the backend bound to the route.

## Configuration

`config.json` (or `config.<env>.json`) only holds static settings:

```jsonc
{
  "server": { "host": "0.0.0.0", "port": 3502, "apiPrefix": "/v1", "basePath": "" },
  "admin":  { "username": "admin", "passwordHash": "$scrypt$16384,8,1$..." },
  "security": { "sessionTtlHours": 168 },
  "auth":   { "methods": ["bearer", "basic", "apiKey"] },
  "logging": {
    "directory": "./logs",
    "retentionDays": 365,
    "detailRetentionDays": 30,
    "enableDetailDatabase": true,
    "enableTextLog": true
  },
  "database": { "path": "" }
}
```

Everything else — users, backends, key pools, routes, models, aliases, admins — is managed from the web console (`/admin`), stored in SQLite, and applied without restart.

## Web console

Open `http://<host>:<port>/admin` and sign in with the super-admin credentials from `config.json`. Features:

- **Home** — welcome page with system overview and quick-start snippets
- **Dashboard** — request volume, success rate, latency, token & cost trends (7/30 days), top users, status distribution, recent requests
- **Users** — create/disable users, reset keys (shown once), quotas, per-user usage stats
- **Backends** — upstream connection info, key pool management, connectivity tests
- **Routes** — entry path → protocol adapter → backend
- **Models** — catalog, pricing, aliases, per-model backend routing, enable/disable
- **Requests** — paginated logs with multi-field filters and request/response body details
- **Settings** — auth methods, log retention, body storage, sub-admins, audit log, VACUUM

Language (English / 中文) is switchable in the sidebar and persisted in the browser.

## CLI

```
token-proxy start | stop | restart | status
token-proxy logs [N]
token-proxy stats
token-proxy init
token-proxy set-password
token-proxy migrate       # import legacy per-day log databases
token-proxy backup        # online SQLite backup
```

## Development

```bash
npm run dev        # hot reload on port 3502
npm run check      # syntax check
npm test           # all tests (unit + integration)
npm run cli -- --help
```

Structure:

```
src/
├── index.js               # entry: Fastify assembly, forwarding, lifecycle
├── config.js              # config hot-reload + validation (server/admin/security/logging/database)
├── env.js                 # environment (.env) + per-env defaults
├── daemon.js              # process daemon (pid file + detached)
├── db/                    # SQLite: schema/migration, records, legacy import
├── store/                 # in-memory snapshot + 1s hot-reload polling
├── usage.js               # token usage & cost parsing
├── auth/                  # inbound auth (bearer / basic / x-api-key)
├── upstream/              # routing, backend selection, adapters, protocol conversion
├── logger/                # text summary + SQLite detail logs
└── admin/                 # web console: sessions, REST API, static SPA (i18n)
```

## Security

- Super-admin password is stored in `config.json` as a **scrypt hash** (never plaintext); set it with `token-proxy set-password`
- The server refuses to start without admin credentials (prevents an open login)
- Upstream keys are stored locally in SQLite (file mode `0600`) and masked in the UI; log in with caution on shared hosts
- Login rate-limiting (5 failures locks for 5 minutes) and full audit logging
- For public deployments, put nginx + HTTPS in front

## License

[MIT](./LICENSE)

---
_Source: https://npm.io/package/token-proxy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._