Environment variables

What the runtime reads from its environment, and what it does with it. The tables below cover the APOLLIA_* names Apollia defines. Apollia also reads standard variables it does not own, where their usual meaning applies: EDITOR when apollia-os config edit opens apollia.toml, XDG_CONFIG_HOME when apollia-os doctor looks for a configuration file left in a former place and when apollia-os service install writes a systemd user unit, NO_COLOR for terminal output, PATH when it looks for a binary, TZ, and USERNAME on Windows to derive the named pipe. An OpenAI-compatible backend reads whatever variable its api_key_env names.

Most configuration belongs in apollia.toml, see Configuration. Environment variables cover three cases the file cannot: a secret you do not want on disk, a per-launch override, and a path that depends on the machine.

Local inference engine

Read at every engine start. See Accelerate local inference for what to tune and why.

Variable	Default	Effect
APOLLIA_LLAMA_SERVER_BIN	the engine bundled with the artifact	Absolute path to a llama-server binary, which takes precedence over the bundled one. The way to run a build of your own, a CUDA build on Linux among them.
APOLLIA_LLAMA_MAX_LOADED	(unset)	An explicit ceiling on how many models stay resident at once. Unset, the load guardrail decides: a model is judged with the footprints of the resident ones added to its own (see [llm.guardrails] in the configuration reference). A zero or unparseable value is ignored.
APOLLIA_LLAMA_N_CTX	(unset)	Context window in tokens, over every other source. Unset, the window is the preset's, the backend's, then the default of [llm.defaults] in apollia.toml, and 32768 last.
APOLLIA_LLAMA_N_GPU_LAYERS	planned, else 999	Layers offloaded to the GPU; 0 forces CPU. Left unset, the daemon plans the count from the model file on a discrete GPU, and passes 999 on Apple Silicon or with no GPU.
APOLLIA_LLAMA_N_BATCH	engine default	Logical batch size.
APOLLIA_LLAMA_N_UBATCH	engine default	Physical micro-batch size.
APOLLIA_LLAMA_N_PARALLEL	planned	Decode slots served concurrently. Unset, the count is planned from the model and the memory, up to 8; set, it is used as given.
APOLLIA_LLAMA_CONT_BATCHING	true	Continuous batching.
APOLLIA_LLAMA_CACHE_TYPE_K	engine default	KV cache quantization, keys.
APOLLIA_LLAMA_CACHE_TYPE_V	engine default	KV cache quantization, values.
APOLLIA_LLAMA_FLASH_ATTN	on	Flash attention mode.
APOLLIA_LLAMA_CACHE_REUSE	engine default	Prefix-reuse threshold.
APOLLIA_LLAMA_METRICS	false	Exposes the engine's metrics endpoint.
APOLLIA_LLAMA_LOG_VERBOSITY	4	Engine log level (-lv); 4 is where the load names its device and offload tally. Wins over [engines] log_level of apollia.toml (Settings > Developer).
APOLLIA_LLAMA_EXTRA_ARGS	empty	Extra flags passed through verbatim.

The GGUF the engine loads has no environment override, deliberately. It is state owned by the model switch in the interface, and an ambient variable pinning it would defeat every switch made there.

Secret storage

Variable	Default	Effect
APOLLIA_TOKEN_STORAGE	keyring	keyring uses the OS keychain. file stores secrets as age-encrypted files under ~/.apollia/secrets/, for a headless Linux host where no keyring daemon is reachable. Connector OAuth tokens follow this switch like every other secret: with file, the Google and Microsoft tokens are written there too. Any other value is refused.
APOLLIA_TOKEN_PASSPHRASE	none	Passphrase for the file backend. Mandatory when APOLLIA_TOKEN_STORAGE=file: startup fails fast without it, rather than falling back to something weaker.

Connector OAuth clients

The two connectors differ, and the variables below behave accordingly.

Microsoft ships ready to use: Apollia registers a public client application and embeds its identifier, so nothing has to be configured. A public client holds no secret, which is what makes shipping the identifier harmless; see Connect Microsoft 365.

Google ships without a client, and no published build embeds one. You register your own application and give Apollia its credentials, because Google requires a verified consent screen and a client secret that a distributed binary cannot hold. See Connect Google Workspace and Set up a Google OAuth client.

Either way, the supported route is the page of the connection, in Connections. The client id entered there is written to ~/.apollia/oauth-clients.toml; the client secret and the Google API key go to the secret store selected above, never to that file.

The variables below are the other way in, ahead of what the page saved, for a shell session, a CI job, or a host with no interface. They are read at process start, so they only reach an Apollia launched from the shell that exported them. Resolution order for each credential: environment variable, then the value the page saved (oauth-clients.toml for a client id, the secret store for a secret or an API key), then the build-time constant.

Variable	Effect
APOLLIA_GOOGLE_CLIENT_ID	Google client id. Required to connect Google.
APOLLIA_GOOGLE_CLIENT_SECRET	Paired secret. Also required: Google's Desktop client type demands it at the token endpoint, PKCE notwithstanding.
APOLLIA_GOOGLE_API_KEY	API key for the Google calls that use one rather than OAuth (Drive Picker).
APOLLIA_MICROSOFT_CLIENT_ID	Microsoft application (client) id. Optional, and it overrides the identifier Apollia ships. Set it only to point the connector at your own Entra registration; exporting it empty leaves Apollia's own identifier in place.
APOLLIA_MICROSOFT_CLIENT_SECRET	Paired secret. Leave unset: a Microsoft public client carries none, and sending one makes the exchange fail.
APOLLIA_MICROSOFT_API_KEY	API key, same role as above. Unused today.
APOLLIA_FIGMA_CLIENT_ID	Client id for the Figma connector.

Connections

Variable	Default	Effect
APOLLIA_MCP_REGISTRY_URL	https://registry.modelcontextprotocol.io	Address of the MCP registry the public catalogue is read from. Set it to point Apollia at a private registry. An empty value leaves the default in place.
APOLLIA_IMAP_PASSWORD	none	Application password read by apollia-os connector imap when --password-stdin is not given. The password is never taken from the command line.

Python and the MLX engine

Paths that depend on the machine. A packaged install sets or finds them on its own; they matter when Apollia runs from a source tree or beside a bundle that is not where it expects it.

Variable	Default	Effect
APOLLIA_BUNDLED_PYTHON	found beside the executable	Absolute path of the bundled Python interpreter. The desktop application exports it at startup.
APOLLIA_PYTHON_BUNDLE_DIR	found beside the executable	Directory the bundled Python interpreter sits in. The command-line launchers export it instead of the variable above; both are read.
APOLLIA_MLX_ENGINE_DIR	the newest MLX environment installed, else the bundled one	Directory holding the packages of the MLX engine.
APOLLIA_MLX_PYTHON	the bundled interpreter	Python interpreter the MLX engine runs on.

Diagnostics

Variable	Default	Effect
APOLLIA_PERF_TRACE	unset	Path to a file receiving a per-turn performance record. Unset means no file is written and no provenance is gathered; the summary is emitted at INFO either way.
APOLLIA_PERF_MODEL_SHA256	unset	Digest of the model file, written as given into the performance record instead of being computed. For a measurement campaign that reloads the same large model many times.
RUST_LOG	apollia=info	Standard tracing filter. apollia=trace is what makes [llm.observability] debug_log_prompt visible; see Configuration.

Desktop automation

APOLLIA_AUTOMATION, APOLLIA_AUTOMATION_OUT and APOLLIA_AUTOMATION_ALLOW_DESTRUCTIVE drive the development-only gestural test harness. They have no effect in a release build, where the harness is compiled out. APOLLIA_POLICY_DIR, which points the runtime at another organisation policy folder, follows the same rule: it is read in debug builds only.

Not read by the runtime

APOLLIA_BUILD_* variables are read at compile time, not at runtime; setting one before launching Apollia does nothing. APOLLIA_PYTHON is of the same kind: it names the Python interpreter the desktop build runs to pack the documentation the application embeds.

They are a hook for rebuilding Apollia from source against your own registered application, a fleet deployment being the obvious case: set them in the build environment and the resulting binary carries those credentials, so the machines it lands on need no per-host configuration.

No Apollia release sets them. For Google that means the compiled-in value is empty in every published build, and the two runtime sources above are the only ones that resolve. For Microsoft the compiled-in value is not empty even so: it comes from a constant in the source, not from these variables, which is why setting APOLLIA_BUILD_MICROSOFT_CLIENT_ID is only ever needed to replace Apollia's registration at build time.