# tingly-box
**Repository Path**: mdunion/tingly-box
## Basic Information
- **Project Name**: tingly-box
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-21
- **Last Updated**: 2026-03-21
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
**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
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)**
```bash
# 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*
```bash
# 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)**
```bash
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**
```python
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**
```python
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:
```bash
# 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**
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
```bash
npx tingly-box@latest
```
## Documentation
**[User Manual](./docs/user-manual.md)** – 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.
## **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**
```bash
git clone https://github.com/your-username/tingly-box.git
cd tingly-box
```
3. **Create a new branch**
```bash
git checkout -b feature/my-new-feature
```
4. **Make your changes** – Follow existing code style and add tests if applicable.
5. **Run tests**
```bash
task test
```
6. **Commit your changes**
```bash
git commit -m "Add concise description of your change"
```
7. **Push your branch**
```bash
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:
---
Mozilla Public License Version 2.0 · © Tingly Dev