Self-Hosting XeroML
XeroML is fully open source and can be self-hosted on your own infrastructure. Self-hosting gives you complete control over your data, lets you run XeroML inside your VPC, and enables compliance with data residency requirements.
Why Self-Host?
- Data residency — keep all trace data in your own environment, never in XeroML Cloud
- Network isolation — run inside a private VPC with no public internet access required
- Custom configuration — integrate with your existing SSO, databases, and storage
- No usage limits — unlimited traces, prompts, and evaluations
- Open source — audit, modify, and contribute to the codebase
Architecture Overview
XeroML consists of:
| Component | Role |
|---|---|
| Web application | Next.js frontend and API server |
| Worker | Background job processing (evaluators, exports) |
| PostgreSQL | Primary relational database |
| ClickHouse | Analytics and trace storage at scale |
| Redis | Caching and queue management |
| Blob Storage | Media files, exports (optional) |
For smaller deployments, PostgreSQL can handle trace storage without ClickHouse.
Deployment Options
| Method | Best for |
|---|---|
| Docker Compose | Single-server, development, small teams |
| Kubernetes / Helm | Production, scalable, existing K8s clusters |
| AWS | ECS or EKS on AWS |
| Azure | AKS or Azure Container Apps |
| GCP | GKE or Cloud Run |
License
XeroML is MIT-licensed. Self-hosted deployments of the core platform do not require a commercial license.
Enterprise features (SSO, audit logs, advanced RBAC, SLA support) may require a license key for self-hosted deployments. See License Key for details.
Getting Started
The fastest way to try self-hosting is with Docker Compose:
For production deployments, start with the Kubernetes/Helm guide:
Configuration
All configuration is done via environment variables. See Configuration Reference for the full list of available settings.
Upgrades
XeroML releases new versions regularly. See the Changelog and follow the upgrade guide:
Support
For self-hosting support:
- GitHub Issues for bugs
- GitHub Discussions for questions
- Enterprise support available with a license key