tingly-dev/tingly-box
> Announcement: Here is fault record. Please update to the latest version to resolve known issues. Thank you for your continued support.
catalog 简介 / catalog descriptioncatalog description：Your Intelligence, Orchestrated. Every builder. Every team. Every agent. For Everyone.
安装Install
dsh plugin --profile web add github:tingly-dev/tingly-box把 tingly-dev/tingly-box 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
Announcement: Here is fault record. Please update to the latest version to resolve known issues. Thank you for your continued support.
Tingly Box
Quick Start • Features • Integration • Documentation • Issues
Tingly Box serves agents, coordinates AI models, optimizes context, and routes requests for maximum efficiency — with built-in remote control and secure, customizable integrations.
Key Features
- Agent-First Model Gateway – Unified endpoint for agents — seamlessly bridge OpenAI, Anthropic, Google Gemini, and more with automatic protocol translation and native agent compatibility
- Agent Integration – One-click config for Claude Code, OpenCode, Codex, Xcode, and more — transparent proxying for SDKs and CLI tools
- Agent Profiles - Run agent like Claude Code with individual profiles, each profile can work with different model and agent config
- Remote Control via IM Bots – Control AI agents remotely through Telegram, DingTalk, Feishu, Lark, Weixin, WeCom, Slack, and Discord
- Multi-Tenant API Tokens – Isolate data per user with dedicated API tokens — each user gets their own usage tracking, provider access, and configuration
- Smart Routing Engine – Intelligently route requests across models and tokens based on cost, speed, or custom policies — far beyond simple load balancing
- Flexible Authentication – Support for both API keys and OAuth providers (Claude.ai, Codex, etc.) — use your existing quotas anywhere
- Visual Control Plane – Intuitive web UI to manage providers, routes, aliases, models, and remote bots at a glance — no config files needed
- Client-Side Usage Analytics – Track token consumption, latency, cost estimates, and model selection per request — directly from your client
- Blazing Fast Performance – Adds typically < 1ms of overhead — get flexibility without latency tax
Quick Start
Install
From npm / npx (recommended)
# Install and run (auto restart, migrate and open webui while run without any args)
# A golang binary release but npx to wrap cli for convenience
npx tingly-box@latest
# or -y for convenience
npx -y tingly-box@latest
# if any network trouble, try bundle with binary built-in
npx -y tingly-box-bundle@latest
# npm mirror is supported for CN (one of below)
npx --registry=https://registry.npmmirror.com -y tingly-box-bundle@latest
npx --registry=https://mirrors.huaweicloud.com/repository/npm/ -y tingly-box-bundle@latest
npx --registry=http://mirrors.tencent.com/npm/ -y tingly-box-bundle@latest
if any trouble, please check tingly-box output, or call for an issue to help.
Install Node & NPX
# 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
From Docker (GitHub Host)
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
From Docker Compose (Recommend for isolated env)
# Build and start in detached mode
docker-compose up -d
# View logs
docker-compose logs -f tingly-box
# Stop services
docker-compose down
# Access Web UI at http://localhost:12581
# (Note: Port 12581 is used to avoid conflict with host tingly on 12580)
Integration Guide
Agent Integration - Claude Code / Claude Desktop / OpenCode / Codex / Xcode / VSCode / OpenClaw
- 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
DeepSeek Best Compatibility
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.
Remote Control Agent via IM Bots - TG / DingTalk / Feishu / Lark / Weixin / WecCom
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 - Navigate to Remote section
- 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
OpenAI SDK
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)
Anthropic SDK
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.
Using OAuth Providers
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.
Web Management UI
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
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.
Contributing Guide — Build & Dev
Prerequisites
| Tool | Version | Install |
|---|---|---|
| Go | 1.26+ | https://go.dev/doc/install |
| Node.js | 20+ | https://nodejs.org/ |
| pnpm | latest | npm install -g pnpm |
| task | latest | go install github.com/go-task/task/v3/cmd/task@latest or https://taskfile.dev/installation/ |
Tip: you can also copy individual shell commands out of
Taskfile.ymland run them directly if you prefer not to installtask.
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
Support
| Telegram | |
|---|---|
| https://t.me/+V1sqeajw1pYwMzU1 | tingly-box |
Early Contributors
Special badges are minted to recognize the contributions from following contributors:
|
|
|
|
|
|
Contributors
License
This project is available under:
- MPL-2.0 · © Tingly Dev – See LICENSE.txt
- Commercial License · © Tingly Dev – See LICENSE-COMMERCIAL.txt
For commercial licensing inquiries, contact biz@tingly.dev.
❤️ Support Tingly Box
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.
| WeChat Pay | Alipay |
|---|---|
 |
 |
相关推荐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: …
-
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…
-
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…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …
-
nocobase/nocobase
NocoBase is an open-source AI + no-code platform for building business systems fast. Instead of generating everything fr…