Settings

Every setting is an environment variable. A command-line argument (--SPARK_PORT=9000) also works, as does a key in a spark.json or spark.yml in the working directory. The console's Settings page shows the effective values and where each came from, with secrets masked.

SPARK_ADMIN_PASSWORD is required, also on a node. Spark stops at start with exit code 0xBAD (173 in a shell) when it is missing or shorter than 8 characters.

Server

Variable	Default	Meaning
SPARK_ADMIN_PASSWORD	none, required	The console's password, at least 8 characters.
SPARK_ADMIN_USER	admin	The console's user name.
SPARK_TITLE	Spark	The name shown in the console.
SPARK_SESSION_HOURS	168	How long a console sign-in lasts.
SPARK_REQUIRE_API_KEY	true	Whether the inference endpoints need a key.
SPARK_API_KEY	none	One more accepted key, at least 16 characters, for scripts.
SPARK_STORAGE	./storage	The database, models and fleet key.
SPARK_PORT	8080	The HTTP port.
SPARK_RESTRICT_LOCALHOST	false	Listen on loopback only.
SPARK_TRUSTED_PROXIES	loopback,private,cloudflare	Proxies whose forwarding headers name the client: addresses, CIDR ranges, loopback, private, cloudflare, none.
SPARK_IMAGE_URLS	public	Images given by http(s) URL: public (fetched from public addresses only), any or off.
SPARK_MAX_BODY_SIZE	64 MB	Largest request body.
SPARK_LOG_LEVEL	Information	The log level. Passed to the runners.

Models

Variable	Default	Meaning
SPARK_MODELS_FOLDER	$SPARK_STORAGE/models	Where GGUF files live. Any .gguf copied there appears in the library.
SPARK_HF_TOKEN	none	A Hugging Face token, for gated repositories and rate limits.
SPARK_DEFAULT_MODEL	none	The model for requests that name none. Otherwise the only model there is.
SPARK_UNKNOWN_MODEL_FALLBACK	false	Serve unknown model names with the default model instead of a 404.
SPARK_CONTEXT_LENGTH	4096	The default KV cache size, in tokens.
SPARK_IDLE_UNLOAD_MINUTES	30	Unload an unused model after this long. 0 is never.
SPARK_MAX_LOADED_MODELS	0	At most this many models loaded at once. 0 lets memory decide.

Devices and memory

Variable	Default	Meaning
SPARK_DEVICE	auto	Where a model runs unless its own setting says: auto, cpu, cuda or cuda:N.
SPARK_CUDA_DEVICES	all	The CUDA devices runners are placed on: all, or 0,1.
SPARK_CPU_RUNNERS	auto	Whether models may run on the CPU: auto (only when there is no CUDA device), true or false.
SPARK_THREADS	0	CPU threads per runner. 0 is all.
SPARK_MEMORY_RESERVE_MB	1024	Host memory never given to runners.
SPARK_VRAM_RESERVE_MB	auto	Memory kept free on each GPU. Auto is the larger of 512 MB and a sixteenth.
SPARK_HOST_EXPERTS	true	A mixture of experts too large for a GPU keeps the routed experts of its first layers in host memory instead of being refused.
SPARK_EXPERT_CACHE_PERCENT	10	With experts in host memory, the share of each such layer's experts the GPU caches. 0 turns the cache off.
SPARK_RUNNER_HANG_SECONDS	120	A runner silent this long is killed and restarted.
SPARK_RUNNER_PATH	beside spark	The spark-runner executable.

KV cache

See KV cache and snapshots.

Variable	Default	Meaning
SPARK_KV_CACHE_FOLDER	$SPARK_STORAGE/kvcache	KV snapshots, one folder per model.
SPARK_KV_CACHE_MB	auto	Per model. A quarter of the memory, at most half the free disk. -1 turns snapshots off.
SPARK_KV_CACHE_ENTRIES	64	Snapshots kept per model.
SPARK_KV_CACHE_MIN_TOKENS	64	Shorter conversations are not snapshotted.
SPARK_KV_CACHE_MIN_FREE_MB	auto	Free space kept on the snapshots' disk. 5% of the disk, between 1 GB and 10 GB.
SPARK_KV_CACHE_MAX_AGE_HOURS	168	A snapshot unused this long is deleted. 0 keeps it while there is room.
SPARK_KV_CACHE_TOTAL_MB	0	The most the snapshots of every model together may take. 0 is no limit beyond the disk margin.
SPARK_KV_CACHE_SWEEP_SECONDS	300	How often the server checks the disk, the age, the total and the folders of deleted models.

Request log

Variable	Default	Meaning
SPARK_REQUEST_LOG_RETENTION_DAYS	30	Delete older entries. 0 keeps them for ever.
SPARK_LOG_REQUEST_BODIES	true	Keep request bodies, prompts and answers in the log. For a zero retention key, in memory only.
SPARK_ZERO_RETENTION_MEMORY_MB	16	Memory for the content of the latest zero retention requests, never written to disk. 0 keeps none.

Fleet

See Fleet: central and nodes.

Variable	Default	Meaning
SPARK_ROLE	standalone	standalone, central or node.
SPARK_CENTRAL_ADDRESS	none	Node: the central's address.
SPARK_NODE_NAME	machine name	Node: its name on the central.
SPARK_NODE_ADDRESS	none	Node: the address the central calls it on.
SPARK_JOIN_TOKEN	none	Node: a join token from the central's Nodes page. Used once.

Install script variables

SPARK_VERSION, SPARK_INSTALL and SPARK_NO_MODIFY_PATH belong to the install scripts, not to the server. See Installation.