Deployment Guide

Xenon supports three deployment topologies. Choose the one that matches your scale and infrastructure.

---

1. Standalone (Single Node)

The simplest setup — one machine running Appium + Xenon with devices connected directly. Best for local development, small teams, or CI runners.

Characteristics:

• SQLite database (zero setup)
• All devices connected to a single host
• Dashboard accessible on the same machine

YAML Config

server:
  keepAliveTimeout: 800
  basePath: /wd/hub
  usePlugins:
    - xenon
  plugin:
    xenon:
      platform: both
      maxSessions: 8
      enableDashboard: true
      bootedSimulators: true

CLI

appium server -ka 800 --use-plugins=xenon \
  -pa /wd/hub \
  --plugin-xenon-platform=both \
  --plugin-xenon-max-sessions=8 \
  --plugin-xenon-enable-dashboard=true

Database

By default, Xenon uses SQLite stored at ~/.cache/xenon/xenon.db. No setup required.

---

2. Hub-Node (Distributed Grid)

For larger teams or CI farms with devices spread across multiple machines. The Hub acts as the controller and the Nodes register via gRPC.

Hub Configuration

server:
  keepAliveTimeout: 800
  basePath: /wd/hub
  usePlugins:
    - xenon
  plugin:
    xenon:
      platform: both
      maxSessions: 16
      enableDashboard: true
      databaseProvider: postgresql
      databaseUrl: "postgresql://user:password@localhost:5432/xenon"

Node Configuration

server:
  keepAliveTimeout: 800
  basePath: /wd/hub
  usePlugins:
    - xenon
  plugin:
    xenon:
      platform: android
      hub: "http://hub-ip:4723"

PostgreSQL Setup

PostgreSQL is required for Hub-Node deployments to maintain shared state across nodes.

# Create the database
createdb xenon

# Set the connection URL
export DATABASE_URL="postgresql://user:password@localhost:5432/xenon"

# Or configure via plugin args
--plugin-xenon-database-provider=postgresql
--plugin-xenon-database-url="postgresql://user:password@localhost:5432/xenon"

info

Xenon automatically runs database migrations on first start. No manual schema setup is needed.

---

3. Cloud Execution

Execute tests on cloud device farms without managing physical hardware. Xenon supports five cloud providers:

Provider	Configuration Key
BrowserStack	browserstack
SauceLabs	sauce
LambdaTest	lambdatest
HeadSpin	headspin
pCloudy	pcloudy

See the Cloud Execution Guide for provider-specific setup.

---

Environment Variables Reference

Variable	Description	Default
DATABASE_URL	PostgreSQL or SQLite connection string	file:~/.cache/xenon/xenon.db
XENON_DB_PROVIDER	Database provider (sqlite or postgresql)	sqlite
GEMINI_API_KEY	Google Gemini API key for AI features	—
OPENAI_API_KEY	OpenAI API key for AI features	—
ANTHROPIC_API_KEY	Anthropic API key for AI features	—
XENON_AI_PROVIDER	AI provider selection	gemini
XENON_AI_MODEL	AI model override	Provider default
XENON_AI_BASE_URL	Custom AI endpoint (for Ollama)	—
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry collector endpoint	—
XENON_OTEL_DEBUG	Log traces to console	false

---

Production Checklist

• Use PostgreSQL for any multi-node deployment
• Set maxSessions to match your hardware capacity (CPU cores × 2 is a good starting point)
• Configure newCommandTimeoutSec to auto-release idle sessions (default: 60s)
• Set up Data Retention policies to prevent disk exhaustion
• Configure Notifications for device_offline alerts
• Enable AI Features for automatic failure triage
• Set keepAliveTimeout to at least 600 for long-running tests