Getting Started with Self-Hosted XAI Router

The self-hosted version of XAI Router is functionally identical to the XAI Control cloud service, but all data and configurations are kept locally, making it ideal for enterprises or teams with strict requirements for data compliance and network isolation.

1. Environment and Domain Requirements

1.1 Server Requirements

Instance Recommendation: We recommend using a Linux server with root privileges, such as an AWS t3.small (2 CPU Cores, 2GB Memory, 8GB+ Disk) or an equivalent instance.

1.2 Domain Requirements

Before deployment, please prepare three domains that are resolved to your server's IP address, for example:

• api-xai.your-domain.com (API Service)
• manage-xai.your-domain.com (Account Management)
• admin-xai.your-domain.com (Configuration Management)

2. Deployment Steps

We offer two deployment options. Please choose one based on your technical stack and environment requirements:

• Option A: Docker Compose Deployment: Suitable for quick, single-server deployments.
• Option B: Kubernetes Deployment: Suitable for Kubernetes environments.

Option A: Docker Compose Deployment

This guide will walk you through deploying XAI Router on your own server. The process relies on Docker and Docker Compose, so please ensure your server has the appropriate environment set up.

Step 1: Install Docker

We recommend installing Docker using the official script, which supports most major Linux distributions.

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Step 2: Install Docker Compose

This command downloads the latest stable release of Docker Compose from GitHub.

curl -L https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose

Step 3: Grant Execute Permissions

Add execute permissions to the Docker Compose binary you just downloaded.

chmod +x /usr/local/bin/docker-compose

Step 4: Generate the docker-compose.yml Configuration File

This is a crucial step in the deployment process. We will generate a docker-compose.yml file tailored for you by calling the official deployment service.

Execute the following command, and be sure to replace the four parameters in the JSON data with your own information:

curl -X POST https://deploy.xaixapi.com/xai?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_mail": "[email protected]",
    "xai_api": "api-xai.your-domain.com",
    "xai_manage": "manage-xai.your-domain.com",
    "xai_admin": "admin-xai.your-domain.com"
  }' > docker-compose.yml

Parameter Descriptions:

• xai_mail (Required): Your administrator's email address. Used for initializing the admin account and receiving system notifications.
• xai_api (Required): The domain you prepared for the API service. All API requests will be sent to this address. Ensure this domain is resolved to your server's public IP address.
• xai_manage (Required): The domain you prepared for account management. This service is for end-users to perform daily management tasks. Ensure this domain is resolved to your server's public IP address.
• xai_admin (Required): The domain you prepared for configuration management. Used for system configuration. Ensure this domain is resolved to your server's public IP address.

Step 5: Start the Services

Use the generated configuration file to start all services in the background.

docker-compose -f docker-compose.yml up -d

This command will automatically pull the required images and start the complete XAI Router service stack as defined in the docker-compose.yml file. After the services start, you can check the status of all containers with the docker-compose ps command.

The core service stack includes the following three components listening on internal ports:

• Core API Service: listens on port 3443.
• Configuration Management Service: listens on port 3080.
• Account Management Service: listens on port 3081.

Please note: These ports are only exposed internally on the server. You do not need to (and should not) access them directly from the public internet. In the next step, we will configure Nginx as a reverse proxy.

Step 6: Configure Nginx as a Reverse Proxy

To make your services accessible via your domains and provide a management interface, you need to configure Nginx as a reverse proxy.

6.1 Install Nginx

# Ubuntu/Debian
sudo apt update && sudo apt install nginx -y

# CentOS/RHEL
sudo yum install nginx -y

6.2 Create the Nginx Configuration File

We recommend backing up and replacing the entire nginx.conf file for the best compatibility.

# Back up the existing configuration
sudo mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak

# Create a new configuration file
curl -X POST https://deploy.xaixapi.com/nginx?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_api": "api-xai.your-domain.com",
    "xai_manage": "manage-xai.your-domain.com",
    "xai_admin": "admin-xai.your-domain.com"
  }' > /etc/nginx/nginx.conf

Be sure to replace api-xai.your-domain.com, manage-xai.your-domain.com, and admin-xai.your-domain.com with your actual domains.

6.3 Restart Nginx

sudo systemctl restart nginx && sudo systemctl enable nginx

Step 7: Configure HTTPS

To ensure data security, we recommend configuring HTTPS for all your services.

Step 8: Verify the Deployment

1. Check Docker service status:

   docker-compose ps
   

   Ensure all services are in the Up or running state.

2. Test service access:

   • Account Management: Open http://manage-xai.your-domain.com in your browser.
   • System Administration: Open http://admin-xai.your-domain.com in your browser.

Option B: Kubernetes Deployment

For environments requiring high availability, auto-scaling, and powerful orchestration, we recommend deploying with Kubernetes.

Prerequisites

• A running Kubernetes cluster.
• The kubectl command-line tool configured to connect to your cluster.
• An Ingress Controller (e.g., Nginx Ingress Controller) installed and configured in your cluster.
• A StorageClass configured in your cluster for dynamic Persistent Volume provisioning.

Step 1: Generate the xai-router-k8s.yaml Configuration File

Similar to Docker Compose, we provide a command to generate a customized Kubernetes deployment manifest.

curl -X POST https://deploy.xaixapi.com/xai/k8s?raw=true \
  -H "Content-Type: application/json" \
  -d '{
    "xai_mail": "[email protected]",
    "xai_api": "api-xai.your-domain.com",
    "xai_manage": "manage-xai.your-domain.com",
    "xai_admin": "admin-xai.your-domain.com"
  }' > xai-router-k8s.yaml

Be sure to replace the four parameters in the JSON data with your own information.

Step 2: Review and Adjust the Configuration File

Before applying the configuration, open the xai-router-k8s.yaml file and make the following key adjustments based on your environment:

2.1 (Important) Adjust the PersistentVolumeClaim (PVC)

To persist data for the Postgres database and Redis, we use a PersistentVolumeClaim. You need to ensure that the storageClassName matches an available storage class in your cluster.

Find the PersistentVolumeClaim definition and modify the storageClassName field:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: xai-router
  namespace: xai-router
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 20Gi
  storageClassName: alicloud-disk-ssd # <--- Modify this line

Note: The storageClassName varies significantly across different cloud providers and self-hosted K8s environments. The following suggestions are for reference only; please use the one that applies to your actual environment.

Environment	Common storageClassNames
AWS (EKS)	gp2, gp3
Alibaba Cloud (ACK)	alicloud-disk-ssd, alicloud-disk-efficiency
Tencent Cloud (TKE)	cbs-ssd, cloud-premium
Google Cloud (GKE)	standard, premium-rwo
Self-hosted (e.g., with local-path-provisioner)	local-path

You can view the available StorageClasses in your cluster by running kubectl get sc.

2.2 Check the Ingress Configuration

Ensure the host fields in the Ingress resource match your prepared domains and that the ingressClassName matches the name of the Ingress Controller installed in your cluster (usually nginx).

Step 3: Deploy to Kubernetes

Apply the configuration file using kubectl. This will automatically create all the necessary resources, including the Namespace, Deployments, Services, PVC, and Ingress.

kubectl apply -f xai-router-k8s.yaml

Step 4: Verify the Deployment

1. Check the status of all resources:

   kubectl get all -n xai-router
   

   Wait for all Pods to reach the Running state. This may take a few minutes as the system needs to pull images and start the services.

2. Check the Ingress address:

   kubectl get ingress -n xai-router
   

   Look at the ADDRESS column to ensure the Ingress Controller has assigned an external IP address to your services. You will need to point your domains to this IP.

3. Test service access:

   • Account Management: Open http://manage-xai.your-domain.com in your browser.
   • System Administration: Open http://admin-xai.your-domain.com in your browser.

3. Service Access Information

Congratulations, the deployment is complete! You now have three core services accessible via different domains:

• http(s)://api-xai.your-domain.com

  • Purpose: API Service. This is the core of the system, where all requests to large models are routed.
  • Access Method: Called via code, SDKs, or API debugging tools (like Postman).

• http(s)://manage-xai.your-domain.com

  • Purpose: Account Management. For use by your end-users or customers.
  • Access Method: Open in a web browser.
  • Key Features: Users can view their spending credits, query request logs, and create/view/recharge/update/delete sub-accounts.

• http(s)://admin-xai.your-domain.com

  • Purpose: Configuration Management. For system administrators. Only allows login with the XAI API ROOT Key.
  • Access Method: Open in a web browser.
  • Key Features: Perform system-level configurations, such as managing model providers and model mappings.