{"id":34618204,"url":"https://github.com/tingly-dev/tingly-box","last_synced_at":"2026-06-10T11:00:42.697Z","repository":{"id":332020953,"uuid":"1100971867","full_name":"tingly-dev/tingly-box","owner":"tingly-dev","description":"Your Intelligence, Orchestrated. Every builder. Every team. Every agent. For Everyone.","archived":false,"fork":false,"pushed_at":"2026-06-08T02:59:57.000Z","size":53687,"stargazers_count":306,"open_issues_count":51,"forks_count":28,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T04:24:29.256Z","etag":null,"topics":["agent","claude-code","gateway","llm","orches","orchestration"],"latest_commit_sha":null,"homepage":"https://tingly-dev.github.io/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tingly-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE-COMMERCIAL.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-21T02:32:46.000Z","updated_at":"2026-06-07T13:50:11.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tingly-dev/tingly-box","commit_stats":null,"previous_names":["tingly-dev/tingly-box"],"tags_count":385,"template":false,"template_full_name":null,"purl":"pkg:github/tingly-dev/tingly-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tingly-dev%2Ftingly-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tingly-dev%2Ftingly-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tingly-dev%2Ftingly-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tingly-dev%2Ftingly-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tingly-dev","download_url":"https://codeload.github.com/tingly-dev/tingly-box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tingly-dev%2Ftingly-box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34149132,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","claude-code","gateway","llm","orches","orchestration"],"created_at":"2025-12-24T14:55:25.637Z","updated_at":"2026-06-10T11:00:42.691Z","avatar_url":"https://github.com/tingly-dev.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Tingly Box Web UI Demo](./docs/hero.png)\n\n\u003e **Announcement:** Here is [fault record](https://github.com/tingly-dev/tingly-box/discussions/626). Please update to the latest version to resolve known issues. Thank you for your continued support.\n\n\n\u003ch1 align=\"center\"\u003eTingly Box\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#key-features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#integration-guide\"\u003eIntegration\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e •\n  \u003ca href=\"https://github.com/tingly-dev/tingly-box/issues\"\u003eIssues\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?style=flat\u0026logo=go\" alt=\"Go Version\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MPL%202.0-brightgreen.svg\" alt=\"License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey\" alt=\"Platform\" /\u003e\n\u003c/p\u003e\n\nTingly Box **serves agents, coordinates AI models, optimizes context, and routes requests** for maximum efficiency — with built-in **remote control and secure, customizable integrations**.\n\n![Tingly Box Web UI Demo](./docs/images/output.gif)\n\n\n## Key Features\n\n- **Agent-First Model Gateway** – Unified endpoint for agents — seamlessly bridge OpenAI, Anthropic, Google Gemini, and more with automatic protocol translation and native agent compatibility\n- **Agent Integration** – One-click config for Claude Code, OpenCode, Codex, Xcode, and more — transparent proxying for SDKs and CLI tools\n- **Agent Profiles** - Run agent like Claude Code with individual profiles, each profile can work with different model and agent config\n- **Remote Control via IM Bots** – Control AI agents remotely through Telegram, DingTalk, Feishu, Lark, Weixin, WeCom, Slack, and Discord\n- **Multi-Tenant API Tokens** – Isolate data per user with dedicated API tokens — each user gets their own usage tracking, provider access, and configuration\n- **Smart Routing Engine** – Intelligently route requests across models and tokens based on cost, speed, or custom policies — far beyond simple load balancing\n- **Flexible Authentication** – Support for both API keys and OAuth providers (Claude.ai, Codex, etc.) — use your existing quotas anywhere\n- **Visual Control Plane** – Intuitive web UI to manage providers, routes, aliases, models, and remote bots at a glance — no config files needed\n- **Client-Side Usage Analytics** – Track token consumption, latency, cost estimates, and model selection per request — directly from your client\n- **Blazing Fast Performance** – Adds typically **\u003c 1ms** of overhead — get flexibility without latency tax\n\n## Quick Start\n\n[English](https://github.com/tingly-dev/tingly-box/issues/678#issuecomment-4273812882) | [中文](https://github.com/tingly-dev/tingly-box/issues/678#issue-4244345496)\n\n### Install\n\n**From npm (recommended)**\n\n```bash\n# Install and run (auto restart, migrate and open webui while run without any args)\n# A golang binary release but npx to wrap cli for convenience\nnpx tingly-box@latest\n\n# or -y for convenience\nnpx -y tingly-box@latest\n\n# if any network trouble, try bundle with binary built-in\nnpx -y tingly-box-bundle@latest\n\n# npm mirror is supported for CN\nnpx --registry=https://mirrors.huaweicloud.com/repository/npm/ -y tingly-box-bundle@latest\n# or\nnpx --registry=http://mirrors.tencent.com/npm/ -y tingly-box-bundle@latest\n```\n\n\u003e if any trouble, please check tingly-box output, or call for an issue to help. \n\n**From Docker (GitHub Host)**\n\n```bash\nmkdir tingly-data\ndocker run -d \\\n  --name tingly-box \\\n  -p 12580:12580 \\\n  -v `pwd`/tingly-data:/home/tingly/.tingly-box \\\n  ghcr.io/tingly-dev/tingly-box\n```\n\n**From Docker Compose (Recommend for isolated env)**\n\n```bash\n# Build and start in detached mode\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f tingly-box\n\n# Stop services\ndocker-compose down\n\n# Access Web UI at http://localhost:12581\n# (Note: Port 12581 is used to avoid conflict with host tingly on 12580)\n```\n\n### Integration Guide\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAgent Integration - Claude Code / Claude Desktop / OpenCode / Codex / Xcode / VSCode / OpenClaw\u003c/strong\u003e\u003c/summary\u003e\n\n- Claude Code (support 1-click config)\n- OpenCode (support 1-click config)\n- Xcode (require manual config)\n- ……\n\nAny application is ready to use.\n\n\u003e We've provided detailed config guide in application\n\n![Agent Integration Demo](./docs/images/5-claude-code.png)\n\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eRemote Control Agent via IM Bots - TG / DingTalk / Feishu / Lark / Weixin / WecCom\u003c/strong\u003e\u003c/summary\u003e\n\nTingly Box now supports remote control through popular IM platforms. Interact with your AI agents remotely without direct server access.\n\n**Supported Platforms**\n\n- ✅ Telegram\n- ✅ DingTalk\n- ✅ Feishu\n- ✅ Lark\n- ✅ Weixin\n- ✅ WeCom\n\n**Quick Setup**\n\n1. Open Web UI like `http://localhost:12580`\n2. Navigate to **Remote** section\n3. Configure your preferred IM platform bot\n4. Start interacting with your agents remotely\n\n**Use Cases**\n\n- Execute tasks and queries from your phone or any device\n- Team collaboration with shared agent access\n- Monitor and control agents while away from your workstation\n\n![Remote Control Demo](./docs/images/7-remote.png)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eOpenAI SDK\u003c/strong\u003e\u003c/summary\u003e\n\n```python\nfrom openai import OpenAI\n\nclient = OpenAI(\n    api_key=\"your-tingly-model-token\",\n    base_url=\"http://localhost:12580/tingly/openai/v1\"\n)\n\nresponse = client.chat.completions.create(\n    model=\"tingly-gpt\",\n    messages=[{\"role\": \"user\", \"content\": \"Hello!\"}]\n)\nprint(response)\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eAnthropic SDK\u003c/strong\u003e\u003c/summary\u003e\n\n```python\nfrom anthropic import Anthropic\n\nclient = Anthropic(\n    api_key=\"your-tingly-model-token\",\n    base_url=\"http://localhost:12580/tingly/anthropic\"\n)\n\nresponse = client.messages.create(\n    model=\"tingly\",\n    max_tokens=1024,\n    messages=[\n        {\"role\": \"user\", \"content\": \"Hello!\"}\n    ]\n)\nprint(response)\n```\n\n\u003e Tingly Box proxies requests transparently for SDKs and CLI tools.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eUsing OAuth Providers\u003c/strong\u003e\u003c/summary\u003e\n\nYou can also add OAuth providers (like Claude Code) and use your existing quota in any OpenAI-compatible tool:\n\n```bash\n# 1. Add Claude Code via OAuth in Web UI (http://localhost:12580)\n# 2. Configure your tool with Tingly Box endpoint\n```\n\nRequests route through your OAuth-authorized provider, using your existing Claude Code quota instead of requiring a separate API key.\n\nThis works with any tool that supports OpenAI-compatible endpoints: Cherry Studio, VS Code extensions, or custom AI agents.\n\n![OAuth Provider Demo](./docs/images/3-connect-ai.png)\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eWeb Management UI\u003c/strong\u003e\u003c/summary\u003e\n\nLaunch the web management interface:\n\n```bash\nnpx tingly-box@latest\n```\n\nThen open `http://localhost:12580` in your browser.\n\n![Dashboard](./docs/images/1-dashboard.png)\n\n\u003c/details\u003e\n\n## Documentation\n\n**[User Manual](./docs/user-manual.md)** – Installation, configuration, and operational guide\n\n**[Guardrails](./docs/guardrails.md)** – Policy-based safety checks, built-in protections, and protected credential masking\n\n**[MCP Web Tools](./docs/mcp-web-tools.md)** – Local stdio MCP server for `web_search` / `web_fetch`\n\n## Contributing\n\nBy contributing to this repository, you agree that your contributions may be\nincluded in this project under the MPL-2.0 and may also be used by Tingly Inc.\nunder separate commercial licensing terms.\n\nSee CONTRIBUTING.md and NOTICE for details.\n\n---\n\nWe welcome contributions! Check the steps below to build from source code.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eContributing Guide — Build \u0026amp; Dev\u003c/strong\u003e\u003c/summary\u003e\n\n### Prerequisites\n\n| Tool | Version | Install |\n|------|---------|---------|\n| Go | 1.26+ | https://go.dev/doc/install |\n| Node.js | 20+ | https://nodejs.org/ |\n| pnpm | latest | `npm install -g pnpm` |\n| task | latest | `go install github.com/go-task/task/v3/cmd/task@latest` or https://taskfile.dev/installation/ |\n\n\u003e Tip: you can also copy individual shell commands out of `Taskfile.yml` and run them directly if you prefer not to install `task`.\n\n### 1. Clone and init submodules\n\n```bash\ngit clone https://github.com/tingly-dev/tingly-box.git\ncd tingly-box\ngit submodule update --init --recursive\n```\n\n### 2. Frontend development\n\nThe frontend is a React + Vite app located in `frontend/`. You can work on it independently of the Go backend.\n\n\u003e **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/\u003ctoken\u003e`). If you need to retrieve it later, run:\n\u003e ```bash\n\u003e tingly-box token view auth --reveal\n\u003e ```\n\n**Mock mode** – no running backend required, uses built-in fixture data:\n\n```bash\ntask web:mock\n# or directly:\ncd frontend \u0026\u0026 pnpm install \u0026\u0026 pnpm dev:mock\n```\n\nOpen http://localhost:9245 in your browser. Use the token obtained above to log in.\n\n**Dev mode** – proxies API calls to a local backend (start the backend first, see step 3):\n\n```bash\ntask web\n# or directly:\ncd frontend \u0026\u0026 pnpm install \u0026\u0026 pnpm dev\n```\n\n### 3. Backend development\n\nRun the Go server (hot-reload via `go run`):\n\n```bash\ntask start\n# or directly:\ngo run ./cli/tingly-box --verbose start --debug --port 12580 --browser=false\n```\n\nOpen http://localhost:12580 in your browser (serves the last built frontend bundle).\n\n### 4. Full build (frontend + backend binary)\n\nBuilds the frontend, embeds it into the binary, then compiles Go:\n\n```bash\ntask build\n```\n\nThe output binary is written to `./build/tingly-box`.\n\n### 5. GUI binary (Wails) *(optional)*\n\n\u003e The GUI build is not yet publicly released. Skip this step unless you are specifically working on the desktop app.\n\n```bash\ntask wails:build\n```\n\n### Other useful commands\n\n```bash\ntask swagger        # Regenerate openapi.json from Go source\ntask codegen        # Regenerate frontend API client from openapi.json\ntask go:test        # Run Go unit tests\n```\n\n\u003c/details\u003e\n\n## Support\n\n| Telegram    | Wechat |\n| :--------: | :-------: |\n| \u003cimg width=\"196\" height=\"196\" alt=\"image\" src=\"https://github.com/user-attachments/assets/56022b70-97da-498f-bf83-822a11668fa7\" /\u003e | \u003cimg width=\"196\" height=\"196\" alt=\"image\" src=\"https://github.com/user-attachments/assets/30d24cc5-666c-425a-b8d2-5f353af453de\" /\u003e |\n| https://t.me/+V1sqeajw1pYwMzU1 | tingly-box |\n\n## Early Contributors\n\nSpecial badges are minted to recognize the contributions from following contributors:\n\n\u003cbr /\u003e\n\n\u003ctable border=\"0\" cellpadding=\"0\" cellspacing=\"0\" style=\"border:none; border-collapse:collapse; \"\u003e\n  \u003ctr style=\"border:none;\"\u003e\n    \u003ctd style=\"border:none; padding:4px;\"\u003e\n      \u003cimg width=\"140\" height=\"140\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ee8bfa35-3c19-4ddb-8e2d-cb0416f3f7b7\" style=\"display:block; border:none;\" /\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"border:none; padding:4px;\"\u003e\n      \u003cimg width=\"144\" height=\"144\" alt=\"image\" src=\"https://github.com/user-attachments/assets/91d2fed3-158a-4dd9-9f8c-9ac552d4dc22\" style=\"display:block; border:none;\" /\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"border:none; padding:4px;\"\u003e\n      \u003cimg width=\"140\" height=\"140\" alt=\"image\" src=\"https://github.com/user-attachments/assets/9e485b5c-dc2d-4d4e-be69-f8559bbb830c\" style=\"display:block; border:none;\" /\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"border:none; padding:4px;\"\u003e\n      \u003cimg width=\"133\" height=\"133\" alt=\"image\" src=\"https://github.com/user-attachments/assets/8450f42c-61e4-4cce-8025-95956146fc35\" style=\"display:block; border:none;\" /\u003e\n    \u003c/td\u003e\n    \u003ctd style=\"border:none; padding:4px;\"\u003e\n      \u003cimg width=\"140\" height=\"140\" alt=\"image\" src=\"https://github.com/user-attachments/assets/1b216610-6fe3-4567-8066-dbc5249b2cbc\" style=\"display:block; border:none;\" /\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n## Contributors\n\n[![Contributors](https://contrib.rocks/image?repo=tingly-dev/tingly-box)](https://github.com/tingly-dev/tingly-box/graphs/contributors)\n\n## License\n\nThis project is available under:\n- **MPL-2.0 · © Tingly Dev** – See [LICENSE.txt](./LICENSE.txt)\n- **Commercial License · © Tingly Dev** – See [LICENSE-COMMERCIAL.txt](./LICENSE-COMMERCIAL.txt)\n\nFor commercial licensing inquiries, contact [biz@tingly.dev](mailto:biz@tingly.dev).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftingly-dev%2Ftingly-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftingly-dev%2Ftingly-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftingly-dev%2Ftingly-box/lists"}