How to Migrate Existing Applications to Use AxonHub Without Code Changes

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:

1. Channel Identification – The system extracts the target channel from the request's model parameter or a preconfigured mapping in 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 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 for Anthropic or 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:

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:

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:

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 – 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 – Implements the public OpenAI-compatible REST endpoints (/v1/chat/completions, /v1/models) that your SDK connects to.

• 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 – Handles bidirectional schema conversion between the OpenAI format and provider-specific payloads.

• internal/server/api/claudecode.go and internal/server/api/gemini.go – Provider-specific outbound handlers that manage connections to Anthropic and Google Gemini APIs.

• internal/ent/model.go – Database schema for enabled models, supporting the model discovery endpoint.

• 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 handles channel selection, request transformation, and response normalization automatically.

• Provider-specific differences are abstracted through transformers (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 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.

How does AxonHub handle different provider APIs?

AxonHub uses a transformation pipeline defined in 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 or internal/server/api/gemini.go.

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

Yes. AxonHub's channel configuration in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}