Environment variables

This page covers the day-to-day surface only: identity/profile selection, provider auth, and the handful of VEYYON_* variables that are actually read by the runtime today. Veyyon also reads a large number of PI_* debug/behavior-toggle variables (timing, startup tracing, TUI flags, eval-runtime toggles, and more) that are not day-to-day configuration. For the complete, code-grounded reference — including every provider credential var, precedence chains, and internal toggles — see docs/environment-variables.md.

Location and identity

There is no VEYYON_HOME. The config directory name (not a full path) is overridable, and the active profile is selected by its own variable:

On Linux, veyyon config init-xdg migrates state under $XDG_DATA_HOME/$XDG_STATE_HOME/$XDG_CACHE_HOME when those are set; unmigrated installs stay under ~/.veyyon. See packages/utils/src/dirs.ts.

There is no separate SQLite-state-directory override; state lives under the resolved agent directory above.

Authentication

Provider BYOK uses each provider’s native key variable — there is no Veyyon-branded API key or access token (a VEYYON_API_KEY/VEYYON_ACCESS_TOKEN legacy alias does not exist in the current runtime). When a provider’s key variable is set, it is used without an interactive sign-in. For providers with OAuth (Anthropic, xAI, Qwen, Cursor, and others), the OAuth token variable takes precedence over the plain API key — see the provider tables below and docs/environment-variables.md.

OAuth sign-in itself is interactive: run /login inside the TUI (or --provider <id> at startup) to open the OAuth selector. There is no veyyon login --with-api-key/--with-access-token CLI subcommand; piping a key into a login command is not part of the shipped CLI surface.

Provider keys

Each model provider reads its own standard key variable (or the name in [model_providers.<id>].env_key for a custom provider). When set, it is used without an interactive sign-in and wins over a stored key.

A custom provider uses whatever variable its [model_providers.<id>].env_key names. See Configuration and the full provider table in docs/environment-variables.md (30+ providers, cloud auth chains for Bedrock/Vertex/Azure, and web-search provider keys).

Local and self-hosted providers

There is no VEYYON_OSS_BASE_URL/VEYYON_OSS_PORT; each local backend has its own discovery variable above.

TLS and certificates

There is no VEYYON_CA_CERTIFICATE or SSL_CERT_FILE support; NODE_EXTRA_CA_CERTS is the real override, honored across providers because Bun’s fetch does not read it natively (Veyyon merges it into RequestInit.tls.ca itself).

Install and updates

There is no VEYYON_NON_INTERACTIVE or VEYYON_INSTALL_URL; the install scripts (scripts/install.sh, scripts/install.ps1) do not read those names today.

MCP

Any MCP server names its own bearer-token secret via [mcp_servers.<name>].bearer_token_env_var in config.yml — this points at any env var you choose (for example plain GITHUB_PERSONAL_ACCESS_TOKEN), not a fixed VEYYON_* name. There is no VEYYON_GITHUB_PERSONAL_ACCESS_TOKEN or VEYYON_CONNECTORS_TOKEN convention in the current runtime.

See Configuration for bearer_token_env_var examples.

Remote auth broker (optional)

Real, shipped VEYYON_* variables that switch credential resolution from local SQLite to a remote broker host:

Most installs never set these. Details: docs/auth-broker-gateway.md.

Repair

There is no VEYYON_REPAIR_LOG; per-(model,tool,shape) repair telemetry is Spec — not shipped.

Terminal behavior

There is no VEYYON_TUI_DISABLE_KEYBOARD_ENHANCEMENT, VEYYON_TUI_RECORD_SESSION, or VEYYON_TUI_SESSION_LOG_PATH; see docs/environment-variables.md for the real PI_*-prefixed TUI flags.

Removed / does not exist

Config values can also be overridden per run with -c key=value, which is usually clearer than an environment variable; see the CLI reference.