All XeroML configuration is done via environment variables. This page documents the available variables for self-hosted deployments.
Required
| Variable | Description |
|---|
NEXTAUTH_URL | The canonical URL of your XeroML instance (e.g., https://xeroml.yourdomain.com) |
NEXTAUTH_SECRET | Random secret for session encryption. Generate with: openssl rand -hex 32 |
SALT | Random secret for hashing. Generate with: openssl rand -hex 32 |
DATABASE_URL | PostgreSQL connection string: postgresql://user:pass@host:5432/xeroml |
Database
| Variable | Default | Description |
|---|
DATABASE_URL | — | PostgreSQL connection string |
DIRECT_URL | Same as DATABASE_URL | Direct connection URL (required for migrations) |
SHADOW_DATABASE_URL | — | Shadow database for migrations in some environments |
ClickHouse (Optional)
ClickHouse is required for large-scale trace storage. Without it, traces are stored in PostgreSQL (limited to ~1M traces).
| Variable | Default | Description |
|---|
CLICKHOUSE_URL | — | ClickHouse connection URL |
CLICKHOUSE_USER | default | ClickHouse username |
CLICKHOUSE_PASSWORD | — | ClickHouse password |
Redis
| Variable | Default | Description |
|---|
REDIS_CONNECTION_STRING | — | Redis connection URL (redis://host:6379) |
REDIS_TLS_ENABLED | false | Enable TLS for Redis connection |
Storage
| Variable | Default | Description |
|---|
XEROML_S3_MEDIA_UPLOAD_ENABLED | false | Enable S3-compatible blob storage |
S3_BUCKET_NAME | — | Bucket name |
S3_ENDPOINT | — | S3 endpoint URL (for non-AWS providers) |
S3_REGION | us-east-1 | AWS region |
S3_ACCESS_KEY | — | Access key ID |
S3_SECRET_KEY | — | Secret access key |
Authentication
| Variable | Default | Description |
|---|
AUTH_DISABLE_USERNAME_PASSWORD | false | Disable email/password login |
AUTH_GOOGLE_CLIENT_ID | — | Google OAuth client ID |
AUTH_GOOGLE_CLIENT_SECRET | — | Google OAuth client secret |
AUTH_GITHUB_CLIENT_ID | — | GitHub OAuth client ID |
AUTH_GITHUB_CLIENT_SECRET | — | GitHub OAuth client secret |
AUTH_OKTA_CLIENT_ID | — | Okta OIDC client ID |
AUTH_OKTA_CLIENT_SECRET | — | Okta OIDC client secret |
AUTH_OKTA_ISSUER | — | Okta issuer URL |
Email
| Variable | Default | Description |
|---|
SMTP_HOST | — | SMTP server hostname |
SMTP_PORT | 587 | SMTP port |
SMTP_USER | — | SMTP username |
SMTP_PASSWORD | — | SMTP password |
EMAIL_FROM | — | Sender address for transactional emails |
Telemetry
| Variable | Default | Description |
|---|
XEROML_ENABLE_EXPERIMENTAL_FEATURES | false | Enable features in active development |
XEROML_DISABLE_EXPENSIVE_POSTGRES_QUERIES | false | Optimize for high trace volume on PostgreSQL-only setups |
XEROML_LOG_LEVEL | info | Log verbosity: debug, info, warn, error |
Security
| Variable | Default | Description |
|---|
ALLOWED_ORIGINS | — | Comma-separated list of allowed CORS origins |
HTTP_PROXY | — | Outbound HTTP proxy for LLM API calls from evaluators |
HTTPS_PROXY | — | Outbound HTTPS proxy |
NO_PROXY | — | Hosts to bypass proxy |
