octopus

Octopus

A Simple, Beautiful, and Elegant LLM API Aggregation Service for Individuals

English | 简体中文

✨ Features

• 🔀 Multi-Channel Aggregation - Connect multiple LLM provider channels with unified management
• 🔄 Protocol Conversion - Seamless conversion between OpenAI Chat / OpenAI Responses / Anthropic API formats
• 💰 Price Sync - Automatic model pricing updates
• 🔃 Model Sync - Automatic synchronization of available model lists with channels
• 🛡️ Automatic Failover - Automatically switches to an available channel when an upstream channel fails
• 🔍 Real-Time End-to-End Request Visualization - Watch the complete request path in the frontend from the moment the client sends it
• 🚧 Upstream Error Shielding - Intercept all upstream errors to keep agent tasks running without interruption
• 📊 Analytics - Comprehensive request statistics, token consumption, and cost tracking
• 🎨 Elegant UI - Clean and beautiful web management panel
• 📦 Lightweight Single-Binary Deployment - Run as a single binary with no external runtime dependencies
• 🗄️ Multi-Database Support - Support for SQLite, MySQL, PostgreSQL

🚀 Quick Start

🐳 Docker

Run directly:

docker run -d --name octopus -v /path/to/data:/app/data -p 8080:8080 bestrui/octopus

Or use docker compose:

wget https://raw.githubusercontent.com/bestruirui/octopus/refs/heads/master/docker-compose.yml
docker compose up -d

📦 Download from Release

Download the binary for your platform from Releases, then run:

./octopus start

🛠️ Build from Source

Requirements:

• Go 1.24.4
• Node.js 18+
• pnpm

# Clone the repository
git clone https://github.com/bestruirui/octopus.git
cd octopus
# Build frontend
cd web && pnpm install && pnpm run build
# Start the backend service
go run main.go start 

💡 Tip: The frontend build artifacts are embedded into the Go binary, so you must build the frontend before starting the backend.

Development Mode

cd web && pnpm install && pnpm run dev
## Open a new terminal, start the backend service
go run main.go start
## Access the frontend at
http://localhost:5173

🔐 Default Credentials

After first launch, visit http://localhost:8080 and log in to the management panel with:

• Username: admin
• Password: admin

⚠️ Security Notice: Please change the default password immediately after first login.

📝 Configuration File

The configuration file is located at data/config.json by default and is automatically generated on first startup.

Complete Configuration Example:

{
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  },
  "database": {
    "type": "sqlite",
    "path": "data/data.db"
  },
  "log": {
    "level": "info"
  }
}

Configuration Options:

Option	Description	Default
server.host	Listen address	0.0.0.0
server.port	Server port	8080
database.type	Database type	sqlite
database.path	Database connection string	data/data.db
log.level	Log level	info

Database Configuration:

Three database types are supported:

Type	database.type	database.path Format
SQLite	sqlite	data/data.db
MySQL	mysql	user:password@tcp(host:port)/dbname
PostgreSQL	postgres	postgresql://user:password@host:port/dbname?sslmode=disable

MySQL Configuration Example:

{
  "database": {
    "type": "mysql",
    "path": "root:password@tcp(127.0.0.1:3306)/octopus"
  }
}

PostgreSQL Configuration Example:

{
  "database": {
    "type": "postgres",
    "path": "postgresql://user:password@localhost:5432/octopus?sslmode=disable"
  }
}

💡 Tip: MySQL and PostgreSQL require manual database creation. The application will automatically create the table structure.

🌐 Environment Variables

All configuration options can be overridden via environment variables using the format OCTOPUS_ + configuration path (joined with _):

Environment Variable	Configuration Option
OCTOPUS_SERVER_PORT	server.port
OCTOPUS_SERVER_HOST	server.host
OCTOPUS_DATABASE_TYPE	database.type
OCTOPUS_DATABASE_PATH	database.path
OCTOPUS_LOG_LEVEL	log.level
OCTOPUS_GITHUB_PAT	For rate limiting when getting the latest version (optional)

📸 Screenshots

🖥️ Desktop

📱 Mobile

📖 Documentation

📡 Channel Management

Channels are the basic configuration units for connecting to LLM providers.

Base URL Guide:

The program automatically appends the API version and endpoint path based on the channel type. You only need to provide the service root URL:

Channel Type	Auto-appended Path	Base URL	Full Request URL Example
OpenAI Chat	/v1/chat/completions	https://api.openai.com	https://api.openai.com/v1/chat/completions
OpenAI Responses	/v1/responses	https://api.openai.com	https://api.openai.com/v1/responses
Anthropic	/v1/messages	https://api.anthropic.com	https://api.anthropic.com/v1/messages
Gemini	/v1beta/models/:model:generateContent	https://generativelanguage.googleapis.com	https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent

💡 Tip: The Base URL does not need to include /v1, /v1beta, or a specific API endpoint path - the program handles them automatically.

---

📁 Group Management

Groups aggregate multiple channels into a unified external model name.

Core Concepts:

• Group name is the model name exposed by the program
• When calling the API, set the model parameter to the group name

💡 Example: Create a group named gpt-4o, add multiple providers' GPT-4o channels to it, then access all channels via a unified model: gpt-4o.

---

💰 Price Management

Manage model pricing information in the system.

Data Sources:

• The system periodically syncs model pricing data from models.dev
• When creating a channel, if the channel contains models not in models.dev, the system automatically creates pricing information for those models on this page, so this page displays models that haven't had their prices fetched from upstream, allowing users to set prices manually
• Manual creation of models that exist in models.dev is also supported for custom pricing

Price Priority:

Priority	Source	Description
🥇 High	This Page	Prices set by user in price management page
🥈 Low	models.dev	Auto-synced default prices

💡 Tip: To override a model's default price, simply set a custom price for it in the price management page.

---

⚙️ Settings

Global system configuration.

Statistics Save Interval (minutes):

Since the program handles numerous statistics, writing to the database on every request would impact read/write performance. The program uses this strategy:

• Statistics are first stored in memory
• Periodically batch-written to the database at the configured interval

⚠️ Important: When exiting the program, use proper shutdown methods (like Ctrl+C or sending SIGTERM signal) to ensure in-memory statistics are correctly written to the database. Do NOT use kill -9 or other forced termination methods, as this may result in statistics data loss.

---

🔌 Client Integration

OpenAI SDK

from openai import OpenAI
import os

client = OpenAI(   
    base_url="http://127.0.0.1:8080/v1",   
    api_key="sk-octopus-P48ROljwJmWBYVARjwQM8Nkiezlg7WOrXXOWDYY8TI5p9Mzg", 
)
completion = client.chat.completions.create(
    model="octopus-openai",  # Use the correct group name
    messages = [
        {"role": "user", "content": "Hello"},
    ],
)
print(completion.choices[0].message.content)

Claude Code

Edit ~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8080",
    "ANTHROPIC_AUTH_TOKEN": "sk-octopus-P48ROljwJmWBYVARjwQM8Nkiezlg7WOrXXOWDYY8TI5p9Mzg",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ANTHROPIC_MODEL": "octopus-sonnet-4-5",
    "ANTHROPIC_SMALL_FAST_MODEL": "octopus-haiku-4-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "octopus-sonnet-4-5",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "octopus-sonnet-4-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "octopus-haiku-4-5"
  }
}

Codex

Edit ~/.codex/config.toml

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
model_provider = "octopus"
preferred_auth_method = "apikey"

[model_providers.octopus]
base_url = "http://127.0.0.1:8080/v1"
name = "octopus"
supports_websockets = false
requires_openai_auth = true
wire_api = "responses"
experimental_bearer_token = "sk-octopus-"

Edit ~/.codex/auth.json

{
  "OPENAI_API_KEY": ""
}

---

🤝 Acknowledgments

• 🙏 looplj/axonhub - The LLM API adaptation module in this project is directly derived from this repository
• 📊 sst/models.dev - AI model database providing model pricing data
• 🇨🇳 AtomGit - China-based code hosting
• 💬 Linux.do