Configuration reference — environment variables, flags and exit codes — AI Server

AI Server is configured by environment variables, which suit containers, and by matching command-line flags, which the Windows app uses for its service. A flag wins over its variable. The Windows app sets all of these for you from its Settings pages; you need this page for containers, Kubernetes and scripted installs.

The container images already set AISUITE_DATA=/data, XDG_DATA_HOME=/data, AISUITE_URLS=http://0.0.0.0:8080, AISUITE_LOG_JSON=1, AISUITE_DRAIN_SECONDS=8 and AISUITE_SHUTDOWN_SECONDS=30.

Network and identity

Variable	Flag	Default	Meaning
`AISUITE_URLS`	`--urls`	—	Exact Kestrel address(es), e.g. `http://0.0.0.0:8080` (the container images set this). `ASPNETCORE_URLS` is honoured when this is unset. A non-loopback address needs a paid licence and at least one API key, or the daemon refuses to start.
`AISUITE_PORT`	`--port`	`11436`	Port when `AISUITE_URLS` is not set. On a network bind the daemon stops if the port is taken; on loopback it picks a free port and reports it in `server.lock`.
`AISUITE_BIND`	`--bind`	`loopback`	`loopback`, `lan` (every IPv4 interface) or `all` (IPv4 and IPv6). Ignored when `AISUITE_URLS` is set. Without a paid licence, or before the first API key exists, `lan`/`all` fall back to loopback and log why (the server still starts).
`AISUITE_SERVER_TLS`	`--tls`	off	`1` serves HTTPS with a self-signed certificate (clients pin its fingerprint). If the certificate cannot be prepared on a network bind, the daemon stops instead of serving plain HTTP.
`AISUITE_SERVER_TLS_CUSTOM`	`--tls-custom`	off	`1` prefers a certificate you installed through the AI Server app over the self-signed one.
`AISUITE_TRUST_PROXY`	—	off	`1` trusts `X-Forwarded-For/-Proto/-Host`. Set it only when a proxy you control sits in front (an ingress, a load balancer, the AI Gateway).
`AISUITE_TRUSTED_PROXIES`	—	any sender	Comma-separated IPs or CIDRs allowed to send forwarded headers when `AISUITE_TRUST_PROXY=1`, e.g. `10.0.0.0/8,192.168.1.10`. Narrow it whenever you can.
`AISUITE_CORS_ORIGINS`	—	off	Comma-separated browser origins allowed to call the API (and to open the live-transcription WebSocket), or `*`.
`AISUITE_NODE_NAME`	—	machine name	Label for this node in the licence fleet view. The Helm chart sets it to the pod name.
`AISUITE_DASHBOARD`	—	on	`0` turns off the built-in `/dashboard` page.

Licensing

Variable	Flag	Default	Meaning
`AISUITE_LICENSE_KEY_FILE`	—	—	Path to a file holding the licence key. Preferred over `AISUITE_LICENSE_KEY`: environment values show up in `docker inspect`, `kubectl describe` and crash dumps.
`AISUITE_LICENSE_KEY`	`--license-key`	—	The licence key itself. One key licenses every node of a deployment; each node activates its own seat. A key that is definitively invalid, revoked or expired stops the daemon (exit code 4).
`AISUITE_REGISTRATION_URL`	—	`https://registration.softwaretailor.com`	Licence activation server. Each node activates there at first start and renews a signed 7-day lease about once a week; with 7 days' grace a node keeps serving through an outage of up to 14 days. An empty value means the default. Prompts and outputs are never sent there.

Without a paid licence the daemon serves loopback only. Personal allows network serving and up to 5 API keys; Commercial adds unlimited keys, governance (quotas, budgets, request scheduling, rate limits) and gateway mode. When a renewed lease changes the plan, the daemon logs it and exits with code 5 so the supervisor restarts it on the new plan.

Data and storage

Variable	Flag	Default	Meaning
`AISUITE_DATA`	`--data`	the AI Server app's data folder	State root: API keys, licence lease, audit log, governance policy, settings, logs. Mount a volume here.
`XDG_DATA_HOME`	—	`/data` in the images	Required when running as a non-root user without a home folder (containers, systemd `DynamicUser=`). Point it at an existing, writable directory — normally the same volume as `AISUITE_DATA`.
`AISUITE_CACHE_ROOT`	`--cache-root`	under the data root	Absolute folder for the large engine and model caches. Use it to put models on a separate, faster disk.
`AISUITE_SHARED_MODEL_CACHE`	`--shared-model-cache`	off	`1` shares one model store with the AI Suite desktop apps on the same machine. Desktop installs only.

Engine and behaviour

Variable	Flag	Default	Meaning
`AISUITE_ENGINE`	`--engine`	`stub`	`real` serves inference (downloads engines and models on first use). `gateway` runs the AI Gateway (Commercial). `stub` answers with canned replies and loads no models — for checking a deployment, never for users; the daemon logs a warning. `relay` runs the AI Relay sharing relay instead of an inference server.
`AISUITE_PER_KEY_RPM`	`--per-key-rpm`	`0` (off)	Requests per minute allowed per API key. Commercial.
`AISUITE_PER_IP_RPM`	`--per-ip-rpm`	`0` (off)	Requests per minute allowed per client IP. Commercial. Behind a proxy, set `AISUITE_TRUST_PROXY` so the real client IP is used.
`AISUITE_BATCH_MAX_JOBS`	—	`64`	Batch jobs kept at once (1–1024). One API key may hold at most a quarter of them.
`AISUITE_BATCH_MAX_INPUTS_PER_JOB`	—	`4096`	Inputs allowed in one batch job (1–65536).
`AISUITE_BATCH_RETENTION_HOURS`	—	`24`	Hours a finished batch job stays retrievable (1–168).

Logging and lifecycle

Variable	Flag	Default	Meaning
`AISUITE_LOG_LEVEL`	`--log-level`	`Information` (or the level chosen in the app)	`Trace`, `Debug`, `Information`, `Warning`, `Error` or `Critical`.
`AISUITE_LOG_JSON`	—	off (`1` in the images)	One JSON object per log line on stdout, for Fluent Bit, Loki or CloudWatch.
`AISUITE_LOG_FILE`	—	on, except in containers	Rolling log at `<data>/logs/aisuite-server-yyyyMMdd.log` (14 files of up to 50 MB, secrets redacted). `1` forces it on, `0` off.
`AISUITE_SERVICE_MODE`	`--service-mode`	off	`1` when running under a service manager (Windows service, systemd, launchd).
`AISUITE_DRAIN_SECONDS`	—	`8` in the images	On SIGTERM, seconds `/readyz` returns 503 before shutdown starts, so load balancers stop sending traffic first.
`AISUITE_SHUTDOWN_SECONDS`	—	`30` in the images	Time allowed for in-flight requests to finish. Keep drain + shutdown below your orchestrator's grace period.

AI Gateway (`AISUITE_ENGINE=gateway`)

Variable	Default	Meaning
`AISUITE_GATEWAY_ACTIVITY_SECONDS`	`600`	Idle timeout for one forwarded request (30–3600). Streaming output resets it.
`AISUITE_GATEWAY_RETRY_AFTER_SECONDS`	`5`	`Retry-After` sent with a 503 when no worker can take interactive work (1–300).
`AISUITE_GATEWAY_BG_RETRY_AFTER_SECONDS`	`30`	`Retry-After` for background work when the farm is busy (1–3600).

The worker pool itself is configured in <data>/gateway.json — see scaling and high availability.

AI Relay (`AISUITE_ENGINE=relay`)

Variable	Flag	Default	Meaning
`AISUITE_RELAY_SELF`	—	—	This node's public URL, for a relay fleet.
`AISUITE_RELAY_NODES`	—	—	Every fleet node's URL (comma or space separated). Groups are spread across nodes by hashing.
`AISUITE_RELAY_TURN_URLS`	—	—	`turn:`/`turns:` URLs of a co-located coturn server.
`AISUITE_RELAY_TURN_SECRET`	—	—	coturn `static-auth-secret`; with the URLs set, the relay issues short-lived TURN credentials.
`AISUITE_RELAY_TURN_TTL`	—	`600`	Lifetime of those credentials, in seconds.
`AISUITE_ENROLL_TOKEN`	`--enroll`	—	One-time token from AI Admin Console → Servers that enrols the relay with your organisation.
`AISUITE_ENROLL_WORKER_URL`	—	the publisher's service	Enrolment service URL. Change only when told to by support.

Exit codes

Code	Meaning
0	Stopped normally.
2	Refused to start: a non-loopback `AISUITE_URLS` without a paid licence or without API keys, gateway mode without Commercial, HTTPS requested on a network bind but no certificate, the port taken on a network bind. The reason is on stderr and in `<data>/logs`.
3	The region policy requires content moderation and none is configured.
4	The licence key was rejected (invalid, revoked or expired).
5	The licence plan changed while running; restart to apply it. Supervisors restart automatically.