Tingly Box connects any agent to any model — for you and your whole team, with built-in power-ups.
Key Features
- Any Agent ⇄ Any Model
- Unified endpoint for AI — bridge any providers, with protocols translated both ways
- One-click config for Agents — Claude Code, OpenCode, Codex, Xcode, and more
- Profiles for Claude Code — switch models for different scenarios
- Both API keys and OAuth — use your existing quotas anywhere
- Smart Routing — route across models and tokens by cost, speed, or custom policies
- Team AI Management
- Shared team endpoint with centrally managed model rules
- Dedicated keys per member, with data isolated per user
- Per-member usage tracking
- Power-ups
- Guardrails, MCP Gateway, and Usage Analytics
- Image API — image generation and editing through the same gateway, with a built-in playground
- Remote Control — drive agents via Telegram, Weixin, WeCom, Feishu, Lark, and DingTalk
- Production-Ready
- VModel (Virtual Model) — for testing, validation, and benchmarking
- Harness-driven for robustness across protocols, routing, and clients
- UX-first visual management of providers, models, team, and remote bots
- Blazing fast — typically adds < 1ms of overhead
Preview
Quick Start
English | 中文 | Fault Record
Install
npm install -g tingly-box@latest # --registry=<mirror> works here too
tb start # tb = tingly-box; runs in the background (--no-daemon for foreground)
tb open # open the web UI
# update: reinstall, then restart to apply
npm install -g tingly-box@latest
tb restart
if any trouble, please check tingly-box output, or call for an issue to help.
# One command: fetch, restart the server in the background, migrate and open the web UI
# (a golang binary release; npx wraps the cli for convenience)
npx tingly-box@latest
# or -y for convenience
npx -y tingly-box@latest
# the binary for your platform comes from npm too (no GitHub download),
# so an npm mirror is all you need for CN (one of below)
npx --registry=https://registry.npmmirror.com -y tingly-box@latest
npx --registry=https://mirrors.huaweicloud.com/repository/npm/ -y tingly-box@latest
npx --registry=http://mirrors.tencent.com/npm/ -y tingly-box@latest
# MacOS & Linux
## Install Node.js LTS via nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
## Restart terminal or load nvm
source ~/.nvm/nvm.sh
## Install Node.js LTS
nvm install --lts
## Verify installation
node -v
npx -v
# Windows
## Powershell with Winget
winget install OpenJS.NodeJS.LTS
## Restart terminal, then verify installation
node -v
npx -v
## Or download and install Node.js LTS manually:
https://nodejs.org/en/download
mkdir tingly-data
docker run -d \
--name tingly-box \
-p 12580:12580 \
-v `pwd`/tingly-data:/home/tingly/.tingly-box \
ghcr.io/tingly-dev/tingly-box
For Docker Compose (recommended for isolated env), building your own image, or troubleshooting — see the Docker Guide.
Integration Guide
- Claude Code (support 1-click config)
- OpenCode (support 1-click config)
- Xcode (require manual config)
- ……
Any application is ready to use.
We've provided detailed config guide in application
Give your whole team one endpoint backed by centrally managed model rules. Each member gets a dedicated Team Key, and usage is tracked per user.
- Open Web UI like
http://localhost:12580
- Navigate to Team, configure the model rules, then hand out keys via Team Keys
- Track per-user consumption under Dashboard → Team usage
Route image generation and editing through the same gateway. Point any OpenAI-compatible image client at http://localhost:12580/tingly/imagegen and pick the upstream image models with rules, like any other scenario. Try prompts right away in Image → Playground.
DeepSeek is optimized for mainstream agent workflows, offering broad compatibility across protocol adapters, agent clients, extended context, vision, web search, and cache optimization.
| Module | Status | What It Solves |
|---|
| Model List | ✅ Supported | Keeps the official model list up to date in real time |
| Protocol Adaptation | ✅ Supported | Supports official Anthropic/OpenAI APIs with bidirectional conversion |
| Reasoning Capability | ✅ Supported | Provides compatibility with Thinking workflows |
| Cache Hit Optimization | ✅ Supported | Improves cache hit rates for DeepSeek requests |
| Vision Proxy | ✅ Supported | Enables DeepSeek to understand and process images |
| Web Search | ✅ Supported | Calls official Web tools through the Anthropic endpoint |
| 1M Context Window | ✅ Supported | Enables one-click setup for 1M context |
| Codex Adaptation | ✅ Supported | Ensures compatibility with mainstream agent workflows |
| Claude Code / Desktop Adaptation | ✅ Supported | Ensures compatibility with mainstream agent workflows |
Supports one-click configuration where available. For applications that require manual setup, detailed in-app configuration guides are provided.
Any compatible application is ready to use.
Detailed configuration guides are available inside each application.
Tingly Box now supports remote control through popular IM platforms. Interact with your AI agents remotely without direct server access.
Supported Platforms
- ✅ Telegram
- ✅ DingTalk
- ✅ Feishu
- ✅ Lark
- ✅ Weixin
- ✅ WeCom
Quick Setup
- Open Web UI like
http://localhost:12580
- Turn on Projects under Power-ups in the gear menu at the bottom of the left rail, then open IM in the rail
- Configure your preferred IM platform bot
- Start interacting with your agents remotely
Use Cases
- Execute tasks and queries from your phone or any device
- Team collaboration with shared agent access
- Monitor and control agents while away from your workstation
from openai import OpenAI
client = OpenAI(
api_key="your-tingly-model-token",
base_url="http://localhost:12580/tingly/openai/v1"
)
response = client.chat.completions.create(
model="tingly-gpt",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response)
from anthropic import Anthropic
client = Anthropic(
api_key="your-tingly-model-token",
base_url="http://localhost:12580/tingly/anthropic"
)
response = client.messages.create(
model="tingly",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello!"}
]
)
print(response)
Tingly Box proxies requests transparently for SDKs and CLI tools.
You can also add OAuth providers (like Claude Code) and use your existing quota in any OpenAI-compatible tool:
# 1. Add Claude Code via OAuth in Web UI (http://localhost:12580)
# 2. Configure your tool with Tingly Box endpoint
Requests route through your OAuth-authorized provider, using your existing Claude Code quota instead of requiring a separate API key.
This works with any tool that supports OpenAI-compatible endpoints: Cherry Studio, VS Code extensions, or custom AI agents.
Already running your own inference server? Tingly Box connects to it like any other provider and exposes it through the same unified gateway.
Supported out of the box
- vLLM
- SGLang
- Ollama
- LM Studio
- LocalAI
- Jan
Anything else that speaks an OpenAI/Anthropic-compatible API still works via Custom endpoint.
Quick Setup
- Open Web UI like
http://localhost:12580
- Click Connect AI → pick your engine from the Self-hosted section (default URL and key are pre-filled)
- Test Connection, then save — it's now usable like any other provider
Launch the web management interface:
npx tingly-box@latest
Then open http://localhost:12580 in your browser.
Documentation
User Manual – Installation, configuration, and operational guide
Docker Guide – Building, running, and troubleshooting the Docker images
Guardrails – Policy-based safety checks, built-in protections, and protected credential masking
MCP Web Tools – Local stdio MCP server for web_search / web_fetch
Contributing
By contributing to this repository, you agree that your contributions may be
included in this project under the MPL-2.0 and may also be used by Tingly Inc.
under separate commercial licensing terms.
See CONTRIBUTING.md and NOTICE for details.
We welcome contributions! Check the steps below to build from source code.
Prerequisites
Tip: you can also copy individual shell commands out of Taskfile.yml and run them directly if you prefer not to install task.
1. Clone and init submodules
git clone https://github.com/tingly-dev/tingly-box.git
cd tingly-box
git submodule update --init --recursive
2. Frontend development
The frontend is a React + Vite app located in frontend/. You can work on it independently of the Go backend.
Login token: the frontend requires an auth token to log in. When the backend starts it prints the full login URL (e.g. Web UI: http://localhost:12580/login/<token>). If you need to retrieve it later, run:
tingly-box token view auth --reveal
Mock mode – no running backend required, uses built-in fixture data:
task web:mock
# or directly:
cd frontend && pnpm install && pnpm dev:mock
Open http://localhost:9245 in your browser. Use the token obtained above to log in.
Dev mode – proxies API calls to a local backend (start the backend first, see step 3):
task web
# or directly:
cd frontend && pnpm install && pnpm dev
3. Backend development
Run the Go server (hot-reload via go run):
task start
# or directly:
go run ./cli/tingly-box --verbose start --debug --port 12580 --browser=false
Open http://localhost:12580 in your browser (serves the last built frontend bundle).
4. Full build (frontend + backend binary)
Builds the frontend, embeds it into the binary, then compiles Go:
task build
The output binary is written to ./build/tingly-box.
5. GUI binary (Wails) (optional)
The GUI build is not yet publicly released. Skip this step unless you are specifically working on the desktop app.
task wails:build
Other useful commands
task swagger # Regenerate openapi.json from Go source
task codegen # Regenerate frontend API client from openapi.json
task go:test # Run Go unit tests
Sponsors
If Tingly Box has been useful to you, consider supporting its development.
Donations are optional. A ⭐ on GitHub or a contribution is just as appreciated.
| Sponsor | Details |
|---|
| 0xbeekeeper | First Sponsor |
| richardxx | Long Term Claude Subscription Support |
| huajiankan | Figma Subscription Support |
Contributors
Tech Support
License
This project is available under:
For commercial licensing inquiries, contact [email protected].
