Installing XiansAi Server¶

This guide walks you through installing and running the XiansAi Server — the core platform API and orchestration engine — using the official Docker images published to DockerHub. It covers the external services you need, every environment variable (app setting) the server understands, and how to run the container for staging and production.

The official Docker image¶

The platform team publishes multi-platform images to DockerHub as 99xio/xiansai-server.

Available tags follow semantic versioning. For a release v2.0.0 you can pull 2.0.0, 2.0, 2, or latest. Pre-releases (e.g. 2.0.0-beta) are published too, but never update the latest tag.

docker pull 99xio/xiansai-server:latest

Prerequisites¶

The Server is stateless itself, but it depends on two external services. Provision these before starting the container.

Redis (distributed cache) and Azure Communication Services (outbound email) can be added later — see optional settings.

Configuration: environment variables¶

All settings are supplied as environment variables using the standard .NET convention where : in a configuration path becomes __ (double underscore). For example, the setting MongoDB:ConnectionString is provided as MongoDB__ConnectionString.

The recommended approach is to keep these in an .env file and pass it to the container with --env-file.

Minimal .env to get started¶

Only the variables below are mandatory — everything else has sensible defaults. Copy this template, fill in the values (the sections that follow explain how to obtain each one), and you can start the server.

# MongoDB (must be a replica set)
MongoDB__ConnectionString=mongodb://user:password@mongodb:27017/xians?replicaSet=rs0&authSource=xians
MongoDB__DatabaseName=xians

# Temporal
Temporal__FlowServerUrl=temporal:7233
Temporal__FlowServerNamespace=default

# Encryption keys — generate each with: openssl rand -base64 32
EncryptionKeys__BaseSecret=<random-base64>
EncryptionKeys__UniqueSecrets__ConversationMessageKey=<random-base64>
EncryptionKeys__UniqueSecrets__TenantOidcSecretKey=<random-base64>
EncryptionKeys__UniqueSecrets__SecretVaultKey=<random-base64>

# Root CA certificate — see "Certificates" below for generation steps
Certificates__AppServerPfxBase64=<base64-encoded-pfx>
Certificates__AppServerCertPassword=<pfx-password>

General¶

Database (MongoDB) — required¶

MongoDB__ConnectionString=mongodb://user:password@mongodb:27017/xians?replicaSet=rs0&authSource=xians
MongoDB__DatabaseName=xians

Connection pool tuning is optional (defaults shown):

MongoDB__MaxConnectionPoolSize=100
MongoDB__MinConnectionPoolSize=5

Where to get the connection string:

• MongoDB Atlas (managed): create a cluster, then copy the connection string from Connect → Drivers. Atlas clusters are always replica sets, so no extra configuration is needed.
• Self-hosted: start mongod with --replSet rs0 and initialize it once with rs.initiate() from mongosh. Then use mongodb://<user>:<password>@<host>:27017/xians?replicaSet=rs0&authSource=<auth-db>.

Temporal workflow engine — required¶

Temporal__FlowServerUrl=temporal:7233
Temporal__FlowServerNamespace=default

Optionally, if agents connect from outside your Docker network via a different hostname:

Temporal__FlowServerUrlExternal=temporal.your-domain.com:7233

Where to get these values:

• FlowServerUrl is the host:port of the Temporal frontend service as reachable from inside the server container. A self-hosted Temporal (e.g. via temporal docker-compose) listens on port 7233 by default.
• FlowServerNamespace is the Temporal namespace to run workflows in. Self-hosted setups ship with default; for Temporal Cloud use your namespace (e.g. my-namespace.a1b2c) and the endpoint shown in the Temporal Cloud console.
• FlowServerUrlExternal is the endpoint handed to agents; it defaults to FlowServerUrl when omitted.

Encryption keys — required¶

The server encrypts sensitive data at rest (chat messages, tenant OIDC secrets, and the secret vault). Generate each key with openssl rand -base64 32 and use different values per environment.

# Foundational secret (min 32 chars)
EncryptionKeys__BaseSecret=<random-base64>

# Per-purpose unique secrets
EncryptionKeys__UniqueSecrets__ConversationMessageKey=<random-base64>
EncryptionKeys__UniqueSecrets__TenantOidcSecretKey=<random-base64>
EncryptionKeys__UniqueSecrets__SecretVaultKey=<random-base64>

Certificates — required¶

The server acts as its own certificate authority: it uses a root CA certificate to sign the client certificates that agents authenticate with. Supply that root CA as a password-protected, base64-encoded PFX (PKCS#12) bundle containing both the certificate and its private key.

Certificates__AppServerPfxBase64=<base64-encoded-pfx>
Certificates__AppServerCertPassword=<pfx-password>

Generating the root certificate with openssl:

# 1. Generate a private key for the CA
openssl genrsa -out ca.key 4096

# 2. Create a self-signed root CA certificate (valid 10 years).
#    The CA basic constraint is required — the server looks for it when loading the bundle.
openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 \
  -subj "/O=YourOrganization/CN=XiansAi Root CA" \
  -addext "basicConstraints=critical,CA:true" \
  -addext "keyUsage=critical,digitalSignature,keyCertSign,cRLSign" \
  -out ca.crt

# 3. Bundle the certificate and key into a password-protected PFX
openssl pkcs12 -export -out ca.pfx -inkey ca.key -in ca.crt \
  -passout pass:<pfx-password>

# 4. Base64-encode the PFX as a single line (portable across macOS/Linux)
openssl base64 -A -in ca.pfx -out ca.pfx.base64

Set Certificates__AppServerPfxBase64 to the contents of ca.pfx.base64 and Certificates__AppServerCertPassword to the password you chose in step 3. Alternatively, the server repository ships a ready-made script that does all of the above: infra/root-cert-gen.sh (run it as ./root-cert-gen.sh -p <pfx-password>).

CORS — optional¶

Only needed when browser-based clients (e.g. custom apps calling the UserAPI) call the server directly. Set the origins they are served from; array entries use index notation. Defaults to no allowed origins.

Cors__AllowedOrigins__0=https://custom-ui.your-domain.com
Cors__AllowedOrigins__1=https://app.your-domain.com

Optional settings¶

None of these are needed to get started — the defaults work out of the box.

# Caching: "memory" (default) or "redis".
# Use Redis when running multiple server replicas so they share cache state.
Cache__Provider=memory
Cache__Redis__ConnectionString=

# Email: "console" (default, prints to logs) or "azure" (Azure Communication Services).
# Used for tenant user-invitation emails.
Email__Provider=console
Email__Azure__ConnectionString=
Email__Azure__SenderEmail=

# WebSockets
WebSockets__Enabled=true

# Logging
Logging__LogLevel__Default=Information
Logging__LogLevel__Microsoft.AspNetCore=Warning

# Data Protection keys directory (see "Persisting Data Protection keys")
DataProtection__KeysDirectory=/app/keys

Running the Server¶

1. Create your environment file¶

Create an .env file with your real values — start from the minimal template above and add optional settings as needed.

# Generate the random secrets you'll need
openssl rand -base64 32   # run once per encryption key

For the certificate PFX, follow the steps in Certificates — required.

2. Run the container¶

docker run -d \
  --name xiansai-server \
  --env-file .env \
  -p 5001:8080 \
  --restart unless-stopped \
  99xio/xiansai-server:latest

3. Verify¶

curl http://localhost:5001/health
# Healthy

# Follow logs
docker logs -f xiansai-server

4. Bootstrap the platform¶

A fresh server has no users or tenants. Initialize it and obtain your first API key:

curl "http://localhost:5001/api/v1/admin/bootstrap?email=admin@your-domain.com"

See Platform Bootstrapping for the full flow, then point Agent Studio at the server using the returned key.

Running with Docker Compose¶

For a self-contained deployment you can define the server alongside its dependencies. The snippet below shows the server service; add your own MongoDB (as a replica set) and Temporal services, or point at managed instances.

services:
  xiansai-server:
    image: 99xio/xiansai-server:latest
    ports:
      - "5001:8080"
    env_file:
      - .env
    restart: unless-stopped
    volumes:
      - xiansai-keys:/app/keys
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

volumes:
  xiansai-keys:

docker compose up -d
docker compose logs -f xiansai-server

Persisting Data Protection keys¶

ASP.NET Core Data Protection keys are used to protect tokens and cookies. In production the container writes them to /app/keys, which is exposed as a Docker volume. Mount a persistent (and, for multiple replicas, shared) volume there so keys survive restarts and are consistent across instances.

docker run -d \
  --name xiansai-server \
  --env-file .env \
  -p 5001:8080 \
  -v xiansai-keys:/app/keys \
  99xio/xiansai-server:latest

Override the location with DataProtection__KeysDirectory if needed. If keys are not persisted, users may be logged out and encrypted cookies invalidated on every restart.

Running as separate microservices¶

The server can run as one combined process (default) or as independent, separately scalable services via SERVICE_TYPE:

Run each as its own container with the appropriate SERVICE_TYPE to scale them independently. See Scaling for guidance.

Updating¶

# Docker Compose
docker compose pull && docker compose up -d

# Plain docker run
docker pull 99xio/xiansai-server:latest
docker rm -f xiansai-server
docker run -d --name xiansai-server \
  --env-file .env -p 5001:8080 -v xiansai-keys:/app/keys \
  --restart unless-stopped 99xio/xiansai-server:latest

Troubleshooting¶

What's next?¶

• Platform Bootstrapping — initialize a fresh server and mint your first API key.
• Installing Agent Studio — stand up the web console against this server.
• Scaling — run and scale the server and agents.
• Chat Message Encryption — how encryption keys protect data at rest.