Configuration Reference

XSI configuration has three layers:

LayerLocationHow it takes effect
DeploymentEnvironment variables of the API and console containers (this page)Read once at startup; changes require a restart
TenantTenant configuration in Redis, changed through /x-config or the configuration consoleImmediately, synced to all instances automatically; see Tenant configuration API
AccountAccount records, changed through /x-users or the account consoleImmediately; 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

VariableDefaultDescription
PORT3443HTTP 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β€”, β€”, 0Primary Redis
MAIL_REDIS_ADDR, MAIL_REDIS_PASSSame as primary RedisRedis used for the mail queue and signup abuse prevention
MAIL_REDIS_DB1Mail 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

VariableDefaultDescription
SINGLE_TENANTtruetrue: self-registered accounts join the root tenant; false: every registered user becomes an independent tenant
SINGLE_MODEtruetrue: single instance, counters and notifications stay in process; false: multiple instances, shared through Redis. Only the literal value false turns it off
TRUSTED_PROXY_CIDRSLoopback and RFC 1918 private rangesTrusted reverse proxy ranges; the client IP is read from forwarding headers only for connections from these addresses
TZImage defaultTime 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.

VariableDefaultDescription
XAI_SVCxsirouter.comPrimary site domain
XAI_APIapi.<XAI_SVC>API URL; the activation link is https://<XAI_API>/x-sign/activate
XAI_ADMINadmin.<XAI_SVC>Configuration console
XAI_MANAGEmanage.<XAI_SVC>Account console
XAI_DOCSdocs.<XAI_SVC>Docs site
XAI_MAILBuilt-in valuePlatform 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

VariableDefaultDescription
SIGN_ENABLEtrueWhether self-service signup is open
SAFE_ENABLEtrueSignup abuse prevention (rate limits per IP and email)
XAI_CREDIT2 single-tenant, 120 multi-tenantSignup bonus (valid for 1 month); set to 0 in the deployment template
XAI_REFERRAL_REWARD_RATE0.05Referral reward rate, range 0–0.1; 0 disables referral codes

Accounts and billing

VariableDefaultDescription
USER_FILTERtrueWhether 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_BALANCE1Freeze 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_BALANCE100Minimum balance required for manager privileges; minimum 2
XAPI_FEE0.012Fixed fee for non-model operations, capped at 0.24
MONTHLY_USER_CREDIT3000Default monthly credit unit for subscription accounts (Role 3); minimum 100
STATS_INTERVAL1000Account state flush frequency: synced to Redis every N requests and written to PostgreSQL every 10N; minimum 10
SYNC_ENABLEfalseSync account state to Redis on every request (for debugging; has a performance cost)

Requests and upstreams

VariableDefaultDescription
REQUEST_BODY_LIMIT_BYTES209715200 (200 MiB)Maximum decompressed request body size; 0 means unlimited
RESPONSE_HEADER_TIMEOUT_SECS1800Maximum time to wait for upstream response headers (seconds)
MASK_ERRORSfalseReplace every upstream error body with status β‰₯ 400 with a uniform JSON
LOG_ENABLEfalseLog 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

VariableDefaultDescription
NO_RETRY_STATUS200,400,403,404,405,413,421,422,499,500Upstream status codes that are neither retried nor counted as model failures
STATUS_CODES429,401,402,503,408,524Upstream status codes that trigger key auto-sleep
KEY_BACK60Auto-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_THRESHOLD3Number of consecutive model failures that triggers group switchover or model failover
SWITCH_OVER_TTL1hGroup switchover duration, minimum 1 minute
MODEL_FAILOVER_TTL1hModel failover duration, minimum 1 minute
STICKY_SCHEDULERtrueGlobal sticky scheduling; when false, it applies only to the tenant's STICKY_LEVELS
STICKY_BINDING_TTL24hRetention time for session-to-key bindings

WebSocket

VariableDefaultDescription
WS_MAX_CONN_DURATION60mMaximum lifetime of a single WebSocket connection, minimum 5 minutes
WS_WRITE_TIMEOUT15sWebSocket write timeout, minimum 3 seconds
WS_DASHSCOPE_REALTIME_MAX_CONN_DURATION120mMaximum lifetime of a DashScope Realtime connection
WS_RESPONSES_INITIAL_CONNECT_ATTEMPTS3Number of keys tried when a Responses WebSocket first connects upstream
WS_RESPONSES_MAX_TURN_RETRIES2Retries per turn for Responses WebSocket

Usage estimation and files

VariableDefaultDescription
SESSION_USAGE_TTL30mRetention time for a session's most recent actual usage, used to estimate usage for interrupted requests
SESSION_USAGE_LIMIT100000Maximum number of entries in that cache
USAGE_ESTIMATE_ALERT_CREDIT100Log an alert when an account's estimated charges for the day reach this amount
USAGE_ESTIMATE_ALERT_SHARE0.3Required together with the previous setting: the estimated portion is at least this share of the day's charges
FILE_REGISTRY_TTL3 yearsRetention 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.

VariableDescription
EMAIL_SMTP, EMAIL_PORT, EMAIL_AUTH, EMAIL_PASS, EMAIL_SENDERDefaults 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_YEARYear 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.

VariableDescription
XAI_APIAPI URL; defaults to api.<current primary domain> if unset
XAI_ADMIN, XAI_MANAGEURLs the two consoles use to link to each other
BRAND_NAMEConsole brand name
XPAY_APIPayment gateway tenant URL, must include /t/<tenant>; when empty, wallet, products, and revenue statistics are disabled
SUPPORT_QR_URLSupport QR code
XAI_CARD_APIWhen non-empty, the brand logo links to this site
XAI_HIDE_MODEL_PRICINGWhen true, hides the "Models & pricing" link
XAI_PLATFORM_MODEConsole display mode
XAI_REFERRAL_REWARD_RATEReferral reward rate shown in the frontend; should match the API variable of the same name
LICENSE_IDCommercial 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.