# AxonHub - All-in-one AI Development Platform
[](https://github.com/looplj/axonhub/actions/workflows/test.yml)
[](https://github.com/looplj/axonhub/actions/workflows/lint.yml)
[](https://golang.org/)
[](https://docker.com)
[English](README.md) | [δΈζ](README.zh-CN.md)
---
## π Project Introduction
### All-in-one AI Development Platform
AxonHub is an all-in-one AI development platform that provides unified API gateway, project management, and comprehensive development tools. It offers OpenAI, Anthropic, and AI SDK compatible API layers, transforming requests to various AI providers through a transformer pipeline architecture. The platform features comprehensive tracing capabilities, project-based organization, and integrated playground for rapid prototyping, helping developers and enterprises better manage AI development workflows.
### Core Features
1. [**Unified API**](docs/en/api-reference/unified-api.md): OpenAI- and Anthropic-compatible interface with automatic API translation lets you use one API format to access any supported model provider.
2. [**Tracing / Threads**](docs/en/guides/tracing.md): Thread-aware tracing captures full request timelines for deep observability and faster debugging.
3. [**Fine-grained Permission**](docs/en/guides/permissions.md): RBAC-based policies help teams govern access, usage, and data segregation precisely.
4. [**Adaptive Load Balancing**](docs/en/guides/load-balance.md): Intelligent multi-strategy load balancing automatically selects optimal AI channels based on health, performance, and session consistency.
---
## π Documentation
For detailed technical documentation, API references, architecture design, and more, please visit
- [](https://deepwiki.com/looplj/axonhub)
- [](https://zread.ai/looplj/axonhub)
---
## π― Demo
Try AxonHub live at our [demo instance](https://axonhub.onrender.com)!
**Note**οΌThe demo instance currently configures Zhipu and OpenRouter free models.
### Demo Account
- **Email**: demo@example.com
- **Password**: 12345678
---
## β Features
### πΈ Screenshots
Here are some screenshots of AxonHub in action:
System Dashboard
|
Channel Management
|
Models
|
Trace Viewer
|
Request Monitoring
|
Usage Logs
|
---
### π API Types
| API Type | Status | Description | Document |
| -------------------- | ---------- | ------------------------------ | -------------------------------------------- |
| **Text Generation** | β
Done | Conversational interface | [Unified API](docs/en/api-reference/unified-api.md) |
| **Image Generation** | β οΈ Partial | Image generation | [Image Generation](docs/en/api-reference/image-generation.md) |
| **Rerank** | β
Done | Results ranking | [Unified API](docs/en/api-reference/unified-api.md#rerank-api) |
| **Embedding** | β
Done | Vector embedding generation | [Unified API](docs/en/api-reference/unified-api.md#embedding-api) |
| **Realtime** | π Todo | Live conversation capabilities | - |
---
### π Multi-Provider AI Gateway
| Feature | Technical Implementation | Business Value |
| ------------------------- | ----------------------------------------------- | ------------------------------------------- |
| **Unified API Interface** | OpenAI compatible standard, zero learning curve | Avoid vendor lock-in, reduce migration risk |
| **Automatic Failover** | Multi-channel retry + load balancing | Service interruption time < 100ms |
| **Stream Processing** | Native SSE support, real-time response | 60% user experience improvement |
---
### 𧡠Threads & Tracing
AxonHub records every request as part of a thread-aware trace without requiring you to adopt any vendor-specific SDK. Bring your existing OpenAI-compatible client, and AxonHub will:
- Require incoming `AH-Trace-Id` headers to stitch multiple requests into the same trace. If the header is omitted, AxonHub will still record the request but cannot automatically link it to related activity.
- Link traces to threads so you can follow the entire conversation journey end to end
- Capture model metadata, prompt / response spans, and timing information for fast root-cause analysis
Learn more about how tracing works and how to integrate it in the [Tracing Guide](docs/en/guides/tracing.md).
### π§ API Format Support
| Format | Status | Compatibility | Modalities |
| --------------------------- | ---------- | ------------------- | --------------- |
| **OpenAI Chat Completions** | β
Done | Fully compatible | Text, Image |
| **OpenAI Responses** | β οΈ Partial | No `previous_response_id` | Text, Image |
| **Anthropic Messages** | β
Done | Fully supported | Text |
| **Gemini** | β
Done | Fully supported | Text, Image |
| **AI SDK** | β οΈ Partial | Partially supported | Text |
**Key Feature**: Use OpenAI API to call Anthropic models, or Anthropic API to call OpenAI models - AxonHub handles automatic API translation!
---
### π’ Permission Control
| Security Feature | Implementation |
| ----------------------------------- | ---------------------------------- |
| **Fine-grained Permission Control** | Role-based access control (RBAC) |
| **Data Localization** | Configurable data storage policies |
| **API Key Management** | JWT + scope control |
---
## π Quick Start
### 1-click Deploy to Render
Deploy AxonHub with 1-click on [Render](https://render.com) for free.
---
## π Deployment Guide
### π» Personal Computer Deployment
Perfect for individual developers and small teams. No complex configuration required.
#### Quick Download & Run
1. **Download the latest release** from [GitHub Releases](https://github.com/looplj/axonhub/releases)
- Choose the appropriate version for your operating system:
2. **Extract and run**
```bash
# Extract the downloaded file
unzip axonhub_*.zip
cd axonhub_*
# Add execution permissions (only for Linux/macOS)
chmod +x axonhub
# Run directly - default SQLite database
# Install AxonHub to system
sudo ./install.sh
# Start AxonHub service
./start.sh
# Stop AxonHub service
./stop.sh
```
3. **Access the application**
```
http://localhost:8090
```
---
### π₯οΈ Server Deployment
For production environments, high availability, and enterprise deployments.
#### Database Support
AxonHub supports multiple databases to meet different scale deployment needs:
| Database | Supported Versions | Recommended Scenario | Auto Migration | Links |
| -------------- | ------------------ | ------------------------------------------------ | -------------- | ----------------------------------------------------------- |
| **TiDB Cloud** | Starter | Serverless, Free tier, Auto Scale | β
Supported | [TiDB Cloud](https://www.pingcap.com/tidb-cloud-starter/) |
| **TiDB Cloud** | Dedicated | Distributed deployment, large scale | β
Supported | [TiDB Cloud](https://www.pingcap.com/tidb-cloud-dedicated/) |
| **TiDB** | V8.0+ | Distributed deployment, large scale | β
Supported | [TiDB](https://tidb.io/) |
| **Neon DB** | - | Serverless, Free tier, Auto Scale | β
Supported | [Neon DB](https://neon.com/) |
| **PostgreSQL** | 15+ | Production environment, medium-large deployments | β
Supported | [PostgreSQL](https://www.postgresql.org/) |
| **MySQL** | 8.0+ | Production environment, medium-large deployments | β
Supported | [MySQL](https://www.mysql.com/) |
| **SQLite** | 3.0+ | Development environment, small deployments | β
Supported | [SQLite](https://www.sqlite.org/index.html) |
#### Configuration
AxonHub uses YAML configuration files with environment variable override support:
```yaml
# config.yml
server:
port: 8090
name: "AxonHub"
debug: false
db:
dialect: "tidb"
dsn: ".root:@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true"
log:
level: "info"
encoding: "json"
```
Environment variables:
```bash
AXONHUB_SERVER_PORT=8090
AXONHUB_DB_DIALECT="tidb"
AXONHUB_DB_DSN=".root:@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true"
AXONHUB_LOG_LEVEL=info
```
For detailed configuration instructions, please refer to [configuration documentation](docs/en/deployment/configuration.md).
#### Docker Compose Deployment
```bash
# Clone project
git clone https://github.com/looplj/axonhub.git
cd axonhub
# Set environment variables
export AXONHUB_DB_DIALECT="tidb"
export AXONHUB_DB_DSN=".root:@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true"
# Start services
docker-compose up -d
# Check status
docker-compose ps
```
#### Virtual Machine Deployment
Download the latest release from [GitHub Releases](https://github.com/looplj/axonhub/releases)
```bash
# Extract and run
unzip axonhub_*.zip
cd axonhub_*
# Set environment variables
export AXONHUB_DB_DIALECT="tidb"
export AXONHUB_DB_DSN=".root:@tcp(gateway01.us-west-2.prod.aws.tidbcloud.com:4000)/axonhub?tls=true"
sudo ./install.sh
# Configuration file check
axonhub config check
# Start service
# For simplicity, we recommend managing AxonHub with the helper scripts:
# Start
./start.sh
# Stop
./stop.sh
```
---
## π Usage Guide
### Unified API Overview
AxonHub provides a unified API gateway that supports both OpenAI Chat Completions and Anthropic Messages APIs. This means you can:
- **Use OpenAI API to call Anthropic models** - Keep using your OpenAI SDK while accessing Claude models
- **Use Anthropic API to call OpenAI models** - Use Anthropic's native API format with GPT models
- **Use Gemini API to call OpenAI models** - Use Gemini's native API format with GPT models
- **Automatic API translation** - AxonHub handles format conversion automatically
- **Zero code changes** - Your existing OpenAI or Anthropic client code continues to work
### 1. Initial Setup
1. **Access Management Interface**
```
http://localhost:8090
```
2. **Configure AI Providers**
- Add API keys in the management interface
- Test connections to ensure correct configuration
3. **Create Users and Roles**
- Set up permission management
- Assign appropriate access permissions
### 2. Channel Configuration
Configure AI provider channels in the management interface. For detailed information on channel configuration, including model mappings, parameter overrides, and troubleshooting, see the [Channel Configuration Guide](docs/en/guides/channel-management.md).
### 3. Model Management
AxonHub provides a flexible model management system that supports mapping abstract models to specific channels and model implementations through Model Associations. This enables:
- **Unified Model Interface** - Use abstract model IDs (e.g., `gpt-4`, `claude-3-opus`) instead of channel-specific names
- **Intelligent Channel Selection** - Automatically route requests to optimal channels based on association rules and load balancing
- **Flexible Mapping Strategies** - Support for precise channel-model matching, regex patterns, and tag-based selection
- **Priority-based Fallback** - Configure multiple associations with priorities for automatic failover
For comprehensive information on model management, including association types, configuration examples, and best practices, see the [Model Management Guide](docs/en/guides/model-management.md).
### 4. Create API Keys
Create API keys to authenticate your applications with AxonHub. Each API key can be configured with multiple profiles that define:
- **Model Mappings** - Transform user-requested models to actual available models using exact match or regex patterns
- **Channel Restrictions** - Limit which channels an API key can use by channel IDs or tags
- **Model Access Control** - Control which models are accessible through a specific profile
- **Profile Switching** - Change behavior on-the-fly by activating different profiles
For detailed information on API key profiles, including configuration examples, validation rules, and best practices, see the [API Key Profile Guide](docs/en/guides/api-key-profiles.md).
### 5. Claude Code/Codex Integration
See the dedicated guides for detailed setup steps, troubleshooting, and tips on combining these tools with AxonHub model profiles:
- [Claude Code Integration Guide](docs/en/guides/claude-code-integration.md)
- [Codex Integration Guide](docs/en/guides/codex-integration.md)
---
### 6. SDK Usage
For detailed SDK usage examples and code samples, please refer to the [Unified API documentation](docs/en/api-reference/unified-api.md).
## π οΈ Development Guide
For detailed development instructions, architecture design, and contribution guidelines, please see [docs/en/guides/development.md](docs/en/guides/development.md).
---
## π€ Acknowledgments
- π [musistudio/llms](https://github.com/musistudio/llms) - LLM transformation framework, source of inspiration
- π¨ [satnaing/shadcn-admin](https://github.com/satnaing/shadcn-admin) - Admin interface template
- π§ [99designs/gqlgen](https://github.com/99designs/gqlgen) - GraphQL code generation
- π [gin-gonic/gin](https://github.com/gin-gonic/gin) - HTTP framework
- ποΈ [ent/ent](https://github.com/ent/ent) - ORM framework
- π§ [air-verse/air](https://github.com/air-verse/air) - Auto reload Go service
- βοΈ [Render](https://render.com) - Free cloud deployment platform for hosting our demo
- ποΈ [TiDB Cloud](https://www.pingcap.com/tidb-cloud/) - Serverless database platform for demo deployment
---
## π License
This project is licensed under multiple licenses (Apache-2.0 and LGPL-3.0). See [LICENSE](LICENSE) file for the detailed licensing overview and terms.
---
**AxonHub** - All-in-one AI Development Platform, making AI development simpler
[π Homepage](https://github.com/looplj/axonhub) β’ [π Documentation](https://deepwiki.com/looplj/axonhub) β’ [π Issue Feedback](https://github.com/looplj/axonhub/issues)
Built with β€οΈ by the AxonHub team
