wink-run/tokenbank
Token Bank — the local LLM gateway that sits between your AI agents and every provider. Know where tokens go · Spend less with smart routing to Ollama, Groq, GitHub Models · Earn by sharing idle quota on a community P2P network. One-click onboarding for Cursor, Claude Code, Codex CLI, Gemini CLI — no agent changes. Full trace, seamless model swap
安装Install
dsh plugin --profile web add github:wink-run/tokenbank把 wink-run/tokenbank 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
Token Bank
Personal AI Hub · Token Manager
See clearly · Spend less · Stay simple · Get smarter with you · Earn from idle
One-click Claude / Cursor / Codex / WorkBuddy onboarding · one-stop trace & routing · portrait-driven discovery · community sharing & remote agents
中文文档 · Download Latest · Architecture · Privacy Policy
Overview
Token Bank is a next-generation personal AI resource hub that enables one-click onboarding and intelligent orchestration of mainstream AI tools like Claude, Cursor, Codex, and WorkBuddy through a local gateway architecture.
Core Value Proposition
- Usage Transparency: Full-chain trace makes every token consumption accountable
- Cost Optimization: Smart routing automatically switches between local models, free quotas, paid subscriptions, and community-shared compute with lossless protocol adaptation
- Sharing Economy: P2P compute-sharing network creates a decentralized exchange for models and agents, monetizing idle resources into credits
Technical Highlights
Zero-Intrusion Integration
Declarative application handlers (CLI env injection + config hot-patching) enable seamless onboarding without modifying agent applications.
Multi-Protocol Adaptation Layer
Transparent protocol conversion (Anthropic Messages, OpenAI Chat, Codex Responses) allows agents to use third-party models without awareness.
Unified Asset Layer Architecture
Community agents run directly on users' existing agent applications (Codex, Claude, Cursor, etc.) without rebuilding harnesses, executing within user-accumulated MCP/Skill/Prompt assets for dual reuse of runtimes and tool ecosystems.
Scenario Routing Engine
- Routing policy learning from usage patterns
- Lossless context compression
- Vision enhancement layer for non-multimodal models (automatic image recognition injection)
MCP Built-in Relay & Resource Projection Gating
Constructs personal knowledge and tool ecosystems with controlled resource deployment.
AI-Native Architecture
Abandons traditional hard-coded rules; lets agents dynamically construct core capabilities (asset discovery, personalized recommendations, routing optimization) based on actual scenarios and continuously evolve—building an agent management platform with agents—achieving high flexibility and robustness.
Usage-Based Evolution
The system automatically extracts work portraits from real call records and session patterns, driving personalized recommendations for MCP/Skill/Prompt/Agent and continuous optimization of routing strategies. Multi-device usage aggregation, agent orchestration, and more make Token Bank truly smarter with you.
Why Token Bank
Pain points it tackles:
- Many model plans, little clarity on where tokens go each day
- Free quotas sit unused while paid bills rise; local models idle
- Tools, accounts, and devices don’t line up; Skills / MCP / prompts pile up
- Month-end plan credits expire unused
Token Bank is your personal AI hub. Plug Claude Code, Codex, Cursor, WorkBuddy, Kimi Code and more into a local gateway—keep familiar clients, see clearly, spend less, stay simple, grow resources from your habits (get smarter with you), and turn idle capacity into credits via community sharing; community agents can run on someone else’s machine (earn from idle).
Five pillars:
| Pillar | What you get |
|---|---|
| See clearly | One-click onboard; full trace; multi-device analytics; subscriptions vs PAYG side by side |
| Spend less | Seamless model swap; smart local-first + task-type routing; scene strategies; optional lossless compression |
| Stay simple | One-click onboard/restore; multi-account CLI by directory; tray status; one local address |
| Get smarter with you | Work portrait; personalized MCP / Skill / Prompt / Agent discover · accumulate · iterate |
| Earn from idle | Contribute idle capacity for credits; hire agents; circles & network map |
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Desktop (Electron · Mac / Windows) or CLI / Docker Web UI │
│ Gateway · Providers · Resources · Playground · Usage · … │
└────────────────────────────┬────────────────────────────────────┘
│ loopback
▼
┌─────────────────────────────────────────────────────────────────┐
│ Local gateway :11430/v1 │
│ · Anthropic Messages / OpenAI Chat / Codex Responses adapters │
│ · keyScene rewrite · scene/task-type routing · compression │
│ · Built-in MCP relay (prompts / models / resources / bridge) │
└───────────────┬─────────────────────────────┬───────────────────┘
│ local keys stay on device │ login + relay key
▼ ▼
Ollama / free API / sub / PAYG Token Bank cloud
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Community P2P Remote agents Multi-device
(WebSocket) (run elsewhere) usage merge
Implementation notes:
| Layer | What it does |
|---|---|
| App handlers | Declarative app-handlers.yaml for CLI shim / config-file patch / session scan; WorkBuddy, Trae, Hermes, Kimi use strong install signals |
| Routing | Unified “route = selector chain”: personal/community/free/paid filters + task-type presets (design / repo-qa / chore / debug) |
| Resource projection | Skill / Prompt / MCP only onto hosted and installed targets; apps without stdio use the built-in MCP relay |
| Telemetry | Live gateway logs + local session import (Claude / Codex / Cursor / WorkBuddy Trace, …) with auto-dedupe |
Core capabilities: one-click onboarding · seamless model swap · full trace
Token Bank is more than an API proxy — it brings Claude Code, Codex, Cursor, WorkBuddy, Kimi Code, OpenClaw, and other mainstream agents under one local gateway. No agent-side changes required for usage tracing, third-party model switching, and smart routing.
One-click agent onboarding
Open the Gateway tab — installed tools appear automatically (desktop apps can be added manually):
| Agent | How it connects |
|---|---|
| Claude Code / Codex CLI / OpenCode / Hermes / Kimi Code | CLI shim: injects BASE_URL (and related) env vars — no command changes |
| Claude Desktop / Codex Desktop / OpenClaw / WorkBuddy | Config-file patch: one click to point at the local gateway (missing configs may be created after strong install detection) |
| Trae Work | Session import + manual gateway params inside the IDE |
| Cursor / Copilot / Qwen / Grok / … | Session stats, or set OPENAI_BASE_URL / a dedicated Gateway key |
Onboarding flow:
- Click Track → start counting that app's token usage (even on the official subscription)
- Pick a model or scene route in the dropdown → config is rewritten automatically; traffic goes through the gateway
- Click Revert → restore the official config and stop tracking
Three states, clearly separated: stats only (official sub + session import), via gateway (route bound + live proxy), reverted (original config restored).
Seamless third-party model switching
Agents keep their native model names (claude-sonnet-4-6, gpt-5, …). The client never needs to change:
Claude Code requests claude-sonnet-4-6
↓ gateway keyScene transparent rewrite
Actually routed → Groq llama-3.3-70b / local Ollama / DeepSeek / …
↓ protocol adapter
Anthropic Messages ↔ OpenAI Chat ↔ Codex Responses
- Model names unchanged — Claude client validation and UI stay the same
- Automatic protocol conversion —
/v1/messages,/v1/chat/completions,/v1/responseseach handled - Per-app bindings — Claude Code on free Groq, Codex on local Ollama, independently
- Switch back anytime — choose "Direct (official)" in the route dropdown; config is restored cleanly
Session trace (live proxy + session import)
Usage is traced whether or not traffic goes through the gateway:
| Mode | What it does |
|---|---|
| Live proxy | Requests via localhost:11430 — logs route chain, resolved model, tokens, latency, cost |
| Session import | Tracked apps that still hit the official API — local session logs (~/.claude, ~/.codex, WorkBuddy Trace, …) are scanned and imported |
| Dedup | Same call recorded by both gateway and session file → counted once |
Trace data appears on the Dashboard sliced by app · provider · model · supply type · device · time; the call log shows route result and latency per request.
Smart routing
Supply is organized into local sources and community sharing sources. Each app can bind its own route; a global supply chain acts as fallback:
Per-app binding (keyScene / scene routes / task-type routes)
↓ unbound or llm-router-* model
Smart supply chain (unified “route = selector chain”)
Local: Ollama → free API (Groq / GitHub Models) → subscription / PAYG API
↓ local unavailable or need extra compute
Community sharing (spend credits on shared community compute)
↓ policy groups
fallback · round-robin · weighted · latency · direct
| Supply type | Includes | Notes |
|---|---|---|
| Local sources | Ollama, free API, APP/API subscriptions, pay-as-you-go | Forwarded by your local gateway; keys never leave the machine |
| Community sharing | Shared community compute network | Spend credits on remote nodes; model list synced dynamically |
- Scene routes — daily chat, code completion, long-doc analysis each get their own chain
- Task-type routes — presets like
design/repo-qa/chore/debug(OpenCode-style inference routing) - Scope / price filters — personal-only, community-only, free-only, or paid-only
- Policy groups — pick provider order from task features (tool calls, context length, …)
- Failover — local source down? try community sharing automatically; fully transparent to the agent
- Egress guards — clamp outbound
max_tokensto upstream limits to cut avoidable 400s
Model modalities
Provider models can be tagged text / vision / image-gen / embedding, driving Playground capabilities and Codex catalog input_modalities (vision models expose image input).
Gateway lossless compression
Optional lossless JSON compression before forwarding — fewer input tokens upstream, semantics unchanged:
- Minifies pretty-printed JSON in messages (tool results, embedded data); strips whitespace only
- Non-JSON content is left byte-for-byte untouched — answers stay the same
- Enable in Config, or set
TOKENBANK_COMPRESS=1 - Dashboard shows compression count, tokens saved, and ratio; cloud merge across devices when signed in
Multi-device usage aggregation
Desktop, CLI, and server gateways each register as a device — usage is reported and merged in the cloud when signed in:
| Capability | What it does |
|---|---|
| Device registration | Each machine gets a persistent device_id; 60s heartbeat tracks online status |
| Inventory snapshots | Reports calls, tokens, cost, local / community sharing mix, top models/apps for 1 / 7 / 30 day windows |
| Cloud merge | Profile and Dashboard show per-device share, online status, detail vs aggregate views |
| Cross-device sync | Subscriptions, PAYG config, and tool lists sync on login — no re-setup when switching machines |
Unified subscription management
The Profile tab is the single hub for all billing accounts; Providers handles keys and routing:
| Type | How it's managed | Typical use |
|---|---|---|
| APP subscription | Register ChatGPT / Claude / Gemini / Cursor plans and monthly cost | Stats-only on official sub, or OAuth → API gateway |
| API subscription | Separate catalog for vendor API plans (e.g. Volcengine Coding Plan) | API Key gateway, billed separately from APP subs |
| Pay-as-you-go | Register providers, model lists, and USD/M-token list prices | Providers page only exposes models configured here; cost estimates use these rates |
- Cloud sync — subscriptions and PAYG config download on login; Mac / Windows / Linux stay in sync
- Billing overlay — daily subscription amortization + PAYG estimates alongside raw token stats
- Supply linkage — Profile defines what you use and what it costs; Providers defines how to connect and route
Dynamic supply delivery
Local source catalogs and tool lists don't require manual version bumps — sync on login, refresh when online:
Server-maintained
├── Local source catalog (Ollama / Groq / GitHub Models / SiliconFlow …)
├── Tool list config.apps (agent onboarding rules, protocol adapters)
└── Scene routes config.scenes (preset routing chains)
↓ auto-fetched on login / startup
Local gateway
├── Merged into ~/.tokenbank/tokenbank.yaml
├── Community sharing online models refreshed periodically (/v1/models → route candidates)
└── One-click env scan — import existing free keys with round-robin
- Local catalog delivery — Groq, Cerebras, GitHub Models, NVIDIA NIM, etc. listed under Local sources; admins hot-update via YAML upload
- Community sharing models — online contributor models pulled live; no manual local registration
- Env scan — one-click import of existing Groq / GitHub Models / Anthropic keys; multi-key round-robin
- Offline fallback — built-in defaults when offline; server deltas merged automatically when back online
Multi-account CLI & directory dispatch
Run multiple logins of the same CLI (Claude Code / Codex). The gateway picks the right instance by working directory so configs never collide:
| Capability | What it does |
|---|---|
| Auto-scan | Discover existing CLI account instances on startup or manual rescan |
| Manual add | Gateway → “CLI instance” for accounts the scanner misses |
| Effective directory | Bind each instance to a workdir; the shim injects env from $PWD |
| Quota visibility | Claude / Codex subscription meters; tray and app list show today’s usage |
Agent orchestration (Playground)
Debug / Playground is more than a single-model chat:
- Set a main agent as the aggregation entry for natural-language tasks (image input supported)
- The main agent can plan steps and dispatch to other onboarded agents (including Kimi / Cursor runtimes)
- Community agents: hire on demand from Contribute; tasks run on their device, without downloading their source — lower risk than running unknown agents locally
- Built-in
tokenbank-agent-bridgeMCP:tb_list_agents/tb_dispatch_agentfor orchestration - Chunked conversation stream, visible tool calls, stop then continue
- Agent visibility is gated by runtime projection + hosted install — only projected, available agents appear
Resource hub: MCP · Skill · Prompt
The Resources tab consolidates community picks and personal assets:
| Type | Capability |
|---|---|
| Community catalog | Sync recommended MCP / Skill / Prompt / Agent lists on login (cache-first, built-in offline fallback) |
| Projection | Project only onto hosted and installed targets; revoke anytime; cascade deps on onboard |
| Built-in MCP relay | For apps without stdio: pick app → bind prompts/models/resources → copy relay config |
| Prompt MCP | Prompts served via tokenbank-prompts (tb_get_prompt / tb_list_prompts) filtered by projection set |
| Work-portrait posters | Dashboard can export four poster styles (pro / cute / humor / minimal) |
Five things it does
1 — See clearly
Token Bank logs every request: which route it took, which model answered, how many tokens, how long it took.
- One-click onboard & inventory: stats-only / via gateway / restore; per-app calls, tokens, cost
- Full trace: live proxy + session import with auto-dedupe
- Multi-device analytics: app · provider · model · cost · device · time; cloud merge when signed in
- Subscriptions vs PAYG: APP / API / metered side by side with daily accrual and list-price estimates
2 — Spend less
A smart local-first routing chain, with community sharing as fallback:
Local: Ollama → free APIs → subscription / PAYG
↓ unavailable or need extra capacity
Community sharing (spend credits on shared compute)
- Seamless model swap: native model names unchanged; protocols adapted automatically (including Codex Responses tool forwarding)
- Scene / task-type strategies: chat / completion / long docs / design·repo-qa·chore·debug; failover transparent to agents
- Lossless compression: fewer upstream input tokens, meaning unchanged
3 — Stay simple
- One-click onboard/restore on the Gateway page
- Multi-account CLI by working directory; menu-bar tray for status and today’s usage (brand logo + glass popover)
- OpenAI-compatible endpoint: point existing tools at one local address
- Playground orchestration: main agent takes tasks and hands off (including community agents); tool streams visible
4 — Get smarter with you
- Work portrait mined from real calls and habits; reusable across skills, prompts, agents
- For You: personalized MCP / Skill / Prompt / Agent discovery
- Accumulate & iterate: keep assets in your library; reuse portrait to rediscover, or remine; compose when the catalog falls short
5 — Earn from idle
Contribute unused compute or API quota to community sharing, earn credits, spend them on shared models; or list / hire agents (tasks run on their device; configs and API keys stay local).
You can contribute compute: local Ollama, unused upstream quota, private LAN models (outbound WebSocket—no inbound port)
credits = (output_tokens / 1000) × contribute_rate × quality_multiplier (0.5–1.5)
spend = ((prompt + completion tokens) / 1000) × consume_rate
Contribute rate > consume rate; plus check-in, wheel, and referrals. Circles share models and credits.
Hire agents: On Contribute, list projected assistants (card/bio only) or hire community agents per use; jobs run on their device without downloading their source; shareable landing pages for tryouts. Launch from Playground or a hosted app.
Quick start
Desktop app (Mac / Windows — recommended)
Download the installer from Releases:
- macOS
.dmg— double-click to install, lives in the menu bar, auto-updates - Windows
.exe— NSIS installer, auto-updates; title bar matches the app shell theme
After installing: open the app → go to Config → enter your backend URL and relay API key → done.
Point your AI tools at the local gateway:
OPENAI_BASE_URL=http://localhost:11430/v1
Create a local API key in the Gateway tab, or use an existing upstream key.
CLI mode (Linux / servers)
git clone https://github.com/wink-run/tokenbank.git
cd tokenbank/client
npm install
node cli/gateway.js start
Open http://localhost:11431 in a browser to configure. Works identically to the desktop app.
# Background (nohup)
nohup node cli/gateway.js start > gateway.log 2>&1 &
# Or with pm2
pm2 start cli/gateway.js -- start
Docker (containerised)
git clone https://github.com/wink-run/tokenbank.git
cd tokenbank
docker compose up gateway -d
The gateway-data/ volume is mounted automatically; local-config.json is created on first start. Configure routes and apps in the Web UI on :11431. See gateway-data/README.md.
| Port | Purpose |
|---|---|
11430 |
LLM requests (OPENAI_BASE_URL=http://host:11430/v1) |
11431 |
Web management UI |
What's in the UI
Gateway · one-click onboarding & toolbox
App list with today's usage, plus the App toolbox to install / remove Claude Code, Kimi Code, Cursor, Codex, and more.
Sessions · unified cross-app trace
Filter by Claude Desktop / Cursor / Kimi Code / Codex, inspect tokens and cost, hand off or export.
Session Trace · step-level observability
Per-session steps, tool calls, skills used, and token breakdown (sealed reasoning when required by the API).
Providers · personal compute + community sharing
Speed-test personal models with status lights; spend credits on community-shared models.
Assets · Agents / Skills / Prompts
Manage agents and project them onto runtime CLIs; community “For You” picks and work portrait.
Playground · agent orchestration
Main agent receives tasks with tool streams and terminal collaboration; runtimes include Claude Code / Codex / Cursor / Kimi Code.
Usage · spend visibility
Requests / tokens / free-hit rate / estimated cost; per-app mix and daily trend.
Circles · share compute with friends
Create or join circles; invite friends to share models and credits.
Contribute · earn from idle quota
Contribute local models to the community network for credits; keys never leave the machine. You can also list assistants for others to hire—only the card and bio are public; runs stay on your device.
Global network · node map
Online nodes, available models, and geographic distribution.
Tray · always-on glance
Gateway status, per-app TTFT / today’s usage; open the main panel in one click.
| Page | What you can do |
|---|---|
| Usage | Multi-dimensional stats: app share, local / community sharing mix, cost estimates; work-portrait posters |
| Gateway | One-click onboarding (WorkBuddy / Trae / …) + multi-account CLI; session Trace; scene / task-type routes |
| Playground | Agent orchestration (community agents, image input); tool streams, stop/resume |
| Assets | Community MCP / Skill / Prompt / Agent catalog; projection gating; built-in MCP relay; portrait recommendations |
| Providers | Local sources and community sharing; modalities (text/vision/image/embedding); speed tests & dynamic catalog |
| Circles / Contribute / Network | Circles · contributor nodes / hire agents · global node map (also usable on the web) |
| Config | Gateway port, timeout, concurrency · lossless compression · cloud account & relay key |
Connecting any OpenAI-compatible client
# Claude Code (or one-click onboard in Gateway — auto-injects ANTHROPIC_BASE_URL)
export ANTHROPIC_BASE_URL=http://localhost:11430
# Codex CLI (Gateway onboarding auto-injects OPENAI_BASE_URL)
export OPENAI_BASE_URL=http://localhost:11430/v1
# Cursor / any OpenAI-compatible tool
OPENAI_BASE_URL=http://localhost:11430/v1
OPENAI_API_KEY=your-local-key
# Quick curl test
curl http://localhost:11430/v1/chat/completions \
-H "Authorization: Bearer your-local-key" \
-H "Content-Type: application/json" \
-d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}],"stream":true}'
Prefer Gateway → Track for one-click onboarding — no manual env vars. Pick a route and the agent keeps its native model names while the gateway transparently forwards to your chosen provider. The app settings panel also lists bound resources and MCP for tryout.
Self-hosted P2P backend (optional)
To run your own private network instead of using the public one:
cp .env.example .env
# Edit .env — set ADMIN_KEY
docker compose up proxy -d
| Variable | Description |
|---|---|
ADMIN_KEY |
Admin dashboard password |
REQUEST_TIMEOUT |
Per-request forwarding timeout in seconds (default 120) |
- Admin dashboard:
http://YOUR_VPS:8000/admin/ui - User portal:
http://YOUR_VPS:8000/app - Worker WebSocket:
ws://YOUR_VPS:8000/ws/worker
Contributing a worker node
cd agent && pip install -r requirements.txt
python agent.py register \
--server "ws://YOUR_VPS:8000/ws/worker" \
--worker-key "wk-... from the user portal" \
--models "llama3,qwen2" \
--llm-url "http://localhost:11434" \
--name "my-machine"
python agent.py start
Upstream API keys never leave your machine. Only the worker key and model list are sent during registration.
License
Apache License 2.0 — see LICENSE and NOTICE.
Redistribution and derivative works must retain the NOTICE and credit the source:
Token Bank · https://github.com/wink-run/tokenbank
Disclaimer
This project is for educational and research purposes only. Users are responsible for complying with applicable laws, regulations, and upstream service terms. The authors assume no liability for any consequences arising from deployment, compute sharing, or request forwarding.
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
esengine/DeepSeek-Reasonix
DeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…