tingly-box

README

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

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
npx --registry=https://mirrors.huaweicloud.com/repository/npm/ -y tingly-box-bundle@latest
# or
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

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

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

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

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.25+	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.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

Support

Telegram	Wechat
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.