octopus

Octopus

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

English | 简体中文

✨ Features

• 🔀 Multi-Channel Aggregation - Connect multiple LLM provider channels with unified management
• 🔑 Multi-Key Support - Support multiple API keys for a single channel
• ⚡ Smart Selection - Multiple endpoints per channel, smart selection of the endpoint with the shortest delay
• ⚖️ Load Balancing - Automatic request distribution for stable and efficient service
• 🔄 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
• 📊 Analytics - Comprehensive request statistics, token consumption, and cost tracking
• 🎨 Elegant UI - Clean and beautiful web management panel
• 🗄️ 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/dev/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 && cd ..
# Move frontend assets to static directory
mv web/out static/
# 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 && NEXT_PUBLIC_API_BASE_URL="http://127.0.0.1:8080" pnpm run dev
## Open a new terminal, start the backend service
go run main.go start
## Access the frontend at
http://localhost:3000

🔐 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:

Database Configuration:

Three database types are supported:

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 _):

📸 Screenshots

🖥️ Desktop

Dashboard	Channel Management	Group Management
Price Management	Logs	Settings

📱 Mobile

Home	Channel	Group	Price	Logs	Settings

📖 Documentation

📡 Channel Management

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

Base URL Guide:

The program automatically appends API paths based on channel type. You only need to provide the base URL:

💡 Tip: No need to include specific API endpoint paths in the Base URL - the program handles this 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

Load Balancing Modes:

💡 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:

💡 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 = "octopus-codex" # Use the correct group name

model_provider = "octopus"

[model_providers.octopus]
name = "octopus"
base_url = "http://127.0.0.1:8080/v1"

Edit ~/.codex/auth.json

{
  "OPENAI_API_KEY": "sk-octopus-P48ROljwJmWBYVARjwQM8Nkiezlg7WOrXXOWDYY8TI5p9Mzg"
}

🤝 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