tingly-box

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

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

English | 中文

Install

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

# 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.

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

• 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 is optimized for mainstream agent workflows, offering broad compatibility across protocol adapters, agent clients, extended context, vision, web search, and cache optimization.

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

1. Open Web UI like http://localhost:12580
2. Navigate to Remote section
3. Configure your preferred IM platform bot
4. 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.

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.

Prerequisites

Tip: you can also c