Configuration Reference
XSI configuration has three layers:
| Layer | Location | How it takes effect |
|---|
| Deployment | Environment variables of the API and console containers (this page) | Read once at startup; changes require a restart |
| Tenant | Tenant configuration in Redis, changed through /x-config or the configuration console | Immediately, synced to all instances automatically; see Tenant configuration API |
| Account | Account records, changed through /x-users or the account console | Immediately; see Account management API |
Parsing rules: an environment variable takes effect whenever it is present, even as an empty string (for example, EMAIL_SMTP: "" yields an empty value, not the default). Integer variables fall back to the default if they cannot be parsed or are below the minimum; duration variables accept 90m, 2h, or integer seconds and are raised to the minimum if below it; list variables are separated by , or ;, and must not have spaces after the separator.
Some variable names start with XAI_. This is a historical naming convention; they behave like any other XSI setting.
Connections and initialization
| Variable | Default | Description |
|---|
PORT | 3443 | HTTP listening port |
POSTGRES_DSN | β | PostgreSQL connection string (GORM format); the process exits if the connection fails. Tables and indexes are created automatically on first start |
REDIS_ADDR, REDIS_PASS, REDIS_DB | β, β, 0 | Primary Redis |
MAIL_REDIS_ADDR, MAIL_REDIS_PASS | Same as primary Redis | Redis used for the mail queue and signup abuse prevention |
MAIL_REDIS_DB | 1 | Mail queue DB, minimum 1; must match the mail service's REDIS_DB |
INIT_USERS | β | Initial accounts in the format name::email::key, separated by ,. Only accounts that do not exist yet are created; existing accounts are never updated. The account named root becomes the platform root and should come first; keys must be in the 51-character sk-Xvs format |
Deployment mode
| Variable | Default | Description |
|---|
SINGLE_TENANT | true | true: self-registered accounts join the root tenant; false: every registered user becomes an independent tenant |
SINGLE_MODE | true | true: single instance, counters and notifications stay in process; false: multiple instances, shared through Redis. Only the literal value false turns it off |
TRUSTED_PROXY_CIDRS | Loopback and RFC 1918 private ranges | Trusted reverse proxy ranges; the client IP is read from forwarding headers only for connections from these addresses |
TZ | Image default | Time zone; determines when date-based statistics, daily quotas, and RPD/TPD reset |
Site URLs
Used in email content, activation links, and console redirects. Use hostnames only, without a scheme or path.
| Variable | Default | Description |
|---|
XAI_SVC | xsirouter.com | Primary site domain |
XAI_API | api.<XAI_SVC> | API URL; the activation link is https://<XAI_API>/x-sign/activate |
XAI_ADMIN | admin.<XAI_SVC> | Configuration console |
XAI_MANAGE | manage.<XAI_SVC> | Account console |
XAI_DOCS | docs.<XAI_SVC> | Docs site |
XAI_MAIL | Built-in value | Platform notification recipient, used when a tenant has not configured XAI_MAIL. The default recipient built into the code does not belong to your organization, so you must set it to your own email when deploying (the Compose template sets it next to the root email) |
QR_CODE | β | Default support QR code URL |
Signup
| Variable | Default | Description |
|---|
SIGN_ENABLE | true | Whether self-service signup is open |
SAFE_ENABLE | true | Signup abuse prevention (rate limits per IP and email) |
XAI_CREDIT | 2 single-tenant, 120 multi-tenant | Signup bonus (valid for 1 month); set to 0 in the deployment template |
XAI_REFERRAL_REWARD_RATE | 0.05 | Referral reward rate, range 0β0.1; 0 disables referral codes |
Accounts and billing
| Variable | Default | Description |
|---|
USER_FILTER | true | Whether to run admission checks (IP, status, quota, rate limits, allowlists) and charge XAPI_FEE. false is only suitable for fully trusted internal environments; billing still runs as usual |
USER_MIN_BALANCE | 1 | Freeze threshold (the account is frozen when its balance falls below this value minus 0.01), also the minimum credit for a new sub-account; minimum 1 |
USER_API_BALANCE | 100 | Minimum balance required for manager privileges; minimum 2 |
XAPI_FEE | 0.012 | Fixed fee for non-model operations, capped at 0.24 |
MONTHLY_USER_CREDIT | 3000 | Default monthly credit unit for subscription accounts (Role 3); minimum 100 |
STATS_INTERVAL | 1000 | Account state flush frequency: synced to Redis every N requests and written to PostgreSQL every 10N; minimum 10 |
SYNC_ENABLE | false | Sync account state to Redis on every request (for debugging; has a performance cost) |
Requests and upstreams
| Variable | Default | Description |
|---|
REQUEST_BODY_LIMIT_BYTES | 209715200 (200 MiB) | Maximum decompressed request body size; 0 means unlimited |
RESPONSE_HEADER_TIMEOUT_SECS | 1800 | Maximum time to wait for upstream response headers (seconds) |
MASK_ERRORS | false | Replace every upstream error body with status β₯ 400 with a uniform JSON |
LOG_ENABLE | false | Log request bodies (for troubleshooting; mind privacy) |
AZURE_AI_APIVERSION | β | Default Azure api-version |
AZURE_AI_APIVERSION_CHAT, _RESPONSES, _EMBEDDINGS, _IMAGES, _AUDIO, _REALTIME | β | Azure api-version per endpoint type; a key's config.api_versions takes precedence |
Retries, sleep, and failover
| Variable | Default | Description |
|---|
NO_RETRY_STATUS | 200,400,403,404,405,413,421,422,499,500 | Upstream status codes that are neither retried nor counted as model failures |
STATUS_CODES | 429,401,402,503,408,524 | Upstream status codes that trigger key auto-sleep |
KEY_BACK | 60 | Auto-sleep duration (minutes), minimum 3 |
AUTO_DISABLE_KEY_STATUS | β | Status codes that trigger key auto-disable, for example 401 |
AUTO_DELETE_KEY_STATUS | β | Status codes that trigger key auto-delete; deletion wins if a code also appears in the previous setting |
MODEL_FAILOVER_THRESHOLD | 3 | Number of consecutive model failures that triggers group switchover or model failover |
SWITCH_OVER_TTL | 1h | Group switchover duration, minimum 1 minute |
MODEL_FAILOVER_TTL | 1h | Model failover duration, minimum 1 minute |
STICKY_SCHEDULER | true | Global sticky scheduling; when false, it applies only to the tenant's STICKY_LEVELS |
STICKY_BINDING_TTL | 24h | Retention time for session-to-key bindings |
WebSocket
| Variable | Default | Description |
|---|
WS_MAX_CONN_DURATION | 60m | Maximum lifetime of a single WebSocket connection, minimum 5 minutes |
WS_WRITE_TIMEOUT | 15s | WebSocket write timeout, minimum 3 seconds |
WS_DASHSCOPE_REALTIME_MAX_CONN_DURATION | 120m | Maximum lifetime of a DashScope Realtime connection |
WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS | 3 | Number of keys tried when a Responses WebSocket first connects upstream |
WS_RESPONSES_MAX_TURN_RETRIES | 2 | Retries per turn for Responses WebSocket |
Usage estimation and files
| Variable | Default | Description |
|---|
SESSION_USAGE_TTL | 30m | Retention time for a session's most recent actual usage, used to estimate usage for interrupted requests |
SESSION_USAGE_LIMIT | 100000 | Maximum number of entries in that cache |
USAGE_ESTIMATE_ALERT_CREDIT | 100 | Log an alert when an account's estimated charges for the day reach this amount |
USAGE_ESTIMATE_ALERT_SHARE | 0.3 | Required together with the previous setting: the estimated portion is at least this share of the day's charges |
FILE_REGISTRY_TTL | 3 years | Retention time for DeepSeek file ownership records |
Mail
The API never connects to SMTP directly. It writes messages to a Redis queue, and the proxyxai/mail service delivers them.
| Variable | Description |
|---|
EMAIL_SMTP, EMAIL_PORT, EMAIL_AUTH, EMAIL_PASS, EMAIL_SENDER | Defaults for tenant mail settings. The deployment template sets EMAIL_SMTP, EMAIL_AUTH, and EMAIL_PASS of the API container to empty strings so the mail service handles all delivery; do not rely on the defaults built into the code |
EMAIL_FOOTER_YEAR | Year shown in the email footer, defaults to the current year |
Mail service (xsirouter-mail) variables: REDIS_ADDR, REDIS_DB (1), EMAIL_SMTP, EMAIL_PORT, EMAIL_TLS, EMAIL_AUTH, EMAIL_PASS, EMAIL_WORKERS, REDIS_POP_TIMEOUT.
Console container
At startup, the console container renders the following variables into the browser-side config.js. Unset variables are empty.
| Variable | Description |
|---|
XAI_API | API URL; defaults to api.<current primary domain> if unset |
XAI_ADMIN, XAI_MANAGE | URLs the two consoles use to link to each other |
BRAND_NAME | Console brand name |
XPAY_API | Payment gateway tenant URL, must include /t/<tenant>; when empty, wallet, products, and revenue statistics are disabled |
SUPPORT_QR_URL | Support QR code |
XAI_CARD_API | When non-empty, the brand logo links to this site |
XAI_HIDE_MODEL_PRICING | When true, hides the "Models & pricing" link |
XAI_PLATFORM_MODE | Console display mode |
XAI_REFERRAL_REWARD_RATE | Referral reward rate shown in the frontend; should match the API variable of the same name |
LICENSE_ID | Commercial license ID; shows a license verification link |
Price table
The API image includes pricing.json in its working directory, /home/nonroot. When running the binary directly, start the process in the directory that contains pricing.json; if the file is missing, XSI falls back to a minimal built-in price table and system-level fuzzy matching stops working (models customized by tenants can still be matched). For routine price changes, use the tenant PRICING, which requires no restart.