Environment Variables

Every environment variable actually read by Hoziron code (crates/, bin/), found by grepping for env::var/env::var_os calls and excluding test-only scaffolding. If a variable isn't in this list, Hoziron doesn't read it.

Platform Variables

Variable	Purpose	Default	Read in
`HOZIRON_HOME`	Config/data/log directory root. Critical in containers — `dirs::home_dir()` returns `None` in the distroless image, so `HOZIRON_HOME` must be set explicitly (the Dockerfile sets it to `/data`)	`~/.hoziron` (falls back to the system temp dir if home can't be resolved)	`bin/hoziron-server/src/main.rs`, `bin/hoziron-cli/src/config.rs`, `crates/platform/hoziron-core/src/config.rs`, `crates/platform/hoziron-core/src/platform/boot.rs`, `crates/platform/hoziron-core/src/catalog/client.rs`, `crates/platform/hoziron-core/src/pii/vault.rs`, `crates/platform/hoziron-core/src/channel/bridge.rs`, `crates/surfaces/hoziron-api/src/routes.rs`, `crates/surfaces/hoziron-registry/src/lib.rs`, `crates/kernel/hoziron-kernel/src/config.rs`, `crates/kernel/hoziron-kernel-types/src/config.rs`
`HOZIRON_LOG`	`tracing`/`EnvFilter` directives (e.g. `info,hoziron_core=debug`)	`info` on the server (falling back to the standard `RUST_LOG` env var, then `"info"`, if unset); `warn` (stderr CLI commands) / `info` (file-logging CLI commands) on the CLI	`bin/hoziron-server/src/main.rs`, `bin/hoziron-cli/src/config.rs`
`HOZIRON_LOG_FORMAT`	Log output format: `json` triggers structured logs on both the server and the CLI; anything else keeps human-readable text	`text`	`bin/hoziron-server/src/main.rs`, `bin/hoziron-cli/src/config.rs`

[logging] in config.toml is parsed but not currently read by either binary — format/level there have no effect today; HOZIRON_LOG / HOZIRON_LOG_FORMAT are the only real controls, on both the server and the CLI. See the [logging] note in config-toml.md.

Provider API Keys

Precedence for every driver: an explicit [[provider]] api_key_env (or api_key on the resolved DriverConfig) always wins. If unset, the driver falls back to its own conventional env var name below — these are the built-in fallbacks, not something you have to opt into.

Variable	Driver(s)	Notes
`ANTHROPIC_API_KEY`	`anthropic`	The only AlwaysCloud driver with a fixed endpoint — no `url` needed
`OPENAI_API_KEY`	`openai`
`GROQ_API_KEY`	`groq`
`AZURE_OPENAI_API_KEY`	`azure` / `azure-openai`	Also requires `base_url` on the provider entry (`https://{resource}.openai.azure.com/openai/deployments`)
`GEMINI_API_KEY`, `GOOGLE_API_KEY`	`gemini`	Checked in that order
`GOOGLE_APPLICATION_CREDENTIALS`	`vertex-ai` / `vertex` / `google-vertex`	Path to a service-account JSON key; project ID is read from it if `GOOGLE_CLOUD_PROJECT`/`GCLOUD_PROJECT`/`GCP_PROJECT` aren't set
`GOOGLE_CLOUD_PROJECT`, `GCLOUD_PROJECT`, `GCP_PROJECT`	`vertex-ai` / `vertex` / `google-vertex`	Project ID, checked in that order before falling back to the service-account JSON
`GOOGLE_CLOUD_REGION`, `VERTEX_AI_REGION`	`vertex-ai` / `vertex` / `google-vertex`	Region, checked in that order; defaults to `us-central1`
`VERTEX_AI_ACCESS_TOKEN`	`vertex-ai` / `vertex` / `google-vertex`	OAuth access token, alternative to service-account credentials
`AWS_BEARER_TOKEN_BEDROCK`	`bedrock`	Bedrock API key (Bearer token)
`AWS_REGION`, `AWS_DEFAULT_REGION`	`bedrock`	Checked in that order
`KIMI_API_KEY`	`kimi_coding`	Anthropic-compatible endpoint
`OLLAMA_BASE_URL`, `OLLAMA_HOST`	`ollama`	Endpoint URL fallback when `[[provider]] url` isn't set — `_BASE_URL` checked first, then `_HOST` (bare host:port, auto-normalized to `http://…/v1`)
`LMSTUDIO_BASE_URL`, `LMSTUDIO_HOST`	`lmstudio`	Same pattern as Ollama
`VLLM_BASE_URL`, `VLLM_HOST`	`vllm`	Same pattern as Ollama
`LEMONADE_BASE_URL`, `LEMONADE_HOST`	`lemonade`	Same pattern as Ollama

All other AlwaysCloud drivers (openrouter, deepseek, together, mistral, fireworks, perplexity, cohere, ai21, cerebras, sambanova, huggingface, xai, replicate, moonshot, qwen, minimax, zhipu/glm, qianfan/baidu, volcengine, chutes, venice, nvidia/nvidia-nim, novita, etc.) take their key exclusively from the [[provider]] api_key_env config field — there is no hardcoded env var fallback for them in the driver dispatch table. Set api_key_env explicitly for these.

Provider keys are resolved lazily at request time — adding or removing them takes effect immediately without a daemon restart.

Telemetry

Variable	Purpose	Default
`OTEL_EXPORTER_OTLP_ENDPOINT`	OpenTelemetry collector endpoint (standard OTel convention). Overridden by `[telemetry].endpoint` in `config.toml` if set	`http://localhost:4317` (only used when `[telemetry].enabled = true` and the server was built with the `telemetry` Cargo feature)

Registry / Catalog

Variable	Purpose	Notes
`HOZIRON_REGISTRY_TOKEN`	Global fallback auth token for private registries (used by CI/CD)	Read in `crates/platform/hoziron-core/src/catalog/client.rs`. Resolution order per registry: inline `token` in `[[catalog.registries]]` → this env var → the registry's own `auth_token_env` (vault first, then env var)

CLI Context (client-side, `hoziron-cli` only)

These configure which server the hoziron-cli CLI talks to — they have no effect on hoziron-server.

Variable	Purpose	Notes
`HOZIRON_URL`	Server URL used by `hoziron-cli init --quick`/non-interactive setup	Read in `bin/hoziron-cli/src/setup.rs`. No default — quick setup aborts without it
`HOZIRON_CONTEXT`	Selects a named CLI context (multi-server setups)	Priority: `--context` flag > this env var > `current_context` in `config.toml`. Default context name on quick setup: `"default"`
`HOZIRON_API_KEY`	API key used during `hoziron-cli init --quick` to configure the new context's auth	Read in `bin/hoziron-cli/src/setup.rs`

Kernel / Runtime Tuning

Lower-level knobs, mostly no-rebuild escape hatches for operators tuning a specific host or debugging a specific driver — not everyday config.

Variable	Purpose	Default	Read in
`HOZIRON_DB_LOCK_RETRY_MS`	How long boot rides out `journal_mode=WAL` SQLite contention before giving up — useful on a slow host or the two-process e2e harness	`10000`	`crates/kernel/hoziron-memory/src/substrate.rs`, and mirrored in `hoziron-extensions/src/secrets/store.rs`, `hoziron-registry/src/index.rs`, `hoziron-core/src/pii/vault.rs`, `hoziron-core/src/store/mod.rs`
`OPENFANG_VAULT_KEY`	Vault encryption key override for headless/CI environments (normally derived interactively)	none	`crates/kernel/hoziron-extensions/src/vault.rs`
`HOZIRON_SURFACE_SCOPE`	Set by `hoziron-server` itself to scope the ADR-064 instance-lock (flock) so multiple surface processes for the same `HOZIRON_HOME` can coexist (Issue #748) — not something an operator sets by hand	empty	`crates/platform/hoziron-core/src/platform/boot.rs`
`OPENFANG_HOME`	Deprecated legacy fallback for `HOZIRON_HOME`. Prints a deprecation warning to stderr if used	—	`crates/kernel/hoziron-kernel-types/src/config.rs`. Resolution order: `HOZIRON_HOME` > `OPENFANG_HOME` (deprecated) > `~/.hoziron`
`OPENFANG_LISTEN`	Kernel-level convenience override for the API listen address, mainly for simple Docker one-liners	none	`crates/kernel/hoziron-kernel/src/kernel.rs`
`OPENFANG_API_KEY`	Kernel-level convenience override that sets the API authentication key	none	`crates/kernel/hoziron-kernel/src/kernel.rs`
`OPENFANG_SUBPROCESS_TIMEOUT_SECS`	No-rebuild override for subprocess-driver timeouts. Only the `claude-code` driver reads it today (highest-precedence: env var > `DriverConfig.subprocess_timeout_secs` from `config.toml` > 300s driver default); other subprocess drivers accept the field silently for forward-compat	300s (driver default)	`crates/kernel/hoziron-runtime/src/drivers/mod.rs`
`CODEX_HOME`	Path override for locating the Codex CLI's `auth.json` when auto-detecting an OpenAI key for the `codex` driver	`~/.codex`	`crates/kernel/hoziron-runtime/src/model_catalog.rs`

Container-Specific

Variable	Purpose	Notes
`HOZIRON_HOME`	See above — must be set to a writable path (`/data` in the shipped image) since the distroless base has no resolvable home directory

Resolution Behavior

Variables prefixed with HOZIRON_ are platform/CLI configuration
Provider key variables are named by convention per driver, or overridden by the api_key_env config field
Registry tokens are named by the auth_token_env field per registry, with HOZIRON_REGISTRY_TOKEN as a global fallback
All credential variables are read lazily — never cached at startup

Related: