Announcement: Here is fault record. Please update to the latest version to resolve known issues. Thank you for your continued support.

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.

• Unified API Gateway – One mixin endpoint to rule them all — seamlessly bridge OpenAI, Anthropic, Google Gemini, and more with automatic protocol translation
• Agent Integration – One-click config for Claude Code, OpenCode, Codex, Xcode, and more — transparent proxying for SDKs and CLI tools
• 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

From npm (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

if any trouble, please check tingly-box output, or call for an issue to help.

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 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)

# 1. Add Claude Code via OAuth in Web UI (http://localhost:12580)
# 2. Configure your tool with Tingly Box endpoint

npx tingly-box@latest

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

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!
Please check steps below to build from source code.

Requires: Go 1.25+, Node.js 20+, pnpm, task

# Install dependencies
# - Go: https://go.dev/doc/install
# - Node.js: https://nodejs.org/
# - pnpm: `npm install -g pnpm`
# - task: https://taskfile.dev/installation/, or `go install github.com/go-task/task/v3/cmd/task@latest`
# - shell: copy and run shell command in taskfile directly

git submodule update --init --recursive

# Build with frontend
task build

# Build GUI binary via wails3
task wails:build

Telegram	Wechat
https://t.me/+V1sqeajw1pYwMzU1	tingly-box

Special badges are minted to recognize the contributions from following contributors:

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 [email protected].