GitHub Go Weekly Trending

steipete/wacli

WhatsApp CLI

🗃️ wacli — WhatsApp CLI: sync, search, send.

WhatsApp CLI built on top of whatsmeow, focused on:

Best-effort local sync of message history + continuous capture
Fast offline search
Sending messages
Contact + group management

This is a third-party tool that uses the WhatsApp Web protocol via whatsmeow and is not affiliated with WhatsApp.

Status

Core implementation is in place. See docs/spec.md for the full design notes.

Recent updates (0.2.0)

Messages: search/list includes display text for reactions, replies, and media types.
Send: wacli send file --filename to override the display name.
Auth: optional WACLI_DEVICE_LABEL / WACLI_DEVICE_PLATFORM env overrides.

Install / Build

Choose one of the following options.
If you install via Homebrew, you can skip the local build step.

Option A: Install via Homebrew (tap)

brew install steipete/tap/wacli

Option B: Build locally

go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli

Run (local build only):

./dist/wacli --help

Quick start

Default store directory is ~/.wacli (override with --store DIR).

# 1) Authenticate (shows QR), then bootstrap sync
pnpm wacli auth
# or: ./dist/wacli auth (after pnpm build)

# 2) Keep syncing (never shows QR; requires prior auth)
pnpm wacli sync --follow

# Diagnostics
pnpm wacli doctor

# Search messages
pnpm wacli messages search "meeting"

# Backfill older messages for a chat (best-effort; requires your primary device online)
pnpm wacli history backfill --chat 1234567890@s.whatsapp.net --requests 10 --count 50

# Download media for a message (after syncing)
./wacli media download --chat 1234567890@s.whatsapp.net --id <message-id>

# Send a message
pnpm wacli send text --to 1234567890 --message "hello"

# Send a file
./wacli send file --to 1234567890 --file ./pic.jpg --caption "hi"
# Or override display name
./wacli send file --to 1234567890 --file /tmp/abc123 --filename report.pdf

# List groups and manage participants
pnpm wacli groups list
pnpm wacli groups rename --jid 123456789@g.us --name "New name"

Prior Art / Credit

This project is heavily inspired by (and learns from) the excellent whatsapp-cli by Vicente Reig:

whatsapp-cli

High-level UX

wacli auth: interactive login (shows QR code), then immediately performs initial data sync.
wacli sync: non-interactive sync loop (never shows QR; errors if not authenticated).
Output is human-readable by default; pass --json for machine-readable output.

Storage

Defaults to ~/.wacli (override with --store DIR).

Environment overrides

WACLI_DEVICE_LABEL: set the linked device label (shown in WhatsApp).
WACLI_DEVICE_PLATFORM: override the linked device platform (defaults to CHROME if unset or invalid).

Backfilling older history

wacli sync stores whatever WhatsApp Web sends opportunistically. To try to fetch older messages, use on-demand history sync requests to your primary device (your phone).

Important notes:

This is best-effort: WhatsApp may not return full history.
Your primary device must be online.
Requests are per chat (DM or group). wacli uses the oldest locally stored message in that chat as the anchor.
Recommended --count is 50 per request.

Backfill one chat

pnpm wacli history backfill --chat 1234567890@s.whatsapp.net --requests 10 --count 50

Backfill all chats (script)

This loops through chats already known in your local DB:

pnpm -s wacli -- --json chats list --limit 100000 \
  | jq -r '.[].JID' \
  | while read -r jid; do
      pnpm -s wacli -- history backfill --chat "$jid" --requests 3 --count 50
    done

License

See LICENSE.

Maintainers

Created by @steipete
Currently maintained by @dinakars777

googleapis/mcp-toolbox

MCP Toolbox for Databases is an open source MCP server for databases.

MCP Toolbox for Databases

MCP Toolbox for Databases is an open source Model Context Protocol (MCP) server that connects your AI agents, IDEs, and applications directly to your enterprise databases.

It serves a dual purpose:

Ready-to-use MCP Server (Build-Time): Instantly connect Gemini CLI, Google Antigravity, Claude Code, Codex, or other MCP clients to your databases using our prebuilt generic tools. Talk to your data, explore schemas, and generate code without writing boilerplate.
Custom Tools Framework (Run-Time): A robust framework to build specialized, highly secure AI tools for your production agents. Define structured queries, semantic search, and NL2SQL capabilities safely and easily.

This README provides a brief overview. For comprehensive details, see the full documentation.

Important

Repository Name Update: The genai-toolbox repository has been officially renamed to mcp-toolbox. To ensure your local environment reflects the new name, you may update your remote: git remote set-url origin https://github.com/googleapis/mcp-toolbox.git

Note

This solution was originally named “Gen AI Toolbox for Databases” (github.com/googleapis/genai-toolbox) as its initial development predated MCP, but was renamed to align with the MCP compatibility.

Why MCP Toolbox?

Out-of-the-Box Database Access: Prebuilt generic tools for instant data exploration (e.g., list_tables, execute_sql) directly from your IDE or CLI.
Custom Tools Framework: Build production-ready tools with your own predefined logic, ensuring safety through Restricted Access, Structured Queries, and Semantic Search.
Simplified Development: Integrate tools into your Agent Development Kit (ADK), LangChain, LlamaIndex, or custom agents in less than 10 lines of code.
Better Performance: Handles connection pooling, integrated auth (IAM), and end-to-end observability (OpenTelemetry) out of the box.
Enhanced Security: Integrated authentication for more secure access to your data.
End-to-end Observability: Out of the box metrics and tracing with built-in support for OpenTelemetry.

Quick Start: Prebuilt Tools

Stop context-switching and let your AI assistant become a true co-developer. By connecting your IDE to your databases with MCP Toolbox, you can query your data in plain English, automate schema discovery and management, and generate database-aware code.

You can use the Toolbox in any MCP-compatible IDE or client (e.g., Gemini CLI, Google Antigravity, Claude Code, Codex, etc.) by configuring the MCP server.

Prebuilt tools are also conveniently available via the Google Antigravity MCP Store with a simple click-to-install experience.

Add the following to your client's MCP configuration file (usually mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "toolbox-postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres"
      ]
    }
  }
}

Set the appropriate environment variables to connect, see the Prebuilt Tools Reference.

When you run Toolbox with a --prebuilt=<database> flag, you instantly get access to standard tools to interact with that database.

Supported databases currently include:

Google Cloud: AlloyDB, BigQuery, Cloud SQL (PostgreSQL, MySQL, SQL Server), Spanner, Firestore, Knowledge Catalog (formerly known as Dataplex).
Other Databases: PostgreSQL, MySQL, SQL Server, Oracle, MongoDB, Redis, Elasticsearch, CockroachDB, ClickHouse, Couchbase, Neo4j, Snowflake, Trino, and more.

For a full list of available tools and their capabilities across all supported databases, see the Prebuilt Tools Reference.

See the Install & Run the Toolbox server section for different execution methods like Docker or binaries.

Tip

For users looking for a managed solution, Google Cloud MCP Servers provide a managed MCP experience with prebuilt tools; you can learn more about the differences here.

Quick Start: Custom Tools

Toolbox can also be used as a framework for customized tools. The primary way to configure Toolbox is through the tools.yaml file. If you have multiple files, you can tell Toolbox which to load with the --config tools.yaml flag.

You can find more detailed reference documentation to all resource types in the Resources.

Sources

The sources section of your tools.yaml defines what data sources your Toolbox should have access to. Most tools will have at least one source to execute against.

kind: source
name: my-pg-source
type: postgres
host: 127.0.0.1
port: 5432
database: toolbox_db
user: toolbox_user
password: my-password

For more details on configuring different types of sources, see the Sources.

Tools

The tools section of a tools.yaml define the actions an agent can take: what type of tool it is, which source(s) it affects, what parameters it uses, etc.

kind: tool
name: search-hotels-by-name
type: postgres-sql
source: my-pg-source
description: Search for hotels based on name.
parameters:
  - name: name
    type: string
    description: The name of the hotel.
statement: SELECT * FROM hotels WHERE name ILIKE '%' || $1 || '%';

For more details on configuring different types of tools, see the Tools.

Toolsets

The toolsets section of your tools.yaml allows you to define groups of tools that you want to be able to load together. This can be useful for defining different groups based on agent or application.

kind: toolset
name: my_first_toolset
tools:
    - my_first_tool
    - my_second_tool
---
kind: toolset
name: my_second_toolset
tools:
    - my_second_tool
    - my_third_tool

Prompts

The prompts section of a tools.yaml defines prompts that can be used for interactions with LLMs.

kind: prompt
name: code_review
description: "Asks the LLM to analyze code quality and suggest improvements."
messages:
  - content: >
         Please review the following code for quality, correctness,
         and potential improvements: \n\n{{.code}}
arguments:
  - name: "code"
    description: "The code to review"

For more details on configuring prompts, see the Prompts.

Install & Run the Toolbox server

You can run Toolbox directly with a configuration file:

npx @toolbox-sdk/server --config tools.yaml

This runs the latest version of the Toolbox server with your configuration file.

Note

This method is optimized for convenience rather than performance. For a more standard and reliable installation, please use the binary or container image as described in Install & Run the Toolbox server.

Install Toolbox

For the latest version, check the releases page and use the following instructions for your OS and CPU architecture.

Binary

To install Toolbox as a binary:

Linux (AMD64)

To install Toolbox as a binary on Linux (AMD64):

# see releases page for other versions
export VERSION=1.1.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

macOS (Apple Silicon)

To install Toolbox as a binary on macOS (Apple Silicon):

# see releases page for other versions
export VERSION=1.1.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/arm64/toolbox
chmod +x toolbox

macOS (Intel)

To install Toolbox as a binary on macOS (Intel):

# see releases page for other versions
export VERSION=1.1.0
curl -L -o toolbox https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/darwin/amd64/toolbox
chmod +x toolbox

Windows (Command Prompt)

To install Toolbox as a binary on Windows (Command Prompt):

:: see releases page for other versions
set VERSION=1.1.0
curl -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v%VERSION%/windows/amd64/toolbox.exe"

Windows (PowerShell)

To install Toolbox as a binary on Windows (PowerShell):

# see releases page for other versions
$VERSION = "1.1.0"
curl.exe -o toolbox.exe "https://storage.googleapis.com/mcp-toolbox-for-databases/v$VERSION/windows/amd64/toolbox.exe"

Container image

You can also install Toolbox as a container:

# see releases page for other versions
export VERSION=1.1.0
docker pull us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION

Homebrew

To install Toolbox using Homebrew on macOS or Linux:

brew install mcp-toolbox

Compile from source

To install from source, ensure you have the latest version of Go installed, and then run the following command:

go install github.com/googleapis/mcp-toolbox@v1.1.0

Gemini CLI

Check out the [Gemini CLI extensions](https://geminicli.com/extensions/) to install prebuilt tools for specific databases like AlloyDB, BigQuery, and Cloud SQL directly into Gemini CLI.

# Install Gemini CLI
npm install -g @google/gemini-cli
# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/cloud-sql-postgres
# Run Gemini CLI
gemini

Interact with your custom tools using natural language through the Gemini CLI.

# Install the extension
gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

Run Toolbox

Configure a tools.yaml to define your tools, and then execute toolbox to start the server:

Binary

To run Toolbox from binary:

./toolbox --config "tools.yaml"

ⓘ Note
Toolbox enables dynamic reloading by default. To disable, use the --disable-reload flag.

Container image

To run the server after pulling the container image:

export VERSION=0.24.0 # Use the version you pulled
docker run -p 5000:5000 \
-v $(pwd)/tools.yaml:/app/tools.yaml \
us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:$VERSION \
--config "/app/tools.yaml"

ⓘ Note
The -v flag mounts your local tools.yaml into the container, and -p maps the container's port 5000 to your host's port 5000.

Source

To run the server directly from source, navigate to the project root directory and run:

go run .

ⓘ Note
This command runs the project from source, and is more suitable for development and testing. It does not compile a binary into your $GOPATH. If you want to compile a binary instead, refer the Developer Documentation.

Homebrew

If you installed Toolbox using Homebrew, the toolbox binary is available in your system path. You can start the server with the same command:

toolbox --config "tools.yaml"

NPM

To run Toolbox directly without manually downloading the binary (requires Node.js):

npx @toolbox-sdk/server --config tools.yaml

Gemini CLI

After installing a [Gemini CLI extensions](https://geminicli.com/extensions/), the prebuilt tools will be available during use.

# Run Gemini CLI
gemini

# List extensions
/exttensions list
# List MCP servers
/mcp list

You can use toolbox help for a full list of flags! To stop the server, send a terminate signal (ctrl+c on most platforms).

For more detailed documentation on deploying to different environments, check out the resources in the Deploy Toolbox section

Connect to Toolbox

Once your Toolbox server is up and running, you can load tools into your MCP-compatible client or application.

MCP Client

Add the following configuration to your MCP client configuration:

{
  "mcpServers": {
    "toolbox": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
    }
  }
}

If you would like to connect to a specific toolset, replace url with "http://127.0.0.1:5000/mcp/{toolset_name}".

Toolbox SDKs: Integrate with your Application

Toolbox Client SDKs provide the easy-to-use building blocks and advanced features for connecting your custom applications to the MCP Toolbox server. See below the list of Client SDKs for using various frameworks:

Python (Github)

Core
Install Toolbox Core SDK:
pip install toolbox-core
Load tools:
from toolbox_core import ToolboxClient

# update the url to point to your server
async with ToolboxClient("http://127.0.0.1:5000") as client:

    # these tools can be passed to your application!
    tools = await client.load_toolset("toolset_name")
For more detailed instructions on using the Toolbox Core SDK, see the project's README.
LangChain / LangGraph
Install Toolbox LangChain SDK:
pip install toolbox-langchain
Load tools:
from toolbox_langchain import ToolboxClient

# update the url to point to your server
async with ToolboxClient("http://127.0.0.1:5000") as client:

    # these tools can be passed to your application!
    tools = client.load_toolset()
For more detailed instructions on using the Toolbox LangChain SDK, see the project's README.
LlamaIndex
Install Toolbox Llamaindex SDK:
pip install toolbox-llamaindex
Load tools:
from toolbox_llamaindex import ToolboxClient

# update the url to point to your server
async with ToolboxClient("http://127.0.0.1:5000") as client:

    # these tools can be passed to your application!
    tools = client.load_toolset()
For more detailed instructions on using the Toolbox Llamaindex SDK, see the project's README.

Javascript/Typescript (Github)

Core

Install Toolbox Core SDK:
```
npm install @toolbox-sdk/core
```

Load tools:

import { ToolboxClient } from '@toolbox-sdk/core';

// update the url to point to your server
const URL = 'http://127.0.0.1:5000';
let client = new ToolboxClient(URL);

// these tools can be passed to your application!
const tools = await client.loadToolset('toolsetName');

For more detailed instructions on using the Toolbox Core SDK, see the project's README.

LangChain / LangGraph

Install Toolbox Core SDK:
```
npm install @toolbox-sdk/core
```

Load tools:

import { ToolboxClient } from '@toolbox-sdk/core';

// update the url to point to your server
const URL = 'http://127.0.0.1:5000';
let client = new ToolboxClient(URL);

// these tools can be passed to your application!
const toolboxTools = await client.loadToolset('toolsetName');

// Define the basics of the tool: name, description, schema and core logic
const getTool = (toolboxTool) => tool(currTool, {
    name: toolboxTool.getName(),
    description: toolboxTool.getDescription(),
    schema: toolboxTool.getParamSchema()
});

// Use these tools in your Langchain/Langraph applications
const tools = toolboxTools.map(getTool);

Genkit

Install Toolbox Core SDK:
```
npm install @toolbox-sdk/core
```

Load tools:

import { ToolboxClient } from '@toolbox-sdk/core';
import { genkit } from 'genkit';

// Initialise genkit
const ai = genkit({
    plugins: [
        googleAI({
            apiKey: process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY
        })
    ],
    model: googleAI.model('gemini-2.0-flash'),
});

// update the url to point to your server
const URL = 'http://127.0.0.1:5000';
let client = new ToolboxClient(URL);

// these tools can be passed to your application!
const toolboxTools = await client.loadToolset('toolsetName');

// Define the basics of the tool: name, description, schema and core logic
const getTool = (toolboxTool) => ai.defineTool({
    name: toolboxTool.getName(),
    description: toolboxTool.getDescription(),
    schema: toolboxTool.getParamSchema()
}, toolboxTool)

// Use these tools in your Genkit applications
const tools = toolboxTools.map(getTool);

ADK

Install Toolbox ADK SDK:
```
npm install @toolbox-sdk/adk
```

Load tools:

import { ToolboxClient } from '@toolbox-sdk/adk';

// update the url to point to your server
const URL = 'http://127.0.0.1:5000';
let client = new ToolboxClient(URL);

// these tools can be passed to your application!
const tools = await client.loadToolset('toolsetName');

For more detailed instructions on using the Toolbox ADK SDK, see the project's README.

Go (Github)

Core

Install Toolbox Go SDK:

go get github.com/googleapis/mcp-toolbox-sdk-go

Load tools:

package main

import (
  "github.com/googleapis/mcp-toolbox-sdk-go/core"
  "context"
)

func main() {
  // Make sure to add the error checks
  // update the url to point to your server
  URL := "http://127.0.0.1:5000";
  ctx := context.Background()

  client, err := core.NewToolboxClient(URL)

  // Framework agnostic tools
  tools, err := client.LoadToolset("toolsetName", ctx)
}

For more detailed instructions on using the Toolbox Go SDK, see the project's README.

LangChain Go

Install Toolbox Go SDK:

go get github.com/googleapis/mcp-toolbox-sdk-go

Load tools:

package main

import (
  "context"
  "encoding/json"

  "github.com/googleapis/mcp-toolbox-sdk-go/core"
  "github.com/tmc/langchaingo/llms"
)

func main() {
  // Make sure to add the error checks
  // update the url to point to your server
  URL := "http://127.0.0.1:5000"
  ctx := context.Background()

  client, err := core.NewToolboxClient(URL)

  // Framework agnostic tool
  tool, err := client.LoadTool("toolName", ctx)

  // Fetch the tool's input schema
  inputschema, err := tool.InputSchema()

  var paramsSchema map[string]any
  _ = json.Unmarshal(inputschema, &paramsSchema)

  // Use this tool with LangChainGo
  langChainTool := llms.Tool{
    Type: "function",
    Function: &llms.FunctionDefinition{
      Name:        tool.Name(),
      Description: tool.Description(),
      Parameters:  paramsSchema,
    },
  }
}

Genkit

Install Toolbox Go SDK:

go get github.com/googleapis/mcp-toolbox-sdk-go

Load tools:

package main
import (
  "context"
  "log"

  "github.com/firebase/genkit/go/genkit"
  "github.com/googleapis/mcp-toolbox-sdk-go/core"
  "github.com/googleapis/mcp-toolbox-sdk-go/tbgenkit"
)

func main() {
  // Make sure to add the error checks
  // Update the url to point to your server
  URL := "http://127.0.0.1:5000"
  ctx := context.Background()
  g := genkit.Init(ctx)

  client, err := core.NewToolboxClient(URL)

  // Framework agnostic tool
  tool, err := client.LoadTool("toolName", ctx)

  // Convert the tool using the tbgenkit package
  // Use this tool with Genkit Go
  genkitTool, err := tbgenkit.ToGenkitTool(tool, g)
  if err != nil {
    log.Fatalf("Failed to convert tool: %v\n", err)
  }
  log.Printf("Successfully converted tool: %s", genkitTool.Name())
}

Go GenAI

Install Toolbox Go SDK:

go get github.com/googleapis/mcp-toolbox-sdk-go

Load tools:

package main

import (
  "context"
  "encoding/json"

  "github.com/googleapis/mcp-toolbox-sdk-go/core"
  "google.golang.org/genai"
)

func main() {
  // Make sure to add the error checks
  // Update the url to point to your server
  URL := "http://127.0.0.1:5000"
  ctx := context.Background()

  client, err := core.NewToolboxClient(URL)

  // Framework agnostic tool
  tool, err := client.LoadTool("toolName", ctx)

  // Fetch the tool's input schema
  inputschema, err := tool.InputSchema()

  var schema *genai.Schema
  _ = json.Unmarshal(inputschema, &schema)

  funcDeclaration := &genai.FunctionDeclaration{
    Name:        tool.Name(),
    Description: tool.Description(),
    Parameters:  schema,
  }

  // Use this tool with Go GenAI
  genAITool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{funcDeclaration},
  }
}

OpenAI Go

Install Toolbox Go SDK:

go get github.com/googleapis/mcp-toolbox-sdk-go

Load tools:

package main

import (
  "context"
  "encoding/json"

  "github.com/googleapis/mcp-toolbox-sdk-go/core"
  openai "github.com/openai/openai-go"
)

func main() {
  // Make sure to add the error checks
  // Update the url to point to your server
  URL := "http://127.0.0.1:5000"
  ctx := context.Background()

  client, err := core.NewToolboxClient(URL)

  // Framework agnostic tool
  tool, err := client.LoadTool("toolName", ctx)

  // Fetch the tool's input schema
  inputschema, err := tool.InputSchema()

  var paramsSchema openai.FunctionParameters
  _ = json.Unmarshal(inputschema, &paramsSchema)

  // Use this tool with OpenAI Go
  openAITool := openai.ChatCompletionToolParam{
    Function: openai.FunctionDefinitionParam{
      Name:        tool.Name(),
      Description: openai.String(tool.Description()),
      Parameters:  paramsSchema,
    },
  }

}

ADK Go

Install Toolbox Go SDK:

go get github.com/googleapis/mcp-toolbox-sdk-go

Load tools:

package main

import (
  "github.com/googleapis/mcp-toolbox-sdk-go/tbadk"
  "context"
)

func main() {
  // Make sure to add the error checks
  // Update the url to point to your server
  URL := "http://127.0.0.1:5000"
  ctx := context.Background()
  client, err := tbadk.NewToolboxClient(URL)
  if err != nil {
    return fmt.Sprintln("Could not start Toolbox Client", err)
  }

  // Use this tool with ADK Go
  tool, err := client.LoadTool("toolName", ctx)
  if err != nil {
    return fmt.Sprintln("Could not load Toolbox Tool", err)
  }
}

For more detailed instructions on using the Toolbox Go SDK, see the project's README.

Additional Features

Test tools with the Toolbox UI

To launch Toolbox's interactive UI, use the --ui flag. This allows you to test tools and toolsets with features such as authorized parameters. To learn more, visit Toolbox UI.

./toolbox --ui

Telemetry

Toolbox emits traces and metrics via OpenTelemetry. Use --telemetry-otlp=<endpoint> to export to any OTLP-compatible backend like Google Cloud Monitoring, Agnost AI, or others. See the telemetry docs for details.

Generate Agent Skills

The skills-generate command allows you to convert a toolset into an Agent Skill compatible with the Agent Skill specification. This is useful for distributing tools as portable skill packages.

toolbox --config tools.yaml skills-generate \
  --name "my-skill" \
  --toolset "my_toolset" \
  --description "A skill containing multiple tools"

Once generated, you can install the skill into the Gemini CLI:

gemini skills install ./skills/my-skill

For more details, see the Generate Agent Skills guide.

Versioning

MCP Toolbox for Databases follows Semantic Versioning.

The Public API includes the Toolbox Server (CLI, configuration manifests, and pre-built toolsets) and the Client SDKs.

Major versions are incremented for breaking changes, such as incompatible CLI or manifest changes.
Minor versions are incremented for new features, including modifications to pre-built toolsets or beta features.
Patch versions are incremented for backward-compatible bug fixes.

For more details, see our Full Versioning Policy.

Contributing

Contributions are welcome. Please, see the CONTRIBUTING guide to get started.

For technical details on setting up a environment for developing on Toolbox itself, see the DEVELOPER guide.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms. See Contributor Code of Conduct for more information.

Community

Join our Discord community to connect with our developers!

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 Poixe Ai for sponsoring this project! Poixe AI provides reliable LLM API services. You can leverage the platform's API endpoints to seamlessly build AI-powered products. Additionally, you can become a vendor by providing AI API resources to the platform and earn revenue. Register through the exclusive sub2api referral link and receive a bonus of $5 USD on your first top-up.
	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 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!
	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!
	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)

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

MIT License

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

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 for personal learning purposes only, with no guarantee of stability or technical support
Users must comply with OpenAI's Terms of Use and applicable laws and regulations, and must not use it for illegal purposes
According to the 《Interim Measures for the Management of Generative Artificial Intelligence Services》, please do not provide any unregistered generative AI services to the public in China.

🤝 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!

📖 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

💰 Payment and Billing

✅ Online recharge (EPay, Stripe)
✅ Pay-per-use model pricing
✅ Cache billing support (OpenAI, Azure, DeepSeek, Claude, Qwen and all supported models)
✅ Flexible billing policy configuration

🔐 Authorization and Security

😈 Discord authorization login
🤖 LinuxDO authorization login
📱 Telegram authorization login
🔑 OIDC unified authentication
🔍 Key quota query usage (with neko-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 - Relay 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	Supports complete call address	-

📡 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
neko-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).

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}

mostlygeek/llama-swap

Reliable model swapping for any local OpenAI/Anthropic compatible server - llama.cpp, vllm, etc

llama-swap

Run multiple generative AI models on your machine and hot-swap between them on demand. llama-swap works with any OpenAI and Anthropic API compatible server and is used by thousands of people to power their local AI workflows.

Built in Go for performance and simplicity, llama-swap has zero dependencies and is incredibly easy to set up. Get started in minutes - just one binary and one configuration file.

Features:

✅ Easy to deploy and configure: one binary, one configuration file. no external dependencies
✅ On-demand model switching
✅ Use any local OpenAI compatible server (llama.cpp, vllm, tabbyAPI, stable-diffusion.cpp, etc.)
- future proof, upgrade your inference servers at any time.
✅ OpenAI API supported endpoints:
- v1/completions
- v1/chat/completions
- v1/responses
- v1/embeddings
- v1/audio/speech (#36)
- v1/audio/transcriptions (docs)
- v1/audio/voices
- v1/images/generations
- v1/images/edits
✅ Anthropic API supported endpoints:
- v1/messages
- v1/messages/count_tokens
✅ llama-server (llama.cpp) supported endpoints
- v1/rerank, v1/reranking, /rerank
- /infill - for code infilling
- /completion - for completion endpoint
✅ SDAPI via stable-diffusion.cpp's server
- /sdapi/v1/txt2img
- /sdapi/v1/img2img
- /sdapi/v1/loras - requires model in request body to fetch the correct loras
✅ llama-swap API
- /ui - web UI
- /upstream/:model_id - direct access to upstream server (demo)
- /models/unload - manually unload running models (#58)
- /running - list currently running models (#61)
- /log - remote log monitoring
- /health - just returns "OK"
✅ API Key support - define keys to restrict access to API endpoints
✅ Customizable
- Run concurrent models with a custom DSL swap matrix (#643)
- Automatic unloading of models after timeout by setting a ttl
- Reliable Docker and Podman support using cmd and cmdStop together
- Preload models on startup with hooks (#235)

Web UI

llama-swap includes a real time web interface with a playground for testing out all sorts of local models:

View detailed token metrics:

Inspect request and responses:

Manually load and unload models:

Real time log streaming:

Installation

llama-swap can be installed in multiple ways

Docker
Homebrew (OSX and Linux)
WinGet
From release binaries
From source

Docker Install (download images)

Nightly container images with llama-swap and llama-server are built for multiple platforms (cuda, vulkan, intel, etc.) including non-root variants with improved security. The stable-diffusion.cpp server is also included for the musa and vulkan platforms.

$ docker pull ghcr.io/mostlygeek/llama-swap:cuda

# run with a custom configuration and models directory
$ docker run -it --rm --runtime nvidia -p 9292:8080 \
 -v /path/to/models:/models \
 -v /path/to/custom/config.yaml:/app/config.yaml \
 ghcr.io/mostlygeek/llama-swap:cuda

# configuration hot reload supported with a
# directory volume mount
$ docker run -it --rm --runtime nvidia -p 9292:8080 \
 -v /path/to/models:/models \
 -v /path/to/custom/config.yaml:/app/config.yaml \
 -v /path/to/config:/config \
 ghcr.io/mostlygeek/llama-swap:cuda -config /config/config.yaml -watch-config

more examples

# pull latest images per platform
docker pull ghcr.io/mostlygeek/llama-swap:cpu
docker pull ghcr.io/mostlygeek/llama-swap:cuda
docker pull ghcr.io/mostlygeek/llama-swap:vulkan
docker pull ghcr.io/mostlygeek/llama-swap:intel
docker pull ghcr.io/mostlygeek/llama-swap:musa

# tagged llama-swap, platform and llama-server version images
docker pull ghcr.io/mostlygeek/llama-swap:v166-cuda-b6795

# non-root cuda
docker pull ghcr.io/mostlygeek/llama-swap:cuda-non-root

Homebrew Install (macOS/Linux)

brew tap mostlygeek/llama-swap
brew install llama-swap
llama-swap --config path/to/config.yaml --listen localhost:8080

WinGet Install (Windows)

Note

WinGet is maintained by community contributor Dvd-Znf (#327). It is not an official part of llama-swap.

# install
C:\> winget install llama-swap

# upgrade
C:\> winget upgrade llama-swap

Pre-built Binaries

Binaries are available on the release page for Linux, Mac, Windows and FreeBSD.

Building from source

Building requires Go and Node.js (for UI).
git clone https://github.com/mostlygeek/llama-swap.git
make clean all
look in the build/ subdirectory for the llama-swap binary

Configuration

# minimum viable config.yaml

models:
  model1:
    cmd: llama-server --port ${PORT} --model /path/to/model.gguf

That's all you need to get started:

models - holds all model configurations
model1 - the ID used in API calls
cmd - the command to run to start the server.
${PORT} - an automatically assigned port number

Almost all configuration settings are optional and can be added one step at a time:

Advanced features
- matrix to run concurrent models with a custom swap logic DSL
- hooks to run things on startup
- macros reusable snippets
Model customization
- ttl to automatically unload models
- aliases to use familiar model names (e.g., "gpt-4o-mini")
- env to pass custom environment variables to inference servers
- cmdStop gracefully stop Docker/Podman containers
- useModelName to override model names sent to upstream servers
- ${PORT} automatic port variables for dynamic port assignment
- filters rewrite parts of requests before sending to the upstream server

See the configuration documentation for all options.

How does llama-swap work?

When a request is made to an OpenAI compatible endpoint, llama-swap will extract the model value and load the appropriate server configuration to serve it. If the wrong upstream server is running, it will be replaced with the correct one. This is where the "swap" part comes in. The upstream server is automatically swapped to handle the request correctly.

In the most basic configuration llama-swap handles one model at a time. For more advanced use cases, using a matrix allows multiple models to be loaded at the same time. You have complete control over how your system resources are used.

Reverse Proxy Configuration (nginx)

If you deploy llama-swap behind nginx, disable response buffering for streaming endpoints. By default, nginx buffers responses which breaks Server‑Sent Events (SSE) and streaming chat completion. (#236)

Recommended nginx configuration snippets:

# SSE for UI events/logs
location /api/events {
    proxy_pass http://your-llama-swap-backend;
    proxy_buffering off;
    proxy_cache off;
}

# Streaming chat completions (stream=true)
location /v1/chat/completions {
    proxy_pass http://your-llama-swap-backend;
    proxy_buffering off;
    proxy_cache off;
}

As a safeguard, llama-swap also sets X-Accel-Buffering: no on SSE responses. However, explicitly disabling proxy_buffering at your reverse proxy is still recommended for reliable streaming behavior.

Monitoring Logs on the CLI

# sends up to the last 10KB of logs
$ curl http://host/logs

# streams combined logs
curl -Ns http://host/logs/stream

# stream llama-swap's proxy status logs
curl -Ns http://host/logs/stream/proxy

# stream logs from upstream processes that llama-swap loads
curl -Ns http://host/logs/stream/upstream

# stream logs only from a specific model
curl -Ns http://host/logs/stream/{model_id}

# stream and filter logs with linux pipes
curl -Ns http://host/logs/stream | grep 'eval time'

# appending ?no-history will disable sending buffered history first
curl -Ns 'http://host/logs/stream?no-history'

Do I need to use llama.cpp's server (llama-server)?

Any OpenAI compatible server would work. llama-swap was originally designed for llama-server and it is the best supported.

For Python based inference servers like vllm or tabbyAPI it is recommended to run them via podman or docker. This provides clean environment isolation as well as responding correctly to SIGTERM signals for proper shutdown.

Star History

Note

⭐️ Star this project to help others discover it!

netbirdio/netbird

Connect your devices into a secure WireGuard®-based overlay network with SSO, MFA and granular access controls.

Start using NetBird at netbird.io
See Documentation
Join our Slack channel or our Community forum

🚀 We are hiring! Join us at careers.netbird.io

New: NetBird terraform provider

NetBird combines a configuration-free peer-to-peer private network and a centralized access control system in a single platform, making it easy to create secure private networks for your organization or home.

Connect. NetBird creates a WireGuard-based overlay network that automatically connects your machines over an encrypted tunnel, leaving behind the hassle of opening ports, complex firewall rules, VPN gateways, and so forth.

Secure. NetBird enables secure remote access by applying granular access policies while allowing you to manage them intuitively from a single place. Works universally on any infrastructure.

Open Source Network Security in a Single Platform

https://github.com/user-attachments/assets/10cec749-bb56-4ab3-97af-4e38850108d2

Self-Host NetBird (Video)

Key features

Connectivity	Management	Security	Automation	Platforms
- [x] Kernel WireGuard	- [x] Admin Web UI	- [x] SSO & MFA support	- [x] Public API	- [x] Linux
- [x] Peer-to-peer connections	- [x] Auto peer discovery and configuration	- [x] Access control - groups & rules	- [x] Setup keys for bulk network provisioning	- [x] Mac
- [x] Connection relay fallback	- [x] IdP integrations	- [x] Activity logging	- [x] Self-hosting quickstart script	- [x] Windows
- [x] Routes to external networks	- [x] Private DNS	- [x] Device posture checks	- [x] IdP groups sync with JWT	- [x] Android
- [x] NAT traversal with BPF	- [x] Multiuser support	- [x] Peer-to-peer encryption		- [x] iOS
		- [x] Quantum-resistance with Rosenpass		- [x] OpenWRT
		- [x] Periodic re-authentication		- [x] Serverless
				- [x] Docker

Quickstart with NetBird Cloud

Download and install NetBird at https://app.netbird.io/install
Follow the steps to sign-up with Google, Microsoft, GitHub or your email address.
Check NetBird admin UI.
Add more machines.

Quickstart with self-hosted NetBird

This is the quickest way to try self-hosted NetBird. It should take around 5 minutes to get started if you already have a public domain and a VM. Follow the Advanced guide with a custom identity provider for installations with different IDPs.

Infrastructure requirements:

A Linux VM with at least 1CPU and 2GB of memory.
The VM should be publicly accessible on TCP ports 80 and 443 and UDP port: 3478.
Public domain name pointing to the VM.

Software requirements:

Docker installed on the VM with the docker-compose plugin (Docker installation guide) or docker with docker-compose in version 2 or higher.
jq installed. In most distributions Usually available in the official repositories and can be installed with sudo apt install jq or sudo yum install jq
curl installed. Usually available in the official repositories and can be installed with sudo apt install curl or sudo yum install curl

Steps

Download and run the installation script:

export NETBIRD_DOMAIN=netbird.example.com; curl -fsSL https://github.com/netbirdio/netbird/releases/latest/download/getting-started.sh | bash

Once finished, you can manage the resources via docker-compose

A bit on NetBird internals

Every machine in the network runs NetBird Agent (or Client) that manages WireGuard.
Every agent connects to Management Service that holds network state, manages peer IPs, and distributes network updates to agents (peers).
NetBird agent uses WebRTC ICE implemented in pion/ice library to discover connection candidates when establishing a peer-to-peer connection between machines.
Connection candidates are discovered with the help of STUN servers.
Agents negotiate a connection through Signal Service passing p2p encrypted messages with candidates.
Sometimes the NAT traversal is unsuccessful due to strict NATs (e.g. mobile carrier-grade NAT) and a p2p connection isn't possible. When this occurs the system falls back to a relay server called TURN, and a secure WireGuard tunnel is established via the TURN server.

Coturn is the one that has been successfully used for STUN and TURN in NetBird setups.

See a complete architecture overview for details.

Community projects

NetBird installer script
NetBird ansible collection by Dominion Solutions
netbird-tui — terminal UI for managing NetBird peers, routes, and settings

Note: The main branch may be in an unstable or even broken state during development. For stable versions, see releases.

Support acknowledgement

In November 2022, NetBird joined the StartUpSecure program sponsored by The Federal Ministry of Education and Research of The Federal Republic of Germany. Together with CISPA Helmholtz Center for Information Security NetBird brings the security best practices and simplicity to private networking.

Testimonials

We use open-source technologies like WireGuard®, Pion ICE (WebRTC), Coturn, and Rosenpass. We very much appreciate the work these guys are doing and we'd greatly appreciate if you could support them in any way (e.g., by giving a star or a contribution).

Legal

This repository is licensed under BSD-3-Clause license that applies to all parts of the repository except for the directories management/, signal/ and relay/. Those directories are licensed under the GNU Affero General Public License version 3.0 (AGPLv3). See the respective LICENSE files inside each directory.

WireGuard and the WireGuard logo are registered trademarks of Jason A. Donenfeld.

rapidaai/voice-ai

Rapida is an open-source, end-to-end voice AI orchestration platform for building real-time conversational voice agents with audio streaming, STT, TTS, VAD, multi-channel integration, agent state management, and observability.

Rapida: End-to-End Voice Orchestration Platform

Rapida is an open-source platform for designing, building, and deploying voice agents at scale.
It’s built around three core principles:

Reliable — designed for production workloads, real-time audio, and fault-tolerant execution
Observable — deep visibility into calls, latency, metrics, and tool usage
Customizable — flexible architecture that adapts to any LLM, workflow, or enterprise stack

Rapida provides both a platform and a framework for building real-world voice agents—from low-latency audio streaming to orchestration, monitoring, and integrations.

Rapida is written in Go, using the highly optimized gRPC protocol for fast, efficient, bidirectional communication.

Architecture

Features

Real-time Voice Orchestration
Stream and process audio with low latency using GRPC.
LLM-Agnostic Architecture
Bring your own model—OpenAI, Anthropic, open-source models, or custom inference.
Production-grade Reliability
Built-in retries, error handling, call lifecycle management, and health checks.
Full Observability
Call logs, streaming events, tool traces, latency breakdowns, metrics, and dashboards.
Flexible Tooling System
Build custom tools and actions for your agents, or integrate with any backend.
Developer-friendly
Clear APIs, modular components, and simple configuration.
Enterprise-ready
Scalable design, efficient protocol, and predictable performance.

Documentation & Guides

https://doc.rapida.ai

Prerequisites

Docker & Docker Compose (Install)
16GB+ RAM (for all services)

Quick Start

Get all services running in 4 commands:

# Clone repo
git clone https://github.com/rapidaai/voice-ai.git && cd voice-ai

# Setup & build
make setup-local && make build-all

# Start all services
make up-all

# View running services
docker compose ps

Services Ready (make up-all):

UI: http://localhost:3000
API Gateway (nginx): http://localhost:8080
Web API: internal-only by default (container network)
Assistant API: http://localhost:9007
Endpoint API: http://localhost:9005
Integration API: http://localhost:9004

To include knowledge services (OpenSearch + Document API), run:

make up-all-with-knowledge

Then:

Document API: http://localhost:9010

Stop services:

make down-all

Development

Work on Specific Services

# Start only database
make up-db

# Start only UI
make up-ui

# Start only Assistant API
make up-assistant

# List all start commands
make help

View Logs

# All services
make logs-all

# Specific service
make logs-web
make logs-assistant

Rebuild After Code Changes

# Rebuild and restart one service
make rebuild-assistant

# Rebuild all
make rebuild-all

Configure Services

Edit environment files before starting:

docker/web-api/.web.env - Web API (port 9001)
docker/assistant-api/.assistant.env - Assistant API (port 9007)
docker/endpoint-api/.endpoint.env - Endpoint API (port 9005)
docker/integration-api/.integration.env - Integration API (port 9004)
docker/document-api/config.yaml - Document API (port 9010)

Add your API keys (OpenAI, Anthropic, Deepgram, Twilio, etc.) in these files.

Local Development (Without Docker)

Go Services

# Install dependencies
go mod download

# Build service
go build -o bin/web ./cmd/web

# Run service
./bin/web

Requires PostgreSQL, Redis, OpenSearch running separately.

React UI

cd ui

# Install & run
yarn install
yarn start:dev

# Build for production
yarn build

Troubleshooting

Port already in use:

lsof -i :3000    # Find process
kill -9 <PID>    # Kill it

Services won't start:

make logs-all    # Check logs
docker compose ps  # Verify status

Database issues:

# Test connection
docker compose exec postgres psql -U rapida -d web_db -c "SELECT 1"

# Reset everything
make clean
make setup-local
make build-all
make up-all

All Commands

make help          # Show all available commands
make setup-local   # Create data directories
make build-all     # Build all Docker images
make up-all        # Start all services
make down-all      # Stop all services
make logs-all      # View all logs
make clean         # Remove containers & volumes
make restart-all   # Restart all services

Contributing

See CONTRIBUTING.md for guidelines.

Want to add:

New STT/TTS provider? Check api/assistant-api/internal/transformer/
New telephony channel? Check api/assistant-api/internal/telephony/

SDKs & Tools

Client SDKs

Client SDKs enable your frontend to include interactive, multi-user experiences.

Language	Repo	Docs
Web (React)	rapida-react	docs
Web Widget (react)	react-widget

Server SDKs

Server SDKs enable your backend to build and manage agents.

Language	Repo	Docs
Go	rapida-go	docs
Python	rapida-python	docs

Contributing

For those who'd like to contribute code, see our Contribution Guide. At the same time, please consider supporting RapidaAi by sharing it on social media and at events and conferences.

Security disclosure

To protect your privacy, please avoid posting security issues on GitHub. Instead, report issues to contact@rapida.ai, and our team will respond with detailed answer.

License

Rapida is open-source under the GPL-2.0 license, with additional conditions:

Open-source users must keep the Rapida logo visible in UI components.
Future license terms may change; this does not affect released versions.

A commercial license is available for enterprise use, which allows:

Removal of branding
Closed-source usage
Private modifications Contact sales@rapida.ai for details.

anthropics/anthropic-cli

The CLI for the Claude API

Claude Platform CLI

The official CLI for the Claude Developer Platform.

Installation

Installing with Homebrew

brew install anthropics/tap/ant

Installing with Go

To test or install the CLI locally, you need Go version 1.22 or later installed.

go install 'github.com/anthropics/anthropic-cli/cmd/ant@latest'

Once you have run go install, the binary is placed in your Go bin directory:

Default location: $HOME/go/bin (or $GOPATH/bin if GOPATH is set)
Check your path: Run go env GOPATH to see the base directory

If commands aren't found after installation, add the Go bin directory to your PATH:

# Add to your shell profile (.zshrc, .bashrc, etc.)
export PATH="$PATH:$(go env GOPATH)/bin"

Running Locally

After cloning the git repository for this project, you can use the scripts/run script to run the tool locally:

./scripts/run args...

Usage

The CLI follows a resource-based command structure:

ant [resource] <command> [flags...]

ant messages create \
  --api-key my-anthropic-api-key \
  --max-tokens 1024 \
  --message '{content: [{text: x, type: text}], role: user}' \
  --model claude-sonnet-4-5-20250929

For details about specific commands, use the --help flag.

Environment variables

Environment variable	Required	Default value
`ANTHROPIC_API_KEY`	no	`null`
`ANTHROPIC_AUTH_TOKEN`	no	`null`

Global flags

--api-key (can also be set with ANTHROPIC_API_KEY env var)
--auth-token (can also be set with ANTHROPIC_AUTH_TOKEN env var)
--help - Show command line usage
--debug - Enable debug logging (includes HTTP request/response details)
--version, -v - Show the CLI version
--base-url - Use a custom API backend URL
--format - Change the output format (auto, explore, json, jsonl, pretty, raw, yaml)
--format-error - Change the output format for errors (auto, explore, json, jsonl, pretty, raw, yaml)
--transform - Transform the data output using GJSON syntax
--transform-error - Transform the error output using GJSON syntax

Passing files as arguments

To pass files to your API, you can use the @myfile.ext syntax:

ant <command> --arg @abe.jpg

Files can also be passed inside JSON or YAML blobs:

ant <command> --arg '{image: "@abe.jpg"}'
# Equivalent:
ant <command> <<YAML
arg:
  image: "@abe.jpg"
YAML

If you need to pass a string literal that begins with an @ sign, you can escape the @ sign to avoid accidentally passing a file.

ant <command> --username '\@abe'

Explicit encoding

For JSON endpoints, the CLI tool does filetype sniffing to determine whether the file contents should be sent as a string literal (for plain text files) or as a base64-encoded string literal (for binary files). If you need to explicitly send the file as either plain text or base64-encoded data, you can use @file://myfile.txt (for string encoding) or @data://myfile.dat (for base64-encoding). Note that absolute paths will begin with @file:// or @data://, followed by a third / (for example, @file:///tmp/file.txt).

ant <command> --arg @data://file.txt

Linking different Go SDK versions

You can link the CLI against a different version of the Anthropic Go SDK for development purposes using the ./scripts/link script.

To link to a specific version from a repository (version can be a branch, git tag, or commit hash):

./scripts/link github.com/org/repo@version

To link to a local copy of the SDK:

./scripts/link ../path/to/anthropic-go

If you run the link script without any arguments, it will default to ../anthropic-go.

NoFxAiOS/nofx

Your personal AI trading assistant. Any market. Any model. Pay with USDC, not API keys.

NOFX

Your personal AI trading assistant.
Any market. Any model. Pay with USDC, not API keys.

English · 中文 · 日本語 · 한국어 · Русский · Українська · Tiếng Việt

NOFX is an open-source autonomous AI trading assistant. Unlike traditional AI tools that require you to manually configure models, manage API keys, and wire up data sources — NOFX's AI perceives markets, selects models, and fetches data entirely on its own. Zero human intervention. You set the strategy, the AI handles everything else.

Fully autonomous: The AI decides which model to use, what market data to pull, when to trade — all by itself. No manual model configuration. No juggling API keys for different services. Just fund a USDC wallet and let it run.

What makes it different: built-in x402 micropayments. No API keys. Fund a USDC wallet and pay per request. Your wallet is your identity.

curl -fsSL https://raw.githubusercontent.com/NoFxAiOS/nofx/main/install.sh | bash

Open http://127.0.0.1:3000. Done.

How x402 Works

Traditional flow: register account → buy credits → get API key → manage quota → rotate keys.

x402 flow:

Request → 402 (here's the price) → wallet signs USDC → retry → done

No accounts. No API keys. No prepaid credits. One wallet, every model.

Built-in x402 Providers

Provider	Chain	Models
Claw402	Base	GPT-5.4, Claude Opus, DeepSeek, Qwen, Grok, Gemini, Kimi — 15+ models

What It Does

Feature	Description
Multi-AI	DeepSeek, Qwen, GPT, Claude, Gemini, Grok, Kimi, MiniMax — switch anytime
Multi-Exchange	Binance, Bybit, OKX, Bitget, KuCoin, Gate, Hyperliquid, Aster, Lighter
Strategy Studio	Visual builder — coin sources, indicators, risk controls
AI Competition	AIs compete in real-time, leaderboard ranks performance
Telegram Agent	Chat with your trading assistant — streaming, tool calling, memory
Dashboard	Live positions, P/L, AI decision logs with Chain of Thought

Markets

Crypto · US Stocks · Forex · Metals

Exchanges (CEX)

Exchange	Status	Register (Fee Discount)
Binance	✅	Register
Bybit	✅	Register
OKX	✅	Register
Bitget	✅	Register
KuCoin	✅	Register
Gate	✅	Register

Exchanges (Perp-DEX)

Exchange	Status	Register (Fee Discount)
Hyperliquid	✅	Register
Aster DEX	✅	Register
Lighter	✅	Register

AI Models (API Key Mode)

AI Model	Status	Get API Key
DeepSeek	✅	Get API Key
Qwen	✅	Get API Key
OpenAI (GPT)	✅	Get API Key
Claude	✅	Get API Key
Gemini	✅	Get API Key
Grok	✅	Get API Key
Kimi	✅	Get API Key
MiniMax	✅	Get API Key

AI Models (x402 Mode — No API Key)

15+ models via Claw402 — just a USDC wallet

Screenshots

Config Page

AI Models & Exchanges	Traders List

Dashboard

Overview	Market Chart

Trading Stats	Position History

Positions	Trader Details

Strategy Studio

Strategy Editor	Indicators Config

Competition

Competition Mode

Install

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/NoFxAiOS/nofx/main/install.sh | bash

Railway (Cloud)

Docker

curl -O https://raw.githubusercontent.com/NoFxAiOS/nofx/main/docker-compose.prod.yml
docker compose -f docker-compose.prod.yml up -d

Windows

Install Docker Desktop, then:

curl -o docker-compose.prod.yml https://raw.githubusercontent.com/NoFxAiOS/nofx/main/docker-compose.prod.yml
docker compose -f docker-compose.prod.yml up -d

From Source

# Prerequisites: Go 1.21+, Node.js 18+, TA-Lib
# macOS: brew install ta-lib
# Ubuntu: sudo apt-get install libta-lib0-dev

git clone https://github.com/NoFxAiOS/nofx.git && cd nofx
go build -o nofx && ./nofx          # backend
cd web && npm install && npm run dev  # frontend (new terminal)

Update

curl -fsSL https://raw.githubusercontent.com/NoFxAiOS/nofx/main/install.sh | bash

Setup

Beginner mode: First-time users get a guided onboarding flow — select beginner mode at registration and the system walks you through AI, exchange, and strategy setup step by step.

Advanced mode:

AI — Add API keys or configure x402 wallet
Exchange — Connect exchange API credentials
Strategy — Build in Strategy Studio
Trader — Combine AI + Exchange + Strategy
Trade — Launch from the dashboard

Everything through the web UI at http://127.0.0.1:3000.

Deploy to Server

HTTP (quick):

curl -fsSL https://raw.githubusercontent.com/NoFxAiOS/nofx/main/install.sh | bash
# Access via http://YOUR_IP:3000

HTTPS (Cloudflare):

Add domain to Cloudflare (free plan)
A record → your server IP (Proxied)
SSL/TLS → Flexible
Set TRANSPORT_ENCRYPTION=true in .env

Architecture

                              NOFX
    ┌─────────────────────────────────────────────────┐
    │                 Web Dashboard                     │
    │           React + TypeScript + TradingView        │
    ├─────────────────────────────────────────────────┤
    │                  API Server (Go)                  │
    ├──────────┬──────────┬──────────┬────────────────┤
    │  Strategy  │      Telegram       │
    │   Engine   │       Agent         │
    ├──────────┴──────────┴──────────┴────────────────┤
    │               MCP AI Client Layer                │
    │    ┌───────────┐  ┌───────────┐  ┌───────────┐  │
    │    │  API Key   │  │   x402    │  │           │  │
    │    │ DeepSeek   │  │ Claw402   │  │           │  │
    │    │ GPT,Claude │  │           │  │           │  │
    │    └───────────┘  └───────────┘  └───────────┘  │
    ├─────────────────────────────────────────────────┤
    │             Exchange Connectors                   │
    │  Binance · Bybit · OKX · Bitget · KuCoin · Gate  │
    │      Hyperliquid · Aster DEX · Lighter            │
    └─────────────────────────────────────────────────┘

Docs


Architecture	System design and module index
Strategy Module	Coin selection, AI prompts, execution
FAQ	Common questions
Getting Started	Deployment guide

Contributing

See Contributing Guide · Code of Conduct · Security Policy

Contributor Airdrop Program

All contributions are tracked. When NOFX generates revenue, contributors receive airdrops.

Pinned Issues get the highest rewards.

Contribution	Weight
Pinned Issue PRs	★★★★★★
Code (Merged PRs)	★★★★★
Bug Fixes	★★★★
Feature Ideas	★★★
Bug Reports	★★
Documentation	★★

Links


Website	nofxai.com
Dashboard	nofxos.ai/dashboard
API Docs	nofxos.ai/api-docs
Telegram	nofx_dev_community
Twitter	@nofx_official

Risk Warning: AI auto-trading carries significant risks. Recommended for learning/research or small amounts only.

License

AGPL-3.0

ollama/ollama

Get up and running with Kimi-K2.5, GLM-5, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.

Ollama

Start building with open models.

Download

macOS

curl -fsSL https://ollama.com/install.sh | sh

or download manually

Windows

irm https://ollama.com/install.ps1 | iex

or download manually

Linux

curl -fsSL https://ollama.com/install.sh | sh

Manual install instructions

Docker

The official Ollama Docker image ollama/ollama is available on Docker Hub.

Libraries

Community

Get started

ollama

You'll be prompted to run a model or connect Ollama to your existing agents or applications such as Claude Code, OpenClaw, OpenCode , Codex, Copilot, and more.

Coding

To launch a specific integration:

ollama launch claude

Supported integrations include Claude Code, Codex, Copilot CLI, Droid, and OpenCode.

AI assistant

Use OpenClaw to turn Ollama into a personal AI assistant across WhatsApp, Telegram, Slack, Discord, and more:

ollama launch openclaw

Chat with a model

Run and chat with Gemma 3:

ollama run gemma3

See ollama.com/library for the full list.

See the quickstart guide for more details.

REST API

Ollama has a REST API for running and managing models.

curl http://localhost:11434/api/chat -d '{
  "model": "gemma3",
  "messages": [{
    "role": "user",
    "content": "Why is the sky blue?"
  }],
  "stream": false
}'

See the API documentation for all endpoints.

Python

pip install ollama

from ollama import chat

response = chat(model='gemma3', messages=[
  {
    'role': 'user',
    'content': 'Why is the sky blue?',
  },
])
print(response.message.content)

JavaScript

npm i ollama

import ollama from "ollama";

const response = await ollama.chat({
  model: "gemma3",
  messages: [{ role: "user", content: "Why is the sky blue?" }],
});
console.log(response.message.content);

Supported backends

llama.cpp project founded by Georgi Gerganov.

Documentation

Community Integrations

Want to add your project? Open a pull request.

Chat Interfaces

Web

Open WebUI - Extensible, self-hosted AI interface
Onyx - Connected AI workspace
LibreChat - Enhanced ChatGPT clone with multi-provider support
Lobe Chat - Modern chat framework with plugin ecosystem (docs)
NextChat - Cross-platform ChatGPT UI (docs)
Perplexica - AI-powered search engine, open-source Perplexity alternative
big-AGI - AI suite for professionals
Lollms WebUI - Multi-model web interface
ChatOllama - Chatbot with knowledge bases
Bionic GPT - On-premise AI platform
Chatbot UI - ChatGPT-style web interface
Hollama - Minimal web interface
Chatbox - Desktop and web AI client
chat - Chat web app for teams
Ollama RAG Chatbot - Chat with multiple PDFs using RAG
Tkinter-based client - Python desktop client

Desktop

Dify.AI - LLM app development platform
AnythingLLM - All-in-one AI app for Mac, Windows, and Linux
Maid - Cross-platform mobile and desktop client
Witsy - AI desktop app for Mac, Windows, and Linux
Cherry Studio - Multi-provider desktop client
Ollama App - Multi-platform client for desktop and mobile
PyGPT - AI desktop assistant for Linux, Windows, and Mac
Alpaca - GTK4 client for Linux and macOS
SwiftChat - Cross-platform including iOS, Android, and Apple Vision Pro
Enchanted - Native macOS and iOS client
RWKV-Runner - Multi-model desktop runner
Ollama Grid Search - Evaluate and compare models
macai - macOS client for Ollama and ChatGPT
AI Studio - Multi-provider desktop IDE
Reins - Parameter tuning and reasoning model support
ConfiChat - Privacy-focused with optional encryption
LLocal.in - Electron desktop client
MindMac - AI chat client for Mac
Msty - Multi-model desktop client
BoltAI for Mac - AI chat client for Mac
IntelliBar - AI-powered assistant for macOS
Kerlig AI - AI writing assistant for macOS
Hillnote - Markdown-first AI workspace
Perfect Memory AI - Productivity AI personalized by screen and meeting history

Mobile

Ollama Android Chat - One-click Ollama on Android

SwiftChat, Enchanted, Maid, Ollama App, Reins, and ConfiChat listed above also support mobile platforms.

Code Editors & Development

Cline - VS Code extension for multi-file/whole-repo coding
Continue - Open-source AI code assistant for any IDE
Void - Open source AI code editor, Cursor alternative
Copilot for Obsidian - AI assistant for Obsidian
twinny - Copilot and Copilot chat alternative
gptel Emacs client - LLM client for Emacs
Ollama Copilot - Use Ollama as GitHub Copilot
Obsidian Local GPT - Local AI for Obsidian
Ellama Emacs client - LLM tool for Emacs
orbiton - Config-free text editor with Ollama tab completion
AI ST Completion - Sublime Text 4 AI assistant
VT Code - Rust-based terminal coding agent with Tree-sitter
QodeAssist - AI coding assistant for Qt Creator
AI Toolkit for VS Code - Microsoft-official VS Code extension
Open Interpreter - Natural language interface for computers

Libraries & SDKs

LiteLLM - Unified API for 100+ LLM providers
Semantic Kernel - Microsoft AI orchestration SDK
LangChain4j - Java LangChain (example)
LangChainGo - Go LangChain (example)
Spring AI - Spring framework AI support (docs)
LangChain and LangChain.js with example
Ollama for Ruby - Ruby LLM library
any-llm - Unified LLM interface by Mozilla
OllamaSharp for .NET - .NET SDK
LangChainRust - Rust LangChain (example)
Agents-Flex for Java - Java agent framework (example)
Elixir LangChain - Elixir LangChain
Ollama-rs for Rust - Rust SDK
LangChain for .NET - .NET LangChain (example)
chromem-go - Go vector database with Ollama embeddings (example)
LangChainDart - Dart LangChain
LlmTornado - Unified C# interface for multiple inference APIs
Ollama4j for Java - Java SDK
Ollama for Laravel - Laravel integration
Ollama for Swift - Swift SDK
LlamaIndex and LlamaIndexTS - Data framework for LLM apps
Haystack - AI pipeline framework
Firebase Genkit - Google AI framework
Ollama-hpp for C++ - C++ SDK
PromptingTools.jl - Julia LLM toolkit (example)
Ollama for R - rollama - R SDK
Portkey - AI gateway
Testcontainers - Container-based testing
LLPhant - PHP AI framework

Frameworks & Agents

AutoGPT - Autonomous AI agent platform
crewAI - Multi-agent orchestration framework
Strands Agents - Model-driven agent building by AWS
Cheshire Cat - AI assistant framework
any-agent - Unified agent framework interface by Mozilla
Stakpak - Open source DevOps agent
Hexabot - Conversational AI builder
Neuro SAN - Multi-agent orchestration (docs)

RAG & Knowledge Bases

RAGFlow - RAG engine based on deep document understanding
R2R - Open-source RAG engine
MaxKB - Ready-to-use RAG chatbot
Minima - On-premises or fully local RAG
Chipper - AI interface with Haystack RAG
ARGO - RAG and deep research on Mac/Windows/Linux
Archyve - RAG-enabling document library
Casibase - AI knowledge base with RAG and SSO
BrainSoup - Native client with RAG and multi-agent automation

Bots & Messaging

LangBot - Multi-platform messaging bots with agents and RAG
AstrBot - Multi-platform chatbot with RAG and plugins
Discord-Ollama Chat Bot - TypeScript Discord bot
Ollama Telegram Bot - Telegram bot
LLM Telegram Bot - Telegram bot for roleplay

Terminal & CLI

aichat - All-in-one LLM CLI with Shell Assistant, RAG, and AI tools
oterm - Terminal client for Ollama
gollama - Go-based model manager for Ollama
tlm - Local shell copilot
tenere - TUI for LLMs
ParLlama - TUI for Ollama
llm-ollama - Plugin for Datasette's LLM CLI
ShellOracle - Shell command suggestions
LLM-X - Progressive web app for LLMs
cmdh - Natural language to shell commands
VT - Minimal multimodal AI chat app

Productivity & Apps

AppFlowy - AI collaborative workspace, self-hostable Notion alternative
Screenpipe - 24/7 screen and mic recording with AI-powered search
Vibe - Transcribe and analyze meetings
Page Assist - Chrome extension for AI-powered browsing
NativeMind - Private, on-device browser AI assistant
Ollama Fortress - Security proxy for Ollama
1Panel - Web-based Linux server management
Writeopia - Text editor with Ollama integration
QA-Pilot - GitHub code repository understanding
Raycast extension - Ollama in Raycast
Painting Droid - Painting app with AI integrations
Serene Pub - AI roleplaying app
Mayan EDMS - Document management with Ollama workflows
TagSpaces - File management with AI tagging

Observability & Monitoring

Opik - Debug, evaluate, and monitor LLM applications
OpenLIT - OpenTelemetry-native monitoring for Ollama and GPUs
Lunary - LLM observability with analytics and PII masking
Langfuse - Open source LLM observability
HoneyHive - AI observability and evaluation for agents
MLflow Tracing - Open source LLM observability

Database & Embeddings

pgai - PostgreSQL as a vector database (guide)
MindsDB - Connect Ollama with 200+ data platforms
chromem-go - Embeddable vector database for Go (example)
Kangaroo - AI-powered SQL client

Infrastructure & Deployment

Cloud

Google Cloud
Fly.io
Koyeb
Harbor - Containerized LLM toolkit with Ollama as default backend

Package Managers

cloudwego/eino

The ultimate LLM/AI application development framework in Go.

Eino

English | 中文

Overview

Eino['aino] is an LLM application development framework in Golang. It draws from LangChain, Google ADK, and other open-source frameworks, and is designed to follow Golang conventions.

Eino provides:

Components: reusable building blocks like ChatModel, Tool, Retriever, and ChatTemplate, with official implementations for OpenAI, Ollama, and more.
Agent Development Kit (ADK): build AI agents with tool use, multi-agent coordination, context management, interrupt/resume for human-in-the-loop, and ready-to-use agent patterns.
Composition: connect components into graphs and workflows that can run standalone or be exposed as tools for agents.
Examples: working code for common patterns and real-world use cases.

Quick Start

ChatModelAgent

Configure a ChatModel, optionally add tools, and you have a working agent:

chatModel, _ := openai.NewChatModel(ctx, &openai.ChatModelConfig{
    Model:  "gpt-4o",
    APIKey: os.Getenv("OPENAI_API_KEY"),
})

agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model: chatModel,
})

runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: agent})
iter := runner.Query(ctx, "Hello, who are you?")
for {
    event, ok := iter.Next()
    if !ok {
        break
    }
    fmt.Println(event.Message.Content)
}

Add tools to give the agent capabilities:

agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model: chatModel,
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{weatherTool, calculatorTool},
        },
    },
})

The agent handles the ReAct loop internally — it decides when to call tools and when to respond.

→ ChatModelAgent examples · docs

DeepAgent

For complex tasks, use DeepAgent. It breaks down problems into steps, delegates to sub-agents, and tracks progress:

deepAgent, _ := deep.New(ctx, &deep.Config{
    ChatModel: chatModel,
    SubAgents: []adk.Agent{researchAgent, codeAgent},
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{shellTool, pythonTool, webSearchTool},
        },
    },
})

runner := adk.NewRunner(ctx, adk.RunnerConfig{Agent: deepAgent})
iter := runner.Query(ctx, "Analyze the sales data in report.csv and generate a summary chart")

DeepAgent can be configured to coordinate multiple specialized agents, run shell commands, execute Python code, and search the web.

→ DeepAgent example · docs

Composition

When you need precise control over execution flow, use compose to build graphs and workflows:

graph := compose.NewGraph[*Input, *Output]()
graph.AddLambdaNode("validate", validateFn)
graph.AddChatModelNode("generate", chatModel)
graph.AddLambdaNode("format", formatFn)

graph.AddEdge(compose.START, "validate")
graph.AddEdge("validate", "generate")
graph.AddEdge("generate", "format")
graph.AddEdge("format", compose.END)

runnable, _ := graph.Compile(ctx)
result, _ := runnable.Invoke(ctx, input)

Compositions can be exposed as tools for agents, bridging deterministic workflows with autonomous behavior:

tool, _ := graphtool.NewInvokableGraphTool(graph, "data_pipeline", "Process and validate data")

agent, _ := adk.NewChatModelAgent(ctx, &adk.ChatModelAgentConfig{
    Model: chatModel,
    ToolsConfig: adk.ToolsConfig{
        ToolsNodeConfig: compose.ToolsNodeConfig{
            Tools: []tool.BaseTool{tool},
        },
    },
})

This lets you build domain-specific pipelines with exact control, then let agents decide when to use them.

→ GraphTool examples · compose docs

Key Features

Component Ecosystem

Eino defines component abstractions (ChatModel, Tool, Retriever, Embedding, etc.) with official implementations for OpenAI, Claude, Gemini, Ark, Ollama, Elasticsearch, and more.

→ eino-ext

Stream Processing

Eino automatically handles streaming throughout orchestration: concatenating, boxing, merging, and copying streams as data flows between nodes. Components only implement the streaming paradigms that make sense for them; the framework handles the rest.

→ docs

Callback Aspects

Inject logging, tracing, and metrics at fixed points (OnStart, OnEnd, OnError, OnStartWithStreamInput, OnEndWithStreamOutput) across components, graphs, and agents.

→ docs

Interrupt/Resume

Any agent or tool can pause execution for human input and resume from checkpoint. The framework handles state persistence and routing.

→ docs · examples

Framework Structure

The Eino framework consists of:

Eino (this repo): Type definitions, streaming mechanism, component abstractions, orchestration, agent implementations, aspect mechanisms
EinoExt: Component implementations, callback handlers, usage examples, evaluators, prompt optimizers
Eino Devops: Visualized development and debugging
EinoExamples: Example applications and best practices

Documentation

Dependencies

Go 1.18 and above.

Code Style

This repo uses golangci-lint. Check locally with:

golangci-lint run ./...

Rules enforced:

Exported functions, interfaces, packages, etc. should have GoDoc comments
Code should be formatted with gofmt -s
Import order should follow goimports (std -> third party -> local)

Security

If you discover a potential security issue in this project, or think you may have discovered a security issue, we ask that you notify Bytedance Security via our security center or vulnerability reporting email.

Do not create a public GitHub issue.

Contact

Membership: COMMUNITY MEMBERSHIP
Issues: Issues
Lark: Scan the QR code below with Feishu to join the CloudWeGo/eino user group.

License

This project is licensed under the Apache-2.0 License.

kyverno/kyverno

Unified Policy as Code

Kyverno

Cloud Native Policy Management 🎉

📑 Table of Contents

About Kyverno

Kyverno is a Kubernetes-native policy engine designed for platform engineering teams. It enables security, compliance, automation, and governance through policy-as-code. Kyverno can:

Validate, mutate, generate, and clean up resources using Kubernetes admission controls and background scans.
Verify container image signatures for supply chain security.
Operate with tools you already use — like kubectl, kustomize, and Git.

📙 Documentation

Kyverno installation and reference documentation is available at kyverno.io.

👉 Quick Start
👉 Installation Guide
👉 Policy Library

🎥 Demos & Tutorials

▶️ Getting Started with Kyverno – YouTube
🧪 Kyverno Playground

🎯 Popular Use Cases

Kyverno helps platform teams enforce best practices and security standards. Some common use cases include:

1. Security & Compliance

Enforce Pod Security Standards (PSS)
Require specific security contexts
Validate container image sources and signatures
Enforce CIS Benchmark policies

2. Operational Excellence

Auto-label workloads
Enforce naming conventions
Generate default configurations (e.g., NetworkPolicies)
Validate YAML and Helm manifests

3. Cost Optimization

Enforce resource quotas and limits
Require cost allocation labels
Validate instance types
Clean up unused resources

4. Developer Guardrails

Require readiness/liveness probes
Enforce ingress/egress policies
Validate container image versions
Auto-inject config maps or secrets

📚 Explore the Policy Library

Discover hundreds of production-ready Kyverno policies for security, operations, cost control, and developer enablement.

👉 Browse the Policy Library

🙋 Getting Help

We’re here to help:

🐞 File a GitHub Issue
💬 Join the Kyverno Slack Channel
📅 Attend Community Meetings
⭐️ Star this repository to stay updated

➕ Contributing

Thank you for your interest in contributing to Kyverno!

✅ Read the Contribution Guidelines
🤖 Read The AI_Usage_Policy
🧵 Join GitHub Discussions
📖 Read the Development Guide
🏁 Check Good First Issues and request with /assign
🌱 Explore the Community page

🧾 Software Bill of Materials

All Kyverno images include a Software Bill of Materials (SBOM) in CycloneDX format. SBOMs are available at:

👉 ghcr.io/kyverno/sbom
👉 Fetching the SBOM

👥 Contributors

Kyverno is built and maintained by our growing community of contributors!

Made with contributors-img

📄 License

Kyverno is a Cloud Native Computing Foundation (CNCF) Incubating project and was contributed by Nirmata.

XIU2/CloudflareSpeedTest

🌩「自选优选 IP」测试 Cloudflare CDN 延迟和速度，获取最快 IP ！当然也支持其他 CDN / 多个解析 IP 的网站 ~

XIU2/CloudflareSpeedTest

国外很多网站都在使用 Cloudflare CDN，但分配给中国内地访客的 IP 并不友好（延迟高、丢包多、速度慢）。
虽然 Cloudflare 公开了所有 IP 段，但想要在这么多 IP 中找到适合自己的，怕是要累死，于是就有了这个软件。

「自选优选 IP」测试 Cloudflare CDN 延迟和速度，获取最快 IP (IPv4+IPv6)！好用的话点个⭐鼓励一下叭~

分享我其他开源项目：TrackersList.com - 全网热门 BT Tracker 列表！有效提高 BT 下载速度~
UserScript - 🐵 Github 高速下载、知乎增强、自动无缝翻页、护眼模式等十几个油猴脚本~
SNIProxy - 🧷 自用的简单 SNI Proxy（支持全平台、全系统、前置代理、配置简单等~

当然了，本项目也支持对 其他 CDN / 多个解析 IP 的网站 延迟测速，但相对应的下载测速地址需自行寻找。

Important

Cloudflare CDN 已明文禁止代理方式使用，对于代理套 CDN 的自行承担风险，请勿过度依赖 #382 #383

# 快速使用

下载运行

下载编译好的可执行文件（ Github Releases / 蓝奏云）并解压。
双击运行 cfst.exe 文件（Windows 系统），等待测速完成...

「点击查看 Windows 系统下其他安装方式」

如果你有 scoop(Windows 下的命令行安装程序)，则可以这样安装:

# 添加最多人使用的中文软件包仓库：dorado
scoop bucket add dorado https://github.com/chawyehsu/dorado
# 安装cloudflare-speedtest
scoop install dorado/cloudflare-speedtest

「点击查看 Linux 系统下的使用示例」

以下命令仅为示例，版本号和文件名请前往 Releases 查看。

# 如果是第一次使用，则建议创建新文件夹（后续更新时，跳过该步骤）
mkdir cfst

# 进入文件夹（后续更新，只需要从这里重复下面的下载、解压命令即可）
cd cfst

# 下载 CFST 压缩包（自行根据需求替换 URL 中 [版本号] 和 [文件名]）
wget -N https://github.com/XIU2/CloudflareSpeedTest/releases/download/v2.3.4/cfst_linux_amd64.tar.gz
# 如果你是在国内网络环境中下载，那么请使用下面这几个镜像加速之一：
# wget -N https://wget.la/https://github.com/XIU2/CloudflareSpeedTest/releases/download/v2.3.4/cfst_linux_amd64.tar.gz
# wget -N https://ghfast.top/https://github.com/XIU2/CloudflareSpeedTest/releases/download/v2.3.4/cfst_linux_amd64.tar.gz
# wget -N https://ghproxy.it/https://github.com/XIU2/CloudflareSpeedTest/releases/download/v2.3.4/cfst_linux_amd64.tar.gz
# wget -N https://gh-proxy.org/https://github.com/XIU2/CloudflareSpeedTest/releases/download/v2.3.4/cfst_linux_amd64.tar.gz
# wget -N https://cdn.gh-proxy.org/https://github.com/XIU2/CloudflareSpeedTest/releases/download/v2.3.4/cfst_linux_amd64.tar.gz
# 如果下载失败的话，尝试删除 -N 参数（如果是为了更新，则记得提前删除旧压缩包 rm cfst_linux_amd64.tar.gz ）

# 解压（不需要删除旧文件，会直接覆盖，自行根据需求替换 文件名）
tar -zxf cfst_linux_amd64.tar.gz

# 赋予执行权限
chmod +x cfst

# 运行（不带参数）
./cfst

# 运行（带参数示例）
./cfst -tl 200 -dn 20

如果平均延迟非常低（如 0.xx），则说明 CFST 测速时走了代理，请先关闭代理软件后再测速。
如果在路由器上运行，建议先关闭路由器内的代理（或将其排除），否则测速结果可能会不准确/无法使用。

在手机上独立运行 CFST 测速的简单教程：Android、Android APP、Android APP、IOS

Note

注意！本软件仅适用于网站，不支持给使用 UDP 协议的 Cloudflare WARP 优选 IP，具体见：#392

结果示例

测速完毕后，默认会显示最快的 10 个 IP，示例（仅为输出内容示例）：

IP 地址           已发送  已接收  丢包率  平均延迟  下载速度(MB/s)  地区码
104.27.200.69     4      4       0.00   146.23    28.64          LAX
172.67.60.78      4      4       0.00   139.82    15.02          SEA
104.25.140.153    4      4       0.00   146.49    14.90          SJC
104.27.192.65     4      4       0.00   140.28    14.07          LAX
172.67.62.214     4      4       0.00   139.29    12.71          LAX
104.27.207.5      4      4       0.00   145.92    11.95          LAX
172.67.54.193     4      4       0.00   146.71    11.55          LAX
104.22.66.8       4      4       0.00   147.42    11.11          SEA
104.27.197.63     4      4       0.00   131.29    10.26          FRA
172.67.58.91      4      4       0.00   140.19    9.14           SJC
...

# 如果平均延迟非常低（如 0.xx），则说明 CFST 测速时走了代理，请先关闭代理软件后再测速。
# 如果在路由器上运行，请先关闭路由器内的代理（或将其排除），否则测速结果可能会不准确/无法使用。

# 因为每次测速都是在每个 IP 段中随机 IP，所以每次的测速结果都不可能相同，这是正常的！

# 注意！我发现电脑开机后第一次测速延迟会明显偏高（手动 TCPing 也一样），后续测速都正常
# 因此建议大家开机后第一次正式测速前，先随便测几个 IP（无需等待延迟测速完成，只要进度条动了就可以直接关了）

# 软件在 默认参数 下的整个流程大概步骤：
# 1. 延迟测速（默认 TCPing 模式，HTTPing 模式需要手动加上参数）
# 2. 延迟排序（延迟 从低到高 排序并按条件过滤，不同丢包率会分开排序，因此可能会有一些延迟低但丢包的 IP 排到后面）
# 3. 下载测速（从延迟最低的 IP 开始依次下载测速，默认测够 10 个就会停止）
# 4. 速度排序（速度从高到低排序）
# 5. 输出结果（通过参数控制是否输出到命令行(-p 0)或输出到文件(-o "")）

# 注意：输出的结果文件 result.csv 通过微软 Excel 表格打开会中文乱码，这是正常的，其他表格软件/记事本都显示正常

测速结果第一行就是既下载速度最快、又平均延迟最低的最快 IP！

完整结果保存在当前目录下的 result.csv 文件中，用记事本/表格软件打开，格式如下：

IP 地址,已发送,已接收,丢包率,平均延迟,下载速度(MB/s),地区码
104.27.200.69,4,4,0.00,146.23,28.64,LAX

Note

如果你发现下载速度为 0.00，那么可以用调试模式 -debug 排查一下，详见：# 下载测速都是 0.00 ？

大家可以按自己需求，对完整结果进一步筛选处理，或者去看一看进阶使用指定过滤条件！

# 进阶使用

直接运行使用的是默认参数，如果想要更好更高效的寻找最适合自己的 IP，那么就需要善用各个参数的搭配组合：

C:\>cfst -h

CloudflareSpeedTest vX.X.X
测试各个 CDN 或网站所有 IP 的延迟和速度，获取最快 IP (IPv4+IPv6)！
https://github.com/XIU2/CloudflareSpeedTest

参数：
    -n 200
        延迟测速线程；越多延迟测速越快，性能弱的设备 (如路由器) 请勿太高；(默认 200 最多 1000)
    -t 4
        延迟测速次数；单个 IP 延迟测速的次数；(默认 4 次)
    -dn 10
        下载测速数量；延迟测速并排序后，从最低延迟起下载测速的数量；(默认 10 个)
    -dt 10
        下载测速时间；单个 IP 下载测速最长时间，不能太短；(默认 10 秒)
    -tp 443
        指定测速端口；延迟测速/下载测速时使用的端口；(默认 443 端口)
    -url https://cf.xiu2.xyz/url
        指定测速地址；延迟测速(HTTPing)/下载测速时使用的地址，默认地址不保证可用性，建议自建；
        当下载测速时，软件会从 HTTP 响应头中获取该 IP 当前地区码（支持 Cloudflare、AWS CloudFront、Fastly、Gcore、CDN77、Bunny 等 CDN）并显示出来。

    -httping
        切换测速模式；延迟测速模式改为 HTTP 协议，所用测试地址为 [-url] 参数；(默认 TCPing)
        当使用 HTTP 测速模式时，软件会从 HTTP 响应头中获取该 IP 当前地区码（支持 Cloudflare、AWS CloudFront、Fastly、Gcore、CDN77、Bunny 等 CDN）并显示出来。
        注意：HTTPing 本质上也算一种 网络扫描 行为，因此如果你在服务器上面运行，需要降低并发(-n)，否则可能会被一些严格的商家暂停服务。
        如果你遇到 HTTPing 首次测速可用 IP 数量正常，后续测速越来越少甚至直接为 0，但停一段时间后又恢复了的情况，那么也可能是被 运营商、Cloudflare CDN 认为你在网络扫描而 触发临时限制机制，因此才会过一会儿就恢复了，建议降低并发(-n)减少这种情况的发生。
    -httping-code 200
        有效状态代码；HTTPing 延迟测速时网页返回的有效 HTTP 状态码，仅限一个；(默认 200 301 302)
    -cfcolo HKG,KHH,NRT,LAX,SEA,SJC,FRA,MAD
        匹配指定地区；IATA 机场地区码或国家/城市码，英文逗号分隔，大小写均可，仅 HTTPing 模式可用；(默认 所有地区)
        支持 Cloudflare、AWS CloudFront、Fastly、Gcore、CDN77、Bunny 等 CDN
        其中 Cloudflare、AWS CloudFront、Fastly 使用的是 IATA 三字机场地区码，如：HKG,LAX
        其中 CDN77、Bunny 使用的是 二字国家/区域码，如：US,CN
        其中 Gcore 使用的是 二字城市码，如：FR,AM
        因此大家使用 -cfcolo 指定地区码时要根据不同的 CDN 来指定不同类型的地区码。

    -tl 200
        平均延迟上限；只输出低于指定平均延迟的 IP，各上下限条件可搭配使用；(默认 9999 ms)
    -tll 40
        平均延迟下限；只输出高于指定平均延迟的 IP；(默认 0 ms)
    -tlr 0.2
        丢包几率上限；只输出低于/等于指定丢包率的 IP，范围 0.00~1.00，0 过滤掉任何丢包的 IP；(默认 1.00)
    -sl 5
        下载速度下限；只输出高于指定下载速度的 IP，凑够指定数量 [-dn] 才会停止测速；(默认 0.00 MB/s)

    -p 10
        显示结果数量；测速后直接显示指定数量的结果，为 0 时不显示结果直接退出；(默认 10 个)
    -f ip.txt
        IP段数据文件；如路径含有空格请加上引号；支持其他 CDN IP段；(默认 ip.txt)
    -ip 1.1.1.1,2.2.2.2/24,2606:4700::/32
        指定IP段数据；直接通过参数指定要测速的 IP 段数据，英文逗号分隔；(默认 空)
    -o result.csv
        写入结果文件；如路径含有空格请加上引号；值为空时不写入文件 [-o ""]；(默认 result.csv)
        注意：在一些环境下使用 -o "" 可能会被忽略掉这个空参数导致报错，可加个空格 -o " " 解决

    -dd
        禁用下载测速；禁用后测速结果会按延迟排序 (默认按下载速度排序)；(默认 启用)
    -allip
        测速全部的IP；对 IP 段中的每个 IP (仅支持 IPv4) 进行测速；(默认 每个 /24 段随机测速一个 IP)

    -debug
        调试输出模式；会在一些非预期情况下输出更多日志以便判断原因；(默认 关闭)
        目前该功能仅针对 HTTPing 延迟测速过程 及 下载测速过程，当过程中因为各种原因导致当前 IP 测速中断都会输出错误原因
        例如：HTTPing 延迟测速过程中，因为 HTTP 状态码不符合或测速地址有问题或超时等原因而终止测速
        例如：下载测速过程中，因为下载测速地址有问题（被阻断、403状态码、超时）等原因而终止测速（导致显示 0.00）

    -v
        打印程序版本 + 检查版本更新
    -h
        打印帮助说明

界面解释

为了避免大家对测速过程中的输出内容产生误解（可用、队列等数字，下载测速一半就"中断"？下载测速"卡住"不动？），我特意解释下。

「点击展开查看内容」

该示例把常用参数都给加上了，即为：-tll 40 -tl 150 -sl 1 -dn 5，最后输出结果如下：

# XIU2/CloudflareSpeedTest vX.X.X

开始延迟测速（模式：TCP, 端口：443, 范围：40 ~ 150 ms, 丢包：1.00)
321 / 321 [-----------------------------------------------------------] 可用: 30
开始下载测速（下限：1.00 MB/s, 数量：5, 队列：10）
3 / 5 [-----------------------------------------↗--------------------]
IP 地址           已发送  已接收  丢包率  平均延迟  下载速度(MB/s)  地区码
XXX.XXX.XXX.XXX   4      4       0.00   83.32     3.66           LAX
XXX.XXX.XXX.XXX   4      4       0.00   107.81    2.49           LAX
XXX.XXX.XXX.XXX   4      3       0.25   149.59    1.04           N/A

完整测速结果已写入 result.csv 文件，可使用记事本/表格软件查看。
按下 回车键 或 Ctrl+C 退出。

刚接触 CFST 的人，可能会迷惑明明延迟测速可用 IP 有 30 个，怎么最后只剩下 3 个了呢？
下载测速里的队列又是什么意思？难道我下载测速还要排队？

CFST 会先延迟测速，在这过程中进度条右侧会实时显示可用 IP 数量（可用: 30），但注意该可用数量指的是测试通过没有超时的 IP 数量，和延迟上下限、丢包条件无关。当延迟测速完成后，因为还指定了延迟上下限、丢包的条件，所以按照条件过滤后只剩下 10 个了（也就是等待下载测速的 队列：10）。

即以上示例中，321 个 IP 延迟测速完成后，只有 30 个 IP 测试通过没有超时，然后根据延迟上下限范围：40 ~ 150 ms 及丢包上限条件过滤后，只剩下 10 个满足要求的 IP 了。如果你 -dd 禁用了下载测速，那么就会直接输出这 10 个 IP 了。当然该示例并未禁用，因此接下来软件会继续对这 10 个 IP 进行下载测速（队列：10）。

因为下载测速是单线程一个个 IP 挨着排队测速的，因此等待下载测速的 IP 数量才会叫做 队列。

你可能注意到了，明明指定了要找到 5 个满足下载速度条件的 IP，怎么才 3 个就 “中断” 了呢？

下载测速进度条中的 3 / 5，前者指的是找到了 3 个满足下载速度下限条件的 IP（即下载速度高于 1 MB/s ），后者 5 指的是你要求找到 5 个满足下载速度下限条件的 IP（-dn 5）。

另外，提醒一下，如果你指定的 -dn 大于下载测速队列，比如你延迟测速后只剩下 4 个 IP 了，那么下载测速进度条中后面的数字就会和下载测速队列一样都是 4 个，而非你 -dn 指定的 5 个了。

软件在测速完这 10 个 IP 后，只找到了 3 个下载速度高于 1 MB/s 的 IP，剩下的 7 个 IP 都是 “不及格” 的。

因此，这不是 “每次测速都不到 5 就中断了”，而是所有 IP 都下载测速完了，但却只找到了 3 个满足条件的。

还有一种情况，那就是当可用 IP 很多时（几百几千），你还设置了下载速度条件，那么可能就会遇到：怎么下载测速进度条老是卡在 X / 5 了呢？

这其实并不是卡住了，而是只有当找到一个满足条件的 IP 时，进度条才会 +1，因此如果一直找不到，那么 CFST 就会一直下载测速下去，因此在表现为进度条卡住不动，但这也是在提醒你：你设置的下载速度条件对你来说已经高于实际了，你需要适当调低预期。

如果不想遇到这种全部测速一遍都没几个满足条件的情况，那么就要调低下载速度上限参数 -sl，或者移除。

因为只要指定了 -sl 参数，那么只要没有凑够 -dn 的数量（默认 10 个），就会一直测速下去，直到凑够或全部测速完。移除 -sl 并添加 -dn 20 参数，这样就是只测速延迟最低的前 20 个 IP，测速完就停止，节省时间。

另外，如果全部队列 IP 都测速完了，但一个满足下载速度条件的 IP 都没有，你可能需要调低预期的下载测速下限条件，但你需要知道当前的大概测速速度都在什么范围，那么你就可以加上 -debug 参数开启调试模式，这样再遇到这种情况时，就会忽略条件返回所有测速结果，你就能看到这些 IP 的下载速度都有多少，心里也就有数了，然后适当调低 -sl 再试试。

注意，如果你没有指定下载测速下限 -sl 条件，那么无论什么情况下 CFST 都会输出所有测速结果。

同样，延迟测速方面，可用: 30、队列：10 这两个数值也可以让你清楚，你设置的延迟条件对你来说是否过于苛刻。如果可用 IP 一大堆，但条件过滤后只剩下 2、3 个，那不用说就知道需要调低预期的延迟/丢包条件了。

这两个机制，一个是告诉你延迟丢包条件是否合适的，一个是告诉你下载速度条件是否合适的。

使用示例

Windows 要指定参数需要在 CMD 中运行，或者把参数添加到快捷方式目标中。

Tip

各参数均有默认值，当使用默认值时参数可以省略（按需选择），参数不分前后顺序。
Windows PowerShell 只需把下面命令中的 cfst 改为 .\cfst 即可。
Linux / macOS 系统只需要把下面命令中的 cfst 改为 ./cfst 即可。

# CMD 带参数运行

对命令行程序不熟悉的人，可能不知道该如何带参数运行，我就简单说一下。

「点击展开查看内容」

很多人打开 CMD 直接就以绝对路径运行 CFST 会报错，这是因为默认的 -f ip.txt 参数是相对路径，需要指定绝对路径的 ip.txt 才行，但这样毕竟太麻烦了，因此还是建议进入 CFST 程序目录下，以相对路径方式运行：

方式一：

打开 CFST 程序所在目录
空白处按下 Shift + 鼠标右键 显示右键菜单
选择 [在此处打开命令窗口] 来打开 CMD 窗口，此时默认就位于当前目录下
输入带参数的命令，如：cfst -tl 200 -dn 20 即可运行

方式二：

打开 CFST 程序所在目录
直接在文件夹地址栏中全选(或清空)并输入 cmd 回车就能打开 CMD 窗口，此时默认就位于当前目录下
输入带参数的命令，如：cfst -tl 200 -dn 20 即可运行

当然你也可以随便打开一个 CMD 窗口，然后输入如 cd /d "D:\Program Files\cfst" 来进入程序目录

提示：如果用的是 PowerShell 只需把命令中的 cfst 改为 .\cfst 即可。
注意：在 PowerShell 下使用 -o "" 会被忽略掉空参数导致报错，可加个空格 -o " " 解决

# Windows 快捷方式带参数运行

如果不经常修改运行参数（比如平时都是直接双击运行）的人，建议使用快捷方式，更方便点。

「点击展开查看内容」

右键 cfst.exe 文件 - [创建快捷方式]，然后右键该快捷方式 - [属性]，修改其目标：

# 如果要不输出结果文件，那么请加上 -o " "，引号里的是空格（不加空格会导致该空参数被忽略从而报错）。
D:\ABC\cfst\cfst.exe -tl 200 -dn 20 -o " "

# 如果文件路径包含引号，则需要把启动参数放在引号外面，记得引号和 - 之间有空格。
"D:\Program Files\cfst\cfst.exe" -tl 200 -dn 20 -o " "

# 注意！快捷方式 - 起始位置 不能是空的，否则就会因为绝对路径而找不到 ip.txt 文件

# IPv4/IPv6

「点击展开查看内容」

# 指定自带的 IPv4 数据文件可测速这些 IPv4 地址（-f 默认值就是 ip.txt，所以该参数可省略）
cfst -f ip.txt

# 指定自带的 IPv6 数据文件可测速这些 IPv6 地址
# 另外，v2.1.0 版本后支持 IPv4+IPv6 混合测速并移除了 -ipv6 参数，因此一个文件内可以同时包含 IPv4+IPv6 地址
cfst -f ipv6.txt

# 也可以直接通过参数指定要测速的 IP
cfst -ip 1.1.1.1,2606:4700::/32

测速 IPv6 时，可能会注意到每次测速数量都不一样，了解原因： #120
因为 IPv6 太多（以亿为单位），且绝大部分 IP 段压根未启用，所以我只扫了一部分可用的 IPv6 段写到 ipv6.txt 文件中，有兴趣的可以自行扫描增删，ASN 数据源来自：bgp.he.net

# HTTPing

「点击展开查看内容」

目前有两种延迟测速模式，分别为 TCP 协议、HTTP 协议。
TCP 协议耗时更短、消耗资源更少，超时时间为 1 秒，该协议为默认模式。
HTTP 协议适用于快速测试某域名指向某 IP 时是否可以访问，超时时间为 2 秒。
同一个 IP，各协议去 Ping 得到的延迟一般为：ICMP < TCP < HTTP，越靠右对丢包等网络波动越敏感。

注意：HTTPing 本质上也算一种网络扫描行为，因此如果你在服务器上面运行，需要降低并发(-n)，否则可能会被一些严格的商家暂停服务。如果你遇到 HTTPing 首次测速可用 IP 数量正常，后续测速越来越少甚至直接为 0，但停一段时间后又恢复了的情况，那么也可能是被运营商、Cloudflare CDN 认为你在网络扫描而触发临时限制机制，因此才会过一会儿就恢复了，建议降低并发(-n)减少这种情况的发生。

另外，本软件 HTTPing 仅获取响应头(response headers)，并不获取正文内容（即 URL 文件大小不影响 HTTPing 测试，但如果你还要下载测速的话，那么还是需要一个大文件的），类似于 curl -i 功能。

另外，HTTPing 过程中，软件会从 HTTP 响应头中获取该 IP 当前地区码（支持 Cloudflare、AWS CloudFront、Fastly、Gcore、CDN77、Bunny 等 CDN）并显示出来，而 TCPing 过程中无法这样做（但下载测速时也会这样做来获取地区码，毕竟下载测速也是个 HTTP 链接）

# 只需加上 -httping 参数即可切换到 HTTP 协议延迟测速模式
cfst -httping

# 软件会根据访问时网页返回的有效 HTTP 状态码来判断可用性（当然超时也算），默认对返回 200 301 302 这三个 HTTP 状态码的视为有效，可以手动指定认为有效的 HTTP 状态码，但只能指定一个（你需要提前确定测试地址正常情况下会返回哪个状态码）
cfst -httping -httping-code 200

# 通过 -url 参数来指定 HTTPing 测试地址（可以是任意网页 URL，不局限于具体文件地址）
cfst -httping -url https://cf.xiu2.xyz/url
# 如果你要 HTTPing 测试其他网站/CDN，那么指定一个该网站/使用该 CDN 的地址（因为软件默认地址是 Cloudflare 的，只能用于测试 Cloudflare 的 IP）

# 注意：如果测速地址为 HTTP 协议，记得加上 -tp 80（这个参数会影响 延迟测速/下载测速 时使用的端口）
# 同理，如果要测速 80 端口，那么也需要加上 -url 参数来指定一个 http:// 协议的地址才行（且该地址不会强制重定向至 HTTPS），如果是非 80 443 端口，那么需要确定该下载测速地址是否支持通过该端口访问。
cfst -httping -tp 80 -url http://cdn.cloudflare.steamstatic.com/steam/apps/5952/movie_max.webm

# 匹配指定地区

「点击展开查看内容」

Cloudflare CDN 的节点 IP 是 Anycast IP，即每个 IP 对应的服务器节点及地区不是固定的，而是动态变化的，不同地区、不同运营商、不同时间段访问同一个 IP 分配到的服务器节点地区和路线也都是不一样的（比如同一个 IP，美国人访问就是分配到就近的美国节点服务器，日本人访问则就又变成了就近的日本节点服务器了，国内内地就比较特殊了，只能给你分配到其他国家，当然不同的 IP 段路由变化/分配逻辑也是不同的，有的 IP 段会较为固定）。

注意！虽然 Cloudflare CDN 有很多亚洲节点，但不代表你就能用上，新加坡人测速可能随便一抓一大把的新加坡节点，但你全部扫一遍可能都遇不到一个，因为这是由 CDN 控制的。Anycast IP 的路由是经常变的，同一个 IP 今天可能是美国，明天你再访问可能就又分配到欧洲节点了（当然这只是个例子，一般没有那么频繁，这也和很多因素有关，比如线路拥塞程度，成本变动等），因此不要对该功能有过高期待~

或者你随便找个 Cloudflare CDN 的 IP（比如官网域名的解析 IP 104.16.123.96），然后去那些有全球节点的在线 Ping 测试网站，你就会发现这个 IP 在全球大部分地区的延迟都是个位数（而且很多都是 0.X ms），就算一些地方延迟高一些但也基本都控制在几十ms，只有在国内才会发现突然变成了上百ms 了。

这就是 Anycast 技术，也就只有国内大陆这种特殊的网络情况，才需要对 Anycast 的 CDN IP 进行优选。

因此，对于这种 Anycast IP 的实际服务器位置，就不能靠那些在线 IP 地址位置查询网站来判断了。

除了通过 HTTP 响应头获取地区码外（该功能的实现方式），还可以手动访问 http://CloudflareIP/cdn-cgi/trace 来获知 CDN 分配给你的实际节点地区码。

该功能支持 Cloudflare、AWS CloudFront、Fastly、Gcore、CDN77、Bunny 等 CDN。
但注意，不是所有 CDN 都支持 Anycast 技术的，很多 CDN 会限制一个网站能使用的 IP 范围。

其中 Cloudflare、AWS CloudFront、Fastly 都使用的是 IATA 三字机场地区码，如：HKG,LAX
而 CDN77、Bunny 使用的是 二字国家/区域码，如：US,CN
Gcore 则使用的是 二字城市码，如：FR,AM
因此大家使用 -cfcolo 指定地区码时要根据不同的 CDN 来指定不同类型的地区码。

注意：如果你要用于筛选 AWS CloudFront CDN 地区，那么要通过 -url 参数指定一个使用 AWS CloudFront CDN 的下载测速地址（因为软件默认下载测速地址是 Cloudflare CDN 的），另外有时候 HTTPing 模式测速一些 AWS CloudFront 地址会返回 403 错误，这种情况下需要加上 -httping-code 403 才能正确获取地区码。

# 指定地区名后，延迟测速后得到的结果就都是指定地区的 IP 了（如果没有指定 -dd 的话则会继续进行下载测速）
# 如果延迟测速后结果为 0，则说明没有找到任何一个（未超时可用的）指定地区的 IP。
# 节点地区名为当地 IATA 机场地区码或国家/城市码，指定多个时用英文逗号分隔，v2.2.3 版本后支持小写

cfst -httping -cfcolo HKG,KHH,NRT,LAX,SEA,SJC,FRA,MAD

# 注意，该参数只有在 HTTPing 延迟测速模式下才可用（因为软件是通过 HTTP 链接中的响应头来获得该 IP 的实际地区码）

# 另外，HTTPing 过程中，软件会从 HTTP 响应头中获取该 IP 当前地区码（支持 Cloudflare、AWS CloudFront、Fastly、Gcore、CDN77、Bunny 等 CDN）并显示出来，而 TCPing 过程中无法这样做（但 下载测速 时也会这样做来获取地区码，毕竟下载测速也是个 HTTP 链接）

IATA 三字机场地区码，可见：https://www.cloudflarestatus.com/
二字国家码，可见：https://zh.wikipedia.org/wiki/ISO_3166-1二位字母代码#正式分配代码

# 文件相对/绝对路径

「点击展开查看内容」

# 指定 IPv4 数据文件，不显示结果直接退出，输出结果到文件（-p 值为 0）
cfst -f 1.txt -p 0 -dd

# 指定 IPv4 数据文件，不输出结果到文件，直接显示结果（-p 值为 10 条，-o 值为空但引号不能少）
cfst -f 2.txt -o "" -p 10 -dd

# 指定 IPv4 数据文件 及 输出结果到文件（相对路径，即当前目录下，如含空格请加上引号）
cfst -f 3.txt -o result.txt -dd


# 指定 IPv4 数据文件 及 输出结果到文件（相对路径，即当前目录内的 abc 文件夹下，如含空格请加上引号）
# Linux（CFST 程序所在目录内的 abc 文件夹下）
./cfst -f abc/3.txt -o abc/result.txt -dd

# Windows（注意是反斜杠）
cfst -f abc\3.txt -o abc\result.txt -dd


# 指定 IPv4 数据文件 及 输出结果到文件（绝对路径，即 C:\abc\ 目录下，如含空格请加上引号）
# Linux（/abc/ 目录下）
./cfst -f /abc/4.txt -o /abc/result.csv -dd

# Windows（注意是反斜杠）
cfst -f C:\abc\4.txt -o C:\abc\result.csv -dd


# 如果要以【绝对路径】运行 CFST，那么 -f / -o 参数中的文件名也必须是【绝对路径】，否则会报错找不到文件！
# Linux（/abc/ 目录下）
/abc/cfst -f /abc/4.txt -o /abc/result.csv -dd

# Windows（注意是反斜杠）
C:\abc\cfst -f C:\abc\4.txt -o C:\abc\result.csv -dd

# 测速其他端口

「点击展开查看内容」

# 如果你想要测速非默认 443 的其他端口，则需要通过 -tp 参数指定（该参数会影响 延迟测速/下载测速 时使用的端口）

# 如果要延迟测速 80 端口+下载测速（如果 -dd 禁用了下载测速则不需要），那么还需要指定 http:// 协议的下载测速地址才行（且该地址不会强制重定向至 HTTPS，因为那样就变成 443 端口了）
cfst -tp 80 -url http://speed.cloudflare.com/__down?bytes=99999999

# 如果是非 80 443 的其他端口，那么需要确定你使用的下载测速地址是否支持通过该非标端口访问。

# 自定义测速地址

「点击展开查看内容」

# 该参数适用于下载测速 及 HTTP 协议的延迟测速，对于后者该地址可以是任意网页 URL（不局限于具体文件地址）

# 地址要求：可以直接下载、文件大小超过 200MB、用的是 Cloudflare CDN
cfst -url https://cf.xiu2.xyz/url

# 注意：如果测速地址为 HTTP 协议（该地址不能强制重定向至 HTTPS），记得加上 -tp 80（这个参数会影响 延迟测速/下载测速 时使用的端口），如果是非 80 443 端口，那么需要确定下载测速地址是否支持通过该端口访问。
cfst -tp 80 -url http://speed.cloudflare.com/__down?bytes=99999999

# 自定义测速条件（指定延迟/丢包/下载速度的目标范围）

「点击展开查看内容」

注意：延迟测速进度条右边的可用数量，仅指延迟测速过程中未超时的 IP 数量，和延迟上下限条件无关。

仅指定 [平均延迟上限] 条件

# 平均延迟上限：200 ms，下载速度下限：0 MB/s
# 即找到平均延迟低于 200 ms 的 IP，然后再按延迟从低到高进行 10 次下载测速
cfst -tl 200

如果没有找到一个满足延迟条件的 IP，那么不会输出任何内容。

指定 [平均延迟上限] 条件，且只延迟测速，不下载测速

# 平均延迟上限：200 ms，下载速度下限：0 MB/s，数量：不知道多少 个
# 即只输出低于 200ms 的 IP，且不再下载测速（因为不再下载测速，所以 -dn 参数就无效了）
cfst -tl 200 -dd

同时指定 [平均延迟下限] + [平均延迟上限] 条件

# 平均延迟下限：60 ms，平均延迟下限：200 ms，下载速度下限：0 MB/s
# 即找到平均延迟高于 60 ms 且低于 200 ms 的 IP（也就是 60~200ms 之间的），然后再按延迟从低到高进行 10 次下载测速
cfst -tll 60 -tl 200

可能很多纳闷延迟不是越低越好吗？为什么还要丢掉低延迟的 IP ？

一方面是：一些人确实存在个性化需求，需要指定延迟区间。

另一方面则是：延迟和丢包最低的 IP 不一定就速度更快（当然一般情况下延迟更低且不丢包是更好的，因为这意味着 "物理距离近+中间路由环节少+网络稳定"，因此显然这种网络质量遇到速度快的概率更高），但网络质量好就不一定速度更快，因为传输速度是可以被控制的（比如 QOS），因此也会出现一些明明延迟更高，但是速度反而更快的情况（仅限于延迟差异，如果还涉及到丢包，那么因为丢包对传输速度影响极大，也会导致这种情况）

比如国内移动用户默认参数测速结果基本上都是清一色的几十ms 的香港节点 IP，但容易遇到延迟很低还不丢包，但就是速度很差，或者时快时慢的，很折磨人，此时改用其它地区的虽然延迟更高但可能反而速度更快，就可以使用 -tll 来过滤掉这些香港的（除此之外就只有 httping 模式下的 colo 参数可以过滤了）

仅指定 [丢包几率上限] 条件

# 丢包几率上限：0.25
# 即找到丢包率低于等于 0.25 的 IP，范围 0.00~1.00，如果 -tlr 0 则代表过滤掉任何丢包的 IP
cfst -tlr 0.25

仅指定 [下载速度下限] 条件

# 平均延迟上限：9999 ms，下载速度下限：5 MB/s，数量：10 个（可选）
# 即需要找到 10 个平均延迟低于 9999 ms 且下载速度高于 5 MB/s 的 IP 才会停止测速
cfst -sl 5 -dn 10

如果没有找到一个满足速度条件的 IP，那么不会输出任何内容，你可能需要调低预期的下载测速下限条件，但你需要知道当前的大概测速速度都在什么范围，那么你就可以加上 -debug 参数开启调试模式，这样再遇到这种情况时，就会忽略条件返回所有测速结果，你就能看到这些 IP 的下载速度都有多少，心里也就有数了，然后适当调低 -sl 再试试。
注意，如果你没有指定下载测速下限 -sl 条件，那么无论什么情况下 CFST 都会输出所有测速结果。

没有指定平均延迟上限时，如果一直凑不够满足条件的 IP 数量，就会一直测速下去。
建议同时指定 [下载速度下限] + [平均延迟上限]，这样测速到指定延迟上限还没凑够数量，就会终止测速。

同时指定 [平均延迟上限] + [下载速度下限] 条件

# 平均延迟上限、下载速度下限均支持小数（如 -sl 0.5）
# 平均延迟上限：200 ms，下载速度下限：5.6 MB/s，数量：10 个（可选）
# 即需要找到 10 个平均延迟低于 200 ms 且下载速度高于 5 .6MB/s 的 IP 才会停止测速
cfst -tl 200 -sl 5.6 -dn 10

如果没有找到一个满足延迟条件的 IP，那么不会输出任何内容。
如果没有找到一个满足速度条件的 IP，那么不会输出任何内容，但可以通过加上 -debug 参数开启调试模式，这时会忽略条件输出所有 IP 测速结果（方便你下次测速时调整条件）。
所以建议先不指定条件测速一遍，看看平均延迟和下载速度大概在什么范围，避免指定条件过低/过高！

因为 Cloudflare 公开的 IP 段是回源 IP+任播 IP，而回源 IP是无法使用的，所以下载测速是 0.00。
运行时可以加上 -sl 0.01（下载速度下限），过滤掉回源 IP（下载测速低于 0.01MB/s 的结果）。

为了避免大家迷糊，我列出了在各种条件组合下的预期输出结果都是什么样的。

没有指定任何延迟/速度条件 (即都是默认值)：

无论如何，都直接输出 所有测速结果

指定了任何延迟条件（-tl -tll，且无论是否开启调试模式 -debug 都一样）：

如果找到最少 1 个满足条件的 IP，则只输出 这几个满足条件的 IP（如没有禁用下载测速，则会继续下载测速）
如果没找到任何满足条件的 IP，则会输出空（如没有禁用下载测速，也会因为数量为 0 而跳过下载测速）

指定了任何下载速度条件 (-sl)：

且当 关闭调试模式 时（即没加上 -debug 参数，这种情况下和延迟测速的逻辑完全一致）：

如果找到最少 1 个满足条件的 IP，则只输出 这几个满足条件的 IP
如果没找到任何满足条件的 IP，则输出空

且当 开启调试模式 时（即加上了 -debug 参数，延迟测速并没有加上下面第二条里的逻辑，所以依然输出空）：

如果找到最少 1 个满足条件的 IP，则只输出 这几个满足条件的 IP
如果没找到任何满足条件的 IP，则直接输出 所有测速结果

# 单独对一个或多个 IP 测速

「点击展开查看内容」

方式一：直接通过参数指定要测速的 IP 段数据。

# 先进入 CFST 所在目录，然后运行：
# Windows 系统（在 CMD 中运行）
cfst -ip 1.1.1.1,2.2.2.2/24,2606:4700::/32

# Linux 系统
./cfst -ip 1.1.1.1,2.2.2.2/24,2606:4700::/32

方式二：或者把这些 IP 按如下格式写入到任意文本文件中，例如：1.txt

1.1.1.1
1.1.1.200
1.0.0.1/24
2606:4700::/32

单个 IP 的话可以省略 /32 子网掩码了（即 1.1.1.1等同于 1.1.1.1/32）。
子网掩码 /24 指的是这个 IP 最后一段，即 1.0.0.1~1.0.0.255。

然后运行 CFST 时加上启动参数 -f 1.txt 来指定 IP 段数据文件。

# 先进入 CFST 所在目录，然后运行：
# Windows 系统（在 CMD 中运行）
cfst -f 1.txt

# Linux 系统
./cfst -f 1.txt

# 对于 1.0.0.1/24 这样的 IP 段只会随机最后一段（1.0.0.1~255），如果要测速该 IP 段中的所有 IP，请加上 -allip 参数。

# 下载测速都是 0.00 ？

「点击展开查看内容」

## 原理简单解释：

首先要明白，CFST 下载测速过程，本质上和你将 IP 下载测速地址域名 写入 hosts 文件，然后浏览器去访问下载测速地址是一样的，只不过软件将其自动化了（类似于 curl -I --resolve 下载测速地址域名:443:IP https://下载测速地址）。

因此如果下载测速结果全都是 0.00 MB/s，那么代表下载测速过程中出问题报错，导致直接终止测速了（并最终显示为 0.00），就只有这几种可能性：

下载测速地址有问题
测速的 IP 地址有问题
你的网络有问题

## 调试模式排查：

接下来请务必先在你原先使用的 CFST 运行命令后追加一个 -debug 参数来开启调试模式，重新跑一遍测速，这样下载测速过程中出现任何报错都会显示具体原因方便你排查。

常见的下载测速失败报错原因有（因为是 Go 语言的原生报错信息，因此基本都是英文）：

... read: connection reset by peer ...
链接被重置，可能是下载测速地址被阻断了或测速 IP 被针对性 HTTPS 阻断了，可能是蔷干的，也可能是运营商干的（比如移动或部分地区的白名单），当然也可能是测速 IP 服务器单纯的重置了你这个不合法的链接请求
... HTTP 状态码: 403 ...
像这种直接提示 HTTP 状态码的，比较好判断，如 403 就是下载测速地址禁止你访问，404 就是下载测速地址路径对应的文件找不到（具体其他的可以搜索 HTTP 状态码含义）
... context deadline exceeded (Client.Timeout exceeded while awaiting headers) ...
这种一般是请求超时引起的，可能是 IP 或网络问题，也可能是 -dt 下载测速时间设置的太短了（当然默认的 10 秒肯定算不上短）
... tls: handshake failure ... 或 ... tls: failed to verify certificate ...
这种 TLS 握手失败/SSL 证书错误 代表下载测速地址和测速 IP 服务器不匹配，也就是下载测速地址与测速 IP 其中一方有误（例如下载测速地址是托管在 Fastly CDN 的，但测速 IP 是 Cloudflare CDN 的，或者反过来，总之就是你访问下载测速地址时该测速的 IP 服务器告诉你这个网站域名它不认识并把你拒之门外）
... tls: failed to verify certificate: x509: certificate is valid for XXX.XX, not YYY.YY ...
这种是 SSL 证书里没有包含你下载测速地址的域名，要么是下载测速地址证书配置有问题，要么就是该测速服务器 IP 上并没有该下载测速地址域名对应的 SSL 证书，也就意味着这个服务器 IP 是不能用于该下载测速地址域名的（比如你用谷歌的服务器 IP 去下载测速百度的域名就会这样，或像上面 4 的原因一样）
... tls: failed to verify certificate: x509: certificate has expired or is not yet valid: current time ...
这种是 SSL 证书过期了或者尚未到有效时间，除了这个原因外，也可能是和上面 4、5 的原因一样（这 4、5、6 三种报错可能会同时出现在同一个服务器 IP 上）
... tls: failed to verify certificate: x509: certificate signed by unknown authority.
这种代表系统证书配置有问题，导致 TLS 握手时无法验证证书，目前只在 Termux 内遇到过（解决方法见：https://github.com/XIU2/CloudflareSpeedTest/discussions/61 帖子末尾）

如果你遇到了其他报错原因，且翻译后还是不懂，可以发 Issues 或 Discussions 询问，我也会更新到这里。
但注意，发 Issues 或 Discussions 询问时，请记得带上调试模式下 CFST 输出的完整内容（或者完整截图）。

根据上面的报错原因排查一遍后，如果还是无法解决，那么可以尝试下面这些进一步排查：

一、下载测速地址有问题：

先去 #490 找几个其他的下载测速地址都试试。

如果其中有能下载测速出结果的，则就代表你之前使用的下载测速地址有问题（注意，目前默认下载测速地址仅为一个带负载均衡轮询的重定向链接，会自动重定向到上面帖子里大家分享的公益下载测速地址，而这些地址在不同地区的可用性可能有差异，因此可能出现之前不行现在又正常的情况，如果想要稳定，建议自建，上面帖子写了几种自建方法）。

如果找了很多，都是一样 0.00，那么就要考虑其他可能性了。

二、测速的 IP 地址有问题：

你用来测速的 IP 地址，可能一些 TCP 测试是通的，但实际上因为各种原因导致不能建立 HTTP 链接（比如是回源 IP，比如是企业用户专用 IP 等等），因此你可以多尝试一些其他的 IP 看是否可行。

三、你的网络有问题：

这个就比较麻烦了，如果你现在是用电脑+宽带来使用 CFST 测速的，那么可以尝试关闭手机 WIFI 并打开流量，然后数据线连接电脑，设置好 USB 网络共享（不同手机系统不太一样，具体自行搜索哈），并拔掉电脑的网线，这样你的电脑现在就是走的手机流量数据网络了（如果手机流量数据和宽带不是一个运营商会更好排查），然后再次运行 CFST 测速看看结果是否改变（也可以同时尝试上面的排查方法来交叉验证）。

如果测速结果正常了，那么显然就是宽带网络的问题，如果还是一样的 0.00，那么就麻烦了。。。

# 一劳永逸加速所有使用 Cloudflare CDN 的网站（不需要再一个个添加域名到 Hosts 了）

我以前说过，开发该软件项目的目的就是为了通过改 Hosts 的方式来加速访问使用 Cloudflare CDN 的网站。

但就如 #8 所说，一个个添加域名到 Hosts 实在太麻烦了，于是我就找到了个一劳永逸的办法！可以看这个 还在一个个添加 Hosts？完美本地加速所有使用 Cloudflare CDN 的网站方法来了！ 和另一个依靠本地 DNS 服务来修改域名解析 IP 为自选 IP 的教程。

# 自动更新 Hosts

考虑到很多人获得最快 Cloudflare CDN IP 后，需要替换 Hosts 文件中的 IP。

可以看这个 Issues 获取 Windows/Linux 自动更新 Hosts 脚本！

问题反馈

如果你遇到什么问题，可以先去 Issues、Discussions 里看看是否有别人问过了（记得去看下 Closed 的）。
如果没找到类似问题，请新开个 Issues 来告诉我！

Note

注意！与 CFST 本身 反馈问题、功能建议 无关的，请前往项目内部论坛讨论（顶部的 💬 Discussions

如果帮到你的话就 "打赏" 一下吧~🎉✨

衍生项目

https://github.com/Hsia97/CFSTAPP
CFST 安卓版 APP #638
_https://github.com/xianshenglu/cloudflare-ip-tester-app_
CFST 安卓版 APP #202
_https://github.com/mingxiaoyu/luci-app-cloudflarespeedtest_
CFST OpenWrt 路由器插件版 #174
_https://github.com/immortalwrt-collections/openwrt-cdnspeedtest_
CFST OpenWrt 原生编译版本 #64
_https://github.com/GuangYu-yu/CloudflareST-Rust_
CFST Rust 版本
_https://github.com/masgzy/CloudflareST_
CFST 的分支衍生版本（依然是 Go）
_https://github.com/hoseinnikkhah/CloudflareSpeedTest-English_
English language version of CFST (Text language differences only) #64

此处仅收集了在本项目中宣传过的部分 CFST 相关衍生项目，如果有遗漏可以告诉我~

感谢项目

_https://github.com/Spedoske/CloudflareScanner_

因为该项目已经很长时间没更新了，而我又产生了很多功能需求，所以我临时学了下 Go 语言就上手了 (菜)...
本软件基于该项目，但已彻底重构并添加大量功能/修复BUG，根据大家的使用反馈积极添加/优化功能 (闲)...

手动编译

「点击展开查看内容」

为了方便，我是在编译的时候将版本号写入代码中的 version 变量，因此你手动编译时，需要像下面这样在 go build 命令后面加上 -ldflags 参数来指定版本号：

go build -ldflags "-s -w -X main.version=v1.0.0"
# 在 CloudflareSpeedTest 目录中通过命令行（例如 CMD、Bat 脚本）运行该命令，即可编译一个可在和当前设备同样系统、位数、架构的环境下运行的二进制程序（Go 会自动检测你的系统位数、架构）且版本号为 v1.0.0

如果想要在 Windows 64位系统下编译其他系统、架构、位数，那么需要指定 GOOS 和 GOARCH 变量。

例如在 Windows 系统下编译一个适用于 Linux 系统 amd 架构 64 位的二进制程序：

SET GOOS=linux
SET GOARCH=amd64
go build -ldflags "-s -w -X main.version=v1.0.0"

例如在 Linux 系统下编译一个适用于 Windows 系统 amd 架构 32 位的二进制程序：

GOOS=windows
GOARCH=386
go build -ldflags "-s -w -X main.version=v1.0.0"

可以运行 go tool dist list 来查看当前 Go 版本支持编译哪些组合。

当然，为了方便批量编译，我会专门指定一个变量为版本号，后续编译直接调用该版本号变量即可。
同时，批量编译的话，还需要分开放到不同文件夹才行（或者文件名不同），需要加上 -o 参数指定。

:: Windows 系统下是这样：
SET version=v1.0.0
SET GOOS=linux
SET GOARCH=amd64
go build -o Releases\cfst_linux_amd64\cfst -ldflags "-s -w -X main.version=%version%"

# Linux 系统下是这样：
version=v1.0.0
GOOS=windows
GOARCH=386
go build -o Releases/cfst_windows_386/cfst.exe -ldflags "-s -w -X main.version=${version}"

License

The GPL-3.0 License.

grpc/grpc-go

The Go language implementation of gRPC. HTTP/2 based RPC

gRPC-Go

The Go implementation of gRPC: A high performance, open source, general RPC framework that puts mobile and HTTP/2 first. For more information see the Go gRPC docs, or jump directly into the quick start.

Prerequisites

Go: any one of the two latest major releases.

Installation

Simply add the following import to your code, and then go [build|run|test] will automatically fetch the necessary dependencies:

import "google.golang.org/grpc"

Note: If you are trying to access grpc-go from China, see the FAQ below.

Learn more

Go gRPC docs, which include a quick start and API reference among other resources
Low-level technical docs from this repository
Performance benchmark
Examples
Contribution guidelines

FAQ

I/O Timeout Errors

The golang.org domain may be blocked from some countries. go get usually produces an error like the following when this happens:

$ go get -u google.golang.org/grpc
package google.golang.org/grpc: unrecognized import path "google.golang.org/grpc" (https fetch: Get https://google.golang.org/grpc?go-get=1: dial tcp 216.239.37.1:443: i/o timeout)

To build Go code, there are several options:

Set up a VPN and access google.golang.org through that.
With Go module support: it is possible to use the replace feature of go mod to create aliases for golang.org packages. In your project's directory:
```
go mod edit -replace=google.golang.org/grpc=github.com/grpc/grpc-go@latest
go mod tidy
go mod vendor
go build -mod=vendor
```
Again, this will need to be done for all transitive dependencies hosted on golang.org as well. For details, refer to golang/go issue #28652.

Compiling error, undefined: grpc.SupportPackageIsVersion

Please update to the latest version of gRPC-Go using go get google.golang.org/grpc.

How to turn on logging

The default logger is controlled by environment variables. Turn everything on like this:

$ export GRPC_GO_LOG_VERBOSITY_LEVEL=99
$ export GRPC_GO_LOG_SEVERITY_LEVEL=info

The RPC failed with error `"code = Unavailable desc = transport is closing"`

This error means the connection the RPC is using was closed, and there are many possible reasons, including:

mis-configured transport credentials, connection failed on handshaking
bytes disrupted, possibly by a proxy in between
server shutdown
Keepalive parameters caused connection shutdown, for example if you have configured your server to terminate connections regularly to trigger DNS lookups. If this is the case, you may want to increase your MaxConnectionAgeGrace, to allow longer RPC calls to finish.

It can be tricky to debug this because the error happens on the client side but the root cause of the connection being closed is on the server side. Turn on logging on both client and server, and see if there are any transport errors.

grafana/loki

Like Prometheus, but for logs.

Loki: like Prometheus, but for logs.

Loki is a horizontally-scalable, highly-available, multi-tenant log aggregation system inspired by Prometheus. It is designed to be very cost effective and easy to operate. It does not index the contents of the logs, but rather a set of labels for each log stream.

Compared to other log aggregation systems, Loki:

does not do full text indexing on logs. By storing compressed, unstructured logs and only indexing metadata, Loki is simpler to operate and cheaper to run.
indexes and groups log streams using the same labels you’re already using with Prometheus, enabling you to seamlessly switch between metrics and logs using the same labels that you’re already using with Prometheus.
is an especially good fit for storing Kubernetes Pod logs. Metadata such as Pod labels is automatically scraped and indexed.
has native support in Grafana (needs Grafana v6.0).

A Loki-based logging stack consists of 3 components:

Alloy is agent, responsible for gathering logs and sending them to Loki.
Loki is the main service, responsible for storing logs and processing queries.
Grafana for querying and displaying the logs.

Note that Alloy replaced Promtail in the stack, because Promtail is considered to be feature complete, and future development for logs collection will be in Grafana Alloy.

Loki is like Prometheus, but for logs: we prefer a multidimensional label-based approach to indexing, and want a single-binary, easy to operate system with no dependencies. Loki differs from Prometheus by focusing on logs instead of metrics, and delivering logs via push, instead of pull.

Getting started

⚠️ Helm Chart Migration

Effective March 16, 2026, the Grafana Loki Helm chart will be forked to a new repository grafana-community/helm-charts. The chart in the Loki repository will continue to be maintained for GEL users only. See #20705 for details.

Upgrading

Upgrading Loki

Documentation

Latest release
Upcoming release, at the tip of the main branch

Commonly used sections:

API documentation for getting logs into Loki.
Labels
Operations
Docker Driver Client is a Docker plugin to send logs directly to Loki from Docker containers.
LogCLI provides a command-line interface for querying logs.
Loki Canary monitors your Loki installation for missing logs.
Troubleshooting presents help dealing with error messages.
Loki in Grafana describes how to set up a Loki datasource in Grafana.

Getting Help

If you have any questions or feedback regarding Loki:

Search existing thread in the Grafana Labs community forum for Loki: https://community.grafana.com
Ask a question on the Loki Slack channel. To invite yourself to the Grafana Slack, visit https://slack.grafana.com/ and join the #loki channel.
File an issue for bugs, issues and feature suggestions.
Send an email to lokiproject@googlegroups.com, or use the web interface.
UI issues should be filed directly in Grafana.

Your feedback is always welcome.

Contributing

Refer to CONTRIBUTING.md

Building from source

Loki can be run in a single host, no-dependencies mode using the following commands.

You need an up-to-date version of Go, we recommend using the version found in our Makefile

# Checkout source code
$ git clone https://github.com/grafana/loki
$ cd loki

# Build binary
$ go build ./cmd/loki

# Run executable
$ ./loki -config.file=./cmd/loki/loki-local-config.yaml

Alternatively, on Unix systems you can use make to build the binary, which adds additional arguments to the go build command.

# Build binary
$ make loki

# Run executable
$ ./cmd/loki/loki -config.file=./cmd/loki/loki-local-config.yaml

To run multiple Loki tenants locally, ensure that auth_enabled is set to true and provide a runtime config with any tenant specific overrides.

# Build binary
$ make loki

# Run executable
./loki -config.file=./cmd/loki/loki-local-multi-tenant-config.yaml -runtime-config.file=./cmd/loki/loki-overrides.yaml

Adopters

Please see ADOPTERS.md for some of the organizations using Loki today. If you would like to add your organization to the list, please open a PR to add it to the list.

License

Grafana Loki is distributed under AGPL-3.0-only. For Apache-2.0 exceptions, see LICENSING.md.

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.

glanceapp/glance

A self-hosted dashboard that puts all your feeds in one place

Glance

Install • Configuration • Discord • Sponsor

Community widgets • Preconfigured pages • Themes

A lightweight, highly customizable dashboard that displays
your feeds in a beautiful, streamlined interface

Features

Various widgets

RSS feeds
Subreddit posts
Hacker News posts
Weather forecasts
YouTube channel uploads
Twitch channels
Market prices
Docker containers status
Server stats
Custom widgets
and many more...

Fast and lightweight

Low memory usage
Few dependencies
Minimal vanilla JS
Single <20mb binary available for multiple OSs & architectures and just as small Docker container
Uncached pages usually load within ~1s (depending on internet speed and number of widgets)

Tons of customizability

Different layouts
As many pages/tabs as you need
Numerous configuration options for each widget
Multiple styles for some widgets
Custom CSS

Optimized for mobile devices

Because you'll want to take it with you on the go.

Themeable

Easily create your own theme by tweaking a few numbers or choose from one of the already available themes.

Configuration

Configuration is done through YAML files, to learn more about how the layout works, how to add more pages and how to configure widgets, visit the configuration documentation.

Preview example configuration file

pages:
  - name: Home
    columns:
      - size: small
        widgets:
          - type: calendar
            first-day-of-week: monday

          - type: rss
            limit: 10
            collapse-after: 3
            cache: 12h
            feeds:
              - url: https://selfh.st/rss/
                title: selfh.st
                limit: 4
              - url: https://ciechanow.ski/atom.xml
              - url: https://www.joshwcomeau.com/rss.xml
                title: Josh Comeau
              - url: https://samwho.dev/rss.xml
              - url: https://ishadeed.com/feed.xml
                title: Ahmad Shadeed

          - type: twitch-channels
            channels:
              - theprimeagen
              - j_blow
              - piratesoftware
              - cohhcarnage
              - christitustech
              - EJ_SA

      - size: full
        widgets:
          - type: group
            widgets:
              - type: hacker-news
              - type: lobsters

          - type: videos
            channels:
              - UCXuqSBlHAE6Xw-yeJA0Tunw # Linus Tech Tips
              - UCR-DXc1voovS8nhAvccRZhg # Jeff Geerling
              - UCsBjURrPoezykLs9EqgamOA # Fireship
              - UCBJycsmduvYEL83R_U4JriQ # Marques Brownlee
              - UCHnyfMqiRRG1u-2MsSQLbXA # Veritasium

          - type: group
            widgets:
              - type: reddit
                subreddit: technology
                show-thumbnails: true
              - type: reddit
                subreddit: selfhosted
                show-thumbnails: true

      - size: small
        widgets:
          - type: weather
            location: London, United Kingdom
            units: metric
            hour-format: 12h

          - type: markets
            markets:
              - symbol: SPY
                name: S&P 500
              - symbol: BTC-USD
                name: Bitcoin
              - symbol: NVDA
                name: NVIDIA
              - symbol: AAPL
                name: Apple
              - symbol: MSFT
                name: Microsoft

          - type: releases
            cache: 1d
            repositories:
              - glanceapp/glance
              - go-gitea/gitea
              - immich-app/immich
              - syncthing/syncthing

Installation

Choose one of the following methods:

Docker compose using provided directory structure (recommended)

Create a new directory called glance as well as the template files within it by running:

mkdir glance && cd glance && curl -sL https://github.com/glanceapp/docker-compose-template/archive/refs/heads/main.tar.gz | tar -xzf - --strip-components 2

click here to view the files that will be created

Then, edit the following files as desired:

docker-compose.yml to configure the port, volumes and other containery things
config/home.yml to configure the widgets or layout of the home page
config/glance.yml if you want to change the theme or add more pages

Other files you may want to edit

.env to configure environment variables that will be available inside configuration files
assets/user.css to add custom CSS

When ready, run:

docker compose up -d

If you encounter any issues, you can check the logs by running:

docker compose logs

Docker compose manual

Create a docker-compose.yml file with the following contents:

services:
  glance:
    container_name: glance
    image: glanceapp/glance
    restart: unless-stopped
    volumes:
      - ./config:/app/config
    ports:
      - 8080:8080

Then, create a new directory called config and download the example starting glance.yml file into it by running:

mkdir config && wget -O config/glance.yml https://raw.githubusercontent.com/glanceapp/glance/refs/heads/main/docs/glance.yml

Feel free to edit the glance.yml file to your liking, and when ready run:

docker compose up -d

If you encounter any issues, you can check the logs by running:

docker logs glance

Manual binary installation

Precompiled binaries are available for Linux, Windows and macOS (x86, x86_64, ARM and ARM64 architectures).

Linux

Visit the latest release page for available binaries. You can place the binary in /opt/glance/ and have it start with your server via a systemd service. By default, when running the binary, it will look for a glance.yml file in the directory it's placed in. To specify a different path for the config file, use the --config option:

/opt/glance/glance --config /etc/glance.yml

To grab a starting template for the config file, run:

wget https://raw.githubusercontent.com/glanceapp/glance/refs/heads/main/docs/glance.yml

Windows

Download and extract the executable from the latest release (most likely the file called glance-windows-amd64.zip if you're on a 64-bit system) and place it in a folder of your choice. Then, create a new text file called glance.yml in the same folder and paste the content from here in it. You should then be able to run the executable and access the dashboard by visiting http://localhost:8080 in your browser.

Other

Glance can also be installed through the following 3rd party channels:

Common issues

Requests timing out

The most common cause of this is when using Pi-Hole, AdGuard Home or other ad-blocking DNS services, which by default have a fairly low rate limit. Depending on the number of widgets you have in a single page, this limit can very easily be exceeded. To fix this, increase the rate limit in the settings of your DNS service.

If using Podman, in some rare cases the timeout can be caused by an unknown issue, in which case it may be resolved by adding the following to the bottom of your docker-compose.yml file:

networks:
  podman:
    external: true

Broken layout for markets, bookmarks or other widgets

This is almost always caused by the browser extension Dark Reader. To fix this, disable dark mode for the domain where Glance is hosted.

cannot unmarshal !!map into []glance.page

The most common cause of this is having a pages key in your glance.yml and then also having a pages key inside one of your included pages. To fix this, remove the pages key from the top of your included pages.

FAQ

Does the information on the page update automatically?

No, a page refresh is required to update the information. Some things do dynamically update where it makes sense, like the clock widget and the relative time showing how long ago something happened.

How frequently do widgets update?

No requests are made periodically in the background, information is only fetched upon loading the page and then cached. The default cache lifetime is different for each widget and can be configured.

Can I create my own widgets?

Yes, there are multiple ways to create custom widgets:

iframe widget - allows you to embed things from other websites
html widget - allows you to insert your own static HTML
extension widget - fetch HTML from a URL
custom-api widget - fetch JSON from a URL and render it using custom HTML

Can I change the title of a widget?

Yes, the title of all widgets can be changed by specifying the title property in the widget's configuration:

- type: rss
  title: My custom title

- type: markets
  title: My custom title

- type: videos
  title: My custom title

# and so on for all widgets...

Feature requests

New feature suggestions are always welcome and will be considered, though please keep in mind that some of them may be out of scope for what the project is trying to achieve (or is reasonably capable of). If you have an idea for a new feature and would like to share it, you can do so here.

Feature requests are tagged with one of the following:

Roadmap - will be implemented in a future release
Backlog - may be implemented in the future but needs further feedback or interest from the community
Icebox - no plans to implement as it doesn't currently align with the project's goals or capabilities, may be revised at a later date

Building from source

Choose one of the following methods:

Build binary with Go

Requirements: Go >= v1.23

To build the project for your current OS and architecture, run:

go build -o build/glance .

To build for a specific OS and architecture, run:

GOOS=linux GOARCH=amd64 go build -o build/glance .

click here for a full list of GOOS and GOARCH combinations

Alternatively, if you just want to run the app without creating a binary, like when you're testing out changes, you can run:

go run .

Build project and Docker image with Docker

Requirements: Docker

To build the project and image using just Docker, run:

(replace owner with your name or organization)

docker build -t owner/glance:latest .

If you wish to push the image to a registry (by default Docker Hub), run:

docker push owner/glance:latest

Contributing guidelines

Before working on a new feature it's preferable to submit a feature request first and state that you'd like to implement it yourself
Please don't submit PRs for feature requests that are either in the roadmap^[1], backlog^[2] or icebox^[3]
Use dev for the base branch if you're adding new features or fixing bugs, otherwise use main
Avoid introducing new dependencies
Avoid making backwards-incompatible configuration changes
Avoid introducing new colors or hard-coding colors, use the standard primary, positive and negative
For icons, try to use heroicons where applicable
Provide a screenshot of the changes if UI related where possible
No package.json

^{[1] [2] [3]}

[1] The feature likely already has work put into it that may conflict with your implementation

[2] The demand, implementation or functionality for this feature is not yet clear

[3] No plans to add this feature for the time being

Thank you

To all the people who were generous enough to sponsor the project and to everyone who has contributed in any way, be it PRs, submitting issues, helping others in the discussions or Discord server, creating guides and tools or just mentioning Glance on social media. Your support is greatly appreciated and helps keep the project going.

tailscale/tailscale

The easiest, most secure way to use WireGuard and 2FA.

Tailscale

https://tailscale.com

Private WireGuard® networks made easy

Overview

This repository contains the majority of Tailscale's open source code. Notably, it includes the tailscaled daemon and the tailscale CLI tool. The tailscaled daemon runs on Linux, Windows, macOS, and to varying degrees on FreeBSD and OpenBSD. The Tailscale iOS and Android apps use this repo's code, but this repo doesn't contain the mobile GUI code.

Other Tailscale repos of note:

the Android app is at https://github.com/tailscale/tailscale-android
the Synology package is at https://github.com/tailscale/tailscale-synology
the QNAP package is at https://github.com/tailscale/tailscale-qpkg
the Chocolatey packaging is at https://github.com/tailscale/tailscale-chocolatey

For background on which parts of Tailscale are open source and why, see https://tailscale.com/opensource/.

Using

We serve packages for a variety of distros and platforms at https://pkgs.tailscale.com.

Other clients

The macOS, iOS, and Windows clients use the code in this repository but additionally include small GUI wrappers. The GUI wrappers on non-open source platforms are themselves not open source.

Building

We always require the latest Go release, currently Go 1.26. (While we build releases with our Go fork, its use is not required.)

go install tailscale.com/cmd/tailscale{,d}

If you're packaging Tailscale for distribution, use build_dist.sh instead, to burn commit IDs and version info into the binaries:

./build_dist.sh tailscale.com/cmd/tailscale
./build_dist.sh tailscale.com/cmd/tailscaled

If your distro has conventions that preclude the use of build_dist.sh, please do the equivalent of what it does in your distro's way, so that bug reports contain useful version information.

Bugs

Please file any issues about this code or the hosted service on the issue tracker.

Contributing

PRs welcome! But please file bugs. Commit messages should reference bugs.

We require Developer Certificate of Origin Signed-off-by lines in commits.

See commit-messages.md (or skim git log) for our commit message style.

About Us

Tailscale is primarily developed by the people at https://github.com/orgs/tailscale/people. For other contributors, see:

Legal

WireGuard is a registered trademark of Jason A. Donenfeld.

alireza0/s-ui

An advanced Web Panel • Built for SagerNet/Sing-Box

S-UI

An Advanced Web Panel • Built on SagerNet/Sing-Box

Disclaimer: This project is only for personal learning and communication, please do not use it for illegal purposes, please do not use it in a production environment

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

Want to contribute? See CONTRIBUTING.md for development setup, coding conventions, testing, and the pull request process.

Quick Overview

Features	Enable?
Multi-Protocol	✔️
Multi-Language	✔️
Multi-Client/Inbound	✔️
Advanced Traffic Routing Interface	✔️
Client & Traffic & System Status	✔️
Subscription Link (link/json/clash + info)	✔️
Dark/Light Theme	✔️
API Interface	✔️

Supported Platforms

Platform	Architecture	Status
Linux	amd64, arm64, armv7, armv6, armv5, 386, s390x	✅ Supported
Windows	amd64, 386, arm64	✅ Supported
macOS	amd64, arm64	🚧 Experimental

Screenshots

Other UI Screenshots

API Documentation

API-Documentation Wiki

Default Installation Information

Panel Port: 2095
Panel Path: /app/
Subscription Port: 2096
Subscription Path: /sub/
User/Password: admin

Install & Upgrade to Latest Version

Linux/macOS

bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/master/install.sh)

Windows

Download the latest Windows release from GitHub Releases
Extract the ZIP file
Run install-windows.bat as Administrator
Follow the installation wizard

Install legacy Version

Step 1: To install your desired legacy version, add the version to the end of the installation command. e.g., ver 1.0.0:

VERSION=1.0.0 && bash <(curl -Ls https://raw.githubusercontent.com/alireza0/s-ui/$VERSION/install.sh) $VERSION

Manual installation

Linux/macOS

Get the latest version of S-UI based on your OS/Architecture from GitHub: https://github.com/alireza0/s-ui/releases/latest
OPTIONAL Get the latest version of s-ui.sh https://raw.githubusercontent.com/alireza0/s-ui/master/s-ui.sh
OPTIONAL Copy s-ui.sh to /usr/bin/ and run chmod +x /usr/bin/s-ui.
Extract s-ui tar.gz file to a directory of your choice and navigate to the directory where you extracted the tar.gz file.
Copy *.service files to /etc/systemd/system/ and run systemctl daemon-reload.
Enable autostart and start S-UI service using systemctl enable s-ui --now
Start sing-box service using systemctl enable sing-box --now

Windows

Get the latest Windows version from GitHub: https://github.com/alireza0/s-ui/releases/latest
Download the appropriate Windows package (e.g., s-ui-windows-amd64.zip)
Extract the ZIP file to a directory of your choice
Run install-windows.bat as Administrator
Follow the installation wizard
Access the panel at http://localhost:2095/app

Uninstall S-UI

sudo -i

systemctl disable s-ui  --now

rm -f /etc/systemd/system/sing-box.service
systemctl daemon-reload

rm -fr /usr/local/s-ui
rm /usr/bin/s-ui

Install using Docker

Click for details

Usage

Step 1: Install Docker

curl -fsSL https://get.docker.com | sh

Step 2: Install S-UI

Docker compose method

mkdir s-ui && cd s-ui
wget -q https://raw.githubusercontent.com/alireza0/s-ui/master/docker-compose.yml
docker compose up -d

Use docker

mkdir s-ui && cd s-ui
docker run -itd \
    -p 2095:2095 -p 2096:2096 -p 443:443 -p 80:80 \
    -v $PWD/db/:/app/db/ \
    -v $PWD/cert/:/root/cert/ \
    --name s-ui --restart=unless-stopped \
    alireza7/s-ui:latest

Build your own image

git clone https://github.com/alireza0/s-ui
git submodule update --init --recursive
docker build -t s-ui .

Manual run ( contribution )

Click for details

Build and run whole project

./runSUI.sh

Clone the repository

# clone repository
git clone https://github.com/alireza0/s-ui
# clone submodules
git submodule update --init --recursive

- Frontend

Visit s-ui-frontend for frontend code

- Backend

Please build frontend once before!

To build backend:

# remove old frontend compiled files
rm -fr web/html/*
# apply new frontend compiled files
cp -R frontend/dist/ web/html/
# build
go build -o sui main.go

To run backend (from root folder of repository):

./sui

Languages

English
Farsi
Vietnamese
Chinese (Simplified)
Chinese (Traditional)
Russian

Features

Supported protocols:
- General: Mixed, SOCKS, HTTP, HTTPS, Direct, Redirect, TProxy
- V2Ray based: VLESS, VMess, Trojan, Shadowsocks
- Other protocols: ShadowTLS, Hysteria, Hysteria2, Naive, TUIC
Supports XTLS protocols
An advanced interface for routing traffic, incorporating PROXY Protocol, External, and Transparent Proxy, SSL Certificate, and Port
An advanced interface for inbound and outbound configuration
Clients’ traffic cap and expiration date
Displays online clients, inbounds and outbounds with traffic statistics, and system status monitoring
Subscription service with ability to add external links and subscription
HTTPS for secure access to the web panel and subscription service (self-provided domain + SSL certificate)
Dark/Light theme

Environment Variables

Click for details

Usage

Variable	Type	Default
SUI_LOG_LEVEL	`"debug"` \| `"info"` \| `"warn"` \| `"error"`	`"info"`
SUI_DEBUG	`boolean`	`false`
SUI_BIN_FOLDER	`string`	`"bin"`
SUI_DB_FOLDER	`string`	`"db"`
SINGBOX_API	`string`	-

SSL Certificate

Click for details

Certbot

snap install core; snap refresh core
snap install --classic certbot
ln -s /snap/bin/certbot /usr/bin/certbot

certbot certonly --standalone --register-unsafely-without-email --non-interactive --agree-tos -d <Your Domain Name>

Stargazers over Time

iawia002/lux

👾 Fast and simple video download library and CLI tool written in Go

Lux

Let there be Lux!

👾 Lux is a fast and simple video downloader built with Go.

Installation

Prerequisites

The following dependencies are required and must be installed separately.

FFmpeg

Note: FFmpeg does not affect the download, only affects the final file merge.

Install via `go install`

To install Lux, use go install, or download the binary file from Releases page.

$ go install github.com/iawia002/lux@latest

Homebrew (macOS only)

For macOS users, you can install lux via:

$ brew install lux

Arch Linux

For Arch Users AUR package is available.

Void Linux

For Void linux users, you can install lux via:

$ xbps-install -S lux

Scoop on Windows

$ scoop install lux

Chocolatey on Windows

$ choco install lux

Cask on Windows/macOS/Linux

$ cask install github.com/iawia002/lux

Getting Started

Usage:

lux [OPTIONS] URL [URL...]

Download a video

$ lux "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

 Site:      YouTube youtube.com
 Title:     Rick Astley - Never Gonna Give You Up (Video)
 Type:      video
 Stream:
     [248]  -------------------
     Quality:         1080p video/webm; codecs="vp9"
     Size:            63.93 MiB (67038963 Bytes)
     # download with: lux -f 248 ...

 41.88 MiB / 63.93 MiB [=================>-------------]  65.51% 4.22 MiB/s 00m05s

The -i option displays all available quality of video without downloading.

$ lux -i "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

 Site:      YouTube youtube.com
 Title:     Rick Astley - Never Gonna Give You Up (Video)
 Type:      video
 Streams:   # All available quality
     [248]  -------------------
     Quality:         1080p video/webm; codecs="vp9"
     Size:            49.29 MiB (51687554 Bytes)
     # download with: lux -f 248 ...

     [137]  -------------------
     Quality:         1080p video/mp4; codecs="avc1.640028"
     Size:            43.45 MiB (45564306 Bytes)
     # download with: lux -f 137 ...

     [398]  -------------------
     Quality:         720p video/mp4; codecs="av01.0.05M.08"
     Size:            37.12 MiB (38926432 Bytes)
     # download with: lux -f 398 ...

     [136]  -------------------
     Quality:         720p video/mp4; codecs="avc1.4d401f"
     Size:            31.34 MiB (32867324 Bytes)
     # download with: lux -f 136 ...

     [247]  -------------------
     Quality:         720p video/webm; codecs="vp9"
     Size:            31.03 MiB (32536181 Bytes)
     # download with: lux -f 247 ...

Use lux -f stream "URL" to download a specific stream listed in the output of -i option.

Download anything else

If Lux is provided the URL of a specific resource, then it will be downloaded directly:

$ lux "https://img9.bcyimg.com/drawer/15294/post/1799t/1f5a87801a0711e898b12b640777720f.jpg"

lux doesn't support this URL right now, but it will try to download it directly

 Site:      Universal
 Title:     1f5a87801a0711e898b12b640777720f
 Type:      image/jpeg
 Stream:
     [default]  -------------------
     Size:            1.00 MiB (1051042 Bytes)
     # download with: lux -f default "URL"

 1.00 MiB / 1.00 MiB [===================================] 100.00% 1.21 MiB/s 0s

Download playlist

The -p option downloads an entire playlist instead of a single video.

$ lux -i -p "https://www.bilibili.com/bangumi/play/ep198061"

 Site:      哔哩哔哩 bilibili.com
 Title:     Doctor X 第四季：第一集
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            845.66 MiB (886738354 Bytes)
     # download with: lux -f default "URL"


 Site:      哔哩哔哩 bilibili.com
 Title:     Doctor X 第四季：第二集
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            930.71 MiB (975919195 Bytes)
     # download with: lux -f default "URL"

......

You can use the -start, -end or -items option to specify the download range of the list:

-start
    	Playlist video to start at (default 1)
-end
    	Playlist video to end at
-items
    	Playlist video items to download. Separated by commas like: 1,5,6,8-10

For bilibili playlists only:

-eto
  File name of each bilibili episode doesn't include the playlist title

Multiple inputs

You can also download multiple URLs at once:

$ lux -i "https://www.bilibili.com/video/av21877586" "https://www.bilibili.com/video/av21990740"

 Site:      哔哩哔哩 bilibili.com
 Title:     【莓机会了】甜到虐哭的13集单集MAD「我现在什么都不想干,更不想看14集」
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            51.88 MiB (54403767 Bytes)
     # download with: lux -f default "URL"


 Site:      哔哩哔哩 bilibili.com
 Title:     【莓救了】甜到虐哭！！！国家队单集MAD-当熟悉的bgm响起，眼泪从脸颊滑下
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            77.63 MiB (81404093 Bytes)
     # download with: lux -f default "URL"

These URLs will be downloaded one by one.

You can also use the -F option to read URLs from file:

$ lux -F ~/Desktop/u.txt

 Site:      微博 weibo.com
 Title:     在Google，我们设计什么？ via@阑夕
 Type:      video
 Stream:
     [default]  -------------------
     Size:            19.19 MiB (20118196 Bytes)
     # download with: lux -f default "URL"

 19.19 MiB / 19.19 MiB [=================================] 100.00% 9.69 MiB/s 1s

......

You can use the -start, -end or -items option to specify the download range of the list:

-start
    	File line to start at (default 1)
-end
    	File line to end at
-items
    	File lines to download. Separated by commas like: 1,5,6,8-10

Resume a download

Ctrl+C interrupts a download.

A temporary .download file is kept in the output directory. If lux is ran with the same arguments, then the download progress will resume from the last session.

Auto retry

lux will auto retry when the download failed, you can specify the retry times by -retry option (default is 100).

Cookies

Cookies can be provided to lux with the -c option if they are required for accessing the video.

Cookies can be the following format or Netscape Cookie format:

name=value; name2=value2; ...

Cookies can be a string or a text file, supply cookies in one of the two following ways.

As a string:

$ lux -c "name=value; name2=value2" "https://www.bilibili.com/video/av20203945"

As a text file:

$ lux -c cookies.txt "https://www.bilibili.com/video/av20203945"

Proxy

You can set the HTTP/SOCKS5 proxy using environment variables:

$ HTTP_PROXY="http://127.0.0.1:1087/" lux -i "https://www.youtube.com/watch?v=Gnbch2osEeo"

$ HTTP_PROXY="socks5://127.0.0.1:1080/" lux -i "https://www.youtube.com/watch?v=Gnbch2osEeo"

Multi-Thread

Use --multi-thread or -m multiple threads to download single video.

Use --thread or -n option to set the number of download threads(default is 10).

Note: If the video has multi fragment, the number of actual download threads will increase.

For example:

If -n is set to 10, and the video has 2 fragments, then 20 threads will actually be used.

If the video has 20 fragments, only 10 fragments are downloaded in the same time, the actual threads count is 100.

Special Tips: Use too many threads in mgtv download will cause HTTP 403 error, we recommend setting the number of threads to 1.

Short link

bilibili

You can just use av or ep number to download bilibili's video:

$ lux -i ep198381 av21877586

 Site:      哔哩哔哩 bilibili.com
 Title:     狐妖小红娘：第79话 南国公主的吃货本色
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            485.23 MiB (508798478 Bytes)
     # download with: lux -f default "URL"


 Site:      哔哩哔哩 bilibili.com
 Title:     【莓机会了】甜到虐哭的13集单集MAD「我现在什么都不想干,更不想看14集」
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            51.88 MiB (54403767 Bytes)
     # download with: lux -f default "URL"

Use specified Referrer

A Referrer can be used for the request with the -r option:

$ lux -r "https://www.bilibili.com/video/av20383055/" "http://cn-scnc1-dx.acgvideo.com/"

Specify the output path and name

The -o option sets the path, and -O option sets the name of the downloaded file:

$ lux -o ../ -O "hello" "https://example.com"

Debug Mode

The -d option outputs network request messages:

$ lux -i -d "http://www.bilibili.com/video/av20088587"

URL:         http://www.bilibili.com/video/av20088587
Method:      GET
Headers:     http.Header{
    "Referer":         {"http://www.bilibili.com/video/av20088587"},
    "Accept":          {"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"},
    "Accept-Charset":  {"UTF-8,*;q=0.5"},
    "Accept-Encoding": {"gzip,deflate,sdch"},
    "Accept-Language": {"en-US,en;q=0.8"},
    "User-Agent":      {"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.146 Safari/537.36"},
}
Status Code: 200

URL:         https://interface.bilibili.com/v2/playurl?appkey=84956560bc028eb7&cid=32782944&otype=json&qn=116&quality=116&type=&sign=fb2e3f261fec398652f96d358517e535
Method:      GET
Headers:     http.Header{
    "Accept-Charset":  {"UTF-8,*;q=0.5"},
    "Accept-Encoding": {"gzip,deflate,sdch"},
    "Accept-Language": {"en-US,en;q=0.8"},
    "User-Agent":      {"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.146 Safari/537.36"},
    "Referer":         {"https://interface.bilibili.com/v2/playurl?appkey=84956560bc028eb7&cid=32782944&otype=json&qn=116&quality=116&type=&sign=fb2e3f261fec398652f96d358517e535"},
    "Accept":          {"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"},
}
Status Code: 200

 Site:      哔哩哔哩 bilibili.com
 Title:     燃油动力的遥控奥迪R8跑赛道
 Type:      video
 Streams:   # All available quality
     [default]  -------------------
     Quality:         高清 1080P
     Size:            64.38 MiB (67504795 Bytes)
     # download with: lux -f default "URL"

Reuse extracted data

The -j option will print the extracted data in JSON format.

$ lux -j "https://www.bilibili.com/video/av20203945"

{
    "site": "哔哩哔哩 bilibili.com",
    "title": "【2018拜年祭单品】相遇day by day",
    "type": "video",
    "streams": {
        "15": {
            "urls": [
                {
                    "url": "...",
                    "size": 18355205,
                    "ext": "flv"
                }
            ],
            "quality": "流畅 360P",
            "size": 18355205
        },
        "32": {
            "urls": [
                {
                    "url": "...",
                    "size": 40058632,
                    "ext": "flv"
                }
            ],
            "quality": "清晰 480P",
            "size": 40058632
        },
        "64": {
            "urls": [
                {
                    "url": "...",
                    "size": 82691087,
                    "ext": "flv"
                }
            ],
            "quality": "高清 720P",
            "size": 82691087
        },
        "80": {
            "urls": [
                {
                    "url": "...",
                    "size": 121735559,
                    "ext": "flv"
                }
            ],
            "quality": "高清 1080P",
            "size": 121735559
        }
    }
}

Options

  -i	Information only
  -F string
    	URLs file path
  -d	Debug mode
  -j	Print extracted data
  -s	Minimum outputs
  -v	Show version

Download:

  -f string
    	Select specific stream to download
  -p	Download playlist
  -n int
    	The number of download thread (only works for multiple-parts video) (default 10)
  -c string
    	Cookie
  -r string
    	Use specified Referrer
  -cs int
    	HTTP chunk size for downloading (in MB) (default 1)

Network:

  -retry int
    	How many times to retry when the download failed (default 10)

Playlist:

  -start int
    	Playlist video to start at (default 1)
  -end int
    	Playlist video to end at
  -items string
    	Playlist video items to download. Separated by commas like: 1,5,6,8-10

Filesystem:

  -o string
    	Specify the output path
  -O string
    	Specify the output file name

Subtitle:

  -C	Download subtitles
  -C -items en,zh
    	Download specific languages (YouTube only)
  -C -items en,zh -embed 
    	Embed subtitles into the video (YouTube only)

Youku:

  -ccode string
    	Youku ccode (default "0502")
  -ckey string
    	Youku ckey (default "7B19C0AB12633B22E7FE81271162026020570708D6CC189E4924503C49D243A0DE6CD84A766832C2C99898FC5ED31F3709BB3CDD82C96492E721BDD381735026")
  -password string
    	Youku password

aria2:

Note: If you use aria2 to download, you need to merge the multi-part videos yourself.

  -aria2
    	Use Aria2 RPC to download
  -aria2addr string
    	Aria2 Address (default "localhost:6800")
  -aria2method string
    	Aria2 Method (default "http")
  -aria2token string
    	Aria2 RPC Token

Supported Sites

Site	URL	🎬 Videos	🌁 Images	🔊 Audio	📚 Playlist	🍪 VIP adaptation
抖音	https://www.douyin.com	✓	✓
哔哩哔哩	https://www.bilibili.com	✓			✓	✓
半次元	https://bcy.net		✓
pixivision	https://www.pixivision.net		✓
优酷	https://www.youku.com	✓				✓
YouTube	https://www.youtube.com	✓			✓
西瓜视频（头条）	https://m.toutiao.com, https://v.ixigua.com, https://www.ixigua.com	✓
爱奇艺	https://www.iqiyi.com	✓
新片场	https://www.xinpianchang.com	✓
芒果 TV	https://www.mgtv.com	✓
糖豆广场舞	https://www.tangdou.com	✓
Tumblr	https://www.tumblr.com	✓	✓
Vimeo	https://vimeo.com	✓
Facebook	https://facebook.com	✓
斗鱼视频	https://v.douyu.com	✓
秒拍	https://www.miaopai.com	✓
微博	https://weibo.com	✓
Instagram	https://www.instagram.com	✓	✓
Threads	https://www.threads.net	✓	✓
Twitter	https://twitter.com	✓
腾讯视频	https://v.qq.com	✓
网易云音乐	https://music.163.com	✓
音悦台	https://yinyuetai.com	✓
极客时间	https://time.geekbang.org	✓
Pornhub	https://pornhub.com	✓
XVIDEOS	https://xvideos.com	✓
聯合新聞網	https://udn.com	✓
TikTok	https://www.tiktok.com	✓
Pinterest	https://www.pinterest.com	✓
好看视频	https://haokan.baidu.com	✓
AcFun	https://www.acfun.cn	✓			✓
Eporner	https://eporner.com	✓
StreamTape	https://streamtape.com	✓
虎扑	https://hupu.com	✓
虎牙视频	https://v.huya.com	✓
喜马拉雅	https://www.ximalaya.com			✓
快手	https://www.kuaishou.com	✓
Reddit	https://www.reddit.com	✓	✓
VKontakte	https://vk.com	✓
知乎	https://zhihu.com	✓
Rumble	https://rumble.com	✓
小红书	https://xiaohongshu.com	✓
Zing MP3	https://zingmp3.vn	✓		✓
Bitchute	https://www.bitchute.com	✓
Odysee	https://odysee.com	✓		✓

Known issues

优酷

优酷的 ccode 经常变化导致 lux 不可用，如果你知道有新的可用的 ccode，可以直接使用 lux -ccode ... 而不用等待 lux 更新（当然，也欢迎你给我们提一个 Pull request 来更新默认的 ccode）

最好是每次下载都附带登录过的 Cookie 以避免部分 ccode 的问题

西瓜/头条视频

西瓜/头条视频必须带 Cookie 才能下载成功，西瓜和头条可共用西瓜视频的 Cookie，Cookie 的有效期可能较短，下载失败就更新 Cookie 尝试：

$ lux -c "msToken=yoEh0-qLUq4obZ8Sfxsem_CxCo9R3NM6ViTrWaRcM1...; ttwid=1%7C..." "https://m.toutiao.com/is/iYbTfJ79/"

Contributing

Lux is an open source project and built on the top of open-source projects. Check out the Contributing Guide to get started.