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 • Usage • Documentation • Issues

Tingly Box coordinates AI models, optimizes context, and routes requests for maximum efficiency — with built-in remote control and secure, customizable integrations.

Key Features

• Unified API – One mixin endpoint to rule them all, use what you like - OpenAI / Anthropic / Google, seamlessly bridge all of them with auto translation
• Smart Routing, Not Just Load Balancing – Intelligently route requests across models and tokens based on cost, speed, or custom policies, not simple load balancing
• Smart Context Compression – (Coming soon) Automatically distill context to its essential parts: sharper relevance, lower cost, and faster responses
• Blazing Fast – Adds typically < 1ms of overhead—so you get flexibility without latency tax
• Flexible Auth – Support for both API keys and OAuth (e.g., Claude.ai), so you can use your existing quotas anywhere
• Visual Control Plane – Intuitive UI to manage providers, routes, aliases, and models at a glance
• Client Side Usage Stats - Track token consumption, latency, cost estimates, and model selection per request—directly from your client
• Remote Control - Control your AI agents remotely via IM bots (Slack, Discord, Telegram, DingTalk, Feishu). Interact with your agents from anywhere without direct server access

Quick Start

Install

From npm (recommended)

# Install and run (auto service migration without any args)
npx tingly-box@latest

if any trouble, please check tingly-box process and port 12580 and confirm to kill them.

From source code

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

# 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

From Docker (Github)

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

Use with IDE, CLI, SDK and any AI application

Tool Integration

• 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

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.

Remote Control via IM Bots

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
• Slack
• Discord

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

Web Management UI

npx tingly-box@latest

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

Philosophy

• One endpoint, many providers – Consolidates multiple providers behind a single API with minimal configuration.
• Seamless integration – Works with SDKs and CLI tools with minimal setup.

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.

How to Contribute

We welcome contributions! Follow these steps, inspired by popular open-source repositories:

1. Fork the repository – Click the “Fork” button on GitHub.

2. Clone your fork

   git clone https://github.com/your-username/tingly-box.git
   cd tingly-box
   

3. Create a new branch

   git checkout -b feature/my-new-feature
   

4. Make your changes – Follow existing code style and add tests if applicable.

5. Run tests

   task test
   

6. Commit your changes

   git commit -m "Add concise description of your change"
   

7. Push your branch

   git push origin feature/my-new-feature
   

8. Open a Pull Request – Go to the GitHub repository and open a PR against main.

Support

Telegram	Wechat
https://t.me/+V1sqeajw1pYwMzU1	http://chv.ckcoa5.cn/t/OSFb

Early Contributors

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

License

This project is available under:

• MPL-2.0 – See LICENSE.txt
• Commercial License – See LICENSE-COMMERCIAL.txt

For commercial licensing inquiries, contact biz@tingly.dev.

Mozilla Public License Version 2.0 · © Tingly Dev