GitHub Go Monthly Trending

QuantumNous/new-api

A unified AI model hub for aggregation & distribution. It supports cross-converting various LLMs into OpenAI-compatible, Claude-compatible, or Gemini-compatible formats. A centralized gateway for personal and enterprise model management. 🍥

New API

🍥 Next-Generation LLM Gateway and AI Asset Management System

简体中文 | 繁體中文 | English | Français | 日本語

Quick Start • Key Features • Deployment • Documentation • Help

📝 Project Description

Important

This project is intended solely for lawful and authorized AI API gateway, organization-level authentication, multi-model management, usage analytics, cost accounting, and private deployment scenarios.
Users must lawfully obtain upstream API keys, accounts, model services, and interface permissions, and must comply with upstream terms of service and applicable laws and regulations.
Users should ensure their use complies with upstream terms of service and applicable laws and regulations.
When providing generative AI services to the public, users should comply with applicable regulatory requirements and fulfill all filing, licensing, content safety, real-name verification, log retention, tax, and upstream authorization obligations required by their jurisdiction.

🤝 Trusted Partners

No particular order

🙏 Special Thanks

Thanks to JetBrains for providing free open-source development license for this project

🚀 Quick Start

Using Docker Compose (Recommended)

# Clone the project
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# Edit docker-compose.yml configuration
nano docker-compose.yml

# Start the service
docker-compose up -d

Using Docker Commands

# Pull the latest image
docker pull calciumion/new-api:latest

# Using SQLite (default)
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

# Using MySQL
docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

💡 Tip: -v ./data:/data will save data in the data folder of the current directory, you can also change it to an absolute path like -v /your/custom/path:/data

🎉 After deployment is complete, visit http://localhost:3000 to start using!

Warning

When operating this project as a public generative AI service or API resale service, users should first complete all required filing, licensing, content safety, real-name verification, log retention, tax, payment, and upstream authorization obligations.

📖 For more deployment methods, please refer to Deployment Guide

📚 Documentation

📖 Official Documentation |

Quick Navigation:

Category	Link
🚀 Deployment Guide	Installation Documentation
⚙️ Environment Configuration	Environment Variables
📡 API Documentation	API Documentation
❓ FAQ	FAQ
💬 Community Interaction	Communication Channels

✨ Key Features

For detailed features, please refer to Features Introduction

🎨 Core Functions

Feature	Description
🎨 New UI	Modern user interface design
🌍 Multi-language	Supports Simplified Chinese, Traditional Chinese, English, French, Japanese
🔄 Data Compatibility	Fully compatible with the original One API database
📈 Data Dashboard	Visual console and statistical analysis
🔒 Permission Management	Token grouping, model restrictions, user management

💰 Authorized Usage Accounting and Billing

✅ Internal top-up and quota allocation for lawful authorized scenarios (EPay, Stripe)
✅ Organization-level per-request, usage-based, and cache-hit cost accounting
✅ Cache billing statistics for OpenAI, Azure, DeepSeek, Claude, Qwen, and supported models
✅ Flexible billing policies for internal management or authorized enterprise customers

🔐 Authorization and Security

😈 Discord authorization login
🤖 LinuxDO authorization login
📱 Telegram authorization login
🔑 OIDC unified authentication
🔍 Key quota query usage (with new-api-key-tool)

🚀 Advanced Features

API Format Support:

⚡ OpenAI Responses
⚡ OpenAI Realtime API (including Azure)
⚡ Claude Messages
⚡ Google Gemini
🔄 Rerank Models (Cohere, Jina)

Intelligent Routing:

⚖️ Channel weighted random
🔄 Automatic retry on failure
🚦 User-level model rate limiting

Format Conversion:

🔄 OpenAI Compatible ⇄ Claude Messages
🔄 OpenAI Compatible → Google Gemini
🔄 Google Gemini → OpenAI Compatible - Text only, function calling not supported yet
🚧 OpenAI Compatible ⇄ OpenAI Responses - In development
🔄 Thinking-to-content functionality

Reasoning Effort Support:

View detailed configuration

OpenAI series models:

o3-mini-high - High reasoning effort
o3-mini-medium - Medium reasoning effort
o3-mini-low - Low reasoning effort
gpt-5-high - High reasoning effort
gpt-5-medium - Medium reasoning effort
gpt-5-low - Low reasoning effort

Claude thinking models:

claude-3-7-sonnet-20250219-thinking - Enable thinking mode

Google Gemini series models:

gemini-2.5-flash-thinking - Enable thinking mode
gemini-2.5-flash-nothinking - Disable thinking mode
gemini-2.5-pro-thinking - Enable thinking mode
gemini-2.5-pro-thinking-128 - Enable thinking mode with thinking budget of 128 tokens
You can also append -low, -medium, or -high to any Gemini model name to request the corresponding reasoning effort (no extra thinking-budget suffix needed).

🤖 Model Support

For details, please refer to API Documentation - Gateway Interface

Model Type	Description	Documentation
🤖 OpenAI-Compatible	OpenAI compatible models	Documentation
🤖 OpenAI Responses	OpenAI Responses format	Documentation
🎨 Midjourney-Proxy	Midjourney-Proxy(Plus)	Documentation
🎵 Suno-API	Suno API	Documentation
🔄 Rerank	Cohere, Jina	Documentation
💬 Claude	Messages format	Documentation
🌐 Gemini	Google Gemini format	Documentation
🔧 Dify	ChatFlow mode	-
🎯 Custom upstream	Supports configuring legally authorized upstream endpoints	-

📡 Supported Interfaces

View complete interface list

🚢 Deployment

Tip

Latest Docker image: calciumion/new-api:latest

📋 Deployment Requirements

Component	Requirement
Local database	SQLite (Docker must mount `/data` directory)
Remote database	MySQL ≥ 5.7.8 or PostgreSQL ≥ 9.6
Container engine	Docker / Docker Compose

⚙️ Environment Variable Configuration

Common environment variable configuration

Variable Name	Description	Default Value
`SESSION_SECRET`	Session secret (required for multi-machine deployment)	-
`CRYPTO_SECRET`	Encryption secret (required for Redis)	-
`SQL_DSN`	Database connection string	-
`REDIS_CONN_STRING`	Redis connection string	-
`STREAMING_TIMEOUT`	Streaming timeout (seconds)	`300`
`STREAM_SCANNER_MAX_BUFFER_MB`	Max per-line buffer (MB) for the stream scanner; increase when upstream sends huge image/base64 payloads	`64`
`MAX_REQUEST_BODY_MB`	Max request body size (MB, counted after decompression; prevents huge requests/zip bombs from exhausting memory). Exceeding it returns `413`	`32`
`AZURE_DEFAULT_API_VERSION`	Azure API version	`2025-04-01-preview`
`ERROR_LOG_ENABLED`	Error log switch	`false`
`PYROSCOPE_URL`	Pyroscope server address	-
`PYROSCOPE_APP_NAME`	Pyroscope application name	`new-api`
`PYROSCOPE_BASIC_AUTH_USER`	Pyroscope basic auth user	-
`PYROSCOPE_BASIC_AUTH_PASSWORD`	Pyroscope basic auth password	-
`PYROSCOPE_MUTEX_RATE`	Pyroscope mutex sampling rate	`5`
`PYROSCOPE_BLOCK_RATE`	Pyroscope block sampling rate	`5`
`HOSTNAME`	Hostname tag for Pyroscope	`new-api`

📖 Complete configuration: Environment Variables Documentation

🔧 Deployment Methods

Method 1: Docker Compose (Recommended)

# Clone the project
git clone https://github.com/QuantumNous/new-api.git
cd new-api

# Edit configuration
nano docker-compose.yml

# Start service
docker-compose up -d

Method 2: Docker Commands

Using SQLite:

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

Using MySQL:

docker run --name new-api -d --restart always \
  -p 3000:3000 \
  -e SQL_DSN="root:123456@tcp(localhost:3306)/oneapi" \
  -e TZ=Asia/Shanghai \
  -v ./data:/data \
  calciumion/new-api:latest

💡 Path explanation:

./data:/data - Relative path, data saved in the data folder of the current directory

You can also use absolute path, e.g.: /your/custom/path:/data

Method 3: BaoTa Panel

Install BaoTa Panel (≥ 9.2.0 version)
Search for New-API in the application store
One-click installation

📖 Tutorial with images

⚠️ Multi-machine Deployment Considerations

Warning

Must set SESSION_SECRET - Otherwise login status inconsistent
Shared Redis must set CRYPTO_SECRET - Otherwise data cannot be decrypted

🔄 Channel Retry and Cache

Retry configuration: Settings → Operation Settings → General Settings → Failure Retry Count

Cache configuration:

REDIS_CONN_STRING: Redis cache (recommended)
MEMORY_CACHE_ENABLED: Memory cache

🔗 Related Projects

Upstream Projects

Project	Description
One API	Original project base
Midjourney-Proxy	Midjourney interface support

Supporting Tools

Project	Description
new-api-key-tool	Key quota query tool
new-api-horizon	New API high-performance optimized version

💬 Help Support

📖 Documentation Resources

Resource	Link
📘 FAQ	FAQ
💬 Community Interaction	Communication Channels
🐛 Issue Feedback	Issue Feedback
📚 Complete Documentation	Official Documentation

🤝 Contribution Guide

Welcome all forms of contribution!

🐛 Report Bugs
💡 Propose New Features
📝 Improve Documentation
🔧 Submit Code

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3).

Additional terms under AGPLv3 Section 7 apply. Modified versions must preserve the author attribution notice Frontend design and development by New API contributors. in the appropriate legal notices and in any prominent about, legal, footer, or attribution location presented by the user interface.

Modified versions that present a user interface must also preserve a visible link to the original project: https://github.com/QuantumNous/new-api.

This is an open-source project developed based on One API (MIT License).

If your organization's policies do not permit the use of AGPLv3-licensed software, or if you wish to avoid the open-source obligations of AGPLv3, please contact us at: support@quantumnous.com

🌟 Star History

💖 Thank you for using New API

If this project is helpful to you, welcome to give us a ⭐️ Star！

Official Documentation • Issue Feedback • Latest Release

_{Built with ❤️ by QuantumNous}

google/osv-scanner

Vulnerability scanner written in Go which uses the data provided by https://osv.dev

Use OSV-Scanner to find existing vulnerabilities affecting your project's dependencies. OSV-Scanner provides an officially supported frontend to the OSV database and CLI interface to OSV-Scalibr that connects a project’s list of dependencies with the vulnerabilities that affect them.

OSV-Scanner supports a wide range of project types, package managers and features, including but not limited to:

Languages: C/C++, Dart, Elixir, Go, Java, Javascript, PHP, Python, R, Ruby, Rust.
Package Managers: npm, pip, yarn, maven, go modules, cargo, gem, composer, nuget and others.
Operating Systems: Detects vulnerabilities in OS packages on Linux systems.
Containers: Scans container images for vulnerabilities in their base images and included packages.
Guided Remediation: Provides recommendations for package version upgrades based on criteria such as dependency depth, minimum severity, fix strategy, and return on investment.

OSV-Scanner uses the extensible OSV-Scalibr library under the hood to provide this functionality. If a language or package manager is not supported currently, please file a feature request.

Underlying database

The underlying database, OSV.dev has several benefits in comparison with closed source advisory databases and scanners:

Covering most open source language and OS ecosystems (including Git), it’s comprehensive.
Each advisory comes from an open and authoritative source (e.g. GitHub Security Advisories, RustSec Advisory Database, Ubuntu security notices)
Anyone can suggest improvements to advisories, resulting in a very high quality database.
The OSV format unambiguously stores information about affected versions in a machine-readable format that precisely maps onto a developer’s list of packages

The above all results in accurate and actionable vulnerability notifications, which reduces the time needed to resolve them. Check out OSV.dev for more details!

Basic installation

To install OSV-Scanner, please refer to the installation section of our documentation. OSV-Scanner releases can be found on the releases page of the GitHub repository. The recommended method is to download a prebuilt binary for your platform. Alternatively, you can use go install github.com/google/osv-scanner/v2/cmd/osv-scanner@latest to build it from source.

Key Features

For more information, please read our detailed documentation to learn how to use OSV-Scanner. For detailed information about each feature, click their titles in this README.

Please note: These are the instructions for the latest OSV-Scanner V2 beta. If you are using V1, checkout the V1 README and documentation instead.

Scanning a source directory

$ osv-scanner scan source -r /path/to/your/dir

This command will recursively scan the specified directory for any supported package files, such as package.json, go.mod, pom.xml, etc. and output any discovered vulnerabilities.

OSV-Scanner has the option of using call analysis to determine if a vulnerable function is actually being used in the project, resulting in fewer false positives, and actionable alerts.

OSV-Scanner can also detect vendored C/C++ code for vulnerability scanning. See here for details.

Supported Lockfiles

OSV-Scanner supports 11+ language ecosystems and 19+ lockfile types. To check if your ecosystem is covered, please check out our detailed documentation.

Container Scanning

OSV-Scanner also supports comprehensive, layer-aware scanning for container images to detect vulnerabilities in the following operating system packages and language-specific dependencies.

Distro Support	Language Artifacts Support
Alpine OS	Go
Debian	Java
Ubuntu	Node
	Python

See the full documentation for details on support.

Usage:

$ osv-scanner scan image my-image-name:tag

License Scanning

Check your dependencies' licenses using deps.dev data. For a summary:

osv-scanner --licenses path/to/repository

To check against an allowed license list (SPDX format):

osv-scanner --licenses="MIT,Apache-2.0" path/to/directory

Offline Scanning

Scan your project against a local OSV database. No network connection is required after the initial database download. The database can also be manually downloaded.

osv-scanner --offline --download-offline-databases ./path/to/your/dir

Guided Remediation (Experimental)

Warning

Guided remediation (the fix command) can be risky when run on untrusted projects. It may trigger the package manager to execute scripts or follow external registries specified in the project. Please ensure you trust the source code and artifacts before proceeding.

OSV-Scanner provides guided remediation, a feature that suggests package version upgrades based on criteria such as dependency depth, minimum severity, fix strategy, and return on investment. We currently support remediating vulnerabilities in the following files:

Ecosystem	File Format (Type)	Supported Remediation Strategies
npm	`package-lock.json` (lockfile)	`in-place`
npm	`package.json` (manifest)	`relock`
Maven	`pom.xml` (manifest)	`override`

This is available as a headless CLI command, as well as an interactive mode.

Example (for npm)

$ osv-scanner fix \
    --max-depth=3 \
    --min-severity=5 \
    --ignore-dev  \
    --strategy=in-place \
    -L path/to/package-lock.json

Interactive mode (for npm)

$ osv-scanner fix \
    -M path/to/package.json \
    -L path/to/package-lock.json

Data Sources and Privacy

OSV-Scanner communicates with the following external services during operation:

OSV.dev API

The primary data source for vulnerability information. OSV-Scanner queries this API to check packages for known vulnerabilities and to identify vendored C/C++ dependencies. Data sent includes package names, versions, ecosystems, and file hashes. Use --offline mode to disable network requests and scan against a local database instead.

deps.dev API

Used for supplementary package information:

Dependency resolution: Resolves dependency graphs for vulnerability scanning and remediation
Container image scanning: Queries container image metadata for vulnerability detection
License scanning (--licenses flag): Retrieves license information for packages
Package deprecation: Checks if packages are deprecated

Data sent includes package names, versions, and ecosystems. No source code is transmitted.

Package Registries

When using native registry for dependency resolution (instead of deps.dev), OSV-Scanner may query:

Registry	URL	Used For
Maven Central	`repo.maven.apache.org/maven2`	Maven package metadata and POM files
npm Registry	`registry.npmjs.org`	npm package metadata
PyPI	`pypi.org`	Python package metadata

Contribute

Report Problems

If you have what looks like a bug, please use the GitHub issue tracking system. Before you file an issue, please search existing issues to see if your issue is already covered.

Contributing code to `osv-scanner`

See CONTRIBUTING.md for documentation on how to contribute code.

Star History

Wei-Shaw/sub2api

Sub2API-CRS2 一站式开源中转服务，让 Claude、Openai 、Gemini、Antigravity订阅统一接入，支持拼车共享，更高效分摊成本，原生工具无缝使用。

Sub2API

AI API Gateway Platform for Subscription Quota Distribution

English | 中文 | 日本語

Sub2API officially uses only the domains sub2api.org and pincc.ai. Other websites using the Sub2API name may be third-party deployments or services and are not affiliated with this project. Please verify and exercise your own judgment.

Demo

Try Sub2API online: https://demo.sub2api.org/

Demo credentials (shared demo environment; not created automatically for self-hosted installs):

Email	Password
admin@sub2api.org	admin123

Overview

Sub2API is an AI API gateway platform designed to distribute and manage API quotas from AI product subscriptions. Users can access upstream AI services through platform-generated API Keys, while the platform handles authentication, billing, load balancing, and request forwarding.

Features

Multi-Account Management - Support multiple upstream account types (OAuth, API Key)
API Key Distribution - Generate and manage API Keys for users
Precise Billing - Token-level usage tracking and cost calculation
Smart Scheduling - Intelligent account selection with sticky sessions
Concurrency Control - Per-user and per-account concurrency limits
Rate Limiting - Configurable request and token rate limits
Built-in Payment System - Supports EasyPay, Alipay, WeChat Pay, and Stripe for user self-service top-up, no separate payment service needed (Configuration Guide)
Admin Dashboard - Web interface for monitoring and management
External System Integration - Embed external systems (e.g. ticketing) via iframe to extend the admin dashboard

❤️ Sponsors

Want to appear here?

	PinCC is the official relay service built on Sub2API, offering stable access to Claude Code, Codex, Gemini and other popular models — ready to use, no deployment or maintenance required.
	Thanks to PackyCode for sponsoring this project! PackyCode is a reliable and efficient API relay service provider, offering relay services for Claude Code, Codex, Gemini, and more. PackyCode provides special discounts for our software users: register using this link and enter the "sub2api" promo code during first recharge to get 10% off.
	Thanks to CTok.ai for sponsoring this project! CTok.ai is dedicated to building a one-stop AI programming tool service platform. We offer professional Claude Code packages and technical community services, with support for Google Gemini and OpenAI Codex. Through carefully designed plans and a professional tech community, we provide developers with reliable service guarantees and continuous technical support, making AI-assisted programming a true productivity tool. Click here to register!
	Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for sub2api users: if you register via this link, you'll receive an extra 10% bonus credit on your first top-up!
	Thanks to SilkAPI for sponsoring this project! SilkAPI is a relay service built on Sub2API, specializing in providing high-speed and stable Codex API relay.
	Thanks to YLS Code for sponsoring this project! YLS Code is dedicated to building secure enterprise-grade Coding Agent productivity services, offering stable and fast Codex / Claude / Gemini subscription services along with pay-as-you-go API options for flexible choices. Register now for a limited-time 3-day Codex trial bonus!
	Thanks to AICodeMirror for sponsoring this project! AICodeMirror provides official high-stability relay services for Claude Code / Codex / Gemini CLI, with enterprise-grade concurrency, fast invoicing, and 24/7 dedicated technical support. Claude Code / Codex / Gemini official channels at 38% / 2% / 9% of original price, with extra discounts on top-ups! AICodeMirror offers special benefits for sub2api users: register via this link to enjoy 20% off your first top-up, and enterprise customers can get up to 25% off!
	Huge thanks to BmoPlus for sponsoring this project! BmoPlus is a highly reliable AI account provider built strictly for heavy AI users and developers. They offer rock-solid, ready-to-use accounts and official top-up services for ChatGPT Plus / ChatGPT Pro (Full Warranty) / Claude Pro / Super Grok / Gemini Pro. By registering and ordering through BmoPlus - Premium AI Accounts & Top-ups, users can unlock the mind-blowing rate of 10% of the official GPT subscription price (90% OFF)
	Thanks to Bestproxy for sponsoring this project! Bestproxy provides high-purity residential IPs with dedicated one-IP-per-account support. By combining real home networks with fingerprint isolation, it enables link environment isolation and reduces the probability of association-based risk control.
	Thanks to PatewayAI for sponsoring this project! PatewayAI is a premium model API relay service provider built for heavy AI developers, focused on direct official connections. Offering the full Claude series and Codex series models, 100% sourced directly from official providers — no dilution, no substitution, open to verification. Billing is fully transparent with token-level invoices that can be audited line by line. Enterprise-grade high concurrency is also supported, with a dedicated management platform for enterprise clients. Enterprise customers can sign formal contracts and receive invoices. Visit the official website for more details and contact information. Register now via this link to receive $3 in trial credits. User top-ups start as low as 60% off, and referring friends earns both parties rewards — referral bonuses up to $150.
	Thanks to PPToken.org for sponsoring this project! PPToken.org specializes in GPT model API relay services, supporting Codex, Claude Code, OpenAI-compatible clients, and Gemini CLI integration. Top-ups are 1:1 (¥1 = $1 credit); GPT models start at 0.16x rate multiplier, with overall cost at roughly 2.2% of official pricing and first-token latency around 1 second — ideal for developers seeking low-cost, high-speed access to GPT model capabilities. Technical support: 24/7 real human responses (no bots), @tech in the group chat and get a reply within 10 minutes. Sponsor benefit: the first 200 users who register via the exclusive registration link and enter promo code `SUB2API` can claim free Codex / Claude Code trial credits — no minimum spend, no card required.

Ecosystem

Community projects that extend or integrate with Sub2API:

Project	Description	Features
~~Sub2ApiPay~~	~~Self-service payment system~~	Now Built-in — Payment is now integrated into Sub2API, no separate deployment needed. See Payment Configuration Guide
sub2api-mobile	Mobile admin console	Cross-platform app (iOS/Android/Web) for user management, account management, monitoring dashboard, and multi-backend switching; built with Expo + React Native

Tech Stack

Component	Technology
Backend	Go 1.25.7, Gin, Ent
Frontend	Vue 3.4+, Vite 5+, TailwindCSS
Database	PostgreSQL 15+
Cache/Queue	Redis 7+

Nginx Reverse Proxy Note

When using Nginx as a reverse proxy for Sub2API (or CRS) with Codex CLI, add the following to the http block in your Nginx configuration:

underscores_in_headers on;

Nginx drops headers containing underscores by default (e.g. session_id), which breaks sticky session routing in multi-account setups.

Deployment

Method 1: Script Installation (Recommended)

One-click installation script that downloads pre-built binaries from GitHub Releases.

Prerequisites

Linux server (amd64 or arm64)
PostgreSQL 15+ (installed and running)
Redis 7+ (installed and running)
Root privileges

Installation Steps

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash

The script will:

Detect your system architecture
Download the latest release
Install binary to /opt/sub2api
Create systemd service
Configure system user and permissions

Post-Installation

# 1. Start the service
sudo systemctl start sub2api

# 2. Enable auto-start on boot
sudo systemctl enable sub2api

# 3. Open Setup Wizard in browser
# http://YOUR_SERVER_IP:8080

The Setup Wizard will guide you through:

Database configuration
Redis configuration
Admin account creation

Upgrade

You can upgrade directly from the Admin Dashboard by clicking the Check for Updates button in the top-left corner.

The web interface will:

Check for new versions automatically
Download and apply updates with one click
Support rollback if needed

Useful Commands

# Check status
sudo systemctl status sub2api

# View logs
sudo journalctl -u sub2api -f

# Restart service
sudo systemctl restart sub2api

# Uninstall
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash -s -- uninstall -y

Method 2: Docker Compose (Recommended)

Deploy with Docker Compose, including PostgreSQL and Redis containers.

Prerequisites

Docker 20.10+
Docker Compose v2+

Quick Start (One-Click Deployment)

Use the automated deployment script for easy setup:

# Create deployment directory
mkdir -p sub2api-deploy && cd sub2api-deploy

# Download and run deployment preparation script
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# Start services
docker compose up -d

# View logs
docker compose logs -f sub2api

What the script does:

Downloads docker-compose.local.yml (saved as docker-compose.yml) and .env.example
Generates secure credentials (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
Creates .env file with auto-generated secrets
Creates data directories (uses local directories for easy backup/migration)
Displays generated credentials for your reference

Manual Deployment

If you prefer manual setup:

# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. Copy environment configuration
cp .env.example .env

# 3. Edit configuration (generate secure passwords)
nano .env

Required configuration in .env:

# PostgreSQL password (REQUIRED)
POSTGRES_PASSWORD=your_secure_password_here

# JWT Secret (RECOMMENDED - keeps users logged in after restart)
JWT_SECRET=your_jwt_secret_here

# TOTP Encryption Key (RECOMMENDED - preserves 2FA after restart)
TOTP_ENCRYPTION_KEY=your_totp_key_here

# Optional: Admin account
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# Optional: Custom port
SERVER_PORT=8080

Generate secure secrets:

# Generate JWT_SECRET
openssl rand -hex 32

# Generate TOTP_ENCRYPTION_KEY
openssl rand -hex 32

# Generate POSTGRES_PASSWORD
openssl rand -hex 32

# 4. Create data directories (for local version)
mkdir -p data postgres_data redis_data

# 5. Start all services
# Option A: Local directory version (recommended - easy migration)
docker compose -f docker-compose.local.yml up -d

# Option B: Named volumes version (simple setup)
docker compose up -d

# 6. Check status
docker compose -f docker-compose.local.yml ps

# 7. View logs
docker compose -f docker-compose.local.yml logs -f sub2api

Deployment Versions

Version	Data Storage	Migration	Best For
docker-compose.local.yml	Local directories	✅ Easy (tar entire directory)	Production, frequent backups
docker-compose.yml	Named volumes	⚠️ Requires docker commands	Simple setup

Recommendation: Use docker-compose.local.yml (deployed by script) for easier data management.

Access

Open http://YOUR_SERVER_IP:8080 in your browser.

If admin password was auto-generated, find it in logs:

docker compose -f docker-compose.local.yml logs sub2api | grep "admin password"

Upgrade

# Pull latest image and recreate container
docker compose -f docker-compose.local.yml pull
docker compose -f docker-compose.local.yml up -d

Easy Migration (Local Directory Version)

When using docker-compose.local.yml, migrate to a new server easily:

# On source server
docker compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

# Transfer to new server
scp sub2api-complete.tar.gz user@new-server:/path/

# On new server
tar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker compose -f docker-compose.local.yml up -d

Useful Commands

# Stop all services
docker compose -f docker-compose.local.yml down

# Restart
docker compose -f docker-compose.local.yml restart

# View all logs
docker compose -f docker-compose.local.yml logs -f

# Remove all data (caution!)
docker compose -f docker-compose.local.yml down
rm -rf data/ postgres_data/ redis_data/

Method 3: Build from Source

Build and run from source code for development or customization.

Prerequisites

Go 1.21+
Node.js 18+
PostgreSQL 15+
Redis 7+

Build Steps

# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 2. Install pnpm (if not already installed)
npm install -g pnpm

# 3. Build frontend
cd frontend
pnpm install
pnpm run build
# Output will be in ../backend/internal/web/dist/

# 4. Build backend with embedded frontend
cd ../backend
go build -tags embed -o sub2api ./cmd/server

# 5. Create configuration file
cp ../deploy/config.example.yaml ./config.yaml

# 6. Edit configuration
nano config.yaml

Note: The -tags embed flag embeds the frontend into the binary. Without this flag, the binary will not serve the frontend UI.

Key configuration in config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"

database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "your_password"
  dbname: "sub2api"

redis:
  host: "localhost"
  port: 6379
  password: ""

jwt:
  secret: "change-this-to-a-secure-random-string"
  expire_hour: 24

default:
  user_concurrency: 5
  user_balance: 0
  api_key_prefix: "sk-"
  rate_multiplier: 1.0

Sora Status (Temporarily Unavailable)

⚠️ Sora-related features are temporarily unavailable due to technical issues in upstream integration and media delivery. Please do not rely on Sora in production at this time. Existing gateway.sora_* configuration keys are reserved and may not take effect until these issues are resolved.

Additional security-related options are available in config.yaml:

cors.allowed_origins for CORS allowlist
security.url_allowlist for upstream/pricing/CRS host allowlists
security.url_allowlist.enabled to disable URL validation (use with caution)
security.url_allowlist.allow_insecure_http to allow HTTP URLs when validation is disabled
security.url_allowlist.allow_private_hosts to allow private/local IP addresses
security.response_headers.enabled to enable configurable response header filtering (disabled uses default allowlist)
security.csp to control Content-Security-Policy headers
billing.circuit_breaker to fail closed on billing errors
server.trusted_proxies to enable X-Forwarded-For parsing
turnstile.required to require Turnstile in release mode

⚠️ Security Warning: HTTP URL Configuration

When security.url_allowlist.enabled=false, the system performs minimal URL validation by default, rejecting HTTP URLs and only allowing HTTPS. To allow HTTP URLs (e.g., for development or internal testing), you must explicitly set:

security:
  url_allowlist:
    enabled: false                # Disable allowlist checks
    allow_insecure_http: true     # Allow HTTP URLs (⚠️ INSECURE)

Or via environment variable:

SECURITY_URL_ALLOWLIST_ENABLED=false
SECURITY_URL_ALLOWLIST_ALLOW_INSECURE_HTTP=true

Risks of allowing HTTP:

API keys and data transmitted in plaintext (vulnerable to interception)
Susceptible to man-in-the-middle (MITM) attacks
NOT suitable for production environments

When to use HTTP:

✅ Development/testing with local servers (http://localhost)
✅ Internal networks with trusted endpoints
✅ Testing account connectivity before obtaining HTTPS
❌ Production environments (use HTTPS only)

Example error without this setting:

Invalid base URL: invalid url scheme: http

If you disable URL validation or response header filtering, harden your network layer:

Enforce an egress allowlist for upstream domains/IPs
Block private/loopback/link-local ranges
Enforce TLS-only outbound traffic
Strip sensitive upstream response headers at the proxy

# 6. Run the application
./sub2api

Development Mode

# Backend (with hot reload)
cd backend
go run ./cmd/server

# Frontend (with hot reload)
cd frontend
pnpm run dev

Code Generation

When editing backend/ent/schema, regenerate Ent + Wire:

cd backend
go generate ./ent
go generate ./cmd/server

Simple Mode

Simple Mode is designed for individual developers or internal teams who want quick access without full SaaS features.

Enable: Set environment variable RUN_MODE=simple
Difference: Hides SaaS-related features and skips billing process
Security note: In production, you must also set SIMPLE_MODE_CONFIRM=true to allow startup

Antigravity Support

Sub2API supports Antigravity accounts. After authorization, dedicated endpoints are available for Claude and Gemini models.

Dedicated Endpoints

Endpoint	Model
`/antigravity/v1/messages`	Claude models
`/antigravity/v1beta/`	Gemini models

Claude Code Configuration

export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"

Hybrid Scheduling Mode

Antigravity accounts support optional hybrid scheduling. When enabled, the general endpoints /v1/messages and /v1beta/ will also route requests to Antigravity accounts.

⚠️ Warning: Anthropic Claude and Antigravity Claude cannot be mixed within the same conversation context. Use groups to isolate them properly.

Known Issues

In Claude Code, Plan Mode cannot exit automatically. (Normally when using the native Claude API, after planning is complete, Claude Code will pop up options for users to approve or reject the plan.)

Workaround: Press Shift + Tab to manually exit Plan Mode, then type your response to approve or reject the plan.

Project Structure

sub2api/
├── backend/                  # Go backend service
│   ├── cmd/server/           # Application entry
│   ├── internal/             # Internal modules
│   │   ├── config/           # Configuration
│   │   ├── model/            # Data models
│   │   ├── service/          # Business logic
│   │   ├── handler/          # HTTP handlers
│   │   └── gateway/          # API gateway core
│   └── resources/            # Static resources
│
├── frontend/                 # Vue 3 frontend
│   └── src/
│       ├── api/              # API calls
│       ├── stores/           # State management
│       ├── views/            # Page components
│       └── components/       # Reusable components
│
└── deploy/                   # Deployment files
    ├── docker-compose.yml    # Docker Compose configuration
    ├── .env.example          # Environment variables for Docker Compose
    ├── config.example.yaml   # Full config file for binary deployment
    └── install.sh            # One-click installation script

Disclaimer

Please read carefully before using this project:

🚨 Terms of Service Risk: Using this project may violate Anthropic's Terms of Service. Please read Anthropic's user agreement carefully before use. All risks arising from the use of this project are borne solely by the user.

📖 Disclaimer: This project is for technical learning and research purposes only. The author assumes no responsibility for account suspension, service interruption, or any other losses caused by the use of this project.

Star History

License

This project is licensed under the GNU Lesser General Public License v3.0 (or later).

If you find this project useful, please give it a star!

Tencent/WeKnora

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

| English | 简体中文 | 日本語 | 한국어 |

Overview • Architecture • Key Features • Getting Started • API Reference • Developer Guide

💡 WeKnora — Turn Documents into Living Knowledge with RAG, Agents and Auto-Wiki

📌 Overview

WeKnora is an open-source, LLM-powered knowledge framework built for enterprise-grade document understanding, semantic retrieval, and autonomous reasoning.

It is organized around three core capabilities: RAG-based Quick Q&A for everyday lookups, a ReAct Agent that autonomously orchestrates retrieval, MCP tools and web search to handle complex multi-step tasks, and a brand-new Wiki Mode in which agents distill raw documents into a self-maintaining, interlinked markdown knowledge base with an interactive knowledge graph. Combined with multi-source ingestion (Feishu / Notion / Yuque, and growing), 20+ LLM provider integrations, full Langfuse observability, and a fully self-hostable modular architecture, WeKnora turns scattered documents into a queryable, reasoning-capable, continuously evolving knowledge asset.

The framework supports auto-syncing knowledge from Feishu, Notion, and Yuque (more data sources coming soon), handles 10+ document formats including PDF, Word, images, and Excel, and can serve Q&A directly through IM channels like WeCom, Feishu, Slack, and Telegram. It is compatible with major LLM providers including OpenAI, DeepSeek, Qwen (Alibaba Cloud), Zhipu, Hunyuan, Gemini, MiniMax, NVIDIA, and Ollama. Its fully modular design allows swapping LLMs, vector databases, and storage backends, with support for local and private cloud deployment ensuring complete data sovereignty. WeKnora also integrates with Langfuse for comprehensive observability into agent reasoning, token usage, and pipeline tracing.

✨ Latest Updates

v0.5.2 Highlights:

Wiki Mode at Scale: Wiki ingest now handles tens-of-thousands-document KBs via a generic task queue with dead-letter handling; the page-link graph gains a subgraph API + interactive exploration UI.
MCP Human-in-the-Loop Approval: Sensitive MCP tool calls pause the agent and wait for explicit user approval in the chat UI.
More LLM / Vector DB / Storage / Search: Anthropic (Claude), Apache Doris 4.1, Tencent VectorDB, Kingsoft Cloud KS3, and SearXNG are all new backends — pairing with the Vector Store management UI and per-KB indexing strategy toggles.
Deeper Observability: Langfuse spans expanded across retrieval / rerank / agent stages; end-to-end TTFB logged on both ends of the chat stream; LLM call timeouts hardened to keep worker pools healthy.
Adaptive 3-Tier Chunking: Documents are auto-routed to heading-aware / heuristic / recursive strategies, with a live preview panel in the KB editor. See docs/CHUNKING.md.
Global Command Palette: A ⌘K palette replaces the standalone search page and can start a new chat directly from any result.
More Connectors & Mobile: Yuque connector (full + incremental sync) joins Feishu / Notion; lightweight WeChat Mini Program client under miniprogram/.
weknora CLI (Preview): An early version of the official command-line client lives under cli/ — feedback welcome.
Other Improvements: Per-tenant RRF tuning, a dedicated query-understanding model, batch KB management, user-scoped session pinning, a tenant-wide IM channels overview, per-user font / theme preferences, a new OpenMaiC Classroom agent skill, and a full API-docs / Swagger / Client-SDK overhaul.
Bug Fixes: Embedder (nil, nil) SIGSEGV fixed; Mimo / DeepSeek reasoning_content round-trip restored; multi-turn agent history rebuilt from DB (with attachment replay); OIDC login fixed; many Wiki ingest reliability fixes; FAQ no longer hallucinates summaries from filenames on empty PDFs.

Earlier Releases

v0.4.0 Highlights:

Knowledge Assistant: Cloud-hosted knowledge assistant service for quick onboarding without local deployment
WeKnora Cloud: WeKnora Cloud provider with hosted LLM models and document parsing service, credential management and status checks
Chrome Extension: Browser extension for web page knowledge capture
ClawHub Skill: ClawHub Skill marketplace integration for one-click agent skill installation
WeChat IM Integration: WeChat channel adapter with QR code login and long-polling message support
Attachment Processing: File attachment support in chat pipeline with content formatting and metadata injection
Azure OpenAI Provider: Full Azure OpenAI support for chat, VLM, and embedding models with deployment name preservation and dimensions parameter
Alibaba Cloud OSS Storage: Object storage support via S3-compatible mode with configuration UI, connectivity test, and multi-language i18n
Notion Connector: Notion data source integration with API client, markdown renderer, and Connector interface
Baidu & Ollama Web Search: Added Baidu and Ollama as web search providers
VectorStore Management: Full VectorStore CRUD with entity, repository, service layer, connection testing, and API endpoints
Bug Fixes: Fixed Azure OpenAI endpoint handling, embedding truncation, IM citation tag stripping, neo4j Go 1.24 Windows compatibility, and OSS signature issues

v0.3.6 Highlights:

ASR (Automatic Speech Recognition): Integrated ASR model support with audio file upload, in-document audio preview, and transcription capabilities
Data Source Auto-Sync (Feishu): Complete data source management with Feishu Wiki/Drive auto-sync, incremental and full sync, sync logs, and tenant isolation
OIDC Authentication: OpenID Connect login support with auto-discovery, custom endpoints, and user info mapping
IM Quote/Reply Context: Quoted messages extracted in IM channels and injected into LLM prompts for contextual replies; anti-hallucination for non-text quotes
Thread-Based IM Sessions: Per-thread session mode for IM channels (Slack, Mattermost, Feishu, Telegram), enabling multi-user collaboration within threads
Document Summarization: AI-generated document summaries with configurable input limits and a dedicated summary section in document detail view
Tavily Web Search: Added Tavily as a web search provider; refactored web search provider architecture for extensibility
MCP Auto-Reconnection: Automatic reconnection for MCP tool calls when server connection is lost
Parallel Tool Calling: Concurrent execution of multiple agent tool calls via errgroup for faster complex task handling
Agent @Mention Scope Restriction: User @mentions restricted to agent's allowed knowledge base scope, preventing unauthorized access
Login Page Performance: Removed all backdrop-filter blur effects, reduced animations, added GPU compositing hints for faster page load

v0.3.5 Highlights:

Telegram, DingTalk & Mattermost IM Integration: Added Telegram bot (webhook/long-polling, streaming via editMessageText), DingTalk bot (webhook/Stream mode, AI Card streaming), and Mattermost adapter; IM channel coverage now includes WeCom, Feishu, Slack, Telegram, DingTalk, and Mattermost
IM Slash Commands & QA Queue: Pluggable slash-command system (/help, /info, /search, /stop, /clear) with a bounded QA worker pool, per-user rate limiting, and Redis-based multi-instance coordination
Suggested Questions: Agents surface context-aware suggested questions based on configured knowledge bases; image knowledge automatically enqueues question generation
VLM Auto-Describe MCP Tool Images: When MCP tools return images, the agent generates text descriptions via the configured VLM model, enabling image content to be used by text-only LLMs
Novita AI Provider: New LLM provider with OpenAI-compatible API supporting chat, embedding, and VLLM model types
MCP Tool Name Stability: Tool names now based on service name (stable across reconnections) instead of UUID; unique name constraint added; frontend formats names into human-readable form
Channel Tracking: Knowledge entries and messages record source channel (web/api/im/browser_extension) for traceability
Bug Fixes: Fixed agent empty response when no knowledge base is configured, UTF-8 truncation in summaries for Chinese/emoji documents, API key encryption loss on tenant settings update, vLLM streaming reasoning content propagation, and rerank empty passage errors

v0.3.4 Highlights:

IM Bot Integration: WeCom, Feishu, and Slack IM channel support with WebSocket/Webhook modes, streaming, and knowledge base integration
Multimodal Image Support: Image upload and multimodal image processing with enhanced session management
Manual Knowledge Download: Download manual knowledge content as files with proper filename sanitization
NVIDIA Model API: Support NVIDIA chat model API with custom endpoint and VLM model configuration
Weaviate Vector DB: Added Weaviate as a new vector database backend for knowledge retrieval
AWS S3 Storage: Integrated AWS S3 storage adapter with configuration UI and database migrations
AES-256-GCM Encryption: API keys encrypted at rest with AES-256-GCM for enhanced security
Built-in MCP Service: Built-in MCP service support for extending agent capabilities
Hybrid Search Optimization: Grouped targets and reused query embeddings for better retrieval performance
Final Answer Tool: New final_answer tool with agent duration tracking for improved agent workflows

v0.3.3 Highlights:

Parent-Child Chunking: Hierarchical parent-child chunking strategy for enhanced context management and more accurate retrieval
Knowledge Base Pinning: Pin frequently-used knowledge bases for quick access
Fallback Response: Fallback response handling with UI indicators when no relevant results are found
Passage Cleaning for Rerank: Passage cleaning for rerank model to improve relevance scoring accuracy
Storage Auto-Creation: Storage engine connectivity check with auto-creation of buckets
Milvus Vector DB: Added Milvus as a new vector database backend for knowledge retrieval

v0.3.2 Highlights:

🔍 Knowledge Search: New "Knowledge Search" entry point with semantic retrieval, supporting bringing search results directly into the conversation window
⚙️ Parser & Storage Engine Configuration: Configure document parser engines and storage engines for different sources in settings, with per-file-type parser selection in knowledge base
🖼️ Image Rendering in Local Storage: Support image rendering during conversations in local storage mode, with optimized streaming image placeholders
📄 Document Preview: Embedded document preview component for previewing user-uploaded original files
🎨 UI Optimization: Knowledge base, agent, and shared space list page interaction redesign
🗄️ Milvus Support: Added Milvus as a new vector database backend for knowledge retrieval
🌋 Volcengine TOS: Added Volcengine TOS object storage support
📊 Mermaid Rendering: Support mermaid diagram rendering in chat with fullscreen viewer, zoom, pan, toolbar and export
💬 Batch Conversation Management: Batch management and delete all sessions functionality
🔗 Remote URL Knowledge: Support creating knowledge entries from remote file URLs
🧠 Memory Graph Preview: Preview of user-level memory graph visualization
🔄 Async Re-parse: Async API for re-processing existing knowledge documents

v0.3.0 Highlights:

🏢 Shared Space: Shared space with member invitations, shared knowledge bases and agents across members, tenant-isolated retrieval
🧩 Agent Skills: Agent skills system with preloaded skills for smart-reasoning agent, sandboxed execution environment for security isolation
🤖 Custom Agents: Support for creating, configuring, and selecting custom agents with knowledge base selection modes (all/specified/disabled)
📊 Data Analyst Agent: Built-in Data Analyst agent with DataSchema tool for CSV/Excel analysis
🧠 Thinking Mode: Support thinking mode for LLM and agents, intelligent filtering of thinking content
🔍 Web Search Providers: Added Bing and Google search providers alongside DuckDuckGo
📋 Enhanced FAQ: Batch import dry run, similar questions, matched question in search results, large imports offloaded to object storage
🔑 API Key Auth: API Key authentication mechanism with Swagger documentation security
📎 In-Input Selection: Select knowledge bases and files directly in the input box with @mention display
☸️ Helm Chart: Complete Helm chart for Kubernetes deployment with Neo4j GraphRAG support
🌍 i18n: Added Korean (한국어) language support
🔒 Security Hardening: SSRF-safe HTTP client, enhanced SQL validation, MCP stdio transport security, sandbox-based execution
⚡ Infrastructure: Qdrant vector DB support, Redis ACL, configurable log level, Ollama embedding optimization, DISABLE_REGISTRATION control

v0.2.0 Highlights:

🤖 Agent Mode: New ReACT Agent mode that can call built-in tools, MCP tools, and web search, providing comprehensive summary reports through multiple iterations and reflection
📚 Multi-Type Knowledge Bases: Support for FAQ and document knowledge base types, with new features including folder import, URL import, tag management, and online entry
⚙️ Conversation Strategy: Support for configuring Agent models, normal mode models, retrieval thresholds, and Prompts, with precise control over multi-turn conversation behavior
🌐 Web Search: Support for extensible web search engines with built-in DuckDuckGo search engine
🔌 MCP Tool Integration: Support for extending Agent capabilities through MCP, with built-in uvx and npx launchers, supporting multiple transport methods
🎨 New UI: Optimized conversation interface with Agent mode/normal mode switching, tool call process display, and comprehensive knowledge base management interface upgrade
⚡ Infrastructure Upgrade: Introduced MQ async task management, support for automatic database migration, and fast development mode

📱 Interface Showcase

💬 Intelligent Q&A Conversation
📖 Wiki Browser	🕸️ Wiki Knowledge Graph
🤖 Agent Mode · Tool Call Process	⚙️ Conversation Settings
🔭 Observability · Langfuse Tracing

🏗️ Architecture

Fully modular pipeline from document parsing, vectorization, and retrieval to LLM inference — every component is swappable and extensible. Supports local / private cloud deployment with full data sovereignty and a zero-barrier Web UI for quick onboarding.

🧩 Feature Overview

Intelligent Conversation

Capability	Details
Intelligent Reasoning	ReACT progressive multi-step reasoning, autonomously orchestrating knowledge retrieval, MCP tools, and web search; custom agent support
Quick Q&A	RAG-based Q&A over knowledge bases for fast and accurate answers
Wiki Mode	Agent-driven auto-generation of structured, interlinked markdown Wiki pages from raw documents
Tool Calling	Built-in tools, MCP tools, web search
Conversation Strategy	Online Prompt editing, retrieval threshold tuning, multi-turn context awareness
Suggested Questions	Auto-generated question suggestions based on knowledge base content

Knowledge Management

Capability	Details
Knowledge Base Types	FAQ / Document / Wiki with folder import, URL import, tag management, and online entry
Data Source Import	Auto-sync from Feishu / Notion / Yuque (more data sources coming soon); incremental and full sync
Document Formats	PDF / Word / Txt / Markdown / HTML / Images / CSV / Excel / PPT / JSON
Retrieval Strategies	BM25 sparse / Dense retrieval / GraphRAG / parent-child chunking / multi-dimensional indexing
E2E Testing	Full-pipeline visualization with recall hit rate, BLEU / ROUGE metric evaluation

Integrations & Extensions

Capability	Details
LLMs	OpenAI / Azure OpenAI / Anthropic (Claude) / DeepSeek / Qwen (Alibaba Cloud) / Zhipu / Hunyuan / Doubao (Volcengine) / Gemini / MiniMax / NVIDIA / Novita AI / SiliconFlow / OpenRouter / Ollama
Embeddings	Ollama / BGE / GTE / OpenAI-compatible APIs
Vector DBs	PostgreSQL (pgvector) / Elasticsearch / Milvus / Weaviate / Qdrant / Apache Doris / Tencent VectorDB
Object Storage	Local / MinIO / AWS S3 / Volcengine TOS / Alibaba Cloud OSS / Kingsoft Cloud KS3
IM Channels	WeCom / Feishu / Slack / Telegram / DingTalk / Mattermost / WeChat
Web Search	DuckDuckGo / Bing / Google / Tavily / Baidu / Ollama / SearXNG

Platform

Capability	Details
Deployment	Local / Docker / Kubernetes (Helm) with private and offline support
UI	Web UI / RESTful API / CLI (`weknora`) / Chrome Extension / WeChat Mini Program
Observability	Integrated Langfuse for ReAct loops, token tracking, tool calls, and pipeline tracing
Task Management	MQ async tasks, automatic database migration on version upgrade
Model Management	Centralized config, per-knowledge-base model selection, multi-tenant built-in model sharing, WeKnora Cloud hosted models and parsing

🧩 Chrome Extension

WeKnora Chrome Extension lets you capture web content directly into your WeKnora knowledge base. Select text, images, or entire pages in the browser and save them as knowledge entries with one click — no copy-paste or file upload needed.

📱 WeChat Mini Program

The WeKnora Mini Program provides a lightweight mobile client for configuring WeKnora API access, selecting knowledge bases, importing URLs, and asking knowledge chat from WeChat.

🦞 ClawHub Skill

WeKnora ClawHub Skill is a WeKnora skill published on the ClawHub platform. Once installed, it enables document import (file / URL / Markdown), hybrid search (vector + keyword) across knowledge bases, and knowledge entry management — all through the WeKnora REST API.

Document Import — Upload files, import web pages, or write Markdown knowledge via the agent
Hybrid Search — Search within or across knowledge bases with vector + keyword retrieval
Knowledge Management — List, browse, edit, and delete knowledge entries programmatically

⌨️ Command-Line Interface

weknora is the official CLI for driving the API from a terminal or AI agent. The command surface mirrors gh CLI's <noun> <verb> convention; output is human-readable by default and switches to a stable JSON envelope with --json.

weknora auth login --host https://kb.example.com
weknora kb list
weknora link --kb my-knowledge-base    # bind the current directory
weknora doc upload notes.md
weknora chat "summarise the design doc"

See cli/README.md for install + 5-minute quickstart and cli/AGENTS.md for the operational contract that AI agents (Claude Code, Cursor, Aider, …) can rely on.

🚀 Getting Started

🛠 Prerequisites

Docker & Docker Compose
Git

📦 Installation & Launch

git clone https://github.com/Tencent/WeKnora.git
cd WeKnora
cp .env.example .env   # Edit .env as needed, see comments in the file
docker compose up -d   # Start core services

Once started, visit http://localhost to get started.

To use a local Ollama model, run ollama serve > /dev/null 2>&1 & first.

🔧 Optional Services (Docker Compose Profiles)

Add --profile flags to enable additional components. Multiple profiles can be combined:

Profile	Description	Command
(default)	Core services	`docker compose up -d`
`full`	All features	`docker compose --profile full up -d`
`neo4j`	Knowledge Graph (Neo4j)	`docker compose --profile neo4j up -d`
`minio`	Object Storage (MinIO)	`docker compose --profile minio up -d`
`langfuse`	Tracing (Langfuse)	`docker compose --profile langfuse up -d`

Combine profiles: docker compose --profile neo4j --profile minio up -d

Stop services: docker compose down

🌐 Service URLs

Service	URL
Web UI	`http://localhost`
Backend API	`http://localhost:8080`
Langfuse Tracing	`http://localhost:3000`

MCP Server

Please refer to the MCP Configuration Guide for the necessary setup.

🔌 Using WeChat Dialog Open Platform

WeKnora serves as the core technology framework for the WeChat Dialog Open Platform, providing a more convenient usage approach:

Zero-code Deployment: Simply upload knowledge to quickly deploy intelligent Q&A services within the WeChat ecosystem, achieving an "ask and answer" experience
Efficient Question Management: Support for categorized management of high-frequency questions, with rich data tools to ensure accurate, reliable, and easily maintainable answers
WeChat Ecosystem Integration: Through the WeChat Dialog Open Platform, WeKnora's intelligent Q&A capabilities can be seamlessly integrated into WeChat Official Accounts, Mini Programs, and other WeChat scenarios, enhancing user interaction experiences

📘 API Reference

Troubleshooting FAQ: Troubleshooting FAQ

Detailed API documentation is available at: API Docs

Product plans and upcoming features: Roadmap

🧭 Developer Guide

⚡ Fast Development Mode (Recommended)

If you need to frequently modify code, you don't need to rebuild Docker images every time! Use fast development mode:

# Start infrastructure
make dev-start

# Start backend (new terminal)
make dev-app

# Start frontend (new terminal)
make dev-frontend

Development Advantages:

✅ Frontend modifications auto hot-reload (no restart needed)
✅ Backend modifications quick restart (5-10 seconds, supports Air hot-reload)
✅ No need to rebuild Docker images
✅ Support IDE breakpoint debugging

Detailed Documentation: Development Environment Quick Start

📁 Directory Structure

WeKnora/
├── client/      # go client
├── cmd/         # Main entry point
├── config/      # Configuration files
├── docker/      # docker images files
├── docreader/   # Document parsing app
├── docs/        # Project documentation
├── frontend/    # Frontend app
├── internal/    # Core business logic
├── mcp-server/  # MCP server
├── migrations/  # DB migration scripts
└── scripts/     # Shell scripts

🤝 Contributing

Welcome to submit Issues or Pull Requests.

Process: Fork → Create branch → Commit changes → Open PR

Standards: Format code with gofmt, follow Conventional Commits (feat: / fix: / docs: / test: / refactor:)

🔒 Security Notice

Important: Starting from v0.1.3, WeKnora includes login authentication functionality to enhance system security. For production deployments, we strongly recommend:

Deploy WeKnora services in internal/private network environments rather than public internet
Avoid exposing the service directly to public networks to prevent potential information leakage
Configure proper firewall rules and access controls for your deployment environment
Regularly update to the latest version for security patches and improvements

👥 Contributors

Thanks to these excellent contributors:

📄 License

This project is licensed under the MIT License. You are free to use, modify, and distribute the code with proper attribution.

📈 Project Statistics

MHSanaei/3x-ui

Xray panel supporting multi-protocol multi-user expire day & traffic & IP limit (Vmess, Vless, Trojan, ShadowSocks, Wireguard, Hysteria, Tunnel, Mixed, HTTP, Tun)

3X-UI — advanced, open-source web-based control panel designed for managing Xray-core server. It offers a user-friendly interface for configuring and monitoring various VPN and proxy protocols.

Important

This project is only for personal usage, please do not use it for illegal purposes, and please do not use it in a production environment.

As an enhanced fork of the original X-UI project, 3X-UI provides improved stability, broader protocol support, and additional features.

Quick Start

bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

For full documentation, please visit the project Wiki.

A Special Thanks to

alireza0

Acknowledgment

Iran v2ray rules (License: GPL-3.0): Enhanced v2ray/xray and v2ray/xray-clients routing rules with built-in Iranian domains and a focus on security and adblocking.
Russia v2ray rules (License: GPL-3.0): This repository contains automatically updated V2Ray routing rules based on data on blocked domains and addresses in Russia.

Community Tools

Tools and integrations built by the community around 3x-ui.

terraform-provider-3x-ui (License: MIT): Manage inbounds, clients, panel settings, and Xray configuration as code with Terraform / OpenTofu.

Support project

If this project is helpful to you, you may wish to give it a🌟

Stargazers over Time

masterking32/MasterDnsVPN

Advanced DNS tunneling VPN for censorship bypass, optimized beyond DNSTT and SlipStream with low-overhead ARQ, resolver load balancing, high packet-loss stability and speed.

# MasterDnsVPN Project 🔐

| نسخه فارسی | English Version |

MasterDnsVPN is a scientific and research-oriented project for carrying TCP traffic through DNS queries and responses. In broad goal, it is similar to projects such as DNSTT or SlipStream, but it follows a fundamentally different structure and implementation approach. This system is designed around compatibility with many resolver behaviors and harsh network conditions, with the goal of preserving the highest possible stability and data delivery even in the worst cases.

📊 MasterDnsVPN Compared with Similar Projects

Feature	SlipStream	DNSTT	MasterDnsVPN
Protocol type	Advanced DNS tunnel	Classic DNS tunnel	Advanced DNS tunnel / VPN
Transport protocol	QUIC	KCP + Noise	Custom protocol + ARQ
Transport header overhead	🟠 ~24B	🔴 ~59B	🟢 ~5–7B ≈88% lower than DNSTT ≈71% lower than SlipStream
Encryption style	TLS 1.3 (inside QUIC)	Noise (Curve25519)	AES / ChaCha20 / XOR (if XOR is used: lightweight with lower security and no extra overhead)
Architecture	Unified (QUIC handles everything)	Multi-layered (KCP + SMUX + Noise)	🟢 Lightweight custom design optimized for DNS
Speed	🟡 High (up to ~5× faster than DNSTT)	🔴 Medium	🟢 Faster than others Up to ~9× faster than DNSTT Up to ~3.6× faster than SlipStream
Stability under packet loss	🟡 Good	🟠 Medium	🟢 Very high (Multipath + ARQ)
Multi-resolver support	Yes (multipath)	❌	Yes — advanced (multi-resolver + duplication)
Resilience under heavy censorship	Good	Medium	Very strong (a core project goal)
Setup complexity	Medium	Simple	Easier installation More complex only if you heavily customize advanced settings
SOCKS5 support	Yes	Yes	Optimized for SOCKS5 / SOCKS4 with reduced SOCKS overhead
Shadowsocks support	✅	❌	Indirectly: TCP Forwarding mode can carry TCP-based protocols e.g. Shadowsocks, VLESS/VMess, etc.
Real multipath	Yes (QUIC multipath)	❌	Yes (multi-resolver + duplication)
Adaptive routing	Limited	❌	Advanced (latency/loss based)
Design goal	High speed and efficiency	Simplicity and stability	Surviving the harshest networks — stability, speed, and efficiency
Implementation language	Rust	Go	Main version is Go Legacy Python version also exists
Built-in balancer	🔴	❌	🟢 (8 built-in balancing modes)
Duplication system	❌	❌	Yes — increases traffic to improve reliability (configurable or can be disabled)
MTU tolerance	Better than DNSTT	-	Works even with very small MTU because protocol overhead is very low
Failover system	❌	❌	✅
Download speed 10MB (Local)	🟡 0.978s	🔴 2.492s	🟢 0.270s
Upload speed 10MB (Local)	🟡 3.249s	🔴 16.207s	🟢 1.746s
Resolver health checks and auto-disable	❌	❌	✅
Background reactivation of healthy resolvers	❌	❌	✅
Local DNS service on client (to reduce DNS hijacking)	❌	❌	✅ (with strong DNS caching)
DNS resolving through SOCKS5	❌	❌	✅ (with DNS caching)
Fine-grained professional configuration	🟠	🟠	🟢 Almost every subsystem is configurable
No external helper software required	❌	❌	🟢 No extra software is required; if needed, you can still combine it with SOCKS or tools such as Shadowsocks or OpenVPN

❌ Disclaimer

MasterDnsVPN is provided as an educational and research project only.

Provided without warranty: This software is provided “AS-IS”, without any express or implied warranty, including merchantability, fitness for a particular purpose, or non-infringement.
Limitation of liability: The developers and contributors of this project accept no responsibility for any direct, indirect, incidental, consequential, or other damages arising from the use of this software or the inability to use it.
User responsibility: Using this project outside test environments may disrupt or damage network behavior. The user alone is responsible for all consequences of installation, configuration, and use.
Legal compliance: Using this project to bypass local laws may result in civil or criminal consequences. Please review the laws and regulations of your country before use. The developers accept no responsibility for violations of local, national, or international laws by users.
License terms: Use, copying, distribution, or modification of this software is governed by the license in the LICENSE file of this repository. Any use outside those terms is prohibited.

Announcement and Support Channel 📢

For the latest news, releases, and project updates, follow our Telegram channel: Telegram Channel

If you like this project, please support it by starring it on GitHub (⭐). It helps the project get discovered.

Optional Financial Support 💸

TON network:

masterking32.ton

EVM-compatible networks (ETH and compatible chains):

0x517f07305D6ED781A089322B6cD93d1461bF8652

TRC20 network (TRON):

TLApdY8APWkFHHoxebxGY8JhMeChiETqFH

Every contribution and every piece of feedback is appreciated. Support directly helps ongoing development and improvement.

Key Features and Advantages ✨

A brief overview of the main capabilities of MasterDnsVPN:

Censorship resistance and harsh-network survivability: 🛡️ Designed to work on filtered networks, unstable links, and strict MTU environments.
Lightweight custom protocol: 🔄 Uses a custom protocol with retransmission logic to reduce overhead and increase usable DNS payload.
Multipath and packet duplication: 📡 Sends traffic through multiple paths and supports selective duplication to increase delivery probability on unstable networks.
Smart resolver selection and health checks: ⚡ Selects resolvers based on quality and health, and manages problematic resolvers automatically.
MTU discovery and synchronization: 🧰 Detects the practical MTU of working paths and aligns around it to reduce fragmentation and improve stability.
SOCKS5 / SOCKS4 support and optimization: 🧦 Optimized local proxy handling for common applications.
Packed control blocks and lower control overhead: 📦 Groups ACK/control traffic together to reduce control chatter.
Optional compression and request packing: 🗜️ Reduces request counts and improves efficiency under small-MTU conditions.
Flexible encryption: 🔐 Supports multiple encryption methods to balance speed and security.
Optional client-side local DNS and caching: 📛 Can expose a local DNS service, reduce latency, and limit hijacking opportunities.
Scalable resource control: ⚙️ Can run on small servers or be tuned for heavier loads.

This list is only a high-level summary. The related sections below explain each area in more detail.

🌐 Battle-Tested During a Total Internet Blackout

MasterDnsVPN isn't just a theoretical project. It is battle-tested and proven to work in environments where the global internet is completely severed.

Recently, during a 70+ day internet blackout in Iran, authorities didn't just block VPNs or filter websites—they completely pulled the plug on international bandwidth. With 99% of the connection to the outside world physically cut off, users were trapped inside a closed, local intranet.

Standard circumvention tools are useless when there is no international internet to connect to. Yet, during this massive shutdown, MasterDnsVPN stood out as one of the very few lifelines that actually kept users connected to the global web.

How did it survive a total shutdown? Instead of acting like a standard VPN, MasterDnsVPN relies on smart DNS tunneling techniques to pierce through the blackout:

Multiple Resolvers: It routes traffic through various DNS resolvers, ensuring the connection never relies on a single, easily blockable path.
Encryption & Data Splitting: It encrypts your data and breaks it down into tiny, scattered pieces.
Disguised as Legitimate Traffic: It wraps these data pieces inside standard, perfectly normal DNS queries.
Bypassing Local Traps: Because the traffic looks exactly like basic, everyday DNS requests, firewalls allow it through. The data gets resolved and reaches the outside world—even if the network forces you to use their own restricted, government-controlled local resolvers.

This exact combination is what allowed MasterDnsVPN to maintain a stable connection when the outside world was completely blocked.

Setup and Getting Started 🧑‍💻

Section 1: 🖥️ Server Setup

Section 1.1: 🌐 Domain Setup and Preparation (Prerequisite)

To receive DNS requests directly on your server, you must delegate a subdomain to it. In short, create two records: one A record that points to your server IP, and one NS record that delegates the tunnel subdomain to that A record.

Step 1.1.1: 🅰️ Create an A Record (Server Address)

Type: A
Name: a short name such as ns
Value: your server IPv4 address

Example: ns.example.com -> 1.2.3.4

Cloudflare note: if the domain uses Cloudflare, open the DNS page and click the cloud icon next to the A record so it becomes gray (DNS only). It must not remain proxied.

Step 1.1.2: 🏷️ Create an NS Record (Delegate the Subdomain)

Type: NS
Name: the tunnel subdomain, for example v
Value / Target: ns.example.com

Example: v.example.com -> ns.example.com

Cloudflare note: add the NS record normally. Cloudflare does not proxy NS records, but make sure the ns A record is already set to DNS only.

Section 1.1.3: 💡 A Short Note About MTU

Shorter domain names leave more space for actual data inside each DNS request. For better throughput, keep names short. If you use Cloudflare, still keep the relevant records in DNS only mode.

Section 1.2: 🐧 Quick Linux Server Installation

Step 1.2.1: Automatic Installation (Script)

If you want to deploy the server on Linux, the easiest method is the automatic installer script. Run this command on the server:

bash <(curl -Ls https://raw.githubusercontent.com/masterking32/MasterDnsVPN/main/server_linux_install.sh)

The script handles installation and configuration automatically. When it finishes, the server starts and the encryption key is shown in the terminal log and also written to encrypt_key.txt next to the executable. Keep this key safe.

Step 1.2.2: Important Notes After Installation

During installation, you will be asked for a domain. It must be the same delegated subdomain you configured in the NS record, for example v.example.com.
After creating DNS records, wait for propagation. This may take from a few minutes to several hours, and in some cases up to 48 hours depending on TTL and the DNS provider.
To verify the DNS setup, you can use tools such as dig or nslookup, for example dig v.example.com NS or nslookup -type=ns v.example.com. For a direct query to the new nameserver: dig @ns.example.com v.example.com A.
If the server firewall is enabled, allow UDP port 53. Example for ufw:

sudo ufw allow 53/udp
sudo ufw reload

For firewalld:

sudo firewall-cmd --add-port=53/udp --permanent
sudo firewall-cmd --reload

If port 53 is already occupied by another service, such as systemd-resolved, see the troubleshooting section “Fixing Port 53 Already in Use”.
The encryption key (encrypt_key.txt) is shown after installation. Copy it and store it safely because the client needs it to connect.

Section 2: 🚀 Installation and Launch (Client and Server)

You can install and run this project in two ways:

Use the prebuilt binaries (recommended for most users)
Run directly from source with Go (recommended for developers)

Section 2.1: Use Prebuilt Releases (✅ Recommended)

For convenience, prebuilt client and server binaries are published in the release page. Download the correct archive for your operating system and extract it.

💡 Note: Release archives usually include the binary plus sample configuration files.

Client Download Links 📥

Operating System	Architecture	Suitable For	Direct Download
Windows 🪟	`AMD64` (64-bit)	Windows 10 and 11	Download Windows Client ⬇️
Windows 🪟	`x86` (32-bit)	Older 32-bit Windows systems	Download Windows x86 Client ⬇️
Windows 🪟	`ARM64`	Windows on ARM devices	Download Windows ARM64 Client ⬇️
macOS 🍎	`ARM64`	Apple Silicon Macs (M1 / M2 / M3)	Download macOS Client ⬇️
macOS 🍎	`AMD64`	Intel Macs	Download macOS Intel Client ⬇️
Linux 🐧	`AMD64` (64-bit)	Modern distributions (Ubuntu 22.04+, Debian 12+)	Download Linux Client ⬇️
Linux 🐧	`x86` (32-bit)	Older 32-bit Linux systems	Download Linux x86 Client ⬇️
Linux (Legacy) 🐧	`AMD64` (64-bit)	Older distributions (Ubuntu 20.04, Debian 11)	Download Linux Legacy Client ⬇️
Linux (Legacy) 🐧	`ARM64`	Older ARM64 Linux systems that need broader compatibility	Download Linux Legacy ARM64 Client ⬇️
Linux (ARM) 🐧	`ARM64`	ARM servers, Raspberry Pi, and similar boards	Download Linux ARM Client ⬇️
Linux (ARM) 🐧	`ARMv7`	32-bit ARM boards and older embedded Linux devices	Download Linux ARMv7 Client ⬇️
Linux (ARM) 🐧	`ARMv6`	Older ARM boards and lightweight Linux devices	Download Linux ARMv6 Client ⬇️
Linux (ARM) 🐧	`ARMv5`	Very old ARM devices and embedded Linux systems	Download Linux ARMv5 Client ⬇️
Linux 🐧	`RISCV64`	RISC-V Linux boards and servers	Download Linux RISCV64 Client ⬇️
Linux (MIPS) 🐧	`MIPS`	Big-endian MIPS Linux and router platforms	Download Linux MIPS Client ⬇️
Linux (MIPS) 🐧	`MIPSLE`	Little-endian MIPS Linux and router platforms	Download Linux MIPSLE Client ⬇️
Linux (MIPS) 🐧	`MIPS64`	64-bit big-endian MIPS Linux systems	Download Linux MIPS64 Client ⬇️
Linux (MIPS) 🐧	`MIPS64LE`	64-bit little-endian MIPS Linux systems	Download Linux MIPS64LE Client ⬇️
Termux / Android 📱	`ARM64`	Modern Android phones running Termux	Download Termux ARM64 Client ⬇️
Termux / Android 📱	`ARMv7`	Older Android phones running 32-bit Termux environments	Download Termux ARMv7 Client ⬇️

Server Download Links 📤

(Use these if you do not want the automated Linux installer.)

Operating System	Architecture	Suitable For	Direct Download
Windows 🪟	`AMD64` (64-bit)	Windows Server, Windows 10 and 11	Download Windows Server ⬇️
Windows 🪟	`x86` (32-bit)	Older 32-bit Windows systems	Download Windows x86 Server ⬇️
Windows 🪟	`ARM64`	Windows on ARM devices	Download Windows ARM64 Server ⬇️
Linux 🐧	`AMD64` (64-bit)	Ubuntu 22.04+, Debian 12+ servers	Download Linux Server ⬇️
Linux 🐧	`x86` (32-bit)	Older 32-bit Linux systems	Download Linux x86 Server ⬇️
Linux (Legacy) 🐧	`AMD64` (64-bit)	Older servers (Ubuntu 20.04, Debian 11)	Download Linux Legacy Server ⬇️
Linux (Legacy) 🐧	`ARM64`	Older ARM64 Linux systems that need broader compatibility	Download Linux Legacy ARM64 Server ⬇️
Linux (ARM) 🐧	`ARM64`	ARM servers	Download Linux ARM Server ⬇️
Linux (ARM) 🐧	`ARMv7`	32-bit ARM servers and embedded Linux devices	Download Linux ARMv7 Server ⬇️
Linux (ARM) 🐧	`ARMv6`	Older ARM boards and lightweight Linux devices	Download Linux ARMv6 Server ⬇️
Linux (ARM) 🐧	`ARMv5`	Very old ARM devices and embedded Linux systems	Download Linux ARMv5 Server ⬇️
Linux 🐧	`RISCV64`	RISC-V Linux boards and servers	Download Linux RISCV64 Server ⬇️
Linux (MIPS) 🐧	`MIPS`	Big-endian MIPS Linux and router platforms	Download Linux MIPS Server ⬇️
Linux (MIPS) 🐧	`MIPSLE`	Little-endian MIPS Linux and router platforms	Download Linux MIPSLE Server ⬇️
Linux (MIPS) 🐧	`MIPS64`	64-bit big-endian MIPS Linux systems	Download Linux MIPS64 Server ⬇️
Linux (MIPS) 🐧	`MIPS64LE`	64-bit little-endian MIPS Linux systems	Download Linux MIPS64LE Server ⬇️
macOS 🍎	`ARM64`	Apple Silicon Macs	Download macOS Server ⬇️
macOS 🍎	`AMD64`	Intel Macs	Download macOS Intel Server ⬇️
Termux / Android 📱	`ARM64`	Modern Android / Termux environments	Download Termux ARM64 Server ⬇️
Termux / Android 📱	`ARMv7`	Older Android / 32-bit Termux environments	Download Termux ARMv7 Server ⬇️

Section 2.2: 📦 MasterDnsVPN Docker Image

Section 2.2.1: ⚠️ Overview

This Docker image runs the MasterDnsVPN server in a containerized environment and supports multi-architecture builds.

It automatically:

Boots a default configuration if none exists
Injects your domain on first startup
Stores persistent data in /data

Section 2.2.2: 🖥 Supported Architectures

linux/amd64
linux/arm/v5
linux/arm/v7
linux/arm64/v8
linux/mips64le

Section 2.2.3: 🚀 Quick Start

Run the container with Docker:

docker run -d \
  --name masterdnsvpn \
  --restart unless-stopped \
  -e DOMAIN=v.example.com \
  -v $(pwd)/data:/data \
  -p 53:53/tcp \
  -p 53:53/udp \
  ghcr.io/masterking32/masterdnsvpn:latest

Section 2.2.4: 🧪 Example with docker-compose

services:
  masterdnsvpn:
    image: ghcr.io/masterking32/masterdnsvpn:latest
    restart: unless-stopped
    environment:
      - DOMAIN=v.example.com
    volumes:
      - ./data:/data
    ports:
      - "53:53/tcp"
      - "53:53/udp"

Section 2.2.5: ⚙️ Required Environment Variables

Variable	Description
DOMAIN	Your DNS domain (required on first run)

⚠️ If DOMAIN is not set on first boot, the container will stop with an error.

Section 2.2.6: 📁 Persistent Data

Stored in /data:

server_config.toml
encrypt_key.txt

You can mount it as volume:

-v ./data:/data

Section 2.2.7: 🔧 MikroTik / RouterOS Usage

For MikroTik containers:

Use latest v7 MikroTik RouterOS
Destination NAT port UDP/TCP 53 to your container
Full MikroTik container setup: https://help.mikrotik.com/docs/spaces/ROS/pages/84901929/Container

Example:

/container mounts
add dst=/data list=MasterDnsVPN src=/containers/mounts/MasterDnsVPN

/container envs
add key=DOMAIN list=MasterDnsVPN value=v.example.com

/container add check-certificate=no dns=1.1.1.1 envlists=MasterDnsVPN hostname=MasterDnsVPN interface=MasterDnsVPN layer-dir="" mountlists=MasterDnsVPN name=MasterDnsVPN remote-image=ghcr.io/masterking32/masterdnsvpn:latest root-dir=/containers/data/MasterDnsVPN start-on-boot=yes

Section 2.2.8: 📌 Notes

DNS port 53 is required (UDP/TCP)
Do NOT run another DNS service on the same host
Designed for production use but still lightweight
No systemd or host modifications required

Section 2.3: 🪟 Preparing and Running the Client on Windows

After downloading the Windows package, extract it.
Open client_config.toml with a text editor such as Notepad.
Replace the default values with your real domain, encryption key, and resolver list.
Run the client executable.
Configure your browser or app to use the local SOCKS5 proxy at 127.0.0.1:18000 unless you changed the defaults.

Section 2.4: 🐧 Preparing and Running on Linux / macOS

After downloading the package on Linux:

sudo apt update
sudo apt install unzip nano

Extract the archive:

unzip MasterDnsVPN_Client_Linux_AMD64.zip
ls

Give execute permission if needed:

chmod +x MasterDnsVPN_Client_Linux_AMD64
chmod +x MasterDnsVPN_Server_Linux_AMD64

Edit the configuration:

nano client_config.toml
nano server_config.toml

Then run:

./MasterDnsVPN_Client_Linux_AMD64
./MasterDnsVPN_Server_Linux_AMD64

Section 2.5: 🧑‍💻 Run Directly from Source (Go)

⚠️ This section is intended for developers or users who want to run the current Go source directly.

Prerequisite

Go 1.24 or newer

Build from source

git clone https://github.com/masterking32/MasterDnsVPN.git
cd MasterDnsVPN

go build -o masterdnsvpn-client ./cmd/client
go build -o masterdnsvpn-server ./cmd/server

On Windows:

git clone https://github.com/masterking32/MasterDnsVPN.git
cd MasterDnsVPN

go build -o masterdnsvpn-client.exe .\cmd\client
go build -o masterdnsvpn-server.exe .\cmd\server

Create config files

On Linux and macOS:

cp client_config.toml.simple client_config.toml
cp server_config.toml.simple server_config.toml
cp client_resolvers.simple client_resolvers.txt

On Windows:

Copy-Item client_config.toml.simple client_config.toml
Copy-Item server_config.toml.simple server_config.toml
Copy-Item client_resolvers.simple client_resolvers.txt

Run the server and client

./masterdnsvpn-server -config server_config.toml
./masterdnsvpn-client -config client_config.toml

On Windows:

.\masterdnsvpn-server.exe -config server_config.toml
.\masterdnsvpn-client.exe -config client_config.toml

Command-line parameters

Both binaries support these arguments:

Parameter	Description
`-config`	Path to the configuration file
`-log`	Optional path to a log file
`-version`	Print version and exit

Example:

./masterdnsvpn-server -config server_config.toml -log server.log
./masterdnsvpn-client -config client_config.toml -log client.log

Section 3: Configuration Files and Structure 🛠️

Section 3.1: Important Project Files 📂

File	Purpose
`client_config.toml`	Main client configuration
`server_config.toml`	Main server configuration
`client_resolvers.txt`	Resolver list
`encrypt_key.txt`	Shared server-side encryption key
`client_config.toml.simple`	Full sample client config for the current Go version
`server_config.toml.simple`	Full sample server config for the current Go version

Accepted formats in client_resolvers.txt:

IP
IP:PORT
CIDR
CIDR:PORT

Example:

8.8.8.8
1.1.1.1:53
9.9.9.0/24
208.67.222.0/24:5353

Section 3.2: Quick Client Checklist 🚀

These items are required on the client:

ENCRYPTION_KEY must match the content of the server’s encrypt_key.txt
DOMAINS must match the server domain
client_resolvers.txt must contain working resolvers
For normal use, keep PROTOCOL_TYPE = "SOCKS5"

Section 3.3: Quick Server Checklist ⚙️

These settings are critical on the server:

Set DOMAIN to your delegated tunnel domain
DATA_ENCRYPTION_METHOD must match the client
ENCRYPTION_KEY_FILE defines the path to the server key file
If you want direct outbound connections, keep USE_EXTERNAL_SOCKS5 = false
If you want to chain through an upstream SOCKS5 proxy, set USE_EXTERNAL_SOCKS5 = true and fill FORWARD_IP / FORWARD_PORT

Section 3.4: 📘 Client Configuration Variables (`client_config.toml`)

3.4.1) 🧭 Tunnel Identity and Security

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`PROTOCOL_TYPE`	`"SOCKS5"`	`"SOCKS5"` or `"TCP"`	Chooses the local service mode exposed by the client. `SOCKS5` is the default and recommended mode for normal use. `TCP` is useful when you want to forward traffic to one fixed remote target instead of giving applications a SOCKS proxy.
`DOMAINS`	`["v.example.com"]`	Non-empty list of strings	These are the tunnel domains used to build DNS requests. Every domain here must belong to the same tunnel you configured on the server. If this list is wrong, the client may build valid DNS queries that the server will simply ignore.
`DATA_ENCRYPTION_METHOD`	`1`	`0..5`	Must match the server. `0=None`, `1=XOR`, `2=ChaCha20`, `3=AES-128-GCM`, `4=AES-192-GCM`, `5=AES-256-GCM`. XOR is lightweight but weaker. AEAD modes are stronger but have more overhead.
`ENCRYPTION_KEY`	`""`	String	Shared secret used by the client codec. This must be exactly the same as the server-side encryption key. If the key is wrong, packets may be parsed as garbage and the tunnel will not work.

3.4.2) 🧦 Local Proxy

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`LISTEN_IP`	`"127.0.0.1"`	Valid IP string	Address where the client listens for local proxy users. Use `127.0.0.1` for normal local-only usage. If some applications prefer IPv6 localhost on your system, using `localhost` can be a better local-only choice. Use `0.0.0.0` only if you want to share the proxy on the network and understand the security implications.
`LISTEN_PORT`	`18000`	`0..65535`	Port for the local proxy. Your applications must use this port to send traffic into the tunnel.
`SOCKS5_AUTH`	`false`	`true/false`	Enables username/password authentication on the local SOCKS5 proxy. If you bind to `0.0.0.0`, enabling this is strongly recommended.
`SOCKS5_USER`	`"master_dns_vpn"`	Up to 255 bytes	Username for the local SOCKS5 proxy. Used only if `SOCKS5_AUTH=true`.
`SOCKS5_PASS`	`"master_dns_vpn"`	Up to 255 bytes	Password for the local SOCKS5 proxy. Used only if `SOCKS5_AUTH=true`.

3.4.3) 📛 Local DNS

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`LOCAL_DNS_ENABLED`	`false`	`true/false`	If enabled, the client exposes a local DNS service and can resolve DNS through the tunnel. This is useful for reducing DNS hijacking or when you want applications to use the tunnel for DNS as well.
`LOCAL_DNS_IP`	`"127.0.0.1"`	Valid IP string	Bind address for the local DNS listener.
`LOCAL_DNS_PORT`	`53`	`0..65535`	Port of the local DNS service. Port `53` is standard, but on some systems it may already be used by another service.
`LOCAL_DNS_CACHE_MAX_RECORDS`	`5000`	If `<1`, fallback applies	Maximum number of local DNS cache records. A larger value reduces repeated DNS lookups but uses more memory.
`LOCAL_DNS_CACHE_TTL_SECONDS`	`28800.0`	If `<=0`, fallback applies	How long successful DNS records stay in the local cache.
`LOCAL_DNS_PENDING_TIMEOUT_SECONDS`	`300.0`	If `<=0`, fallback applies	If a local DNS query is in progress, follower queries can wait for it instead of launching another upstream request. This value defines how long they may wait.
`LOCAL_DNS_CACHE_PERSIST_TO_FILE`	`true`	`true/false`	If enabled, the local DNS cache can be written to disk for reuse between runs.
`LOCAL_DNS_CACHE_FLUSH_INTERVAL_SECONDS`	`60.0`	If `<=0`, fallback applies	How often the persisted local DNS cache is flushed to disk.
`DNS_RESPONSE_FRAGMENT_TIMEOUT_SECONDS`	`10.0`	If `<=0`, fallback applies	How long the client waits for missing DNS tunnel response fragments before giving up.

3.4.4) ⚡ Resolver Selection, Duplication, Health, and Failover

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`RESOLVER_BALANCING_STRATEGY`	`2`	`0..8`	Chooses how resolvers are selected. `0/2` = Round Robin, `1` = Random, `3` = Least Loss, `4` = Lowest Latency, `5` = Hybrid Score, `6` = Loss Then Latency, `7` = Least Loss Top Random, `8` = Least Loss Top Round Robin. The hybrid mode uses a weighted combined score. The loss-then-latency mode first shortlists by loss, then prefers lower latency inside that tier, and rotates among near-equal top candidates. The top-random mode picks randomly from the best loss tier so load does not stick to one resolver. The top-round-robin mode cycles through the same top loss tier with deterministic rotation.
`PACKET_DUPLICATION_COUNT`	`2`	clamp to valid range in code	Normal outgoing packet duplication count. Higher values increase traffic cost but improve survivability on weak links.
`SETUP_PACKET_DUPLICATION_COUNT`	`2`	clamp to valid range in code	Similar to `PACKET_DUPLICATION_COUNT`, but used for setup-sensitive packets such as stream creation and other critical control events.
`STREAM_RESOLVER_FAILOVER_RESEND_THRESHOLD`	`2`	If `<1`, fallback applies	If a stream accumulates repeated resend pressure on the same preferred resolver, the client may fail over that stream to another resolver. This threshold controls how quickly that happens.
`STREAM_RESOLVER_FAILOVER_COOLDOWN`	`2.5`	If `<=0`, fallback applies	Minimum delay between two failovers for the same stream. This prevents unstable oscillation between resolvers.
`RECHECK_INACTIVE_SERVERS_ENABLED`	`true`	`true/false`	Enables background rechecks for currently disabled or unhealthy resolvers. If disabled, once a resolver becomes unusable, it will stay disabled until restart or manual rebuild.
`AUTO_DISABLE_TIMEOUT_SERVERS`	`true`	`true/false`	Enables automatic disabling of resolvers that keep timing out and show no successful activity.
`AUTO_DISABLE_TIMEOUT_WINDOW_SECONDS`	`30.0`	If `<=0`, fallback applies	Time window used to decide whether a resolver is timeout-only. If all observations in this window are timeouts, it may be disabled.
`BASE_ENCODE_DATA`	`false`	`true/false`	If enabled, payloads are encoded in a base-safe format before tunneling. This usually reduces payload efficiency, but can help in strict resolver environments.

3.4.5) 🗜️ Compression

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`UPLOAD_COMPRESSION_TYPE`	`0`	`0..3`	`0=OFF`, `1=ZSTD`, `2=LZ4`, `3=ZLIB`. Controls client-side compression for outgoing payloads.
`DOWNLOAD_COMPRESSION_TYPE`	`0`	`0..3`	Compression type expected or preferred for server-to-client payloads.
`COMPRESSION_MIN_SIZE`	`120`	If invalid, fallback applies	Minimum payload size before compression is attempted. Very small packets often grow instead of shrinking, so this avoids pointless compression work.

3.4.6) 🧪 MTU Discovery and Initial Testing

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`MIN_UPLOAD_MTU`	`38`	positive integer	Smallest upload MTU the client accepts during resolver testing. Minimum enforced is the session-init payload size (10).
`MIN_DOWNLOAD_MTU`	`100`	positive integer	Smallest download MTU the client accepts during resolver testing. Minimum enforced is the session-accept payload size (20).
`MAX_UPLOAD_MTU`	`150`	positive integer	Upper bound for upload MTU testing.
`MAX_DOWNLOAD_MTU`	`500`	positive integer	Upper bound for download MTU testing.
`MTU_TEST_RETRIES`	`2`	if invalid, fallback applies	Number of retries for each MTU probe.
`MTU_TEST_TIMEOUT`	`2.0`	if invalid, fallback applies	Timeout for a single MTU probe.
`MTU_TEST_PARALLELISM`	`16`	if invalid, fallback applies	Number of resolvers tested in parallel during MTU scanning. Higher values scan faster but use more CPU/network and may produce more noisy failures.
`SAVE_MTU_SERVERS_TO_FILE`	`false`	`true/false`	If enabled, successful resolver results are written to an output file.
`MTU_SERVERS_FILE_NAME`	`"masterdnsvpn_success_test_{time}.log"`	string	Output file name template for successful MTU-tested resolvers.
`MTU_SERVERS_FILE_FORMAT`	`"{IP} ({DOMAIN}) - UP: {UP_MTU} DOWN: {DOWN-MTU}"`	string	Output format used in the MTU results file.
`MTU_USING_SECTION_SEPARATOR_TEXT`	`""`	string	Optional separator text inserted into the MTU output file.
`MTU_REMOVED_SERVER_LOG_FORMAT`	`"Resolver {IP} ({DOMAIN}) removed at {TIME} due to {CAUSE}"`	string	Log/output format when a resolver is removed from the valid set.
`MTU_ADDED_SERVER_LOG_FORMAT`	`"Resolver {IP} ({DOMAIN}) added back at {TIME} (UP {UP_MTU}, DOWN {DOWN_MTU})"`	string	Log/output format when a resolver is restored.
`MTU_REACTIVE_ADDED_SERVER_LOG_FORMAT`	`"Resolver {IP} ({DOMAIN}) added back at {TIME} after reactive recheck (UP {UP_MTU}, DOWN {DOWN_MTU})"`	string	Log/output format when a resolver is restored by background health checks.

3.4.7) 🧵 Runtime Workers, Queues, and Timers

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`RX_TX_WORKERS`	`4`	if invalid, fallback applies	Number of shared runtime workers used for both UDP tunnel reads and writes.
`TUNNEL_PROCESS_WORKERS`	`6`	if invalid, fallback applies	Number of workers processing tunnel packets after read.
`TUNNEL_PACKET_TIMEOUT_SECONDS`	`10.0`	if invalid, fallback applies	Overall timeout for tunnel packet handling.
`DISPATCHER_IDLE_POLL_INTERVAL_SECONDS`	`0.020`	if invalid, fallback applies	When there is nothing to send, the dispatcher sleeps for this interval before polling again.
`RX_CHANNEL_SIZE`	`4096`	if invalid, fallback applies	Capacity of the incoming tunnel packet channel.
`SOCKS_UDP_ASSOCIATE_READ_TIMEOUT_SECONDS`	`30.0`	if invalid, fallback applies	Read timeout for SOCKS UDP associate mode.
`CLIENT_TERMINAL_STREAM_RETENTION_SECONDS`	`45.0`	if invalid, fallback applies	How long terminal streams remain in client bookkeeping before full cleanup.
`CLIENT_CANCELLED_SETUP_RETENTION_SECONDS`	`120.0`	if invalid, fallback applies	Retention time for setup streams cancelled before completion.
`SESSION_INIT_RETRY_BASE_SECONDS`	`1.0`	if invalid, fallback applies	Base delay for session-init retries.
`SESSION_INIT_RETRY_STEP_SECONDS`	`1.0`	if invalid, fallback applies	Step increment used in the retry schedule.
`SESSION_INIT_RETRY_LINEAR_AFTER`	`5`	if invalid, fallback applies	After this many retries, the retry backoff becomes more linear.
`SESSION_INIT_RETRY_MAX_SECONDS`	`60.0`	if invalid, fallback applies	Maximum retry delay for session initialization.
`SESSION_INIT_BUSY_RETRY_INTERVAL_SECONDS`	`60.0`	if invalid, fallback applies	Retry delay when the server explicitly responds with `SESSION_BUSY`.

3.4.8) 📡 Ping / Keepalive

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`PING_AGGRESSIVE_INTERVAL_SECONDS`	`0.100`	positive number	Fastest ping interval used in the hottest activity state.
`PING_LAZY_INTERVAL_SECONDS`	`0.750`	positive number	Normal operating ping interval.
`PING_COOLDOWN_INTERVAL_SECONDS`	`2.0`	positive number	Ping interval during cooldown.
`PING_COLD_INTERVAL_SECONDS`	`15.0`	positive number	Ping interval when the session is cold/mostly idle.
`PING_WARM_THRESHOLD_SECONDS`	`8.0`	positive number	Threshold after which the session is treated as warm.
`PING_COOL_THRESHOLD_SECONDS`	`20.0`	positive number	Threshold after which the session is treated as cooling down.
`PING_COLD_THRESHOLD_SECONDS`	`30.0`	positive number	Threshold after which the session is treated as cold.

3.4.9) 🔄 ARQ and Packet Packing

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`MAX_PACKETS_PER_BATCH`	`8`	if invalid, fallback applies	Maximum number of control items the client tries to batch in one packet turn.
`ARQ_WINDOW_SIZE`	`600`	valid positive range	ARQ send/receive window size per stream.
`ARQ_INITIAL_RTO_SECONDS`	`1.0`	clamped in code	Initial retransmission timeout for data packets.
`ARQ_MAX_RTO_SECONDS`	`5.0`	clamped in code	Maximum retransmission timeout for data packets.
`ARQ_CONTROL_INITIAL_RTO_SECONDS`	`0.5`	clamped in code	Initial retransmission timeout for control packets.
`ARQ_CONTROL_MAX_RTO_SECONDS`	`3.0`	clamped in code	Maximum retransmission timeout for control packets.
`ARQ_MAX_CONTROL_RETRIES`	`400`	clamped in code	Maximum number of retries for control packets.
`ARQ_INACTIVITY_TIMEOUT_SECONDS`	`1800.0`	clamped in code	Stream inactivity timeout.
`ARQ_DATA_PACKET_TTL_SECONDS`	`2400.0`	clamped in code	TTL for data packets before they are abandoned.
`ARQ_CONTROL_PACKET_TTL_SECONDS`	`1200.0`	clamped in code	TTL for control packets.
`ARQ_MAX_DATA_RETRIES`	`1200`	clamped in code	Maximum retries for data packets.
`ARQ_DATA_NACK_MAX_GAP`	`16`	clamped in code	Maximum gap size for NACK generation when packets arrive out of order.
`ARQ_DATA_NACK_INITIAL_DELAY_SECONDS`	`0.1`	clamped in code	Initial delay before sending a NACK for missing data packets. Controls how eagerly the system requests retransmissions.
`ARQ_DATA_NACK_REPEAT_SECONDS`	`1.0`	clamped in code	Minimum interval before repeating a NACK for the same missing sequence.
`ARQ_TERMINAL_DRAIN_TIMEOUT_SECONDS`	`120.0`	clamped in code	After a stream becomes terminal, how long the client waits for queue drain.
`ARQ_TERMINAL_ACK_WAIT_TIMEOUT_SECONDS`	`90.0`	clamped in code	How long the client waits for the final terminal ACK.

3.4.10) 🪵 Logging

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`LOG_LEVEL`	`"INFO"`	usually `DEBUG`, `INFO`, `WARN`, `ERROR`	Controls client log verbosity. `INFO` is usually enough for normal operation. Use `DEBUG` when investigating resolver health, failover, ARQ, or packet paths.

Section 3.5: 📖 Server Configuration (`server_config.toml`)

ℹ️ Note: the sample server config contains a key named CONFIG_VERSION, but the current Go code does not read it into ServerConfig. For that reason it is not included in the table below and has no effect on real server behavior.

3.5.1) 🌐 Tunnel Policy and Protocol Acceptance

Parameter	Sample Value in `server_config.toml.simple`	Allowed Values / Real Behavior	Full Explanation
`DOMAIN`	`["v.domain.com"]`	list of strings	Domain or domains that this server treats as belonging to its tunnel. They must match the client `DOMAINS`, otherwise tunnel packets will not be recognized correctly.
`PROTOCOL_TYPE`	`"SOCKS5"`	only `"SOCKS5"` or `"TCP"`	Determines what kind of setup the server accepts for new streams. In `SOCKS5` mode, the server expects `PACKET_SOCKS5_SYN` and takes the target from the client payload. In `TCP` mode, setup happens through `PACKET_STREAM_SYN` and the server connects to `FORWARD_IP:FORWARD_PORT`.
`MIN_VPN_LABEL_LENGTH`	not shown in sample	if `<=0`, fallback to `3`	Minimum tunnel data label length. This helps avoid confusing ordinary DNS queries with tunnel queries. If this parameter is missing from your old README or config, it is worth adding because the code supports it.
`SUPPORTED_UPLOAD_COMPRESSION_TYPES`	`[0, 1, 2, 3]`	valid compression IDs only	Compression modes the server allows clients to request for upload traffic.
`SUPPORTED_DOWNLOAD_COMPRESSION_TYPES`	`[0, 1, 2, 3]`	valid compression IDs only	Same idea for download traffic from server to client.

3.5.2) 📥 UDP Listener and Front-Door Capacity

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`UDP_HOST`	`"0.0.0.0"`	if empty, this value is used	Address where the DNS server binds. `0.0.0.0` means listen on all interfaces.
`UDP_PORT`	`53`	`1..65535`	UDP port used by the server. In most deployments this should remain `53` so resolvers can query it directly.
`UDP_READERS`	`4`	auto-default if `<=0`	Number of goroutines reading directly from the UDP socket. A larger number may help on very busy servers, but beyond a point it only increases context switching.
`DNS_REQUEST_WORKERS`	`8`	auto-default if `<=0`	Number of workers that take requests from the front-door queue and pass them into the session/decode layer.
`MAX_CONCURRENT_REQUESTS`	`16384`	fallback if `<=0`	Capacity of the incoming request queue. If this queue fills up, packets are dropped and the server emits rate-limited overload logs.
`SOCKET_BUFFER_SIZE`	`4194304`	fallback if `<=0`	Operating-system socket buffer size request for the UDP listener. This matters for heavy bursts of incoming traffic.
`MAX_PACKET_SIZE`	`65535`	fallback if `<=0`	Size of the largest packet buffer that the packet pool allocates.
`DROP_LOG_INTERVAL_SECONDS`	`2.0`	fallback if `<=0`	Minimum interval between repeated overload/drop logs, to avoid log spam during pressure.

3.5.3) 🧠 Deferred Session Runtime

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`DEFERRED_SESSION_WORKERS`	`4`	clamped up to `128`	Number of deferred-session workers. These workers handle ordering-sensitive and setup-heavy tasks such as stream setup, SOCKS connect, and some DNS assembly tasks. Too few can slow down stream setup; too many can create unnecessary contention.
`DEFERRED_SESSION_QUEUE_LIMIT`	`4096`	clamped to `256..14336`	Queue capacity for deferred-session work. If it fills up, new setup or deferred tasks may be rejected.
`SESSION_ORPHAN_QUEUE_INITIAL_CAPACITY`	auto	derived internally	Initial orphan/control queue sizing is derived automatically from server worker counts and batching pressure.
`STREAM_QUEUE_INITIAL_CAPACITY`	auto	derived internally	Per-stream queue initial capacity is derived automatically from ARQ window size and packing pressure.
`DNS_FRAGMENT_STORE_CAPACITY`	auto	derived internally	DNS tunnel fragment store capacity is derived automatically from request concurrency and worker count.
`SOCKS5_FRAGMENT_STORE_CAPACITY`	auto	derived internally	SOCKS5 setup fragment store capacity is derived automatically from deferred-session pressure and concurrency.

3.5.4) 🍪 Session / Stream Lifecycle and Invalid Cookie Tracking

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`INVALID_COOKIE_WINDOW_SECONDS`	`2.0`	fallback if `<=0`	Time window used to count invalid-cookie errors. This helps the server detect broken sessions or clients repeatedly using a wrong cookie.
`INVALID_COOKIE_ERROR_THRESHOLD`	`10`	fallback if `<=0`	If invalid-cookie errors reach this threshold inside the window above, the server responds more aggressively.
`SESSION_TIMEOUT_SECONDS`	`300.0`	fallback if `<=0`	If a session has no activity for this long, the server times it out and cleans it up.
`SESSION_CLEANUP_INTERVAL_SECONDS`	`30.0`	fallback if `<=0`	How often the periodic session cleanup loop runs.
`CLOSED_SESSION_RETENTION_SECONDS`	`600.0`	fallback if `<=0`	How long closed-session metadata is kept so late packets can still be recognized.
`SESSION_INIT_REUSE_TTL_SECONDS`	`600.0`	clamp to `1..86400` seconds	How long session-init signatures are kept for reuse and simple replay protection.
`RECENTLY_CLOSED_STREAM_TTL_SECONDS`	`600.0`	clamp to `1..86400` seconds	How long recently closed streams remain in the “recently closed” table so late SYN packets do not revive them.
`RECENTLY_CLOSED_STREAM_CAP`	`2000`	clamp to `1..1000000`	Maximum number of recently closed stream entries the server keeps.
`TERMINAL_STREAM_RETENTION_SECONDS`	`45.0`	clamp to `1..86400` seconds	How long terminal streams remain before final sweeping.

3.5.5) 📛 DNS Tunnel Upstream

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`DNS_UPSTREAM_SERVERS`	`["1.1.1.1:53", "1.0.0.1:53"]`	fallback if empty	When the client sends a real DNS request through the tunnel, the server forwards it to these upstream resolvers. This section is only for DNS-over-tunnel, not for the tunnel transport itself.
`DNS_UPSTREAM_TIMEOUT`	`4.0`	fallback if `<=0`	Timeout for each exchange with the real DNS upstream.
`DNS_INFLIGHT_WAIT_TIMEOUT_SECONDS`	`60.0`	clamp to `0.1..120` seconds	If several identical DNS queries arrive at the same time, only one upstream lookup is performed and the rest wait as followers. This value controls how long followers wait for the main lookup result.
`DNS_FRAGMENT_ASSEMBLY_TIMEOUT`	`300.0`	fallback if `<=0`	How long the server waits for all fragments of a tunneled DNS query to arrive.
`DNS_CACHE_MAX_RECORDS`	`50000`	fallback if `<1`	Maximum size of the server’s internal DNS cache for tunneled DNS queries.
`DNS_CACHE_TTL_SECONDS`	`300.0`	fallback if `<=0`	TTL of the server-side internal DNS cache.

3.5.6) 🌐 Forwarding and External SOCKS

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`SOCKS_CONNECT_TIMEOUT`	`120.0`	fallback if `<=0`	Timeout for the server’s outbound connection to the final target or to an external SOCKS5 server. The sample shows a higher value, but the real code fallback is `8` seconds.
`USE_EXTERNAL_SOCKS5`	`false`	`true/false`	If `true`, the server sends outbound traffic through an external SOCKS5 server instead of connecting directly. This is mainly useful for chaining or hiding server egress.
`SOCKS5_AUTH`	`false`	`true/false`	Whether the external SOCKS5 server requires username/password authentication.
`SOCKS5_USER`	`"admin"`	up to 255 bytes	Username for the external SOCKS5 server.
`SOCKS5_PASS`	`"123456"`	up to 255 bytes	Password for the external SOCKS5 server. If auth is enabled and username/password are invalid, the config becomes invalid.
`FORWARD_IP`	`""`	string	In `TCP` mode, this is the fixed outbound target. In `SOCKS5` mode with `USE_EXTERNAL_SOCKS5=true`, this is the address of the upstream SOCKS5 server itself.
`FORWARD_PORT`	`0`	`0..65535`	Port of the endpoint above. If `USE_EXTERNAL_SOCKS5=true`, this must be a valid non-zero value.

3.5.7) 🔐 Security

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`DATA_ENCRYPTION_METHOD`	`1`	`0..5`	Must match the client. If an invalid value is supplied, the current code normalizes it back to `1`.
`ENCRYPTION_KEY_FILE`	`"encrypt_key.txt"`	relative or absolute path	Path to the server encryption key file. If it is relative, it is resolved relative to the config directory. If it is empty, the fallback is `encrypt_key.txt`.

3.5.8) 🔄 ARQ, Packing, and Control TTLs

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`MAX_PACKETS_PER_BATCH`	`5`	fallback if `<1`	Maximum number of control blocks the server tries to pack into one response. Important note: if the value is invalid, the real code fallback is `20`.
`PACKET_BLOCK_CONTROL_DUPLICATION`	`1`	clamp to `1..16`	How many extra turns the last packed control block should be repeated. `1` effectively means duplication is off. This is useful on lossy links so critical ACK/close data arrives more reliably.
`STREAM_SETUP_ACK_TTL_SECONDS`	`400.0`	clamp to `1..86400` seconds	TTL of ACK packets related to stream setup.
`STREAM_RESULT_PACKET_TTL_SECONDS`	`300.0`	clamp to `1..86400` seconds	TTL of result packets such as connect success/failure that must reach the client.
`STREAM_FAILURE_PACKET_TTL_SECONDS`	`120.0`	clamp to `1..86400` seconds	TTL of failure packets for setup or outbound errors.
`ARQ_WINDOW_SIZE`	`800`	clamp to `1..16384`	ARQ window size per stream on the server.
`ARQ_INITIAL_RTO_SECONDS`	`1`	clamp to `0.05..60` seconds	Initial retransmission timeout for data packets.
`ARQ_MAX_RTO_SECONDS`	`5.0`	clamp to `[ARQ_INITIAL_RTO_SECONDS, 120]`	Maximum retransmission timeout for data packets.
`ARQ_CONTROL_INITIAL_RTO_SECONDS`	`0.5`	clamp to `0.05..60` seconds	Initial retransmission timeout for control packets.
`ARQ_CONTROL_MAX_RTO_SECONDS`	`3.0`	clamp to `[ARQ_CONTROL_INITIAL_RTO_SECONDS, 120]`	Maximum retransmission timeout for control packets.
`ARQ_MAX_CONTROL_RETRIES`	`300`	clamp to `5..5000`	Maximum retries for control packets.
`ARQ_INACTIVITY_TIMEOUT_SECONDS`	`1800.0`	clamp to `30..86400` seconds	Inactivity timeout for streams.
`ARQ_DATA_PACKET_TTL_SECONDS`	`2400.0`	clamp to `30..86400` seconds	TTL for data packets.
`ARQ_CONTROL_PACKET_TTL_SECONDS`	`1200.0`	clamp to `30..86400` seconds	TTL for control packets.
`ARQ_MAX_DATA_RETRIES`	`1200`	clamp to `60..100000`	Maximum retries for data packets.
`ARQ_DATA_NACK_MAX_GAP`	`16`	clamp to `0..255`	If out-of-order packets arrive, this controls how large a missing gap may be reported with NACK.
`ARQ_DATA_NACK_INITIAL_DELAY_SECONDS`	`0.3`	clamped in code	Initial delay before sending a NACK for missing data packets. Controls how eagerly the system requests retransmissions.
`ARQ_DATA_NACK_REPEAT_SECONDS`	`1.0`	clamp to `0.1..30` seconds	For a missing sequence, this defines how soon a repeated NACK may be issued again.
`ARQ_TERMINAL_DRAIN_TIMEOUT_SECONDS`	`120.0`	clamp to `10..3600` seconds	After a stream becomes terminal, how long the server waits for queues to drain.
`ARQ_TERMINAL_ACK_WAIT_TIMEOUT_SECONDS`	`90.0`	clamp to `5..3600` seconds	After terminal close, how long the server waits for the final ACK.

3.5.9) 🪵 Logging

Parameter	Sample Value	Allowed Values / Real Behavior	Full Explanation
`LOG_LEVEL`	`"INFO"`	usually `DEBUG`, `INFO`, `WARN`, `ERROR`	Server log level. For normal production usage, `INFO` is usually enough. For deep investigation of sessions, deferred workers, or ARQ behavior, temporarily use `DEBUG`.

3.5.10) Session Policy Sync

During SESSION_INIT, the server may append a compact policy block to SESSION_ACCEPT. The client applies these limits immediately before normal runtime starts.

Server-enforced max values reduce the client only when the requested value is higher.
Server-enforced min values raise the client only when the requested value is lower.
MTU limits are enforced on both sides:
- The server clamps the accepted session MTU during init.
- The client also clamps its local runtime settings after decode.
Runtime-derived state such as worker counts, queues, fragment stores, and packed-block sizing is rebuilt from the effective synced values.
Legacy servers that still send the old 7-byte SESSION_ACCEPT payload remain compatible; policy sync is simply skipped.

Section 3.6: 🧪 Testing, Finding, and Scanning Resolvers

Finding suitable resolvers is one of the most important parts of any DNS tunnel project. In this project, the client can automatically find healthy resolvers and test their MTU. You can use this client feature to discover healthy resolvers, test your own resolvers, or scan resolver ranges. Just place all IPs line by line into client_resolvers.txt.

Then back up your current client_config.toml, open it with a text editor, and replace the following values with these suggested ones:

Lower the MTU ceiling so you find all servers that really behave as DNS servers, and make Min and Max equal to speed up scanning by avoiding automatic binary-search style probing.

MIN_UPLOAD_MTU=30
MIN_DOWNLOAD_MTU=40
MAX_UPLOAD_MTU=30
MAX_DOWNLOAD_MTU=40

Increase the number of parallel resolver checks:

MTU_TEST_PARALLELISM = 200

Save healthy resolver results into a text file for later review:

SAVE_MTU_SERVERS_TO_FILE = true

Change the output format so only the IP is written, which is easier to reuse:

MTU_SERVERS_FILE_FORMAT = "{IP}"

Reduce retries and timeout to speed up the scan. With these settings you may miss some slightly slower but still healthy resolvers, so increase them if you want more accurate results.

MTU_TEST_RETRIES = 1
MTU_TEST_TIMEOUT = 1.0

⚠️ Important note: You must already have a server running and must place its key and domain into client_config.toml before doing this. Otherwise the client cannot perform MTU tests correctly and will likely mark all resolvers invalid.

Now run the program and wait for the tests to finish. After the process completes, close the program. You will find the saved resolver list in a new .txt file next to the main file, and you can then use it as your new client_resolvers.txt.

After that, return to your previous settings and use the healthy resolvers you discovered for the best performance.

Section 3.7: ⚡ Better MTU Understanding and Practical Fast Tuning

This project depends heavily on a suitable MTU. If you set the MTU too high:

more resolvers fail
startup becomes longer
fragmentation and loss increase

If you set it too low:

speed decreases
but stability improves

Practical suggestion

Start with the sample config.
Let the client test resolvers.
Review the MTU results and the number of valid resolvers.
If quality is poor, lower MIN_UPLOAD_MTU and MIN_DOWNLOAD_MTU slightly.
If you want faster startup, narrow the MIN/MAX MTU range and bring them closer together.

Section 4: Mobile Usage Guide (Android and iPhone) 📱

Since there is currently no official Android or iOS application published directly by us, you can still use the tunnel on mobile with one of these methods. You can also use Android clients built by other developers that are introduced in Section 5.1.

Method 1: Share the proxy from your computer 📶

Set LISTEN_IP to 0.0.0.0
Run the client on your computer
Put your phone and computer on the same network
Configure a SOCKS5 proxy on the phone using the computer IP and LISTEN_PORT

Method 2: Run the client on an intermediate server 🏗️

Run the main server on the final destination
Run the client on an intermediate server
Set LISTEN_IP to 0.0.0.0
Connect the phone to the SOCKS5 proxy on that intermediate server

Method 3: Combine it with other panels or services 🛠️

If you already have another panel or service on a server, you can point its outbound path to the local SOCKS5 of the MasterDnsVPN client and use it as the exit path.

⚠️ Important Security Notes for Mobile

If LISTEN_IP = "0.0.0.0", enable SOCKS5 authentication or make sure your network is trusted. Otherwise anyone on that network can use your tunnel. Using username/password on Internet-facing SOCKS5 is strongly recommended.
You can also change the default LISTEN_PORT so it is less exposed to automated scans.
If devices cannot connect, check the system firewall.

Section 5: Side Notes and Extra Information 🖥️

Section 5.1: Community Projects Related to MasterDnsVPN 🧩

In this section, we introduce a few projects related to MasterDnsVPN that have been developed by other people. They may be useful for practical use, inspiration, or experimentation. Please note that these projects are independent from MasterDnsVPN itself and may behave differently or include their own additional features and design choices.

If you use these projects or benefit from their ideas, please consider supporting their developers by starring their GitHub repositories. If you encounter issues or have suggestions, it is best to open an issue or, if possible, contribute with a pull request to those projects directly.

You can review these related projects here:

MDV HN Edition Android Client An Android application built around MasterDnsVPN that allows connecting to MasterDnsVPN servers from a phone. This project is developed independently by Hidden Node.
MasterDnsVPN GG Android Client Another Android client built around MasterDnsVPN. This project is developed independently by RevocGG.
Persian Config Builder for MasterDnsVPN - Web Config Builder A tool that helps create MasterDnsVPN configuration files with Persian explanations and a guided interface. This project is developed independently by datacoder-io.
MasterDnsWeb (Web Management Client) A web-based management client for MasterDnsVPN, designed to make it easy to manage one or multiple instances at the same time. Developed independently by Abolix.
KevinNet DNS A companion tool for MasterDnsVPN that discovers and validates working DNS resolvers, especially for users in Iran. It generates ready-to-use configuration files and performs end-to-end tunnel verification. This project is developed independently by Kevin Haji.

Section 5.2: Fixing Port 53 Already in Use (Linux Server) 🛑

On most Linux distributions, port 53 is already occupied by systemd-resolved. If the server does not start:

sudo nano /etc/systemd/resolved.conf

Set this value:

DNSStubListener=no

Then:

sudo systemctl restart systemd-resolved

⚠️ Important warning: You cannot run multiple DNS tunnel projects at the same time on the same server on port 53.

Section 5.3: Integrate with 3X-UI and use as an Outbound in other panels 🧩

You can use the MasterDnsVPN client as a local proxy inside panels such as 3X-UI or any other system that supports local outbound proxies. Follow these steps:

Run the MasterDnsVPN client on the same server where your panel is running.
In 3X-UI, go to Inbound and create a new inbound (VLESS/VMess or any protocol you want).
Open Xray Configs, then go to the Outbound tab.
Click Add Outbound to create a new outbound.
Set Protocol to Socks.
Choose a tag (for example: MasterDnsVPN-Out).
In Address, enter the local IP of the MasterDnsVPN client (usually 127.0.0.1).
In Port, enter the LISTEN_PORT you set in client_config.toml (for example 18000).
If SOCKS authentication is enabled in MasterDnsVPN, enter the same username/password here.
Click Add Outbound to save it.
Go to the Routing Rules tab and click Add Rule.
In Inbound Tags, pick the inbound you created.
In Outbound Tags, select the MasterDnsVPN-Out tag.
Click Save and Restart Xray.

Now all traffic for that inbound will go through MasterDnsVPN and exit via your DNS tunnel.

Section 6: 🛠️ System Architecture and How It Works

MasterDnsVPN combines Session Multiplexing, Resolver Balancing, Packet Duplication, a custom ARQ layer, and a Deferred Session Runtime on top of UDP/DNS to avoid the usual limitations of ordinary tunnels.

Section 6.1: 🌐 High-Level Architecture Diagram

graph TD
    subgraph Client_Side ["🖥️ User Device (Client)"]
        App["📱 Applications (Browser, Telegram, etc.)"]
        Proxy["🧦 Local SOCKS5 / TCP Proxy"]
        LDNS["📛 Local DNS (Optional)"]
        ResolverRuntime["⚡ Balancer + Duplication + Resolver Health"]
        ClientARQ["🔄 ARQ + Session/Stream Runtime"]
    end

    subgraph DNS_Network ["🌐 Public DNS Network"]
        R1["📡 Resolver 1"]
        R2["📡 Resolver 2"]
        RN["📡 Resolver N"]
    end

    subgraph Server_Side ["🖥️ Remote Server"]
        UDP["📥 UDP Listener + Request Workers"]
        Sessions["🧠 Session Store + Deferred Workers"]
        ServerARQ["🔄 Server ARQ + Packed Control Blocks"]
        DNSUp["📛 DNS Upstream / Cache"]
        Out["🌐 Direct Dial or External SOCKS5"]
    end

    App --> Proxy
    App --> LDNS
    Proxy --> ClientARQ
    LDNS --> ClientARQ
    ClientARQ --> ResolverRuntime
    ResolverRuntime --> R1
    ResolverRuntime --> R2
    ResolverRuntime --> RN
    R1 --> UDP
    R2 --> UDP
    RN --> UDP
    UDP --> Sessions
    Sessions --> ServerARQ
    Sessions --> DNSUp
    ServerARQ --> Out
    DNSUp --> UDP

Section 6.2: 🔄 Packet Lifecycle and Flow

sequenceDiagram
    participant App as 📱 User App
    participant Client as 🖥️ Client
    participant DNS as 📡 Resolvers
    participant Server as 🖥️ Server
    participant Target as 🌐 Final Target

    App->>Client: Create SOCKS5 / TCP connection
    Note over Client: Build Session/Stream<br/>Encrypt, ARQ, choose resolver
    Client->>DNS: Send DNS query with duplication and balancing
    DNS->>Server: Deliver query to the server NS
    Note over Server: Checksum / Cookie / Session lookup<br/>Deferred setup / ARQ / Queueing
    Server->>Target: Direct dial or external SOCKS5
    Target-->>Server: Return target response
    Note over Server: Put data into ARQ<br/>Build ACKs and packed control blocks
    Server-->>DNS: DNS response
    DNS-->>Client: DNS reply
    Note over Client: ARQ reorder / ACK consume / deliver to app
    Client-->>App: Ordered clean data

Section 6.3: 🧠 Core Concepts Used by the System

Concept	Description
Session	One overall connection between client and server
Stream	One independent logical connection carried inside a session
Resolver Runtime	Resolver selection, duplication, health tracking, auto-disable, and recheck
ARQ	Ordering, ACK, retransmission, timeout, and terminal handling
Deferred Session Runtime	Ordering-sensitive tasks such as setup, DNS query handling, and sensitive packet flows
Packed Control Blocks	Multiple small ACK or control packets packed into one block
Synced MTU	The shared MTU chosen across the healthy resolver pool

Section 7: ⚙️ Advanced Technical Notes

⚡ Direct connect or external SOCKS5: If USE_EXTERNAL_SOCKS5 = false, the server connects directly to the target. If true, it chains through an external SOCKS5 proxy. In general usage you usually do not need an external SOCKS5 server, so this can stay disabled.
🧠 Per-stream resolver failover: If a stream gets stuck on a weak resolver, its preferred resolver can move to another one.
📦 Repeated packed control blocks: The server can repeat the last packed control block for extra turns so important ACK/close packets have a better chance to survive on lossy links.
🔒 Server-side key generation: If encrypt_key.txt does not exist, the server creates it during startup.

🤝 Contributing

We welcome all contributions. If you have an idea, bug report, or performance improvement, please open an Issue or Pull Request.

Issues

Pull Requests

📄 License

This project is published under the MIT license. For more details, see the LICENSE file.

👨‍💻 Developer

Developed with ❤️ by: MasterkinG32

chenhg5/cc-connect

Bridge local AI coding agents (Claude Code, Cursor, Gemini CLI, Codex) to messaging platforms (Feishu/Lark, DingTalk, Slack, Telegram, Discord, LINE, WeChat Work). Chat with your AI dev assistant from anywhere — no public IP required for most platforms.

English | 中文

❤️ Sponsor

Want to appear here? Contact: chg80333@gmail.com | WeChat: mongorz

Sponsors

MiniMax-M2.7 is a next-generation large language model designed for autonomous evolution and real-world productivity. Unlike traditional models, M2.7 actively participates in its own improvement through agent teams, dynamic tool use, and reinforcement learning loops. It delivers strong performance in software engineering (56.22% on SWE-Pro, 55.6% on VIBE-Pro, 57.0% on Terminal Bench 2) and excels in complex office workflows, achieving a leading 1495 ELO on GDPval-AA. With high-fidelity editing across Word, Excel, and PowerPoint, and a 97% adherence rate across 40+ complex skills, M2.7 sets a new standard for building AI-native workflows and organizations.

Click here to get an exclusive 12% off the MiniMax Token Plan + voucher for cc-connect users!

	Thanks to AIGoCode for sponsoring this project! AIGoCode is an all-in-one platform that integrates Claude Code, Codex, and the latest Gemini models, providing you with stable, efficient, and highly cost-effective AI coding services. The platform offers flexible subscription plans, zero risk of account suspension, direct access with no VPN required, and lightning-fast responses. AIGoCode has prepared a special benefit for cc-connect users: if you register via this link, you'll receive an extra 10% bonus credit on your first top-up!
AIHubMix	Thanks to AIHubMix for sponsoring this project! AIHubMix offers deep integration with 500+ global models including OpenAI, Claude, Gemini, Qwen, DeepSeek, Kimi. Unlimited concurrency, production-grade stability on Google Cloud. One API Key drives all your Agents with native OpenAI/Anthropic/Gemini format support — zero code changes. Pay-as-you-go pricing aligned with official providers, plus free models like coding-glm-5.1-free. Click here to sign up!
	Thanks to NekoCode for sponsoring this project! NekoCode provides reliable, stable, and efficient API relay services for Claude and CodeX with transparent pricing. Exclusive 10% discount for cc-connect users with promo code: CC-CONNECT. High-value, stable AI model access for developers. Register via this link.
	Thanks to DMXAPI for sponsoring this project! DMXAPI provides global large model API services to 200+ enterprise users. One API key for all global models. Features include: instant invoicing, unlimited concurrency, starting from $0.15, 24/7 technical support. GPT/Claude/Gemini all at 32% off, domestic models 20-50% off, Claude Code exclusive models at 66% off! Register via this link.
	Thanks to Shengsuanyun for sponsoring this project! Shengsuanyun is a super factory dedicated to serving AI Native Teams, an industrial-grade AI task parallel execution platform, and a model marketplace that aggregates and supplies computing power from domestic and international LLM and image/video multimedia models such as Claude, Chatgpt, and Gemini. It guarantees no reverse engineering or data manipulation, boasts a 99.7% SLA availability across the entire site, and its monitoring interface is consistently green. Furthermore, it offers an enterprise-grade customized gateway for refined cost and access control, featuring intelligent routing, security protection, and BYOK enterprise-provided key hosting. The platform is billed on a pay-as-you-go basis and with a tokens plan (coming soon), and invoices are available. New users who register using this link will receive 10 yuan in model power and a 10% bonus on their first deposit.
	Thanks to AICodeMirror for sponsoring this project! AICodeMirror provides official high-stability relay services for Claude Code / Codex / Gemini CLI, with enterprise-grade concurrency, fast invoicing, and 24/7 dedicated technical support. Claude Code / Codex / Gemini official channels at 38% / 2% / 9% of original price, with extra discounts on top-ups! AICodeMirror offers special benefits for CC users: register via this link to enjoy 20% off your first top-up, and enterprise customers can get up to 25% off!
	Thanks to AnyRoute.io for sponsoring this project! AnyRoute.io is a reliable, stable, and efficient API relay platform integrating the latest Claude Code and Codex models. Transparent pricing with rates as low as 93% off official prices (just 0.7x), supports invoicing and enterprise-grade high-concurrency usage. Register via this link to get started.
	Thanks to aicanapi.com for sponsoring this project! Aican API provides high-performance, low-latency, high-concurrency API services for enterprises and developers. Claude Code models at up to 84% off, other models at 80% off official price. Doubao Seedance 2 real-person generation service with queue-free access for faster responses. Choose Aican API for simpler, more efficient, and more cost-effective enterprise-grade AI services. Register via this link to get started.
	Thanks to Pateway for sponsoring this project! PatewayAI is a premium API relay service for serious AI developers, offering 100% official direct access to Claude and Codex models — no reverse engineering, no quality degradation. Transparent billing with token-level verification. Enterprise-grade concurrency, formal contracts and invoicing available. Register via this link to get $3 free trial credit, up to 40% off on top-ups, and referral rewards up to $150!
	Thanks to 10点AI for sponsoring this project! 10dian-AI Enterprise Platform is an AI API gateway for developers and enterprises, aggregating GPT, Claude, Gemini, DeepSeek and more. Optimized for production environments with stable high-concurrency operation, avoiding interface jitter and timeout issues. Affordable pricing, stable uptime, official guarantee. Register via this link to get ¥5 free credit!
	Thanks to Code0 for sponsoring this project! Code0 is an AI model aggregation API relay service for Chinese developers, compatible with OpenAI / Anthropic / Gemini protocols. One key for all mainstream models, stable support for Claude Code, Codex, Gemini CLI, cc-connect and more. Fixed exchange rate: ¥1.5 CNY = $1 USD API credit, transparent pricing, domestic direct connection, ready to use. Register via this link.
	Thanks to 优云智算 for sponsoring this project! 优云智算 (UCloud AI Cloud Platform) provides stable and comprehensive domestic and international model APIs with just one key. Featuring high-value Coding Plan packages (monthly or per-use), plus stable official relay for overseas models. Supports Claude Code, Codex, and API calls. Enterprise features include high concurrency, 7x24 technical support, and self-service invoicing. Register via this link to receive ¥5 free platform credit!
	Thanks to DragonCode for supporting this project. DragonCode has prepared a special benefit for cc-connect users: register via this link to get started.
	Thanks to VisionCoder for supporting this project. VisionCoder Developer Platform is a reliable and efficient API relay service provider, offering access to mainstream AI models such as Claude Code, Codex, and Gemini. It helps developers and teams integrate AI capabilities more easily and improve productivity. VisionCoder is also offering our users a limited-time Token Plan promotion: buy 1 month and get 1 month free.
	Thanks to claudeapi.com for sponsoring this project! claudeapi is a high-quality direct Claude connection service for mid-to-high-end users. It is fully integrated with Anthropic's official first-party Keys and AWS Bedrock official channels — no reverse engineering, no intelligence degradation, no stitching. It fully preserves the official capabilities, long context, and tool-calling performance of Opus / Sonnet / Haiku. Designed specifically for Claude Code power users, Agent developers, and enterprise teams, it focuses on out-of-the-box usability and enterprise-grade stability. Invoicing and team onboarding are supported. Register via this link.
	Thanks to DDS for sponsoring this project! DDS Hub is a reliable and high-performance Claude and CodeX API proxy service. We provides cost-effective domestic Claude direct acceleration services for both individual and enterprise users. We offer stable and low-latency Claude Max number pools, with full support for Claude Haiku, Opus, Sonnet, GPT 5.4 and other flagship models. Invoices are available for recharges of 1000 RMB or more. Enterprise customers can also enjoy customized grouping and dedicated technical support services. Exclusive benefit for CC connect users: Register via this link and enjoy an extra 10% credit on your first recharge (please contact the group admin to claim after recharging)!

Control your local AI agents from any chat app. Anywhere, anytime.

cc-connect bridges AI agents running on your machine to the messaging platforms you already use.
Code review, research, automation, data analysis — anything an AI agent can do,
now accessible from your phone, tablet, or any device with a chat app.

🆕 What’s New in v1.3.0

🌐 Web Admin UI (Recommended) — Full management dashboard embedded in the binary — no extra dependencies. Create and edit projects, manage providers, monitor sessions, edit cron jobs, and chat with your agent directly from the browser. Supports 5 languages (en/zh/zh-TW/ja/es). We recommend managing cc-connect through the web UI instead of editing config.toml by hand. Run cc-connect web to configure and open the dashboard, then run cc-connect to start the service.
Lifecycle Event Hooks — New [[hooks]] config triggers shell commands or HTTP webhooks on message, session, cron, permission, and error events. Async by default, fail-open.
Skill Management — New /skills page with local skill browser and recommended presets.
Global Provider Management — Add/edit/delete providers in the web UI; import from cc-switch config.
Personal WeChat — Chat with your local agent from Weixin (personal) via ilink long-polling; QR weixin setup, CDN media, no public IP. Setup → docs/weixin.md
Weibo DM — Chat with your agent via Weibo private messages over WebSocket; no public IP needed, text streaming supported.
Feishu Enhancements — Auto-resolve @name mentions, multi-level reply chain recognition, done-emoji reactions.
New Agents — Kimi CLI and Pi agent support added.

🧩 Platform feature snapshot

High-level view of what each built-in platform can do in cc-connect.

Legend

Symbol	Meaning
✅	Works in stable cc-connect with typical configuration
⚠️	Partial, needs extra config (e.g. speech / ASR), or limited by the vendor app or API
❌	Not supported or not applicable in practice

† QQ (NapCat / OneBot) — unofficial self-hosted bridge; behaviour depends on your NapCat / network setup.

Capability	Feishu	DingTalk	Telegram	Slack	Discord	LINE	WeCom	Weibo	Weixin (personal)	QQ†	QQ Bot
Text & slash commands	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Markdown / cards	✅	✅	✅	✅	✅	⚠️	⚠️	❌	✅	✅	✅
Streaming / chunked replies	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Images & files	✅	✅	✅	✅	✅	⚠️	✅	❌	✅	✅	✅
Voice / STT / TTS	⚠️	⚠️	✅	⚠️	⚠️	❌	⚠️	❌	✅	⚠️	⚠️
Private (DM)	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Group / channel	✅	✅	✅	✅	✅	⚠️	✅	❌	✅	✅	✅

WeCom: Webhook mode needs a public URL; long-connection / WS style setups often do not.
Voice row: many platforms need [speech] / TTS providers enabled in config.toml; values are a best-effort summary.
Per-platform setup: Platform setup guides below.

✨ Why cc-connect?

🤖 Universal Agent Support

10+ AI Agents — Claude Code, Codex, Cursor Agent, Kimi CLI, Qoder CLI, Gemini CLI, OpenCode, iFlow CLI, Pi, Devin — plus any agent that supports the Agent Client Protocol (ACP). Use whichever fits your workflow, or all of them at once.

📱 Platform Flexibility

11 Chat Platforms — Feishu, DingTalk, Slack, Telegram, Discord, WeChat Work, Weibo, LINE, QQ, QQ Bot (Official), plus Weixin (personal ilink) for personal WeChat. Most platforms need zero public IP.

🔄 Multi-Agent Orchestration

Multi-Bot Relay — Bind multiple bots in a group chat and let them communicate with each other. Ask Claude, get insights from Gemini — all in one conversation.

🎮 Complete Chat Control

Full Control from Chat — Switch models (/model), tune reasoning (/reasoning), change permission modes (/mode), manage sessions, all via slash commands.

Directory Switching in Chat — Change where the next session starts with /dir <path> (and /cd <path> as a compatibility alias), plus quick history jump via /dir <number> / /dir -.

🧠 Persistent Memory

Agent Memory — Read and write agent instruction files (/memory) without touching the terminal.

⏰ Intelligent Scheduling

Scheduled Tasks — Set up cron jobs in natural language. "Every day at 6am, summarize GitHub trending" just works.

🎤 Multimodal Support

Voice & Images — Send voice messages or screenshots; cc-connect handles STT/TTS and multimodal forwarding.

📦 Multi-Project Architecture

Multi-Project — One process, multiple projects, each with its own agent + platform combo.

🌍 Multilingual Interface

5 Languages — Native support for English, Chinese (Simplified & Traditional), Japanese, and Spanish. Built-in i18n ensures everyone feels at home.

Left：Lark | Telegram | Right：Wechat

🚀 Quick Start

🤖 Install & Configure via AI Agent (Recommended)

The easiest way — Send this to Claude Code or any AI coding agent, and it will handle the entire installation and configuration for you:

Follow https://raw.githubusercontent.com/chenhg5/cc-connect/refs/heads/main/INSTALL.md to install and configure cc-connect.

📦 Manual Install

Via npm:

npm install -g cc-connect

Via Homebrew (macOS / Linux):

brew install cc-connect

Download binary from GitHub Releases:

# Linux amd64 - Stable
curl -L -o cc-connect https://github.com/chenhg5/cc-connect/releases/latest/download/cc-connect-linux-amd64
chmod +x cc-connect
sudo mv cc-connect /usr/local/bin/

Build from source (requires Go 1.22+):

git clone https://github.com/chenhg5/cc-connect.git
cd cc-connect
make build

⚙️ Configure

💡 Tip: Use the Web UI to configure — After installing, run cc-connect web to configure the web admin and open the dashboard in your browser. You can visually create projects, add platforms, manage providers, and chat with your agent — no need to manually edit TOML files. Note: cc-connect web only configures and opens the browser — you still need to run cc-connect separately to start the service.

If you prefer manual configuration:

mkdir -p ~/.cc-connect
cp config.example.toml ~/.cc-connect/config.toml
vim ~/.cc-connect/config.toml

Set admin_from = "alice,bob" in a project to allow those user IDs to run privileged commands such as /dir and /shell. When a user runs /dir reset, cc-connect restores the configured work_dir and clears the persisted override stored under data_dir/projects/<project>.state.json.

▶️ Run

./cc-connect

🔄 Upgrade

# npm
npm install -g cc-connect

# Homebrew
brew upgrade cc-connect

# Binary self-update
cc-connect update           # Stable
cc-connect update --pre     # Include pre-releases

📊 Support Matrix

Component	Type	Status
Agent	Claude Code	✅ Supported
Agent	Codex (OpenAI)	✅ Supported
Agent	Cursor Agent	✅ Supported
Agent	Gemini CLI (Google)	✅ Supported
Agent	Qoder CLI	✅ Supported
Agent	OpenCode (Crush)	✅ Supported
Agent	iFlow CLI	✅ Supported
Agent	Kimi CLI (Moonshot)	✅ Supported
Agent	Pi (Cursor Background Agent)	✅ Supported
Agent	ACP (Agent Client Protocol)	✅ Any ACP-compatible agent
Agent	Devin (Cognition)	✅ Supported (via ACP)
Agent	Goose (Block)	🔜 Planned
Agent	Aider	🔜 Planned
Platform	Feishu (Lark)	✅ WebSocket — no public IP needed
Platform	DingTalk	✅ Stream — no public IP needed
Platform	Telegram	✅ Long Polling — no public IP needed
Platform	Slack	✅ Socket Mode — no public IP needed
Platform	Discord	✅ Gateway — no public IP needed
Platform	Weibo	✅ WebSocket — no public IP needed
Platform	LINE	✅ Webhook — public URL required
Platform	WeChat Work	✅ WebSocket / Webhook
Platform	Weixin (personal, ilink)	✅— HTTP long polling — no public IP needed
Platform	QQ (NapCat/OneBot)	✅ WebSocket
Platform	QQ Bot (Official)	✅ WebSocket — no public IP needed

📖 Platform Setup Guides

Platform	Guide	Connection	Public IP?
Feishu (Lark)	docs/feishu.md	WebSocket	No
DingTalk	docs/dingtalk.md	Stream	No
Telegram	docs/telegram.md	Long Polling	No
Slack	docs/slack.md	Socket Mode	No
Discord	docs/discord.md	Gateway	No
Weibo	docs/weibo.md	WebSocket	No
WeChat Work	docs/wecom.md	WebSocket / Webhook	No (WS) / Yes (Webhook)
Weixin (personal)	docs/weixin.md	HTTP long polling (ilink)	No
QQ / QQ Bot	docs/qq.md	WebSocket	No

🎯 Key Features

💬 Session Management

/new [name]       Start a new session
/list             List all sessions
/switch <id>      Switch session
/current          Show current session
/dir [path|reset] Show, switch, or reset work directory

Project configs rotate to a fresh session automatically after long inactivity. This prevents "context drift" where stale chat history (failed commands, debugging noise) is repeatedly re-ingested via --continue and starts to dominate the model's attention. The previous session is preserved and remains accessible via /list and /switch.

[[projects]]
reset_on_idle_mins = 30   # default when unset; set to 0 to disable

The default is 30 minutes when unset. Set reset_on_idle_mins = 0 to opt out and always continue the previous session.

🛡️ OS-User Isolation (`run_as_user`)

On Linux/macOS, a project can spawn its agent under a different Unix user for OS-level file-system isolation from the supervisor user that runs cc-connect. Currently supported by Claude Code.

[[projects]]
name = "claude-sandboxed"
run_as_user = "partseeker-coder"
run_as_env = ["PGSSLROOTCERT"]

The target user needs passwordless sudo from the supervisor, no sudo of its own, read+write on work_dir, and its own ~/.claude/settings.json with whatever credentials the agent uses. If you authenticate via claude.ai OAuth, symlink the target user's ~/.claude/.credentials.json to the supervisor's copy so token refresh stays in sync — see the environment propagation checklist for details. See docs/usage.md for the full setup.

Before starting cc-connect, audit the setup with:

cc-connect doctor user-isolation

This runs three go/no-go preflight gates and an isolation probe that reports what the target user can and cannot read. cc-connect refuses to start if any gate fails or if the probe detects a cross-user leak.

🔐 Permission Modes

/mode             Show available modes
/mode yolo        # Auto-approve all tools
/mode default     # Ask for each tool

🔄 Provider Management

/provider list              List providers
/provider switch <name>     Switch API provider at runtime

🤖 Model Selection

/model                      List available models (format: alias - model)
/model switch <alias>       Switch to model by alias

📂 Work Directory

/dir                         Show current work directory and history
/dir <path>                  Switch to a path (relative or absolute)
/dir <number>                Switch from history
/dir -                       Switch to previous directory
/cd <path>                   Compatibility alias for /dir <path>

⏰ Scheduled Tasks

/cron add 0 6 * * * Summarize GitHub trending

📎 Agent Attachment Send-Back

When an agent generates a local screenshot, chart, PDF, bundle, or other file, it can send that attachment back to the current chat.

First release supports:

Feishu
Telegram

If your agent does not natively inject the system prompt, run this once in chat after upgrading:

/bind setup

or:

/cron setup

This refreshes the cc-connect instructions in the project memory file so the agent knows how to send attachments back.

You can control this feature globally in config.toml:

attachment_send = "on"  # default: "on"; set to "off" to block image/file send-back

This switch is independent from the agent's /mode. It only controls cc-connect send --image/--file.

Examples:

cc-connect send --image /absolute/path/to/chart.png
cc-connect send --file /absolute/path/to/report.pdf
cc-connect send --file /absolute/path/to/report.pdf --image /absolute/path/to/chart.png

Notes:

Absolute paths are the safest option.
--image and --file can both be repeated.
attachment_send = "off" disables only attachment send-back; ordinary text replies still work.
This command is for generated attachments, not ordinary text replies.

📖 Full documentation: docs/usage.md

📚 Documentation

Usage Guide — Complete feature documentation
INSTALL.md — AI-agent-friendly installation guide
config.example.toml — Configuration template
CONTRIBUTING.md — How to report issues and contribute pull requests

👥 Community

☕ Support the Project

If cc-connect has been helpful to you, consider buying us a coffee! Your support helps us:

🛠️ Maintain and improve the project
📚 Write better documentation and tutorials
🐛 Fix bugs and add new features faster
☕ Keep the developers caffeinated

How to Donate

Buy Me a Coffee: https://buymeacoffee.com/cg33

WeChat Pay / Alipay:

WeChat Pay	Alipay

Thank You, Donors! 🎉

We're grateful to everyone who has supported this project. Leave your GitHub username in the donation message if you'd like to be recognized here!

Avatar	GitHub Username	Date
	@thx0701	2026-04-29

🤝 Commercial Cooperation

We accept the following commercial collaborations:

Enterprise Customization: Custom deployment for internal AI tooling (Feishu, DingTalk, WeChat Work, Slack, etc.)
Technical Consulting: AI agent integration and architecture design
Outsourcing Projects: AI-related system development

Contact: Email: chg80333@gmail.com | WeChat: mongorz | Telegram | Discord

🙏 Contributors

⭐ Star History

📄 License

MIT License

_{Built with ❤️ by the cc-connect community}

apernet/hysteria

Hysteria is a powerful, lightning fast and censorship resistant proxy.

Get Started

中文文档

Hysteria 1.x (legacy)

🛠️ Jack of all trades

Wide range of modes including SOCKS5, HTTP Proxy, TCP/UDP Forwarding, Linux TProxy, TUN - with more features being added constantly.

⚡ Blazing fast

Powered by a customized QUIC protocol, Hysteria is designed to deliver unparalleled performance over unreliable and lossy networks.

✊ Censorship resistant

The protocol masquerades as standard HTTP/3 traffic, making it very difficult for censors to detect and block without widespread collateral damage.

💻 Cross-platform

We have builds for every major platform and architecture. Deploy anywhere & use everywhere. Not to mention the long list of 3rd party apps.

🔗 Easy integration

With built-in support for custom authentication, traffic statistics & access control, Hysteria is easy to integrate into your infrastructure.

🤗 Chill and supportive

We have well-documented specifications and code for developers to contribute and/or build their own apps. And a helpful community, too.

If you find Hysteria useful, consider giving it a ⭐️!

gitleaks/gitleaks

Find secrets with Gitleaks 🔑

Gitleaks

┌─○───┐
│ │╲  │
│ │ ○ │
│ ○ ░ │
└─░───┘

Gitleaks is a tool for detecting secrets like passwords, API keys, and tokens in git repos, files, and whatever else you wanna throw at it via stdin. If you wanna learn more about how the detection engine works check out this blog: Regex is (almost) all you need.

➜  ~/code(master) gitleaks git -v

    ○
    │╲
    │ ○
    ○ ░
    ░    gitleaks


Finding:     "export BUNDLE_ENTERPRISE__CONTRIBSYS__COM=cafebabe:deadbeef",
Secret:      cafebabe:deadbeef
RuleID:      sidekiq-secret
Entropy:     2.609850
File:        cmd/generate/config/rules/sidekiq.go
Line:        23
Commit:      cd5226711335c68be1e720b318b7bc3135a30eb2
Author:      John
Email:       john@users.noreply.github.com
Date:        2022-08-03T12:31:40Z
Fingerprint: cd5226711335c68be1e720b318b7bc3135a30eb2:cmd/generate/config/rules/sidekiq.go:sidekiq-secret:23

Getting Started

Gitleaks can be installed using Homebrew, Docker, or Go. Gitleaks is also available in binary form for many popular platforms and OS types on the releases page. In addition, Gitleaks can be implemented as a pre-commit hook directly in your repo or as a GitHub action using Gitleaks-Action.

Installing

# MacOS
brew install gitleaks

# Docker (DockerHub)
docker pull zricethezav/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path zricethezav/gitleaks:latest [COMMAND] [OPTIONS] [SOURCE_PATH]

# Docker (ghcr.io)
docker pull ghcr.io/gitleaks/gitleaks:latest
docker run -v ${path_to_host_folder_to_scan}:/path ghcr.io/gitleaks/gitleaks:latest [COMMAND] [OPTIONS] [SOURCE_PATH]

# From Source (make sure `go` is installed)
git clone https://github.com/gitleaks/gitleaks.git
cd gitleaks
make build

Pre-Commit

Install pre-commit from https://pre-commit.com/#install
Create a .pre-commit-config.yaml file at the root of your repository with the following content:
```
repos:
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.24.2
    hooks:
      - id: gitleaks
```
for a native execution of gitleaks or use the gitleaks-docker pre-commit ID for executing gitleaks using the official Docker images
Auto-update the config to the latest repos' versions by executing pre-commit autoupdate
Install with pre-commit install
Now you're all set!

➜ git commit -m "this commit contains a secret"
Detect hardcoded secrets.................................................Failed

Note: to disable the gitleaks pre-commit hook you can prepend SKIP=gitleaks to the commit command and it will skip running gitleaks

➜ SKIP=gitleaks git commit -m "skip gitleaks check"
Detect hardcoded secrets................................................Skipped

Usage

Gitleaks scans code, past or present, for secrets

Usage:
  gitleaks [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  dir         scan directories or files for secrets
  git         scan git repositories for secrets
  help        Help about any command
  stdin       detect secrets from stdin
  version     display gitleaks version

Flags:
  -b, --baseline-path string          path to baseline with issues that can be ignored
  -c, --config string                 config file path
                                      order of precedence:
                                      1. --config/-c
                                      2. env var GITLEAKS_CONFIG
                                      3. env var GITLEAKS_CONFIG_TOML with the file content
                                      4. (target path)/.gitleaks.toml
                                      If none of the four options are used, then gitleaks will use the default config
      --diagnostics string            enable diagnostics (http OR comma-separated list: cpu,mem,trace). cpu=CPU prof, mem=memory prof, trace=exec tracing, http=serve via net/http/pprof
      --diagnostics-dir string        directory to store diagnostics output files when not using http mode (defaults to current directory)
      --enable-rule strings           only enable specific rules by id
      --exit-code int                 exit code when leaks have been encountered (default 1)
  -i, --gitleaks-ignore-path string   path to .gitleaksignore file or folder containing one (default ".")
  -h, --help                          help for gitleaks
      --ignore-gitleaks-allow         ignore gitleaks:allow comments
  -l, --log-level string              log level (trace, debug, info, warn, error, fatal) (default "info")
      --max-archive-depth int         allow scanning into nested archives up to this depth (default "0", no archive traversal is done)
      --max-decode-depth int          allow recursive decoding up to this depth (default "0", no decoding is done)
      --max-target-megabytes int      files larger than this will be skipped
      --no-banner                     suppress banner
      --no-color                      turn off color for verbose output
      --redact uint[=100]             redact secrets from logs and stdout. To redact only parts of the secret just apply a percent value from 0..100. For example --redact=20 (default 100%)
  -f, --report-format string          output format (json, csv, junit, sarif, template)
  -r, --report-path string            report file
      --report-template string        template file used to generate the report (implies --report-format=template)
      --timeout int                   set a timeout for gitleaks commands in seconds (default "0", no timeout is set)
  -v, --verbose                       show verbose output from scan
      --version                       version for gitleaks

Use "gitleaks [command] --help" for more information about a command.

Commands

⚠️ v8.19.0 introduced a change that deprecated detect and protect. Those commands are still available but are hidden in the --help menu. Take a look at this gist for easy command translations. If you find v8.19.0 broke an existing command (detect/protect), please open an issue.

There are three scanning modes: git, dir, and stdin.

Git

The git command lets you scan local git repos. Under the hood, gitleaks uses the git log -p command to scan patches. You can configure the behavior of git log -p with the log-opts option. For example, if you wanted to run gitleaks on a range of commits you could use the following command: gitleaks git -v --log-opts="--all commitA..commitB" path_to_repo. See the git log documentation for more information. If there is no target specified as a positional argument, then gitleaks will attempt to scan the current working directory as a git repo.

Dir

The dir (aliases include files, directory) command lets you scan directories and files. Example: gitleaks dir -v path_to_directory_or_file. If there is no target specified as a positional argument, then gitleaks will scan the current working directory.

Stdin

You can also stream data to gitleaks with the stdin command. Example: cat some_file | gitleaks -v stdin

Creating a baseline

When scanning large repositories or repositories with a long history, it can be convenient to use a baseline. When using a baseline, gitleaks will ignore any old findings that are present in the baseline. A baseline can be any gitleaks report. To create a gitleaks report, run gitleaks with the --report-path parameter.

gitleaks git --report-path gitleaks-report.json # This will save the report in a file called gitleaks-report.json

Once as baseline is created it can be applied when running the detect command again:

gitleaks git --baseline-path gitleaks-report.json --report-path findings.json

After running the detect command with the --baseline-path parameter, report output (findings.json) will only contain new issues.

Pre-Commit hook

You can run Gitleaks as a pre-commit hook by copying the example pre-commit.py script into your .git/hooks/ directory.

Load Configuration

The order of precedence is:

--config/-c option:

gitleaks git --config /home/dev/customgitleaks.toml .

Environment variable GITLEAKS_CONFIG with the file path:

export GITLEAKS_CONFIG="/home/dev/customgitleaks.toml"
gitleaks git .

Environment variable GITLEAKS_CONFIG_TOML with the file content:

export GITLEAKS_CONFIG_TOML=`cat customgitleaks.toml`
gitleaks git .

A .gitleaks.toml file within the target path:
```
gitleaks git .
```

If none of the four options are used, then gitleaks will use the default config.

Configuration

Gitleaks offers a configuration format you can follow to write your own secret detection rules:

# Title for the gitleaks configuration file.
title = "Custom Gitleaks configuration"

# You have basically two options for your custom configuration:
#
# 1. define your own configuration, default rules do not apply
#
#    use e.g., the default configuration as starting point:
#    https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml
#
# 2. extend a configuration, the rules are overwritten or extended
#
#    When you extend a configuration the extended rules take precedence over the
#    default rules. I.e., if there are duplicate rules in both the extended
#    configuration and the default configuration the extended rules or
#    attributes of them will override the default rules.
#    Another thing to know with extending configurations is you can chain
#    together multiple configuration files to a depth of 2. Allowlist arrays are
#    appended and can contain duplicates.

# useDefault and path can NOT be used at the same time. Choose one.
[extend]
# useDefault will extend the default gitleaks config built in to the binary
# the latest version is located at:
# https://github.com/gitleaks/gitleaks/blob/master/config/gitleaks.toml
useDefault = true
# or you can provide a path to a configuration to extend from.
# The path is relative to where gitleaks was invoked,
# not the location of the base config.
# path = "common_config.toml"
# If there are any rules you don't want to inherit, they can be specified here.
disabledRules = [ "generic-api-key"]

# An array of tables that contain information that define instructions
# on how to detect secrets
[[rules]]
# Unique identifier for this rule
id = "awesome-rule-1"

# Short human-readable description of the rule.
description = "awesome rule 1"

# Golang regular expression used to detect secrets. Note Golang's regex engine
# does not support lookaheads.
regex = '''one-go-style-regex-for-this-rule'''

# Int used to extract secret from regex match and used as the group that will have
# its entropy checked if `entropy` is set.
secretGroup = 3

# Float representing the minimum shannon entropy a regex group must have to be considered a secret.
entropy = 3.5

# Golang regular expression used to match paths. This can be used as a standalone rule or it can be used
# in conjunction with a valid `regex` entry.
path = '''a-file-path-regex'''

# Keywords are used for pre-regex check filtering. Rules that contain
# keywords will perform a quick string compare check to make sure the
# keyword(s) are in the content being scanned. Ideally these values should
# either be part of the identiifer or unique strings specific to the rule's regex
# (introduced in v8.6.0)
keywords = [
  "auth",
  "password",
  "token",
]

# Array of strings used for metadata and reporting purposes.
tags = ["tag","another tag"]

    # ⚠️ In v8.21.0 `[rules.allowlist]` was replaced with `[[rules.allowlists]]`.
    # This change was backwards-compatible: instances of `[rules.allowlist]` still  work.
    #
    # You can define multiple allowlists for a rule to reduce false positives.
    # A finding will be ignored if _ANY_ `[[rules.allowlists]]` matches.
    [[rules.allowlists]]
    description = "ignore commit A"
    # When multiple criteria are defined the default condition is "OR".
    # e.g., this can match on |commits| OR |paths| OR |stopwords|.
    condition = "OR"
    commits = [ "commit-A", "commit-B"]
    paths = [
      '''go\.mod''',
      '''go\.sum'''
    ]
    # note: stopwords targets the extracted secret, not the entire regex match
    # like 'regexes' does. (stopwords introduced in 8.8.0)
    stopwords = [
      '''client''',
      '''endpoint''',
    ]

    [[rules.allowlists]]
    # The "AND" condition can be used to make sure all criteria match.
    # e.g., this matches if |regexes| AND |paths| are satisfied.
    condition = "AND"
    # note: |regexes| defaults to check the _Secret_ in the finding.
    # Acceptable values for |regexTarget| are "secret" (default), "match", and "line".
    regexTarget = "match"
    regexes = [ '''(?i)parseur[il]''' ]
    paths = [ '''package-lock\.json''' ]

# You can extend a particular rule from the default config. e.g., gitlab-pat
# if you have defined a custom token prefix on your GitLab instance
[[rules]]
id = "gitlab-pat"
# all the other attributes from the default rule are inherited

    [[rules.allowlists]]
    regexTarget = "line"
    regexes = [ '''MY-glpat-''' ]


# ⚠️ In v8.25.0 `[allowlist]` was replaced with `[[allowlists]]`.
#
# Global allowlists have a higher order of precedence than rule-specific allowlists.
# If a commit listed in the `commits` field below is encountered then that commit will be skipped and no
# secrets will be detected for said commit. The same logic applies for regexes and paths.
[[allowlists]]
description = "global allow list"
commits = [ "commit-A", "commit-B", "commit-C"]
paths = [
  '''gitleaks\.toml''',
  '''(.*?)(jpg|gif|doc)'''
]
# note: (global) regexTarget defaults to check the _Secret_ in the finding.
# Acceptable values for regexTarget are "match" and "line"
regexTarget = "match"
regexes = [
  '''219-09-9999''',
  '''078-05-1120''',
  '''(9[0-9]{2}|666)-\d{2}-\d{4}''',
]
# note: stopwords targets the extracted secret, not the entire regex match
# like 'regexes' does. (stopwords introduced in 8.8.0)
stopwords = [
  '''client''',
  '''endpoint''',
]

# ⚠️ In v8.25.0, `[[allowlists]]` have a new field called |targetRules|.
#
# Common allowlists can be defined once and assigned to multiple rules using |targetRules|.
# This will only run on the specified rules, not globally.
[[allowlists]]
targetRules = ["awesome-rule-1", "awesome-rule-2"]
description = "Our test assets trigger false-positives in a couple rules."
paths = ['''tests/expected/._\.json$''']

Refer to the default gitleaks config for examples or follow the contributing guidelines if you would like to contribute to the default configuration. Additionally, you can check out this gitleaks blog post which covers advanced configuration setups.

Additional Configuration

Composite Rules (Multi-part or `required` Rules)

In v8.28.0 Gitleaks introduced composite rules, which are made up of a single "primary" rule and one or more auxiliary or required rules. To create a composite rule, add a [[rules.required]] table to the primary rule specifying an id and optionally withinLines and/or withinColumns proximity constraints. A fragment is a chunk of content that Gitleaks processes at once (typically a file, part of a file, or git diff), and proximity matching instructs the primary rule to only report a finding if the auxiliary required rules also find matches within the specified area of the fragment.

Proximity matching: Using the withinLines and withinColumns fields instructs the primary rule to only report a finding if the auxiliary required rules also find matches within the specified proximity. You can set:

withinLines: N - required findings must be within N lines (vertically)
withinColumns: N - required findings must be within N characters (horizontally)
Both - creates a rectangular search area (both constraints must be satisfied)
Neither - fragment-level matching (required findings can be anywhere in the same fragment)

Here are diagrams illustrating each proximity behavior:

p = primary captured secret
a = auxiliary (required) captured secret
fragment = section of data gitleaks is looking at


    *Fragment-level proximity*
    Any required finding in the fragment
          ┌────────┐
   ┌──────┤fragment├─────┐
   │      └──────┬─┤     │ ┌───────┐
   │             │a│◀────┼─│✓ MATCH│
   │          ┌─┐└─┘     │ └───────┘
   │┌─┐       │p│        │
   ││a│    ┌─┐└─┘        │ ┌───────┐
   │└─┘    │a│◀──────────┼─│✓ MATCH│
   └─▲─────┴─┴───────────┘ └───────┘
     │    ┌───────┐
     └────│✓ MATCH│
          └───────┘


   *Column bounded proximity*
   `withinColumns = 3`
          ┌────────┐
   ┌────┬─┤fragment├─┬───┐
   │      └──────┬─┤     │ ┌───────────┐
   │    │        │a│◀┼───┼─│+1C ✓ MATCH│
   │          ┌─┐└─┘     │ └───────────┘
   │┌─┐ │     │p│    │   │
┌──▶│a│  ┌─┐  └─┘        │ ┌───────────┐
│  │└─┘ ││a│◀────────┼───┼─│-2C ✓ MATCH│
│  │       ┘             │ └───────────┘
│  └── -3C ───0C─── +3C ─┘
│  ┌─────────┐
│  │ -4C ✗ NO│
└──│  MATCH  │
   └─────────┘


   *Line bounded proximity*
   `withinLines = 4`
         ┌────────┐
   ┌─────┤fragment├─────┐
  +4L─ ─ ┴────────┘─ ─ ─│
   │                    │
   │              ┌─┐   │ ┌────────────┐
   │         ┌─┐  │a│◀──┼─│+1L ✓ MATCH │
   0L  ┌─┐   │p│  └─┘   │ ├────────────┤
   │   │a│◀──┴─┴────────┼─│-1L ✓ MATCH │
   │   └─┘              │ └────────────┘
   │                    │ ┌─────────┐
  -4L─ ─ ─ ─ ─ ─ ─ ─┌─┐─│ │-5L ✗ NO │
   │                │a│◀┼─│  MATCH  │
   └────────────────┴─┴─┘ └─────────┘


   *Line and column bounded proximity*
   `withinLines = 4`
   `withinColumns = 3`
         ┌────────┐
   ┌─────┤fragment├─────┐
  +4L   ┌└────────┴ ┐   │
   │            ┌─┐     │ ┌───────────────┐
   │    │       │a│◀┼───┼─│+2L/+1C ✓ MATCH│
   │         ┌─┐└─┘     │ └───────────────┘
   0L   │    │p│    │   │
   │         └─┘        │
   │    │           │   │ ┌────────────┐
  -4L    ─ ─ ─ ─ ─ ─┌─┐ │ │-5L/+3C ✗ NO│
   │                │a│◀┼─│   MATCH    │
   └───-3C────0L───+3C┴─┘ └────────────┘

Some final quick thoughts on composite rules.

This is an experimental feature! It's subject to change so don't go sellin' a new B2B SaaS feature built ontop of this feature. Scan type (git vs dir) based context is interesting. I'm monitoring the situation. Composite rules might not be super useful for git scans because gitleaks only looks at additions in the git history. It could be useful to scan non-additions in git history for `required` rules. Oh, right this is a readme, I'll shut up now.

gitleaks:allow

If you are knowingly committing a test secret that gitleaks will catch you can add a gitleaks:allow comment to that line which will instruct gitleaks to ignore that secret. Ex:

class CustomClass:
    discord_client_secret = '8dyfuiRyq=vVc3RRr_edRk-fK__JItpZ'  #gitleaks:allow

.gitleaksignore

You can ignore specific findings by creating a .gitleaksignore file at the root of your repo. In release v8.10.0 Gitleaks added a Fingerprint value to the Gitleaks report. Each leak, or finding, has a Fingerprint that uniquely identifies a secret. Add this fingerprint to the .gitleaksignore file to ignore that specific secret. See Gitleaks' .gitleaksignore for an example. Note: this feature is experimental and is subject to change in the future.

Decoding

Sometimes secrets are encoded in a way that can make them difficult to find with just regex. Now you can tell gitleaks to automatically find and decode encoded text. The flag --max-decode-depth enables this feature (the default value "0" means the feature is disabled by default).

Recursive decoding is supported since decoded text can also contain encoded text. The flag --max-decode-depth sets the recursion limit. Recursion stops when there are no new segments of encoded text to decode, so setting a really high max depth doesn't mean it will make that many passes. It will only make as many as it needs to decode the text. Overall, decoding only minimally increases scan times.

The findings for encoded text differ from normal findings in the following ways:

The location points the bounds of the encoded text
- If the rule matches outside the encoded text, the bounds are adjusted to include that as well
The match and secret contain the decoded value
Two tags are added decoded:<encoding> and decode-depth:<depth>

Currently supported encodings:

percent - Any printable ASCII percent encoded values
hex - Any printable ASCII hex encoded values >= 32 characters
base64 - Any printable ASCII base64 encoded values >= 16 characters

Archive Scanning

Sometimes secrets are packaged within archive files like zip files or tarballs, making them difficult to discover. Now you can tell gitleaks to automatically extract and scan the contents of archives. The flag --max-archive-depth enables this feature for both dir and git scan types. The default value of "0" means this feature is disabled by default.

Recursive scanning is supported since archives can also contain other archives. The --max-archive-depth flag sets the recursion limit. Recursion stops when there are no new archives to extract, so setting a very high max depth just sets the potential to go that deep. It will only go as deep as it needs to.

The findings for secrets located within an archive will include the path to the file inside the archive. Inner paths are separated with !.

Example finding (shortened for brevity):

Finding:     DB_PASSWORD=8ae31cacf141669ddfb5da
...
File:        testdata/archives/nested.tar.gz!archives/files.tar!files/.env.prod
Line:        4
Commit:      6e6ee6596d337bb656496425fb98644eb62b4a82
...
Fingerprint: 6e6ee6596d337bb656496425fb98644eb62b4a82:testdata/archives/nested.tar.gz!archives/files.tar!files/.env.prod:generic-api-key:4
Link:        https://github.com/leaktk/gitleaks/blob/6e6ee6596d337bb656496425fb98644eb62b4a82/testdata/archives/nested.tar.gz

This means a secret was detected on line 4 of files/.env.prod. which is in archives/files.tar which is in testdata/archives/nested.tar.gz.

Currently supported formats:

The compression and archive formats supported by mholt's archives package are supported.

Reporting

Gitleaks has built-in support for several report formats: json, csv, junit, and sarif.

If none of these formats fit your need, you can create your own report format with a Go text/template .tmpl file and the --report-template flag. The template can use extended functionality from the Masterminds/sprig template library.

For example, the following template provides a custom JSON output:

# jsonextra.tmpl
[{{ $lastFinding := (sub (len . ) 1) }}
{{- range $i, $finding := . }}{{with $finding}}
    {
        "Description": {{ quote .Description }},
        "StartLine": {{ .StartLine }},
        "EndLine": {{ .EndLine }},
        "StartColumn": {{ .StartColumn }},
        "EndColumn": {{ .EndColumn }},
        "Line": {{ quote .Line }},
        "Match": {{ quote .Match }},
        "Secret": {{ quote .Secret }},
        "File": "{{ .File }}",
        "SymlinkFile": {{ quote .SymlinkFile }},
        "Commit": {{ quote .Commit }},
        "Entropy": {{ .Entropy }},
        "Author": {{ quote .Author }},
        "Email": {{ quote .Email }},
        "Date": {{ quote .Date }},
        "Message": {{ quote .Message }},
        "Tags": [{{ $lastTag := (sub (len .Tags ) 1) }}{{ range $j, $tag := .Tags }}{{ quote . }}{{ if ne $j $lastTag }},{{ end }}{{ end }}],
        "RuleID": {{ quote .RuleID }},
        "Fingerprint": {{ quote .Fingerprint }}
    }{{ if ne $i $lastFinding }},{{ end }}
{{- end}}{{ end }}
]

Usage:

$ gitleaks dir ~/leaky-repo/ --report-path "report.json" --report-format template --report-template testdata/report/jsonextra.tmpl

Sponsorships

coderabbit.ai

Exit Codes

You can always set the exit code when leaks are encountered with the --exit-code flag. Default exit codes below:

0 - no leaks present
1 - leaks or error encountered
126 - unknown flag

Join the Discord!

influxdata/telegraf

Agent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.

Telegraf

Telegraf is an agent for collecting, processing, aggregating, and writing metrics, logs, and other arbitrary data.

Offers a comprehensive suite of over 300 plugins, covering a wide range of functionalities including system monitoring, cloud services, and message passing
Enables the integration of user-defined code to collect, transform, and transmit data efficiently
Compiles into a standalone static binary without any external dependencies, ensuring a streamlined deployment process
Utilizes TOML for configuration, providing a user-friendly and unambiguous setup experience
Developed with contributions from a diverse community of over 1,200 contributors

Users can choose plugins from a wide range of topics, including but not limited to:

Devices: OPC UA, Modbus
Logs: File, Tail, Directory Monitor
Messaging: AMQP, Kafka, MQTT
Monitoring: OpenTelemetry, Prometheus
Networking: Cisco TelemetryMDT, gNMI
System monitoring: CPU, Memory, Disk, Network, SMART, Docker, Nvidia SMI, etc.
Universal: Exec, HTTP, HTTP Listener, SNMP, SQL
Windows: Event Log, Management Instrumentation, Performance Counters

🔨 Installation

For binary builds, Docker images, RPM & DEB packages, and other builds of Telegraf, please see the install guide.

See the releases documentation for details on versioning and when releases are made.

💻 Usage

Users define a TOML configuration with the plugins and settings they wish to use, then pass that configuration to Telegraf. The Telegraf agent then collects data from inputs at each interval and sends data to outputs at each flush interval.

For a basic walkthrough see quick start.

📖 Documentation

For a full list of documentation including tutorials, reference and other material, start with the /docs directory.

Additionally, each plugin has its own README that includes details about how to configure, use, and sometimes debug or troubleshoot. Look under the /plugins directory for specific plugins.

Here are some commonly used documents:

❤️ Contribute

We love our community of over 1,200 contributors! Many of the plugins included in Telegraf were originally contributed by community members. Check out our contributing guide if you are interested in helping out. Also, join us on our Community Slack or Community Forums if you have questions or comments for our engineering teams.

If you are completely new to Telegraf and InfluxDB, you can also enroll for free at InfluxDB university to take courses to learn more.

ℹ️ Support

Please use the Community Slack or Community Forums if you have questions or comments for our engineering teams. GitHub issues are limited to actual issues and feature requests only.

📜 License

hatchet-dev/hatchet

🪓 An orchestration engine for background tasks, AI agents, and durable workflows

An orchestration engine for background tasks, AI agents, and durable workflows

Hatchet Cloud · Documentation · Website · Issues

What is Hatchet?

Hatchet is a platform for orchestrating background tasks, AI agents, and durable workflows at scale. It supports applications written in Python, TypeScript, Go and Ruby, and can be used as a service through Hatchet Cloud or self-hosting. Hatchet provides a full platform for queuing, automatic retries, durability, real-time monitoring, alerting, and logging.

Get started quickly

The fastest way to get started with Hatchet is signing up for Hatchet Cloud to try it out! We recommend this even if you plan on self-hosting, so you can have a look at what a fully-deployed Hatchet platform looks like.

To run Hatchet locally, the fastest path for setup is to install the Hatchet CLI (on MacOS, Linux or WSL) - note that this requires Docker installed locally to work:

curl -fsSL https://install.hatchet.run/install.sh | bash
hatchet --version
hatchet server start

To view full documentation for self-hosting and using cloud, have a look at the docs.

When should I use Hatchet?

You can use Hatchet for running background tasks, AI agents, or other types of long-running workflows. It is designed to be a feature-complete solution for systems where correctness, reliability, horizontal scalability, and observability are essential. From a technical perspective, it differs from other solutions in that it uses Postgres as a durability layer for both the task runtime and the observability system, making it particularly easy to self-host.

For some end-to-end examples of workflows you can build with Hatchet, check out our cookbooks.

Hatchet Features

Background Tasks

Background tasks: Hatchet supports one-off background tasks defined as simple functions. It supports both fire-and-forget and fire-and-wait tasks with subscriptions
Retries: flexible and configurable retry policies for tasks, with optional exponential backoff
Cron jobs and scheduled runs for scheduling tasks at some point in the future
Task routing based on strict conditions, like worker labels, or more complex, weighted scheduling rules using worker affinity
Event-based triggering and listeners to build event-driven, highly distributed systems
Webhook-based triggering for easily triggering Hatchet tasks from upstream data sources

Task orchestration and workflows

Durable tasks for building fault-tolerant, long-running workflows which can easily recover from failure
DAGs (directed acyclic graphs) for building data pipelines and simple workflows. See our guide on choosing between durable tasks and DAGs
Complex pause/resume conditions using durable sleep, event waits, or a combination of both

Scale

Priority so that critical tasks can run before tasks which aren't latency sensitive, like backfill jobs
Rate limiting to deal with third-party APIs, or even to enforce per-user rate limits using dynamic rate limits
Fair scheduling using Hatchet's concurrency policies, which can set a concurrency limit for tasks based on dynamic keys
Worker slots for ensuring that workers cannot take on more work than they can handle

Monitoring, observability, and management

Real-time web UI with alerting, monitoring, and logging
OpenTelemetry (using Hatchet's built-in collector or external destinations)
Prometheus metrics
Multi-tenant by default, so a single Hatchet instance can support multiple teams
Users and roles

Hatchet Cloud features

Autoscaling and pay-as-you-go plans
Multi-region deployments
SSO
Improved performance for monitoring, logging, and observability

Documentation

The most up-to-date documentation can be found at https://docs.hatchet.run.

Community & Support

Discord - best for getting in touch with the maintainers and hanging with the community
Github Issues - used for filing bug reports
Github Discussions - used for starting in-depth technical discussions that are suited for asynchronous communication
Email - best for getting Hatchet Cloud support and for help with billing, data deletion, etc.

Hatchet vs...

Hatchet vs Durable Execution Platforms (Temporal, DBOS)

Hatchet's durable tasks feature is a drop-in replacement for Temporal or DBOS workflows. You also get:

End-to-end observability of durable tasks using OpenTelemetry, monitoring and logging
Features built for running workflows at scale, such as rate limiting, complex routing, and worker-level slot control
Multi-tenancy, users and roles supported out of the box

In addition to making durable execution easier to use, Hatchet can also be used as a general-purpose queue, a DAG-based orchestrator, a durable execution engine, or all three, allowing teams to centralize their async and background processing in a single platform.

Hatchet vs Task Queues (Celery, BullMQ)

Traditional task queues like BullMQ and Celery trade off durability for throughput. Tasks persist on the broker (typically Redis or RabbitMQ) while the task is executing, but are not persisted afterwards. This makes it difficult to build complex workflows, as there is no persistent intermediate state. It also makes it difficult to recover and replay tasks which failed and were removed from the queue, resulting in custom admin tooling to work with these libraries at scale.

On the other hand, Hatchet is a durable task queue, meaning it persists the history of all executions (up to a defined retention period), which allows for easy monitoring, debugging and durable task features. Hatchet's durability features add some overhead: while Hatchet has been load-tested up to 10k tasks/second, it consumes more resources than a system built on Redis or RabbitMQ, which can reach much higher throughput.

Hatchet vs DAG-based platforms (Airflow, Prefect, Dagster)

These tools are usually built with data engineers in mind, and aren’t designed to run as part of a high-volume application. They’re usually higher latency and higher cost, with their primary selling point being integrations with common datastores and connectors.

When to use Hatchet: when you'd like to use a DAG-based framework, write your own integrations and functions, and require higher throughput (>100/s)

When to use other DAG-based platforms: when you'd like to use other data stores and connectors that work out of the box

Issues

Please submit any bugs that you encounter via GitHub issues.

I'd Like to Contribute

Please let us know what you're interested in working on in the #contributing channel on Discord. This will help us shape the direction of the project and will make collaboration much easier!

syncthing/syncthing

Open Source Continuous File Synchronization

Goals

Syncthing is a continuous file synchronization program. It synchronizes files between two or more computers. We strive to fulfill the goals below. The goals are listed in order of importance, the most important ones first. This is the summary version of the goal list - for more commentary, see the full Goals document.

Syncthing should be:

Safe From Data Loss

Protecting the user's data is paramount. We take every reasonable precaution to avoid corrupting the user's files.
Secure Against Attackers

Again, protecting the user's data is paramount. Regardless of our other goals, we must never allow the user's data to be susceptible to eavesdropping or modification by unauthorized parties.
Easy to Use

Syncthing should be approachable, understandable, and inclusive.
Automatic

User interaction should be required only when absolutely necessary.
Universally Available

Syncthing should run on every common computer. We are mindful that the latest technology is not always available to every individual.
For Individuals

Syncthing is primarily about empowering the individual user with safe, secure, and easy to use file synchronization.
Everything Else

There are many things we care about that don't make it on to the list. It is fine to optimize for these values, as long as they are not in conflict with the stated goals above.

Getting Started

Take a look at the getting started guide.

There are a few examples for keeping Syncthing running in the background on your system in the etc directory. There are also several GUI implementations for Windows, Mac, and Linux.

Docker

To run Syncthing in Docker, see the Docker README.

Getting in Touch

The first and best point of contact is the Forum. If you've found something that is clearly a bug, feel free to report it in the GitHub issue tracker.

If you believe that you’ve found a Syncthing-related security vulnerability, please report it by emailing security@syncthing.net. Do not report it in the Forum or issue tracker.

Building

Building Syncthing from source is easy. After extracting the source bundle from a release or checking out git, you just need to run go run build.go and the binaries are created in ./bin. There's a guide with more details on the build process.

Signed Releases

Release binaries are GPG signed with the key available from https://syncthing.net/security/. There is also a built-in automatic upgrade mechanism (disabled in some distribution channels) which uses a compiled in ECDSA signature. macOS and Windows binaries are also code-signed.

Documentation

Please see the Syncthing documentation site [source].

All code is licensed under the MPLv2 License.

knadh/listmonk

High performance, self-hosted, newsletter and mailing list manager with a modern dashboard. Single binary app.

listmonk is a standalone, self-hosted, newsletter and mailing list manager. It is fast, feature-rich, and packed into a single binary. It uses a PostgreSQL database as its data store.

Visit listmonk.app for more info. Check out the live demo.

Installation

Docker

The latest image is available on DockerHub at listmonk/listmonk:latest. Download and use the sample docker-compose.yml.

# Download the compose file to the current directory.
curl -LO https://github.com/knadh/listmonk/raw/master/docker-compose.yml

# Run the services in the background.
docker compose up -d

Visit http://localhost:9000

See installation docs

Binary

Download the latest release and extract the listmonk binary.
./listmonk --new-config to generate config.toml. Edit it.
./listmonk --install to setup the Postgres DB (or --upgrade to upgrade an existing DB. Upgrades are idempotent and running them multiple times have no side effects).
Run ./listmonk and visit http://localhost:9000

See installation docs

Developers

listmonk is free and open source software licensed under AGPLv3. If you are interested in contributing, refer to the developer setup. The backend is written in Go and the frontend is Vue with Buefy for UI.

License

listmonk is licensed under the AGPL v3 license.

go-gitea/gitea

Git with a cup of tea! Painless self-hosted all-in-one software development service, including Git hosting, code review, team collaboration, package registry and CI/CD

Gitea

繁體中文 | 简体中文

Purpose

The goal of this project is to make the easiest, fastest, and most painless way of setting up a self-hosted Git service.

As Gitea is written in Go, it works across all the platforms and architectures that are supported by Go, including Linux, macOS, and Windows on x86, amd64, ARM and PowerPC architectures. This project has been forked from Gogs since November of 2016, but a lot has changed.

For online demonstrations, you can visit demo.gitea.com.

For accessing free Gitea service (with a limited number of repositories), you can visit gitea.com.

To quickly deploy your own dedicated Gitea instance on Gitea Cloud, you can start a free trial at cloud.gitea.com.

Documentation

You can find comprehensive documentation on our official documentation website.

It includes installation, administration, usage, development, contributing guides, and more to help you get started and explore all features effectively.

If you have any suggestions or would like to contribute to it, you can visit the documentation repository

Building

From the root of the source tree, run:

TAGS="bindata" make build

The build target is split into two sub-targets:

make backend which requires Go Stable, the required version is defined in go.mod.
make frontend which requires Node.js LTS or greater and pnpm.

Internet connectivity is required to download the go and npm modules. When building from the official source tarballs which include pre-built frontend files, the frontend target will not be triggered, making it possible to build without Node.js.

More info: https://docs.gitea.com/installation/install-from-source

Using

After building, a binary file named gitea will be generated in the root of the source tree by default. To run it, use:

./gitea web

Note

If you're interested in using our APIs, we have experimental support with documentation.

Contributing

Expected workflow is: Fork -> Patch -> Push -> Pull Request

Note

YOU MUST READ THE CONTRIBUTORS GUIDE BEFORE STARTING TO WORK ON A PULL REQUEST.
If you have found a vulnerability in the project, please write privately to security@gitea.io. Thanks!

Translating

Translations are done through Crowdin. If you want to translate to a new language, ask one of the managers in the Crowdin project to add a new language there.

You can also just create an issue for adding a language or ask on Discord on the #translation channel. If you need context or find some translation issues, you can leave a comment on the string or ask on Discord. For general translation questions there is a section in the docs. Currently a bit empty, but we hope to fill it as questions pop up.

Get more information from documentation.

Official and Third-Party Projects

We provide an official go-sdk, a CLI tool called tea and an action runner for Gitea Action.

We maintain a list of Gitea-related projects at gitea/awesome-gitea, where you can discover more third-party projects, including SDKs, plugins, themes, and more.

Communication

If you have questions that are not covered by the documentation, you can get in contact with us on our Discord server or create a post in the discourse forum.

Authors

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

FAQ

How do you pronounce Gitea?

Gitea is pronounced /ɡɪ’ti:/ as in "gi-tea" with a hard g.

Why is this not hosted on a Gitea instance?

We're working on it.

Where can I find the security patches?

In the release log or the change log, search for the keyword SECURITY to find the security patches.

License

This project is licensed under the MIT License. See the LICENSE file for the full license text.

Further information

Looking for an overview of the interface? Check it out!

Login/Register Page

User Dashboard

User Profile

Explore

Repository

Repository Issue

Repository Pull Requests

Repository Actions

Repository Activity

Organization

maximhq/bifrost

Fastest enterprise AI gateway (50x faster than LiteLLM) with adaptive load balancer, cluster mode, guardrails, 1000+ models support & <100 µs overhead at 5k RPS.

Bifrost AI Gateway

The fastest way to build AI applications that never go down

Bifrost is a high-performance AI gateway that unifies access to 23+ providers (OpenAI, Anthropic, AWS Bedrock, Google Vertex, and more) through a single OpenAI-compatible API. Deploy in seconds with zero configuration and get automatic failover, load balancing, semantic caching, and enterprise-grade features.

Quick Start

Go from zero to production-ready AI gateway in under a minute.

Step 1: Start Bifrost Gateway

# Install and run locally
npx -y @maximhq/bifrost

# Or use Docker
docker run -p 8080:8080 maximhq/bifrost

Step 2: Configure via Web UI

# Open the built-in web interface
open http://localhost:8080

Step 3: Make your first API call

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello, Bifrost!"}]
  }'

That's it! Your AI gateway is running with a web interface for visual configuration, real-time monitoring, and analytics.

Complete Setup Guides:

Gateway Setup - HTTP API deployment
Go SDK Setup - Direct integration

Enterprise Deployments

Bifrost supports enterprise-grade, private deployments for teams running production AI systems at scale. In addition to private networking, custom security controls, and governance, enterprise deployments unlock advanced capabilities including adaptive load balancing, clustering, guardrails, MCP gateway and and other features designed for enterprise-grade scale and reliability.

Explore enterprise capabilities

Key Features

Core Infrastructure

Unified Interface - Single OpenAI-compatible API for all providers
Multi-Provider Support - OpenAI, Anthropic, AWS Bedrock, Google Vertex, Azure, Cerebras, Cohere, Mistral, Ollama, Groq, and more
Automatic Fallbacks - Seamless failover between providers and models with zero downtime
Load Balancing - Intelligent request distribution across multiple API keys and providers

Advanced Features

Model Context Protocol (MCP) - Enable AI models to use external tools (filesystem, web search, databases)
Semantic Caching - Intelligent response caching based on semantic similarity to reduce costs and latency
Multimodal Support - Support for text,images, audio, and streaming, all behind a common interface.
Custom Plugins - Extensible middleware architecture for analytics, monitoring, and custom logic
Governance - Usage tracking, rate limiting, and fine-grained access control

Enterprise & Security

Budget Management - Hierarchical cost control with virtual keys, teams, and customer budgets
SSO Integration - Google and GitHub authentication support
Observability - Native Prometheus metrics, distributed tracing, and comprehensive logging
Vault Support - Secure API key management with HashiCorp Vault integration

Developer Experience

Zero-Config Startup - Start immediately with dynamic provider configuration
Drop-in Replacement - Replace OpenAI/Anthropic/GenAI APIs with one line of code
SDK Integrations - Native support for popular AI SDKs with zero code changes
Configuration Flexibility - Web UI, API-driven, or file-based configuration options

Repository Structure

Bifrost uses a modular architecture for maximum flexibility:

bifrost/
├── npx/                 # NPX script for easy installation
├── core/                # Core functionality and shared components
│   ├── providers/       # Provider-specific implementations (OpenAI, Anthropic, etc.)
│   ├── schemas/         # Interfaces and structs used throughout Bifrost
│   └── bifrost.go       # Main Bifrost implementation
├── framework/           # Framework components for data persistence
│   ├── configstore/     # Configuration storages
│   ├── logstore/        # Request logging storages
│   └── vectorstore/     # Vector storages
├── transports/          # HTTP gateway and other interface layers
│   └── bifrost-http/    # HTTP transport implementation
├── ui/                  # Web interface for HTTP gateway
├── plugins/             # Extensible plugin system
│   ├── governance/      # Budget management and access control
│   ├── jsonparser/      # JSON parsing and manipulation utilities
│   ├── logging/         # Request logging and analytics
│   ├── maxim/           # Maxim's observability integration
│   ├── mocker/          # Mock responses for testing and development
│   ├── semanticcache/   # Intelligent response caching
│   └── telemetry/       # Monitoring and observability
├── docs/                # Documentation and guides
└── tests/               # Comprehensive test suites

Getting Started Options

Choose the deployment method that fits your needs:

1. Gateway (HTTP API)

Best for: Language-agnostic integration, microservices, and production deployments

# NPX - Get started in 30 seconds
npx -y @maximhq/bifrost

# Docker - Production ready
docker run -p 8080:8080 -v $(pwd)/data:/app/data maximhq/bifrost

Features: Web UI, real-time monitoring, multi-provider management, zero-config startup

Learn More: Gateway Setup Guide

2. Go SDK

Best for: Direct Go integration with maximum performance and control

go get github.com/maximhq/bifrost/core

Features: Native Go APIs, embedded deployment, custom middleware integration

Learn More: Go SDK Guide

3. Drop-in Replacement

Best for: Migrating existing applications with zero code changes

# OpenAI SDK
- base_url = "https://api.openai.com"
+ base_url = "http://localhost:8080/openai"

# Anthropic SDK  
- base_url = "https://api.anthropic.com"
+ base_url = "http://localhost:8080/anthropic"

# Google GenAI SDK
- api_endpoint = "https://generativelanguage.googleapis.com"
+ api_endpoint = "http://localhost:8080/genai"

Learn More: Integration Guides

Performance

Bifrost adds virtually zero overhead to your AI requests. In sustained 5,000 RPS benchmarks, the gateway added only 11 µs of overhead per request.

Metric	t3.medium	t3.xlarge	Improvement
Added latency (Bifrost overhead)	59 µs	11 µs	-81%
Success rate @ 5k RPS	100%	100%	No failed requests
Avg. queue wait time	47 µs	1.67 µs	-96%
Avg. request latency (incl. provider)	2.12 s	1.61 s	-24%

Key Performance Highlights:

Perfect Success Rate - 100% request success rate even at 5k RPS
Minimal Overhead - Less than 15 µs additional latency per request
Efficient Queuing - Sub-microsecond average wait times
Fast Key Selection - ~10 ns to pick weighted API keys

Complete Benchmarks: Performance Analysis

Documentation

Complete Documentation: https://docs.getbifrost.ai

Quick Start

Gateway Setup - HTTP API deployment in 30 seconds
Go SDK Setup - Direct Go integration
Provider Configuration - Multi-provider setup

Features

Multi-Provider Support - Single API for all providers
MCP Integration - External tool calling
Semantic Caching - Intelligent response caching
Fallbacks & Load Balancing - Reliability features
Budget Management - Cost control and governance

Integrations

OpenAI SDK - Drop-in OpenAI replacement
Anthropic SDK - Drop-in Anthropic replacement
AWS Bedrock SDK - AWS Bedrock integration
Google GenAI SDK - Drop-in GenAI replacement
LiteLLM SDK - LiteLLM integration
Langchain SDK - Langchain integration

Enterprise

Custom Plugins - Extend functionality
Clustering - Multi-node deployment
Vault Support - Secure key management
Production Deployment - Scaling and monitoring

Need Help?

Join our Discord for community support and discussions.

Get help with:

Quick setup assistance and troubleshooting
Best practices and configuration tips
Community discussions and support
Real-time help with integrations

Contributing

We welcome contributions of all kinds! See our Contributing Guide for:

Setting up the development environment
Code conventions and best practices
How to submit pull requests
Building and testing locally

For development requirements and build instructions, see our Development Setup Guide.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Built with ❤️ by Maxim

looplj/axonhub

⚡️ Open-source AI Gateway — Use any SDK to call 100+ LLMs. Built-in failover, load balancing, cost control & end-to-end tracing.

AxonHub - All-in-one AI Development Platform

Use any SDK. Access any model. Zero code changes.

English | 中文 | 日本語

NOTE

This project is maintained by an individual. The author makes no warranties and assumes no liability for risks arising from its use. Please evaluate carefully.

The core scope of this project does not include 2api (subscription-to-API conversion). If you need that, consider other open-source projects focused on 2api.

📖 Project Introduction

All-in-one AI Development Platform

AxonHub is the AI gateway that lets you switch between model providers without changing a single line of code.

Whether you're using OpenAI SDK, Anthropic SDK, or any AI SDK, AxonHub transparently translates your requests to work with any supported model provider. No refactoring, no SDK swaps—just change a configuration and you're done.

What it solves:

🔒 Vendor lock-in - Switch from GPT-4 to Claude or Gemini instantly
🔧 Integration complexity - One API format for 10+ providers
📊 Observability gap - Complete request tracing out of the box
💸 Cost control - Real-time usage tracking and budget management

Core Features

Feature	What You Get
🔄 Any SDK → Any Model	Use OpenAI SDK to call Claude, or Anthropic SDK to call GPT. Zero code changes.
🔍 Full Request Tracing	Complete request timelines with thread-aware observability. Debug faster.
🔐 Enterprise RBAC	Fine-grained access control, usage quotas, and data isolation.
⚡ Smart Load Balancing	Auto failover in <100ms. Always route to the healthiest channel.
💰 Real-time Cost Tracking	Per-request cost breakdown. Input, output, cache tokens—all tracked.

📚 Documentation

For detailed technical documentation, API references, architecture design, and more:

📑 Documentation Index - Complete documentation navigation

🎯 Demo

Try AxonHub live at our demo instance!

Note：The demo instance currently configures Zhipu and OpenRouter free models.

Demo Account

Email: demo@example.com
Password: 12345678

⭐ Features

📸 Screenshots

Here are some screenshots of AxonHub in action:

System Dashboard	Channel Management	Model Price
Models	Trace Viewer	Request Monitoring

🚀 API Types

API Type	Status	Description	Document
Text Generation	✅ Done	Conversational interface	OpenAI API, Anthropic API, Gemini API
Image Generation	✅ Done	Image generation	Image Generation
Rerank	✅ Done	Results ranking	Rerank API
Embedding	✅ Done	Vector embedding generation	Embedding API
Realtime	📝 Todo	Live conversation capabilities	-

🤖 Supported Providers

Provider	Status	Supported Models	Compatible APIs
OpenAI	✅ Done	GPT-4, GPT-4o, GPT-5, etc.	OpenAI, Anthropic, Gemini, Embedding, Image Generation
Anthropic	✅ Done	Claude 3.5, Claude 3.0, etc.	OpenAI, Anthropic, Gemini
Zhipu AI	✅ Done	GLM-4.5, GLM-4.5-air, etc.	OpenAI, Anthropic, Gemini
Moonshot AI (Kimi)	✅ Done	kimi-k2, etc.	OpenAI, Anthropic, Gemini
DeepSeek	✅ Done	DeepSeek-V3.1, etc.	OpenAI, Anthropic, Gemini
ByteDance Doubao	✅ Done	doubao-1.6, etc.	OpenAI, Anthropic, Gemini, Image Generation
Gemini	✅ Done	Gemini 2.5, etc.	OpenAI, Anthropic, Gemini, Image Generation
Fireworks	✅ Done	MiniMax-M2.5, GLM-5, Kimi K2.5, etc.	OpenAI
Jina AI	✅ Done	Embeddings, Reranker, etc.	Jina Embedding, Jina Rerank
OpenRouter	✅ Done	Various models	OpenAI, Anthropic, Gemini, Image Generation
ZAI	✅ Done	-	Image Generation
AWS Bedrock	🔄 Testing	Claude on AWS	OpenAI, Anthropic, Gemini
Google Cloud	🔄 Testing	Claude on GCP	OpenAI, Anthropic, Gemini
NanoGPT	✅ Done	Various models, Image Gen	OpenAI, Anthropic, Gemini, Image Generation

🚀 Quick Start

30-Second Local Start

# Download and extract (macOS ARM64 example)
curl -sSL https://github.com/looplj/axonhub/releases/latest/download/axonhub_darwin_arm64.tar.gz | tar xz
cd axonhub_*

# Run with SQLite (default)
./axonhub

# Open http://localhost:8090
# First run: Follow the setup wizard to initialize the system (create admin account, password must be at least 6 characters)

That's it! Now configure your first AI channel and start calling models through AxonHub.

Zero-Code Migration Example

Your existing code works without any changes. Just point your SDK to AxonHub:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8090/v1",  # Point to AxonHub
    api_key="your-axonhub-api-key"        # Use AxonHub API key
)

# Call Claude using OpenAI SDK!
response = client.chat.completions.create(
    model="claude-3-5-sonnet",  # Or gpt-4, gemini-pro, deepseek-chat...
    messages=[{"role": "user", "content": "Hello!"}]
)

Switch models by changing one line: model="gpt-4" → model="claude-3-5-sonnet". No SDK changes needed.

1-click Deploy to Render

Deploy AxonHub with 1-click on Render for free.

🚀 Deployment Guide

💻 Personal Computer Deployment

Perfect for individual developers and small teams. No complex configuration required.

Quick Download & Run

Download the latest release from GitHub Releases
- Choose the appropriate version for your operating system:

Extract and run

# Extract the downloaded file
unzip axonhub_*.zip
cd axonhub_*

# Add execution permissions (only for Linux/macOS)
chmod +x axonhub

# Run directly - default SQLite database

# Install AxonHub to system
sudo ./install.sh

# Start AxonHub service
./start.sh

# Stop AxonHub service
./stop.sh

Access the application
```
http://localhost:8090
```

🖥️ Server Deployment

For production environments, high availability, and enterprise deployments.

Database Support

AxonHub supports multiple databases to meet different scale deployment needs:

Database	Supported Versions	Recommended Scenario	Auto Migration	Links
TiDB Cloud	Starter	Serverless, Free tier, Auto Scale	✅ Supported	TiDB Cloud
TiDB Cloud	Dedicated	Distributed deployment, large scale	✅ Supported	TiDB Cloud
TiDB	V8.0+	Distributed deployment, large scale	✅ Supported	TiDB
Neon DB	-	Serverless, Free tier, Auto Scale	✅ Supported	Neon DB
PostgreSQL	15+	Production environment, medium-large deployments	✅ Supported	PostgreSQL
MySQL	8.0+	Production environment, medium-large deployments	✅ Supported	MySQL
SQLite	3.0+	Development environment, small deployments	✅ Supported	SQLite

Configuration

AxonHub uses YAML configuration files with environment variable override support:

# config.yml
server:
  port: 8090
  name: "AxonHub"
  debug: false

db:
  dialect: "tidb"
  dsn: "<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4"

log:
  level: "info"
  encoding: "json"

Environment variables:

AXONHUB_SERVER_PORT=8090
AXONHUB_DB_DIALECT="tidb"
AXONHUB_DB_DSN="<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4"
AXONHUB_LOG_LEVEL=info

For detailed configuration instructions, please refer to configuration documentation.

Docker Compose Deployment

# Clone project
git clone https://github.com/looplj/axonhub.git
cd axonhub

# Set environment variables
export AXONHUB_DB_DIALECT="tidb"
export AXONHUB_DB_DSN="<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4"

# Start services
docker-compose up -d

# Check status
docker-compose ps

Helm Kubernetes Deployment

Deploy AxonHub on Kubernetes using the official Helm chart:

# Quick installation
git clone https://github.com/looplj/axonhub.git
cd axonhub
helm install axonhub ./deploy/helm

# Production deployment
helm install axonhub ./deploy/helm -f ./deploy/helm/values-production.yaml

# Access AxonHub
kubectl port-forward svc/axonhub 8090:8090
# Visit http://localhost:8090

Key Configuration Options:

Parameter	Description	Default
`axonhub.replicaCount`	Replicas	`1`
`axonhub.dbPassword`	DB password	`axonhub_password`
`postgresql.enabled`	Embedded PostgreSQL	`true`
`ingress.enabled`	Enable ingress	`false`
`persistence.enabled`	Data persistence	`false`

For detailed configuration and troubleshooting, see Helm Chart Documentation.

Virtual Machine Deployment

Download the latest release from GitHub Releases

# Extract and run
unzip axonhub_*.zip
cd axonhub_*

# Set environment variables
export AXONHUB_DB_DIALECT="tidb"
export AXONHUB_DB_DSN="<USER>.root:<PASSWORD>@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true&parseTime=true&multiStatements=true&charset=utf8mb4"

sudo ./install.sh

# Configuration file check
axonhub config check

# Start service
#  For simplicity, we recommend managing AxonHub with the helper scripts:

# Start
./start.sh

# Stop
./stop.sh

📖 Usage Guide

Unified API Overview

AxonHub provides a unified API gateway that supports both OpenAI Chat Completions and Anthropic Messages APIs. This means you can:

Use OpenAI API to call Anthropic models - Keep using your OpenAI SDK while accessing Claude models
Use Anthropic API to call OpenAI models - Use Anthropic's native API format with GPT models
Use Gemini API to call OpenAI models - Use Gemini's native API format with GPT models
Automatic API translation - AxonHub handles format conversion automatically
Zero code changes - Your existing OpenAI or Anthropic client code continues to work

1. Initial Setup

Access Management Interface
```
http://localhost:8090
```
Configure AI Providers
- Add API keys in the management interface
- Test connections to ensure correct configuration
Create Users and Roles
- Set up permission management
- Assign appropriate access permissions

2. Channel Configuration

Configure AI provider channels in the management interface. For detailed information on channel configuration, including model mappings, parameter overrides, and troubleshooting, see the Channel Configuration Guide.

3. Model Management

AxonHub provides a flexible model management system that supports mapping abstract models to specific channels and model implementations through Model Associations. This enables:

Unified Model Interface - Use abstract model IDs (e.g., gpt-4, claude-3-opus) instead of channel-specific names
Intelligent Channel Selection - Automatically route requests to optimal channels based on association rules and load balancing
Flexible Mapping Strategies - Support for precise channel-model matching, regex patterns, and tag-based selection
Priority-based Fallback - Configure multiple associations with priorities for automatic failover

For comprehensive information on model management, including association types, configuration examples, and best practices, see the Model Management Guide.

4. Create API Keys

Create API keys to authenticate your applications with AxonHub. Each API key can be configured with multiple profiles that define:

Model Mappings - Transform user-requested models to actual available models using exact match or regex patterns
Channel Restrictions - Limit which channels an API key can use by channel IDs or tags
Model Access Control - Control which models are accessible through a specific profile
Profile Switching - Change behavior on-the-fly by activating different profiles

For detailed information on API key profiles, including configuration examples, validation rules, and best practices, see the API Key Profile Guide.

5. AI Coding Tools Integration

See the dedicated guides for detailed setup steps, troubleshooting, and tips on combining these tools with AxonHub model profiles:

6. SDK Usage

For detailed SDK usage examples and code samples, please refer to the API documentation:

🛠️ Development Guide

For detailed development instructions, architecture design, and contribution guidelines, please see docs/en/development/development.md.

🤝 Acknowledgments

🙏 musistudio/llms - LLM transformation framework, source of inspiration
🎨 satnaing/shadcn-admin - Admin interface template
🔧 99designs/gqlgen - GraphQL code generation
🌐 gin-gonic/gin - HTTP framework
🗄️ ent/ent - ORM framework
🔧 air-verse/air - Auto reload Go service
☁️ Render - Free cloud deployment platform for hosting our demo
🗃️ TiDB Cloud - Serverless database platform for demo deployment

📄 License

This project is licensed under multiple licenses (Apache-2.0 and LGPL-3.0). See LICENSE file for the detailed licensing overview and terms.

AxonHub - All-in-one AI Development Platform, making AI development simpler

🏠 Homepage • 📚 Documentation • 🐛 Issue Feedback

Built with ❤️ by the AxonHub team

harness/harness

Harness Open Source is an end-to-end developer platform with Source Control Management, CI/CD Pipelines, Hosted Developer Environments, and Artifact Registries.

Harness

Harness Open Source is an open source development platform packed with the power of code hosting, automated DevOps pipelines, hosted development environments (Gitspaces), and artifact registries.

Overview

Harness Open source is an open source development platform packed with the power of code hosting, automated DevOps pipelines, Gitspaces, and artifact registries.

Running Harness locally

The latest publicly released docker image can be found on harness/harness.

To install Harness yourself, simply run the command below. Once the container is up, you can visit http://localhost:3000 in your browser.

docker run -d \
  -p 3000:3000 \
  -p 3022:3022 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/harness:/data \
  --name harness \
  --restart always \
  harness/harness

The Harness image uses a volume to store the database and repositories. It is highly recommended to use a bind mount or named volume as otherwise all data will be lost once the container is stopped.

See developer.harness.io to learn how to get the most out of Harness.

Where is Drone?

Harness Open Source represents a massive investment in the next generation of Drone. Where Drone focused solely on continuous integration, Harness adds source code hosting, developer environments (gitspaces), and artifact registries; providing teams with an end-to-end, open source DevOps platform.

The goal is for Harness to eventually be at full parity with Drone in terms of pipeline capabilities, allowing users to seamlessly migrate from Drone to Harness.

But, we expect this to take some time, which is why we took a snapshot of Drone as a feature branch drone (README) so it can continue development.

As for Harness, the development is taking place on the main branch.

For more information on Harness, please visit developer.harness.io.

For more information on Drone, please visit drone.io.

Harness Open Source Development

Pre-Requisites

Install the latest stable version of Node and Go version 1.20 or higher, and then install the below Go programs. Ensure the GOPATH bin directory is added to your PATH.

Install protobuf

Check if you've already installed protobuf protoc --version
If your version is different than v3.21.11, run brew unlink protobuf
Get v3.21.11 curl -s https://raw.githubusercontent.com/Homebrew/homebrew-core/9de8de7a533609ebfded833480c1f7c05a3448cb/Formula/protobuf.rb > /tmp/protobuf.rb
Install it brew install /tmp/protobuf.rb
Check out your version protoc --version

Install protoc-gen-go and protoc-gen-go-rpc:

Install protoc-gen-go v1.28.1 go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28.1 (Note that this will install a binary in $GOBIN so make sure $GOBIN is in your $PATH)
Install protoc-gen-go-grpc v1.2.0 go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2.0

$ make dep
$ make tools

Build

First step is to build the user interface artifacts:

$ pushd web
$ yarn install
$ yarn build
$ popd

After that, you can build the Harness binary:

$ make build

Run

This project supports all operating systems and architectures supported by Go. This means you can build and run the system on your machine; docker containers are not required for local development and testing.

To start the server at localhost:3000, simply run the following command:

./gitness server .local.env

Docker Configuration for Pipelines

Harness pipelines run inside Docker containers. The application automatically negotiates the Docker API version with your Docker daemon, so it works with various Docker versions including Docker Desktop, Rancher Desktop, Colima, and native Docker on Linux.

Docker Socket Location

By default, Harness expects the Docker socket at /var/run/docker.sock. If you're using an alternative Docker runtime, you may need to configure the socket location:

Runtime	Socket Location	Configuration
Docker Desktop	`/var/run/docker.sock`	Works by default
Rancher Desktop	`~/.rd/docker.sock`	Create symlink or set `GITNESS_DOCKER_HOST`
Colima	`~/.colima/default/docker.sock`	Create symlink or set `GITNESS_DOCKER_HOST`
Linux (native)	`/var/run/docker.sock`	Works by default

Option 1: Create a symlink (recommended)

# For Rancher Desktop
sudo ln -sf ~/.rd/docker.sock /var/run/docker.sock

# For Colima
sudo ln -sf ~/.colima/default/docker.sock /var/run/docker.sock

Option 2: Set environment variable

Add to your .local.env:

# For Rancher Desktop
GITNESS_DOCKER_HOST=unix:///Users/<username>/.rd/docker.sock

# For Colima
GITNESS_DOCKER_HOST=unix:///Users/<username>/.colima/default/docker.sock

Pinning Docker API Version

The application automatically negotiates the API version with your Docker daemon. If you need to pin a specific version (e.g., for compatibility testing), you can set:

GITNESS_DOCKER_API_VERSION=1.45

Auto-Generate Harness API Client used by UI using Swagger

Please make sure to update the autogenerated client code used by the UI when adding new rest APIs.

To regenerate the code, please execute the following steps:

Regenerate swagger with latest Harness binary ./gitness swagger > web/src/services/code/swagger.yaml
navigate to the web folder and run yarn services

The latest API changes should now be reflected in web/src/services/code/index.tsx

Run Registry Conformance Tests

make conformance-test

For running conformance tests with existing running service, use:

make hot-conformance-test

User Interface

This project includes a full user interface for interacting with the system. When you run the application, you can access the user interface by navigating to http://localhost:3000 in your browser.

REST API

This project includes a swagger specification. When you run the application, you can access the swagger specification by navigating to http://localhost:3000/swagger in your browser (for raw yaml see http://localhost:3000/openapi.yaml). For registry endpoints, currently swagger is located on different endpoint http://localhost:3000/registry/swagger/ (for raw json see http://localhost:3000/registry/swagger.json). These will be later moved to the main swagger endpoint.

For testing, it's simplest to just use the cli to create a token (this requires Harness server to run):

# LOGIN (user: admin, pw: changeit)
$ ./gitness login

# GENERATE PAT (1 YEAR VALIDITY)
$ ./gitness user pat "my-pat-uid" 2592000

The command outputs a valid PAT that has been granted full access as the user. The token can then be send as part of the Authorization header with Postman or curl:

$ curl http://localhost:3000/api/v1/user \
-H "Authorization: Bearer $TOKEN"

CLI

This project includes VERY basic command line tools for development and running the service. Please remember that you must start the server before you can execute commands.

For a full list of supported operations, please see

$ ./gitness --help

Contributing

Refer to CONTRIBUTING.md

License

Apache License 2.0, see LICENSE.

CJackHwang/ds2api

DeepSeek-Compatible Middleware Interface: A technical exploration project in Go, focusing on high-concurrency protocol adaptation. It serves as a reference implementation for converting diverse web protocols into standardized formats.

DS2API

语言 / Language: 中文 | English

将 DeepSeek Web 对话能力转换为 OpenAI、Claude 与 Gemini 兼容 API。核心后端以 Go 实现，Vercel 流式桥接额外使用少量 Node Runtime，前端为 React WebUI 管理台（源码在 webui/，部署时自动构建到 static/admin）。

文档入口：文档导航 / 架构说明 / 接口文档

【感谢Linux.do社区及GitHub社区各位开发者对项目的支持与贡献】

Star History

重要免责声明

本仓库仅供学习、研究、个人实验和内部验证使用，不提供任何形式的商业授权、适用性保证或结果保证。

作者及仓库维护者不对因使用、修改、分发、部署或依赖本项目而产生的任何直接或间接损失、账号封禁、数据丢失、法律风险或第三方索赔负责。

请勿将本项目用于违反服务条款、协议、法律法规或平台规则的场景。商业使用前请自行确认 LICENSE、相关协议以及你是否获得了作者的书面许可。

架构概览（摘要）

flowchart LR
    Client["🖥️ 客户端 / SDK\n(OpenAI / Claude / Gemini)"]
    Upstream["☁️ DeepSeek API"]

    subgraph DS2API["DS2API 4.x（模块化 HTTP surface + PromptCompat 内核）"]
        Router["chi Router + 中间件\n(RequestID / RealIP / Logger / Recoverer / CORS)"]

        subgraph HTTP["HTTP API surface"]
            OA["OpenAI\nchat / responses / files / embeddings"]
            CA["Claude\n/anthropic/* + /v1/messages"]
            GA["Gemini\n/v1beta/models/* + /v1/models/*"]
            Admin["Admin API\n资源子包"]
            WebUI["WebUI\n/admin（静态托管）"]
            Vercel["Vercel Node Stream\n/v1/chat/completions"]
        end

        subgraph Runtime["运行时核心能力"]
            Compat["PromptCompat\n(API -> 网页纯文本上下文)"]
            Completion["Completion Runtime\n(Session / PoW / Completion)"]
            Turn["AssistantTurn\n(输出语义归一)"]
            Auth["Auth Resolver\n(API key / bearer / x-goog-api-key)"]
            Pool["Account Pool + Queue\n(并发槽位 + 等待队列)"]
            DSClient["DeepSeek Client\n(Session / Auth / Completion / Files)"]
            Pow["PoW 实现\n(纯 Go)"]
            Tool["Tool Sieve\n(Go/Node 语义对齐)"]
            History["Current Input File\n(DS2API_HISTORY.txt)"]
        end
    end

    Client --> Router
    Router --> OA & CA & GA
    Router --> Admin
    Router --> WebUI
    Router --> Vercel

    OA --> Compat
    CA & GA --> Compat
    Compat --> Completion
    Completion -.完整上下文.-> History
    Completion --> Turn
    Vercel -.Go prepare.-> Completion
    Vercel -.Node SSE.-> Tool
    Completion --> Auth
    Completion -.账号轮询.-> Pool
    Completion -.工具调用解析.-> Tool
    Completion -.PoW 计算.-> Pow
    Auth --> DSClient
    DSClient --> Upstream
    Upstream --> DSClient
    Turn --> Client
    Vercel --> Client

详细架构拆分与目录职责见 docs/ARCHITECTURE.md。

后端：Go（cmd/ds2api/、api/、internal/），不依赖 Python 运行时
前端：React 管理台（webui/），运行时托管静态构建产物
部署：本地运行、Docker、Vercel Serverless、Linux systemd

核心能力

能力	说明
OpenAI 兼容	`GET /v1/models`、`GET /v1/models/{id}`、`POST /v1/chat/completions`、`POST /v1/responses`、`GET /v1/responses/{response_id}`、`POST /v1/embeddings`、`POST /v1/files`、`GET /v1/files/{file_id}`
Claude 兼容	`GET /anthropic/v1/models`、`POST /anthropic/v1/messages`、`POST /anthropic/v1/messages/count_tokens`（及快捷路径 `/v1/messages`、`/messages`）
Gemini 兼容	`POST /v1beta/models/{model}:generateContent`、`POST /v1beta/models/{model}:streamGenerateContent`（及 `/v1/models/{model}:*` 路径）
Ollama 兼容	`GET /api/version`、`GET /api/tags`、`POST /api/show`
统一 CORS 兼容	`/v1/`、`/anthropic/`、`/v1beta/models/`、`/api/`、`/admin/*` 统一走同一套 CORS 策略；Vercel 上 `/v1/chat/completions` 的 Node Runtime 也对齐相同放行规则，尽量减少第三方预检请求头限制
多账号轮询	自动 token 刷新、邮箱/手机号双登录方式
并发队列控制	每账号 in-flight 上限 + 等待队列，动态计算建议并发值
DeepSeek PoW	纯 Go 高性能实现（DeepSeekHashV1），毫秒级响应
Tool Calling	防泄漏处理：非代码块高置信特征识别、`delta.tool_calls` 早发、结构化增量输出
Admin API	配置管理、运行时设置热更新、代理管理、账号测试 / 批量测试、会话清理、导入导出、Vercel 同步、版本检查
WebUI 管理台	`/admin` 单页应用（中英文双语、深色模式，支持查看服务器端对话记录）
运维探针	`GET /healthz`（存活）、`GET /readyz`（就绪）

OpenAI /v1/* 仍是推荐的规范路径；同时支持 /models、/chat/completions、/responses、/embeddings、/files、/files/{file_id} 等根路径快捷路由，方便只配置 DS2API 根地址的第三方客户端。

平台兼容矩阵

级别	平台	当前状态
P0	Codex CLI/SDK（`wire_api=chat` / `wire_api=responses`）	✅
P0	OpenAI SDK（JS/Python，chat + responses）	✅
P0	Vercel AI SDK（openai-compatible）	✅
P0	Anthropic SDK（messages）	✅
P0	Google Gemini SDK（generateContent）	✅
P1	LangChain / LlamaIndex / OpenWebUI（OpenAI 兼容接入）	✅

模型支持

OpenAI 接口（`GET /v1/models`）

模型类型	模型 ID	thinking	search
default	`deepseek-v4-flash`	默认开启，可由请求参数控制	❌
default	`deepseek-v4-flash-nothinking`	永久关闭，不受请求参数影响	❌
expert	`deepseek-v4-pro`	默认开启，可由请求参数控制	❌
expert	`deepseek-v4-pro-nothinking`	永久关闭，不受请求参数影响	❌
default	`deepseek-v4-flash-search`	默认开启，可由请求参数控制	✅
default	`deepseek-v4-flash-search-nothinking`	永久关闭，不受请求参数影响	✅
expert	`deepseek-v4-pro-search`	默认开启，可由请求参数控制	✅
expert	`deepseek-v4-pro-search-nothinking`	永久关闭，不受请求参数影响	✅
vision	`deepseek-v4-vision`	默认开启，可由请求参数控制	❌
vision	`deepseek-v4-vision-nothinking`	永久关闭，不受请求参数影响	❌

除原生模型外，也支持常见 alias 输入（如 gpt-4.1、gpt-5、gpt-5-codex、o3、claude-*、gemini-* 等），但 /v1/models 返回的是规范化后的 DeepSeek 原生模型 ID。若 alias 名本身追加 -nothinking 后缀，也会映射到对应的强制关思考模型。完整 alias 行为以 API.md 和 config.example.json 为准。当前上游视觉模型只暴露 vision 通道，不提供独立的联网搜索视觉变体。

Claude 接口（`GET /anthropic/v1/models`）

当前常用模型	默认映射
`claude-sonnet-4-6`	`deepseek-v4-flash`
`claude-sonnet-4-6-nothinking`	`deepseek-v4-flash-nothinking`
`claude-haiku-4-5`（兼容 `claude-3-5-haiku-latest`）	`deepseek-v4-flash`
`claude-haiku-4-5-nothinking`	`deepseek-v4-flash-nothinking`
`claude-opus-4-6`	`deepseek-v4-pro`
`claude-opus-4-6-nothinking`	`deepseek-v4-pro-nothinking`

可通过配置中的 model_aliases 覆盖映射关系；若请求模型名带 -nothinking，会在最终映射结果上强制追加无思考语义。 /anthropic/v1/models 除上述主别名外，还会返回 Claude 4.x snapshots、3.x 历史模型 ID 与常见 alias，便于旧客户端直接兼容。

Claude Code 接入避坑（实测）

ANTHROPIC_BASE_URL 推荐直接指向 DS2API 根地址（例如 http://127.0.0.1:5001），Claude Code 会请求 /v1/messages?beta=true。
ANTHROPIC_API_KEY 需要与 config.json 中 keys 一致；建议同时保留常规 key 与 sk-ant-* 形态 key，兼容不同客户端校验习惯。
若系统设置了代理，建议对 DS2API 地址配置 NO_PROXY=127.0.0.1,localhost,<你的主机IP>，避免本地回环请求被代理拦截。
如遇“工具调用输出成文本、未执行”问题，请优先检查模型输出是否为推荐的半角管道符 DSML 工具块：<|DSML|tool_calls><|DSML|invoke name="..."><|DSML|parameter name="...">...。兼容层也接受旧式 canonical XML：<tool_calls><invoke name="..."><parameter name="...">...；旧式 <tools> / <tool_call> / <tool_name> / <param>、<function_call>、tool_use 或纯 JSON tool_calls 片段不会执行，会作为普通文本处理。

Gemini 接口

Gemini 适配器将模型名通过 model_aliases 或内置精确 alias 映射到 DeepSeek 原生模型（覆盖 gemini-2.5-*、gemini-3*、gemini-pro-vision 等常见名称），支持 generateContent 和 streamGenerateContent 两种调用方式，并完整支持 Tool Calling（functionDeclarations → functionCall 输出）。若 Gemini 模型名带 -nothinking 后缀，例如 gemini-2.5-pro-nothinking，会映射到对应的强制关闭思考模型。

快速开始

部署方式优先级建议

推荐按以下顺序选择部署方式：

下载 Release 构建包运行：最省事，产物已编译完成，最适合大多数用户。
Docker / GHCR 镜像部署：适合需要容器化、编排或云环境部署。
Vercel 部署：适合已有 Vercel 环境且接受其平台约束的场景。
本地源码运行 / 自行编译：适合开发、调试或需要自行修改代码的场景。

通用第一步（所有部署方式）

把 config.json 作为唯一配置源（推荐做法）：

cp config.example.json config.json
# 编辑 config.json

后续部署建议：

本地运行：直接读取 config.json
Docker / Vercel：由 config.json 生成 DS2API_CONFIG_JSON（Base64）注入环境变量，也可以直接写原始 JSON

WebUI 管理台里的“全量配置模板”也直接复用同一份 config.example.json，所以更新示例文件后，前端模板会自动保持一致。

方式一：下载 Release 构建包

每次发布 Release 时，GitHub Actions 会自动构建多平台二进制包：

# 下载对应平台的压缩包后
tar -xzf ds2api_<tag>_linux_amd64.tar.gz
cd ds2api_<tag>_linux_amd64
cp config.example.json config.json
# 编辑 config.json
./ds2api

方式二：Docker 运行

# 1. 准备环境变量和配置文件
cp .env.example .env
cp config.example.json config.json

# 2. 编辑 .env（至少设置 DS2API_ADMIN_KEY；如需修改宿主机端口，可额外设置 DS2API_HOST_PORT）
#    DS2API_ADMIN_KEY=请替换为强密码

# 3. 启动
docker-compose up -d

# 4. 查看日志
docker-compose logs -f

默认 docker-compose.yml 会把宿主机 6011 映射到容器内的 5001。如果你希望直接对外暴露 5001，请设置 DS2API_HOST_PORT=5001（或者手动调整 ports 配置）。同时默认把 ./config.json 挂载到容器 /data/config.json，并设置 DS2API_CONFIG_PATH=/data/config.json，用于避免 /app 只读导致运行时 token 持久化失败。镜像会预创建 /data 并授权给非 root 的 ds2api 用户；如果使用单文件 bind mount，请确保宿主机 config.json 对容器用户可读写，例如 chmod 644 config.json。

更新镜像：docker-compose up -d --build

Zeabur 一键部署（Dockerfile）

点击上方 “Deploy on Zeabur” 按钮，一键部署。
部署完成后访问 /admin，使用 Zeabur 环境变量/模板指引中的 DS2API_ADMIN_KEY 登录。
在管理台导入/编辑配置（会写入并持久化到 /data/config.json）。

Zeabur 首次空卷启动时可以没有 /data/config.json；DS2API 会先使用空的文件模式配置启动，并在管理台首次保存时创建该文件。

不依赖模板手动部署时，在 Zeabur 中选择 GitHub 仓库服务，Root Directory 保持 /，使用仓库根目录 Dockerfile 构建；添加持久卷 /data，设置 PORT=5001、DS2API_ADMIN_KEY=你的强密钥、DS2API_CONFIG_PATH=/data/config.json，然后暴露 HTTP 端口 5001。更完整步骤见 docs/DEPLOY.md。

说明：Zeabur 使用仓库内 Dockerfile 直接构建时，不需要额外传入 BUILD_VERSION；镜像会优先读取该构建参数，未提供时自动回退到仓库根目录的 VERSION 文件。

方式三：Vercel 部署

Fork 仓库到自己的 GitHub
在 Vercel 上导入项目
配置环境变量（最少设置 DS2API_ADMIN_KEY；推荐同时设置 DS2API_CONFIG_JSON）
部署

建议先在仓库目录复制模板并填写：

cp config.example.json config.json
# 编辑 config.json

推荐：先本地把 config.json 转成 Base64，再粘贴到 DS2API_CONFIG_JSON，避免 JSON 格式错误：

base64 < config.json | tr -d '\n'

流式说明：OpenAI Chat 流式在 Vercel 上会由 api/chat-stream.js（Node Runtime）承接，但 vercel.json 只把规范路径 /v1/chat/completions 重写到 Node；根路径快捷别名 /chat/completions 仍走 Go 主链路。鉴权、账号选择、会话/PoW 准备仍由 Go 内部 prepare 接口完成；流式响应（含 tools）在 Node 侧执行与 Go 对齐的输出组装与防泄漏处理。Vercel 上需要实时流式时请使用 /v1/chat/completions。

详细部署说明请参阅部署指南。

方式四：本地源码运行

前置要求：Go 1.26+，Node.js 20.19+ 或 22.12+（仅在需要构建 WebUI 时；CI / Docker 构建使用 Node 24）；同时确保 npm 可用，建议 npm 10+

# 1. 克隆仓库
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# 2. 配置
cp config.example.json config.json
# 编辑 config.json，填入你的 DeepSeek 账号信息和 API key

# 3. 启动
go run ./cmd/ds2api

默认本地访问地址：http://127.0.0.1:5001

服务实际绑定：0.0.0.0:5001，因此同一局域网设备通常也可以通过你的内网 IP 访问。

WebUI 自动构建：本地首次启动时，若 WebUI 静态目录不存在，会自动尝试执行 npm ci --prefix webui（仅在缺少依赖时）和 npm run build --prefix webui -- --outDir static/admin --emptyOutDir（需要本机有 Node.js 和 npm；静态目录可用 DS2API_STATIC_ADMIN_DIR 覆盖）。你也可以手动构建：./scripts/build-webui.sh

配置说明

README 只保留快速入口，完整字段请以 config.example.json 为模板，并参考部署指南与 API 配置最佳实践。

常用字段：

keys / api_keys：客户端访问密钥，api_keys 支持 name 与 remark 元信息，keys 继续兼容。
accounts：DeepSeek 托管账号，支持 email 或 mobile 登录，可配置代理、名称和备注。
model_aliases：OpenAI / Claude / Gemini 共用的模型 alias 映射。
runtime：账号并发、队列与 token 刷新策略，可通过 Admin Settings 热更新。
auto_delete.mode：请求结束后的远端会话清理策略，支持 none / single / all。
current_input_file：全局生效的上下文拆分上传策略；默认开启且阈值为 0，触发时将完整上下文合并上传为 DS2API_HISTORY.txt 上下文文件。
如果关闭 current_input_file，请求会直接透传，不上传拆分上下文文件。
thinking_injection：默认开启；在最新 user 消息末尾追加思考增强提示词，提高高强度推理与工具调用前的思考稳定性；prompt 留空时使用内置默认提示词。

环境变量完整列表见部署指南，接口鉴权规则见 API.md。

鉴权模式

调用业务接口（/v1/*、/anthropic/*、Gemini 路由）时支持两种模式：

模式	说明
托管账号模式	`Bearer` 或 `x-api-key` 传入 `config.keys` 中的 key，由服务自动轮询选择账号
直通 token 模式	传入 token 不在 `config.keys` 中时，直接作为 DeepSeek token 使用

可选请求头 X-Ds2-Target-Account：指定使用某个托管账号（值为 email 或 mobile）。如果指定账号不存在，或者当前管理账号队列已满，请求会返回 429；当前 429 不附带 Retry-After 头。若账号存在但登录/刷新失败，则返回对应的鉴权错误。未指定目标账号时，如果 completion 因上游 thinking-only 空输出在同账号补偿重试后仍将返回 429 upstream_empty_output，托管账号模式会自动切到下一个可用账号，新建 session，并用原始 payload 再 fresh retry 一次。 Gemini 路由还可以使用 x-goog-api-key，或在没有认证头时使用 ?key= / ?api_key= 作为调用方凭据。

并发模型

每账号可用并发 = DS2API_ACCOUNT_MAX_INFLIGHT（默认 2）
建议并发值 = 账号数量 × 每账号并发上限
等待队列上限 = DS2API_ACCOUNT_MAX_QUEUE（默认 = 建议并发值）
429 阈值 = in-flight + 等待队列 ≈ 账号数量 × 4

当 in-flight 槽位满时，请求进入等待队列，不会立即 429
超出总承载上限后才返回 429 Too Many Requests，当前响应不附带 Retry-After
completion 空输出类 429 会先做同账号补偿重试；托管账号模式还会在最终返回 429 前切到另一个可用账号 fresh retry 一次
GET /admin/queue/status 返回实时并发状态

Tool Call 适配

当请求中带 tools 时，DS2API 会做防泄漏处理与结构化转译：

只在非 Markdown 代码上下文启用执行型 toolcall 识别（fenced code block 和行内 code span 中的示例默认不触发）
解析层当前把半角管道符 DSML 外壳视为推荐可执行调用：<|DSML|tool_calls> → <|DSML|invoke name="..."> → <|DSML|parameter name="...">；兼容旧式 canonical XML <tool_calls> → <invoke name="..."> → <parameter name="...">，以及若干 DSML 前缀/分隔符漂移。DSML 只是外壳别名，内部仍以 XML 解析语义为准；旧式 <tools> / <tool_call> / <tool_name> / <param>、<function_call>、tool_use / antml 变体与纯 JSON tool_calls 片段都会按普通文本处理，完整但 malformed 的 wrapper 也会作为普通文本释放
responses 流式严格使用官方 item 生命周期事件（response.output_item.*、response.content_part.*、response.function_call_arguments.*）
responses 支持并执行 tool_choice（auto/none/required/强制函数）；required 违规时非流式返回 422，流式返回 response.failed
客户端请求哪种协议，就按该协议返回工具调用（OpenAI/Claude/Gemini 各自原生结构）；模型侧优先约束输出规范 XML，再由兼容层转译

说明：当前版本 parser 层以”尽量解析成功”为优先，所有格式合法的 XML 工具调用都会通过，不做工具名 allow-list 过滤。解析层会保留显式空字符串或纯空白参数；Prompt 会要求模型不要主动输出空参数，缺参/空命令的拒绝应由工具执行侧或客户端 schema 校验负责。

想评估”把工具调用封装成 XML 再输入模型”的方案，可参考：docs/toolcall-semantics.md。

本地开发抓包工具

用于定位「responses 思考流/工具调用」等问题。开启后会自动记录最近 N 条 DeepSeek 对话上游请求体与响应体（默认 20 条，超出自动淘汰；单条响应体默认最多记录 5 MB）。

启用示例：

DS2API_DEV_PACKET_CAPTURE=true \
DS2API_DEV_PACKET_CAPTURE_LIMIT=20 \
go run ./cmd/ds2api

查询/清空（需 Admin JWT）：

GET /admin/dev/captures：查看抓包列表（最新在前）
DELETE /admin/dev/captures：清空抓包
GET /admin/dev/raw-samples/query?q=关键词&limit=20：按问题关键词查询当前内存抓包，并按 chat_session_id 归并 completion + continue 链
POST /admin/dev/raw-samples/save：把命中的某条抓包链保存为 tests/raw_stream_samples/<sample-id>/ 回放样本

返回字段包含：

request_body：发送给 DeepSeek 的完整请求体
response_body：上游返回的原始流式内容拼接文本
response_truncated：是否触发单条大小截断

保存接口支持用 query、chain_key 或 capture_id 选中目标。例如：

{"query":"广州天气","sample_id":"gz-weather-from-memory"}

文档索引

文档	说明
API.md / API.en.md	API 接口文档（含请求/响应示例）
DEPLOY.md / DEPLOY.en.md	部署指南（本地/Docker/Vercel/systemd）
CONTRIBUTING.md / CONTRIBUTING.en.md	贡献指南
TESTING.md	测试集使用指南

测试

详细测试指南请参阅 docs/TESTING.md。

快速测试命令

# 本地 PR 门禁
./scripts/lint.sh
./tests/scripts/check-refactor-line-gate.sh
./tests/scripts/run-unit-all.sh
npm run build --prefix webui

# 端到端全链路测试（真实账号，生成完整请求/响应日志）
./tests/scripts/run-live.sh

Release 自动构建（GitHub Actions）

工作流文件：.github/workflows/release-artifacts.yml

触发条件：默认仅在 GitHub Release published 时自动触发；也支持在 Actions 页面手动 workflow_dispatch，并填写 release_tag 复跑/补发
构建产物：多平台二进制包（linux/amd64、linux/arm64、linux/armv7、darwin/amd64、darwin/arm64、windows/amd64、windows/arm64）、Linux Docker 镜像导出包 + sha256sums.txt
容器镜像发布：仅推送到 GHCR（ghcr.io/cjackhwang/ds2api）
每个二进制压缩包包含：ds2api 可执行文件、static/admin、config.example.json、.env.example、README.MD、README.en.md、LICENSE

免责声明

本项目基于逆向方式实现，仅供学习、研究、个人实验和内部验证使用，不提供任何商业授权、稳定性保证或可用性保证。作者及仓库维护者不对因使用、修改、分发、部署或依赖本项目而产生的任何直接或间接损失、账号封禁、数据丢失、法律风险或第三方索赔负责。

请勿将本项目用于违反服务条款、协议、法律法规或平台规则的场景。商业使用前请自行确认 LICENSE、相关协议以及你是否获得了作者的书面许可。

microsoft/typescript-go

Staging repo for development of native port of TypeScript

TypeScript 7

Not sure what this is? Read the announcement post!

Preview

A preview build is available on npm as @typescript/native-preview.

npm install @typescript/native-preview
npx tsgo # Use this as you would tsc.

A preview VS Code extension is available on the VS Code marketplace.

To use this, set this in your VS Code settings:

{
    "js/ts.experimental.useTsgo": true
}

What Works So Far?

This is still a work in progress and is not yet at full feature parity with TypeScript. Bugs may exist. Please check this list carefully before logging a new issue or assuming an intentional change.

Feature	Status	Notes
Program creation	done	Same files and module resolution as TS 6.0. Not all resolution modes supported yet.
Parsing/scanning	done	Exact same syntax errors as TS 6.0
Commandline and `tsconfig.json` parsing	done	Done, though `tsconfig` errors may not be as helpful.
Type resolution	done	Same types as TS 6.0.
Type checking	done	Same errors, locations, and messages as TS 6.0. Types printback in errors may display differently.
JavaScript-specific inference and JSDoc	done	Complete, but intentionally lacking some features. Declaration emit differs greatly, intentionally, to be closer to TS declarations.
JSX	done	-
Declaration emit	done	-
Emit (JS output)	done	-
Watch mode	prototype	Watches files and rebuilds, but no incremental rechecking. Not optimized.
Build mode / project references	done	-
Incremental build	done	-
Language service (LSP)	in progress	Nearly all features implemented.
API	not ready	-

Definitions:

done aka "believed done": We're not currently aware of any deficits or major work left to do. OK to log bugs
in progress: currently being worked on; some features may work and some might not. OK to log panics, but nothing else please
prototype: proof-of-concept only; do not log bugs
not ready: either haven't even started yet, or far enough from ready that you shouldn't bother messing with it yet

Other Notes

Long-term, we expect that this repo and its contents will be merged into microsoft/TypeScript. As a result, the repo and issue tracker for typescript-go will eventually be closed, so treat discussions/issues accordingly.

For a list of intentional changes with respect to TypeScript 6.0, see CHANGES.md.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

gastownhall/gascity

Orchestration-builder SDK for multi-agent coding workflows

Gas City

Composable orchestration infrastructure for multi-agent coding workflows.

Gas City is an orchestration-builder SDK for multi-agent systems. It extracts the reusable infrastructure from Gas Town into a configurable toolkit with runtime providers, work routing, formulas, orders, health patrol, and a declarative city configuration.

Sponsors

Coming from Gas Town?

Start with Coming from Gas Town?. It maps Town roles, commands, plugins, convoys, and directory habits onto Gas City's primitive-first model so experienced Gas Town users can ramp without trying to port the entire Town architecture literally.

What You Get

Declarative city configuration in city.toml
Multiple runtime providers: tmux, subprocess, exec, ACP, and Kubernetes
Beads-backed work tracking, formulas, molecules, waits, and mail
A controller/supervisor loop that reconciles desired state to running state
Packs, overrides, and rig-scoped orchestration for multi-project setups

Quickstart

See the full install guide at docs/getting-started/installation.md.

Prerequisites

Gas City requires the following tools on your system. gc init and gc start check for these automatically and report any that are missing.

Dependency	Required	Min Version	Install (macOS)	Install (Linux)
tmux	Always	—	`brew install tmux`	`apt install tmux`
git	Always	—	`brew install git`	`apt install git`
jq	Always	—	`brew install jq`	`apt install jq`
pgrep	Always	—	(included in macOS)	`apt install procps`
lsof	Always	—	(included in macOS)	`apt install lsof`
dolt	Beads provider `bd`	1.86.2 or newer	`brew install dolt`	releases
bd	Beads provider `bd`	1.0.0	releases	releases
flock	Beads provider `bd`	—	`brew install flock`	`apt install util-linux`
gh	Optional GitHub gates	—	`brew install gh`	cli.github.com
claude / codex / gemini	Per provider	—	See provider docs	See provider docs

The bd (beads) provider is the default. To use a file-based store instead (no dolt/bd/flock needed), set GC_BEADS=file or add [beads] provider = "file" to your city.toml.

Managed Dolt checks require a final Dolt 1.86.2 or newer. Earlier and pre-release builds can miss the upstream GC/writer deadlock fix in dolthub/dolt commit ccf7bde206, which can hang dolt_backup sync under heavy write load.

Install from Homebrew:

brew install gastownhall/gascity/gascity
gc version

Or build from source (requires make and Go 1.25+):

make install

gc init ~/bright-lights
cd ~/bright-lights
gc start

mkdir hello-world
cd hello-world
git init
gc rig add .

bd create "Create a script that prints hello world"
gc session attach mayor

For the longer walkthrough, start with Tutorial 01.

Documentation

The docs now use a Mintlify structure rooted in docs/.

Preview the docs locally:

make docs-dev

# or directly from the repo root
./mint.sh dev

Repository Map

cmd/gc/: CLI commands, controller wiring, and supervisor integration
internal/runtime/: runtime provider abstraction and implementations
internal/config/: city.toml schema, pack composition, and validation
internal/beads/: store abstraction and provider implementations
internal/session/: session bead metadata and wait helpers
internal/orders/: periodic formula and exec dispatch
internal/convergence/: bounded iterative refinement loops
examples/: sample cities, packs, formulas, and configs
contrib/: helper scripts and deployment assets
test/: integration and support test packages

Contributing

Read CONTRIBUTING.md and engdocs/contributors/index.md before opening a PR.

Useful commands:

make setup
make check
make check-docs
make test-integration

License

MIT

XTLS/Xray-core

Xray, Penetrates Everything. Also the best v2ray-core. Where the magic happens. An open platform for various uses.

Project X

Project X originates from XTLS protocol, providing a set of network tools such as Xray-core and REALITY.

README is open, so feel free to submit your project here.

Sponsors

Sponsor Xray-core

Donation & NFTs

Collect a Project X NFT to support the development of Project X!

TRX(Tron)/USDT/USDC: TNrDh5VSfwd4RPrwsohr6poyNTfFefNYan
TON: UQApeV-u2gm43aC1uP76xAC1m6vCylstaN1gpfBmre_5IyTH
BTC: 1JpqcziZZuqv3QQJhZGNGBVdCBrGgkL6cT
XMR: 4ABHQZ3yJZkBnLoqiKvb3f8eqUnX4iMPb6wdant5ZLGQELctcerceSGEfJnoCk6nnyRZm73wrwSgvZ2WmjYLng6R7sR67nq
SOL/USDT/USDC: 3x5NuXHzB5APG6vRinPZcsUv5ukWUY1tBGRSJiEJWtZa
ETH/USDT/USDC: 0xDc3Fe44F0f25D13CACb1C4896CD0D321df3146Ee
Project X NFT: https://opensea.io/item/ethereum/0x5ee362866001613093361eb8569d59c4141b76d1/1
VLESS NFT: https://opensea.io/collection/vless
REALITY NFT: https://opensea.io/item/ethereum/0x5ee362866001613093361eb8569d59c4141b76d1/2
Related links: VLESS Post-Quantum Encryption, XHTTP: Beyond REALITY, Announcement of NFTs by Project X

License

Mozilla Public License Version 2.0

Documentation

Project X Official Website

Project X

Project X Channel

Project VLESS (Русский)

Project XHTTP (Persian)

Installation

Linux Script
- XTLS/Xray-install (Official)
- tempest (supports systemd and OpenRC; Linux-only)
Docker
- ghcr.io/xtls/xray-core (Official)
- teddysun/xray
- wulabing/xray_docker
Web Panel
- Remnawave
- 3X-UI
- PasarGuard
- Xray-UI
- X-Panel
- Marzban
- Hiddify
- TX-UI
- CELERITY
One Click
Magisk
- Xray4Magisk
- Xray_For_Magisk
Homebrew
- brew install xray

Usage

GUI Clients

OpenWrt
Asuswrt-Merlin
- XRAYUI
- fancyss
Windows
Android
- v2rayNG
- X-flutter
- SaeedDev94/Xray
- SimpleXray
- XrayFA
- AnyPortal
- OneXray
iOS & macOS arm64 & tvOS
- Happ | Happ RU | Happ tvOS
- Streisand
- OneXray
- INCY
macOS arm64 & x64
- Happ | Happ RU
- V2rayU
- V2RayXS
- Furious
- OneXray
- GoXRay
- AnyPortal
- v2rayN
- GenyConnect
- INCY
Linux
- v2rayA
- Furious
- GorzRay
- GoXRay
- AnyPortal
- v2rayN
- GenyConnect
- OneXray

Others that support VLESS, XTLS, REALITY, XUDP, PLUX...

iOS & macOS arm64 & tvOS
- Anywhere
- Shadowrocket
- Loon
- Egern
- Quantumult X
Xray Tools
- xray-knife
- xray-checker
Xray Wrapper
XrayR
- XrayR-release
- XrayR-V2Board
Cores

Contributing

Code of Conduct

Credits

Xray-core v1.0.0 was forked from v2fly-core 9a03cc5, and we have made & accumulated a huge number of enhancements over time, check the release notes for each version.
For third-party projects used in Xray-core, check your local or the latest go.mod.

One-line Compilation

Windows (PowerShell)

$env:CGO_ENABLED=0
go build -o xray.exe -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

Linux / macOS

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -ldflags="-s -w -buildid=" -v ./main

Reproducible Releases

Make sure that you are using the same Go version, and remember to set the git commit id (7 bytes):

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="all=-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid=" -v ./main

If you are compiling a 32-bit MIPS/MIPSLE target, use this command instead:

CGO_ENABLED=0 go build -o xray -trimpath -buildvcs=false -gcflags="-l=4" -ldflags="-X github.com/xtls/xray-core/core.build=REPLACE -s -w -buildid=" -v ./main

Stargazers over time

go-git/go-git

A highly extensible Git implementation in pure Go.

go-git is a highly extensible git implementation library written in pure Go.

It can be used to manipulate git repositories at low level (plumbing) or high level (porcelain), through an idiomatic Go API. It also supports several types of storage, such as in-memory filesystems, or custom implementations, thanks to the Storer interface.

It has been actively developed since 2015 and is used extensively by Keybase, Gitea, and Pulumi, among many other libraries and tools. It is also a dependency in major CNCF projects such as Kubernetes Prow and Flux.

Project Status

For the full backstory see HISTORY.md.

The project is actively maintained by individual contributors, including several of the original authors. It is backed by GitSight, where go-git is a critical component used at scale, and by Entire, which supports ongoing maintenance and development of new features.

Comparison with git

go-git aims to be fully compatible with git, all the porcelain operations are implemented to work exactly as git does.

git is a humongous project with years of development by thousands of contributors, making it challenging for go-git to implement all the features. You can find a comparison of go-git vs git in the compatibility documentation.

Installation

The recommended way to install go-git is:

import "github.com/go-git/go-git/v6"

Examples

Please note that the CheckIfError and Info functions used in the examples are from the examples package just to be used in the examples.

Basic example

A basic example that mimics the standard git clone command

// Clone the given repository to the given directory
Info("git clone https://github.com/go-git/go-git")

_, err := git.PlainClone("/tmp/foo", &git.CloneOptions{
    URL:      "https://github.com/go-git/go-git",
    Progress: os.Stdout,
})

CheckIfError(err)

Outputs:

Counting objects: 4924, done.
Compressing objects: 100% (1333/1333), done.
Total 4924 (delta 530), reused 6 (delta 6), pack-reused 3533

In-memory example

Cloning a repository into memory and printing the history of HEAD, just like git log does

// Clones the given repository in memory, creating the remote, the local
// branches and fetching the objects, exactly as:
Info("git clone https://github.com/go-git/go-billy")

r, err := git.Clone(memory.NewStorage(), nil, &git.CloneOptions{
    URL: "https://github.com/go-git/go-billy",
})

CheckIfError(err)

// Gets the HEAD history from HEAD, just like this command:
Info("git log")

// ... retrieves the branch pointed by HEAD
ref, err := r.Head()
CheckIfError(err)


// ... retrieves the commit history
cIter, err := r.Log(&git.LogOptions{From: ref.Hash()})
CheckIfError(err)

// ... just iterates over the commits, printing it
err = cIter.ForEach(func(c *object.Commit) error {
	fmt.Println(c)
	return nil
})
CheckIfError(err)

Outputs:

commit ded8054fd0c3994453e9c8aacaf48d118d42991e
Author: Santiago M. Mola <santi@mola.io>
Date:   Sat Nov 12 21:18:41 2016 +0100

    index: ReadFrom/WriteTo returns IndexReadError/IndexWriteError. (#9)

commit df707095626f384ce2dc1a83b30f9a21d69b9dfc
Author: Santiago M. Mola <santi@mola.io>
Date:   Fri Nov 11 13:23:22 2016 +0100

    readwriter: fix bug when writing index. (#10)

    When using ReadWriter on an existing siva file, absolute offset for
    index entries was not being calculated correctly.
...

You can find this example and many others in the examples folder.

Contribute

Contributions are more than welcome, if you are interested please take a look to our Contributing Guidelines.

License

Apache License Version 2.0, see LICENSE

moby/moby

The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems

The Moby Project

Moby is an open-source project created by Docker to enable and accelerate software containerization.

It provides a "Lego set" of toolkit components, the framework for assembling them into custom container-based systems, and a place for all container enthusiasts and professionals to experiment and exchange ideas. Components include container build tools, a container registry, orchestration tools, a runtime and more, and these can be used as building blocks in conjunction with other tools and projects.

Principles

Moby is an open project guided by strong principles, aiming to be modular, flexible and without too strong an opinion on user experience. It is open to the community to help set its direction.

Modular: the project includes lots of components that have well-defined functions and APIs that work together.
Batteries included but swappable: Moby includes enough components to build fully featured container systems, but its modular architecture ensures that most of the components can be swapped by different implementations.
Usable security: Moby provides secure defaults without compromising usability.
Developer focused: The APIs are intended to be functional and useful to build powerful tools. They are not necessarily intended as end user tools but as components aimed at developers. Documentation and UX is aimed at developers not end users.

Audience

The Moby Project is intended for engineers, integrators and enthusiasts looking to modify, hack, fix, experiment, invent and build systems based on containers. It is not for people looking for a commercially supported system, but for people who want to work and learn with open source code.

Relationship with Docker

The components and tools in the Moby Project are initially the open source components that Docker and the community have built for the Docker Project. New projects can be added if they fit with the community goals. Docker is committed to using Moby as the upstream for the Docker Product. However, other projects are also encouraged to use Moby as an upstream, and to reuse the components in diverse ways, and all these uses will be treated in the same way. External maintainers and contributors are welcomed.

The Moby project is not intended as a location for support or feature requests for Docker products, but as a place for contributors to work on open source code, fix bugs, and make the code more useful. The releases are supported by the maintainers, community and users, on a best efforts basis only. For customers who want enterprise or commercial support, Docker Desktop and Mirantis Container Runtime are the appropriate products for these use cases.

Go modules

Important

Starting with Docker v29 (released November 2025), the Go module github.com/docker/docker is deprecated and won't be updated.

The supported public Go modules are:

Module	Description
`github.com/moby/moby/client`	Go client for the Docker Engine API
`github.com/moby/moby/api`	API types shared between client and server

The root module github.com/moby/moby/v2 is the codebase for building container engines based on Moby (such as Docker Engine). It produces binaries only - it is not intended to be imported as a Go library and has no API stability guarantees.

Release tags

Docker Engine releases are tagged with a docker- prefix (e.g. docker-v29.0.0 for Docker Engine 29.0.0).

These tags are only used to build the Docker Engine binary from the root module - they must not be consumed via go get.

The client and api modules are versioned independently with their own tags (e.g. client/v1.x.x, api/v1.x.x).

Migrating from `github.com/docker/docker`

Replace the old import paths:

- import "github.com/docker/docker/client"
+ import "github.com/moby/moby/client"

- import "github.com/docker/docker/api/types"
+ import "github.com/moby/moby/api/types"

Note that v29 includes many breaking API changes (option structs, renamed methods, moved types). See the v29.0.0 release notes for the full list of Go SDK changes.

Legal

Brought to you courtesy of our legal counsel. For more context, please see the NOTICE document in this repo.

Use and transfer of Moby may be subject to certain restrictions by the United States and other governments.

It is your responsibility to ensure that your use and/or transfer does not violate applicable laws.

For more information, please see https://www.bis.doc.gov

Licensing

Moby is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

gastownhall/beads

Beads - A memory upgrade for your coding agent

bd - Beads

Distributed graph issue tracker for AI agents, powered by Dolt.

Platforms: macOS, Linux, Windows, FreeBSD

Docs: https://gastownhall.github.io/beads/

Beads provides a persistent, structured memory for coding agents. It replaces messy markdown plans with a dependency-aware graph, allowing agents to handle long-horizon tasks without losing context.

⚡ Quick Start

# Install beads CLI (system-wide - don't clone this repo into your project)
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash

# Initialize in YOUR project
cd your-project
bd init

# Optional: install richer instructions for your agent
bd setup codex    # Codex CLI - creates/updates AGENTS.md
bd setup claude   # Claude Code - installs hooks/settings
bd setup factory  # Factory.ai Droid - creates/updates AGENTS.md

Note: Beads is a CLI tool you install once and use everywhere. You don't need to clone this repository into your project.

bd init creates or updates AGENTS.md by default so agents can discover the beads workflow. It skips agent files only when you pass --skip-agents or --stealth, or when you configure a custom agent file. Use bd setup --list to see supported integrations, including bd setup codex, bd setup factory, bd setup claude, bd setup mux, bd setup cursor, and more. See Agent and IDE setup.

Manual copy-paste is only for unsupported agents, existing projects where you cannot rerun bd init/bd setup, or custom instruction files. In those cases, run bd onboard and paste the printed snippet into the file your agent reads.

If your agent is not covered by bd setup, add this minimal AGENTS.md section:

This project uses bd (beads) for issue tracking.

- Run `bd prime` for workflow context and command guidance.
- Use `bd ready`, `bd show <id>`, `bd update <id> --claim`, and `bd close <id>`.
- Use `bd remember "insight"` for persistent project memory; do not create MEMORY.md files.
- Do not use markdown TODO lists for task tracking.

🛠 Features

Dolt-Powered: Version-controlled SQL database with cell-level merge, native branching, and built-in sync via Dolt remotes.
Agent-Optimized: JSON output, dependency tracking, and auto-ready task detection.
Zero Conflict: Hash-based IDs (bd-a1b2) prevent merge collisions in multi-agent/multi-branch workflows.
Compaction: Semantic "memory decay" summarizes old closed tasks to save context window.
Messaging: Message issue type with threading (--thread), ephemeral lifecycle, and mail delegation.
Graph Links: relates_to, duplicates, supersedes, and replies_to for knowledge graphs.

📖 Essential Commands

Command	Action
`bd ready`	List tasks with no open blockers.
`bd create "Title" -p 0`	Create a P0 task.
`bd update <id> --claim`	Atomically claim a task (sets assignee + in_progress).
`bd dep add <child> <parent>`	Link tasks (blocks, related, parent-child).
`bd show <id>`	View task details and audit trail.
`bd prime`	Print agent workflow context and persistent memories.
`bd remember "insight"`	Store project memory that `bd prime` injects later.

🔗 Hierarchy & Workflow

Beads supports hierarchical IDs for epics:

bd-a3f8 (Epic)
bd-a3f8.1 (Task)
bd-a3f8.1.1 (Sub-task)

Stealth Mode: Run bd init --stealth to use Beads locally without committing files to the main repo. Perfect for personal use on shared projects. See Git-Free Usage below.

Contributor vs Maintainer: When working on open-source projects:

Contributors (forked repos): Run bd init --contributor to route planning issues to a separate repo (e.g., ~/.beads-planning). Keeps experimental work out of PRs.
Maintainers (write access): Beads auto-detects maintainer role via SSH URLs or HTTPS with credentials. Only need git config beads.role maintainer if using GitHub HTTPS without credentials but you have write access.

📦 Installation

brew install beads           # macOS / Linux (recommended)
npm install -g @beads/bd     # Node.js users

Other methods: install script | go install | from source | Windows | Arch AUR

Requirements: macOS, Linux, Windows, or FreeBSD. See docs/INSTALLING.md for complete installation guide.

Security And Verification

Before trusting any downloaded binary, verify its checksum against the release checksums.txt.

The install scripts verify release checksums before install. For manual installs, do this verification yourself before first run.

On macOS, scripts/install.sh preserves the downloaded signature by default. Local ad-hoc re-signing is explicit opt-in via BEADS_INSTALL_RESIGN_MACOS=1.

See docs/ANTIVIRUS.md for Windows AV false-positive guidance and verification workflow.

💾 Storage Modes

Beads uses Dolt as its database. Two modes are available:

Embedded Mode (default)

bd init

Dolt runs in-process — no external server needed. Data lives in .beads/embeddeddolt/. Single-writer only (file locking enforced). This is the recommended mode for most users.

When the git repo has an origin remote, bd init configures a Dolt remote named origin automatically. Cross-machine sync uses bd dolt push and bd dolt pull against refs/dolt/data; .beads/issues.jsonl is an export for viewers, interchange, and backup, not the source of truth.

Server Mode

bd init --server

Connects to an external dolt sql-server. Data lives in .beads/dolt/. Supports multiple concurrent writers. Configure the connection with flags or environment variables:

Flag	Env Var	Default
`--server-host`	`BEADS_DOLT_SERVER_HOST`	`127.0.0.1`
`--server-port`	`BEADS_DOLT_SERVER_PORT`	`3307`
`--server-socket`	`BEADS_DOLT_SERVER_SOCKET`	(none; uses TCP)
`--server-user`	`BEADS_DOLT_SERVER_USER`	`root`
	`BEADS_DOLT_PASSWORD`	(none)

Unix domain sockets: Use --server-socket to connect via a Unix socket instead of TCP. This avoids port conflicts between concurrent projects and is useful in sandboxed environments (e.g., Claude Code) where file-level access control is simpler than network allowlists. The Dolt server must be started with dolt sql-server --socket <path>. Auto-start is not supported in socket mode.

Backup & Migration

Back up your database and migrate between modes using bd backup:

# Set up a backup destination and push
bd backup init /path/to/backup
bd backup sync

# Restore into a new project (any mode)
bd init           # or bd init --server
bd backup restore --force /path/to/backup

See docs/DOLT.md for full migration instructions.

🌐 Community Tools

See docs/COMMUNITY_TOOLS.md for a curated list of community-built UIs, extensions, and integrations—including terminal interfaces, web UIs, editor extensions, and native apps.

🚀 Git-Free Usage

Beads works without git. The Dolt database is the storage backend — git integration (hooks, repo discovery, identity) is optional.

# Initialize without git
export BEADS_DIR=/path/to/your/project/.beads
bd init --quiet --stealth

# All core commands work with zero git calls
bd create "Fix auth bug" -p 1 -t bug
bd ready --json
bd update bd-a1b2 --claim
bd prime
bd close bd-a1b2 "Fixed"

BEADS_DIR tells bd where to put the .beads/ database directory, bypassing git repo discovery. --stealth sets no-git-ops: true in config, disabling all git hook installation and git operations.

This is useful for:

Non-git VCS (Sapling, Jujutsu, Piper) — no .git/ directory needed
Monorepos — point BEADS_DIR at a specific subdirectory
CI/CD — isolated task tracking without repo-level side effects
Evaluation/testing — ephemeral databases in /tmp

For daemon mode without git, use bd daemon start --local (see PR #433).

📝 Documentation

Documentation site (versioned) | Installing | Sync Concepts | Agent Workflow | Copilot CLI Setup | Copilot VS Code MCP | Articles | Sync Branch Mode | Troubleshooting | FAQ

GitHub Go Monthly Trending

QuantumNous/new-api

New API

📝 Project Description

🤝 Trusted Partners

🙏 Special Thanks

🚀 Quick Start

Using Docker Compose (Recommended)

📚 Documentation

📖 Official Documentation |

✨ Key Features

🎨 Core Functions

💰 Authorized Usage Accounting and Billing

🔐 Authorization and Security

🚀 Advanced Features

🤖 Model Support

📡 Supported Interfaces

🚢 Deployment

📋 Deployment Requirements

⚙️ Environment Variable Configuration

🔧 Deployment Methods

⚠️ Multi-machine Deployment Considerations

🔄 Channel Retry and Cache

🔗 Related Projects

Upstream Projects

Supporting Tools

💬 Help Support

📖 Documentation Resources

🤝 Contribution Guide

📜 License

🌟 Star History

💖 Thank you for using New API

google/osv-scanner

Underlying database

Basic installation

Key Features

Scanning a source directory

Supported Lockfiles

Container Scanning

License Scanning

Offline Scanning

Guided Remediation (Experimental)

Example (for npm)

Interactive mode (for npm)

Data Sources and Privacy

OSV.dev API

deps.dev API

Package Registries

Contribute

Report Problems

Contributing code to osv-scanner

Star History

Wei-Shaw/sub2api

Sub2API

Demo

Overview

Features

❤️ Sponsors

Ecosystem

Tech Stack

Nginx Reverse Proxy Note

Deployment

Method 1: Script Installation (Recommended)

Prerequisites

Installation Steps

Post-Installation

Upgrade

Useful Commands

Method 2: Docker Compose (Recommended)

Prerequisites

Quick Start (One-Click Deployment)

Manual Deployment

Deployment Versions

Access

Upgrade

Easy Migration (Local Directory Version)

Useful Commands

Method 3: Build from Source

Prerequisites

Build Steps

Contributing code to `osv-scanner`