# How to Migrate Existing Applications to Use AxonHub Without Code Changes

> Migrate existing AI apps to AxonHub with zero code changes. Update your SDK base URL and API key thanks to OpenAI-compatible REST endpoints. Get started today.

- Repository: [Loop/axonhub](https://github.com/looplj/axonhub)
- Tags: migration-guide
- Published: 2026-03-06

---

**You can migrate existing AI applications to AxonHub by simply changing the `base_url` and API key in your SDK configuration, requiring zero code modifications thanks to AxonHub's OpenAI-compatible REST endpoints.**

AxonHub acts as a transparent gateway between your existing applications and multiple AI providers. By implementing the exact same REST endpoints that popular AI SDKs expect—such as the OpenAI Chat Completion API, Anthropic Messages API, and Gemini endpoints—AxonHub allows you to redirect traffic through its orchestration layer without touching your application logic.

## How AxonHub Enables Zero-Code Migration

The migration works because AxonHub presents itself as a drop-in replacement for your existing provider's API endpoint. When you point your SDK's `base_url` to AxonHub's address, every request flows through a sophisticated transformation pipeline that handles provider-specific differences transparently.

### The Request Lifecycle

According to the source code in `looplj/axonhub`, the orchestrator processes each request through five distinct stages defined in [`internal/server/orchestrator/orchestrator.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/orchestrator.go):

1. **Channel Identification** – The system extracts the target channel from the request's `model` parameter or a preconfigured mapping in [`conf/conf.go`](https://github.com/looplj/axonhub/blob/main/conf/conf.go).

2. **HTTP Client Selection** – Based on the channel configuration, the orchestrator selects the appropriate HTTP client, optionally applying per-channel proxy settings or header overrides defined in the channel settings.

3. **Request Transformation** – The transformer component in [`internal/server/orchestrator/transformer.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/transformer.go) converts the inbound OpenAI-compatible schema into the provider-specific payload format required by the target API.

4. **Outbound Dispatch** – The request is sent to the actual provider through provider-specific handlers such as [`internal/server/api/claudecode.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/claudecode.go) for Anthropic or [`internal/server/api/gemini.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/gemini.go) for Google's Gemini.

5. **Response Normalization** – The provider's response is converted back into the OpenAI-compatible JSON structure before being returned to your application, ensuring your existing parsing logic continues to work unchanged.

## Configuration Changes Required

To migrate an existing application, you only need to modify two configuration parameters: the endpoint URL and the API key. Below are examples for common SDKs.

### Python OpenAI SDK

Change the `base_url` to point to your AxonHub instance and provide an AxonHub-issued API key:

```python
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8090/v1",          # AxonHub endpoint

    api_key="your-axonhub-api-key"                # AxonHub-issued key

)

# Call any model configured in AxonHub:

response = client.chat.completions.create(
    model="claude-3-5-sonnet",    # Can be swapped for gpt-4, gemini-pro, etc.

    messages=[{"role": "user", "content": "Hello!"}]
)

print(response.choices[0].message.content)

```

### Go OpenAI-Compatible Client

Using the popular `sashabaranov/go-openai` library:

```go
import (
    "context"
    "github.com/sashabaranov/go-openai"
    "log"
)

func main() {
    cfg := openai.DefaultConfig("your-axonhub-api-key")
    cfg.BaseURL = "http://localhost:8090/v1" // AxonHub endpoint

    client := openai.NewClientWithConfig(cfg)

    resp, err := client.CreateChatCompletion(
        context.Background(),
        openai.ChatCompletionRequest{
            Model: "gpt-4", // Any model configured in AxonHub
            Messages: []openai.ChatCompletionMessage{
                {Role: "user", Content": "What is the weather today?"},
            },
        },
    )
    if err != nil {
        log.Fatalf("request failed: %v", err)
    }
    log.Println(resp.Choices[0].Message.Content)
}

```

### Raw HTTP with cURL

Even direct HTTP requests work without modification:

```bash
curl http://localhost:8090/v1/chat/completions \
  -H "Authorization: Bearer your-axonhub-api-key" \
  -H "Content-Type: application/json" \
  -d '{
        "model":"gemini-pro",
        "messages":[{"role":"user","content":"Tell me a joke"}]
      }'

```

## Key Components Behind the Scenes

The zero-code migration capability relies on several critical components in the `looplj/axonhub` repository:

- **[`conf/conf.go`](https://github.com/looplj/axonhub/blob/main/conf/conf.go)** – Loads YAML and environment variable configurations, defining channel mappings, model aliases, and optional proxy settings that determine how requests are routed.

- **[`internal/server/api/openai.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/openai.go)** – Implements the public OpenAI-compatible REST endpoints (`/v1/chat/completions`, `/v1/models`) that your SDK connects to.

- **[`internal/server/orchestrator/orchestrator.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/orchestrator.go)** – The core request-processing engine that selects the appropriate channel, applies retry logic, and manages circuit breakers.

- **[`internal/server/orchestrator/transformer.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/transformer.go)** – Handles bidirectional schema conversion between the OpenAI format and provider-specific payloads.

- **[`internal/server/api/claudecode.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/claudecode.go) and [`internal/server/api/gemini.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/gemini.go)** – Provider-specific outbound handlers that manage connections to Anthropic and Google Gemini APIs.

- **[`internal/ent/model.go`](https://github.com/looplj/axonhub/blob/main/internal/ent/model.go)** – Database schema for enabled models, supporting the model discovery endpoint.

- **[`internal/server/api/auth.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/auth.go)** – Validates API keys and enforces RBAC policies and quota limits for incoming requests.

## Summary

- **AxonHub acts as a transparent proxy** that exposes OpenAI-compatible REST endpoints, allowing existing AI SDKs to connect without modification.

- **Migration requires only configuration changes**: update the `base_url` to point to your AxonHub instance and replace the API key with an AxonHub-issued credential.

- **The orchestration pipeline** in [`internal/server/orchestrator/orchestrator.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/orchestrator.go) handles channel selection, request transformation, and response normalization automatically.

- **Provider-specific differences** are abstracted through transformers ([`transformer.go`](https://github.com/looplj/axonhub/blob/main/transformer.go)) and dedicated outbound handlers, ensuring your application receives consistent OpenAI-formatted responses regardless of the backend provider.

## Frequently Asked Questions

### Do I need to modify my application code to use AxonHub?

No. AxonHub is designed as a drop-in replacement for OpenAI-compatible endpoints. You only need to change the `base_url` (or equivalent endpoint configuration) and API key in your SDK settings. The orchestrator in [`internal/server/orchestrator/orchestrator.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/orchestrator.go) handles all request routing and transformation transparently.

### Which AI SDKs are compatible with AxonHub?

Any SDK that supports the OpenAI Chat Completion API specification works with AxonHub. This includes the official OpenAI Python and Node.js SDKs, the `sashabaranov/go-openai` library for Go, and any custom HTTP client that can target a different base URL. AxonHub also supports direct HTTP requests to `/v1/chat/completions` as implemented in [`internal/server/api/openai.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/openai.go).

### How does AxonHub handle different provider APIs?

AxonHub uses a transformation pipeline defined in [`internal/server/orchestrator/transformer.go`](https://github.com/looplj/axonhub/blob/main/internal/server/orchestrator/transformer.go) to convert between the OpenAI schema and provider-specific formats. When a request arrives, the orchestrator identifies the target channel (e.g., Anthropic, Gemini, or OpenAI) from the model name, then applies the appropriate transformer to rewrite the payload before dispatching via provider-specific handlers like [`internal/server/api/claudecode.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/claudecode.go) or [`internal/server/api/gemini.go`](https://github.com/looplj/axonhub/blob/main/internal/server/api/gemini.go).

### Can I use AxonHub with custom or self-hosted models?

Yes. AxonHub's channel configuration in [`conf/conf.go`](https://github.com/looplj/axonhub/blob/main/conf/conf.go) supports custom base URLs and model mappings. You can define new channels that point to self-hosted endpoints (such as local LLM servers or private deployments) by specifying the custom URL in the channel settings. The orchestrator will route requests to these endpoints while still presenting the standard OpenAI-compatible interface to your application.