Self-Hosted Deployment

Overview

xpander.ai can be deployed on your own infrastructure using Helm charts, giving you full control over your AI agent platform. This guide walks you through setting up a self-hosted xpander.ai deployment on Kubernetes.

Before starting, you’ll need to create an environment in the xpander.ai Console to get your Organization ID and Environment ID.

Prerequisites

Kubernetes 1.20 or later
Helm 3.12 or later
Ingress Controller (e.g., NGINX Ingress Controller)
Storage Class for persistent volumes
TLS certificates (manual or cert-manager)

Network Security & Traffic Flow

Important: xpander.ai self-hosted deployment only makes outbound connections. There is no incoming traffic from xpander.ai to your cluster.

Traffic Direction

✅ Outbound Only: Your self-hosted deployment connects out to xpander.ai services
❌ No Inbound: xpander.ai never initiates connections to your cluster
🔒 Your Control: All data stays within your infrastructure

Required Outbound Access

Your cluster needs outbound (egress) access to these xpander.ai IP addresses:

166.117.85.46
15.197.85.80

Firewall Configuration:

Protocol: HTTPS (port 443)
Direction: Outbound/Egress only
Source: Your Kubernetes cluster
Destination: The IP addresses above

Environment Setup

1. Create Environment

First, create a new self-hosted environment in the xpander.ai Console:

Go to https://app.xpander.ai/environments
Click “Add Environment”
Enter your environment details:
- Name: e.g., “Production”
- URL: Your server’s FQDN (e.g., xpander.my-company.com)
Note down the Organization ID and Environment ID - you’ll need these for installation.

2. Get Installation Commands

The platform will automatically generate the complete Helm installation commands for you with all the required keys and configuration. You don’t need to manually obtain or configure these values.

Installation

The platform will provide you with the exact Helm installation commands tailored to your environment. The examples below show the format and available options for reference.

Quick Start

# Add the Xpander Helm repository
helm repo add xpander https://charts.xpander.ai
helm repo update

Production Installation

For production deployments, configure AI service API keys and custom settings:

helm upgrade --install xpander xpander/xpander \
  --namespace xpander --create-namespace \
  --set ingress.enabled=true \
  --set domain=xpander.my-company.com \
  --set global.organizationId=6aedc41e-9771-4660-b46e-af51c66d2ea8 \
  --set global.environmentId=0e308480-f02c-44a9-97ce-e15bb39d94e8 \
  --set agent-worker.env.AGENTS_OPENAI_API_KEY=YOUR-OPENAI-KEY \
  --set agent-worker.env.ANTHROPIC_API_KEY=YOUR-ANTHROPIC-KEY \
  --set secrets.static.deploymentManagerApiKey=6120718c-ef9b-42e8-93a8-18203d0700a9

Architecture

The Helm chart deploys the following components:

Generated Hostnames

When you set a domain, these hostnames are automatically created:

agent-controller.{domain} - Main API endpoint
ai-gateway.{domain} - AI service gateway
mcp.{domain} - MCP (Model Context Protocol) service

Configuration Options

Required Parameters

Parameter	Description	Example
`global.organizationId`	Your xpander.ai organization ID	`6aedc41e-9771-4660-b46e-af51c66d2ea8`
`global.environmentId`	Your xpander.ai environment ID	`0e308480-f02c-44a9-97ce-e15bb39d94e8`
`secrets.static.deploymentManagerApiKey`	Deployment manager API key	`6120718c-ef9b-42e8-93a8-18203d0700a9`

Optional Parameters

Parameter	Description	Default
`domain`	Base domain for ingress hosts	`""` (ingress disabled)
`ingress.enabled`	Enable external access via ingress	`false`
`agent-worker.env.AGENTS_OPENAI_API_KEY`	OpenAI API key for GPT models	`""`
`agent-worker.env.ANTHROPIC_API_KEY`	Anthropic API key for Claude models	`""`

AI Service Configuration

OpenAI Integration

To use OpenAI models (GPT-3.5, GPT-4, etc.):

helm upgrade xpander xpander/xpander \
  --namespace xpander \
  --reuse-values \
  --set agent-worker.env.AGENTS_OPENAI_API_KEY=sk-your-openai-key

Anthropic Integration

To use Claude models:

helm upgrade xpander xpander/xpander \
  --namespace xpander \
  --reuse-values \
  --set agent-worker.env.ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

Using Kubernetes Secrets (Recommended)

For production, store API keys in Kubernetes secrets:

kubectl create secret generic ai-service-keys \
  --namespace xpander \
  --from-literal=openai-api-key=sk-your-openai-key \
  --from-literal=anthropic-api-key=sk-ant-your-anthropic-key

Verification

After installation, verify your deployment:

Check Pod Status

kubectl -n xpander get pods

Expected output:

NAME                                    READY   STATUS    RESTARTS   AGE
xpander-agent-controller-xxx            1/1     Running   0          2m
xpander-ai-gateway-xxx                  1/1     Running   0          2m
xpander-agent-worker-xxx                1/1     Running   0          2m
xpander-mcp-xxx                         1/1     Running   0          2m
xpander-redis-0                         1/1     Running   0          2m
xpander-postgres-0                      1/1     Running   0          2m

Test Health Endpoints

# Port forward services for testing
kubectl -n xpander port-forward service/xpander-agent-controller 9016:9016 &
kubectl -n xpander port-forward service/xpander-ai-gateway 9018:9018 &
kubectl -n xpander port-forward service/xpander-mcp 8081:8081 &

# Test endpoints
curl http://localhost:9016/health
curl http://localhost:9018/health  
curl http://localhost:8081/health

Connecting Your Environment

Once deployed, connect your environment in the xpander.ai Console:

Go to https://app.xpander.ai/environments
Find your environment and click “Complete setup”
The status should change to “Connected” when the deployment is healthy

Troubleshooting

Common Issues

Pods stuck in Pending state

Ingress not accessible

Health checks failing

Cause: Application startup issuesSolution: Check application logs

kubectl -n xpander logs deployment/xpander-agent-controller
kubectl -n xpander logs deployment/xpander-ai-gateway
kubectl -n xpander logs deployment/xpander-agent-worker
kubectl -n xpander logs deployment/xpander-mcp

API key configuration issues

Cause: Missing or invalid AI service API keysSolution: Verify API key configuration

# Check environment variables in agent-worker
kubectl -n xpander exec deployment/xpander-agent-worker -- env | grep API_KEY

Debug Commands

# Get all resources
kubectl -n xpander get all

# Check events
kubectl -n xpander get events --sort-by=.metadata.creationTimestamp

# Describe problematic pods
kubectl -n xpander describe pod <pod-name>

# Check service endpoints
kubectl -n xpander get endpoints

Upgrading

Regular Updates

helm repo update
helm upgrade xpander xpander/xpander \
  --namespace xpander \
  --reuse-values

Update with New Configuration

helm upgrade xpander xpander/xpander \
  --namespace xpander \
  --values xpander-values.yaml

Uninstalling

# Remove the Helm release
helm uninstall xpander --namespace xpander

# Clean up the namespace (optional)
kubectl delete namespace xpander

Next Steps

Configure Agents: Set up your AI agents using the Quick Start Guide
Connect Slack: Integrate with Slack using the Slack Integration Guide
Add Connectors: Connect to external services with AI Connectors
Monitor Deployment: Set up monitoring and observability for your production deployment

Support

Community Slack: Join our Slack
GitHub Issues: Report issues and contribute
Discord: Developer Discord

Getting Started

Backend Configuration

Task Sources

Self-Hosted Deployment

Overview

Prerequisites

Network Security & Traffic Flow

Traffic Direction

Required Outbound Access

Environment Setup

1. Create Environment

2. Get Installation Commands

Installation

Quick Start

Production Installation

Architecture

Generated Hostnames

Configuration Options

Required Parameters

Optional Parameters

AI Service Configuration

OpenAI Integration

Anthropic Integration

Using Kubernetes Secrets (Recommended)

Verification

Check Pod Status

Test Health Endpoints

Connecting Your Environment

Troubleshooting

Common Issues

Debug Commands

Upgrading

Regular Updates

Update with New Configuration

Uninstalling

Next Steps

Support

Getting Started

Backend Configuration

Task Sources

​Overview

​Prerequisites

​Network Security & Traffic Flow

​Traffic Direction

​Required Outbound Access

​Environment Setup

​1. Create Environment

​2. Get Installation Commands

​Installation

​Quick Start

​Production Installation

​Architecture

​Generated Hostnames

​Configuration Options

​Required Parameters

​Optional Parameters

​AI Service Configuration

​OpenAI Integration

​Anthropic Integration

​Using Kubernetes Secrets (Recommended)

​Verification

​Check Pod Status

​Test Health Endpoints

​Connecting Your Environment

​Troubleshooting

​Common Issues

​Debug Commands

​Upgrading

​Regular Updates

​Update with New Configuration

​Uninstalling

​Next Steps

​Support

Overview

Prerequisites

Network Security & Traffic Flow

Traffic Direction

Required Outbound Access

Environment Setup

1. Create Environment

2. Get Installation Commands

Installation

Quick Start

Production Installation

Architecture

Generated Hostnames

Configuration Options

Required Parameters

Optional Parameters

AI Service Configuration

OpenAI Integration

Anthropic Integration

Using Kubernetes Secrets (Recommended)

Verification

Check Pod Status

Test Health Endpoints

Connecting Your Environment

Troubleshooting

Common Issues

Debug Commands

Upgrading

Regular Updates

Update with New Configuration

Uninstalling

Next Steps

Support