Announcement: We have identified a critical bug in protocol and remote control in v0.260306.0. Please update to the latest version to resolve this issue. Thank you for your continued support.

Tingly Box Web UI Demo

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.

Tingly Box Web UI Demo

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-generator-cli

# 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`
# - openapi-generator-cli: `npm install @openapitools/openapi-generator-cli -g`

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

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

Remote Control Demo

Web Management UI

npx tingly-box@latest

Documentation

User Manual – Installation, configuration, and operational guide

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:

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

Clone your fork

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

Create a new branch
```
git checkout -b feature/my-new-feature
```
Make your changes – Follow existing code style and add tests if applicable.
Run tests
```
task test
```

Commit your changes

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

Push your branch
```
git push origin feature/my-new-feature
```
Open a Pull Request – Go to the GitHub repository and open a PR against main.