Environment Variables

Use this reference when configuring credentials, relocating state, or diagnosing startup and script behavior. It inventories direct environment reads in src/, delegated provider settings, and build/test-only variables.

Get started

octomind login
octomind run

For a provider key you manage yourself, store its actual value in the environment or .env, then select a matching model. octomind config shows credential presence/source without displaying the key.

.env File Support

Octomind automatically loads .env files at startup, as an alternative to exporting variables in your shell. This is useful for API keys:

# .env
OPENROUTER_API_KEY="YOUR_PROVIDER_KEY"

Two .env locations are loaded, in precedence order (later wins):

1. User-scope — <config_dir>/.env in the shared config directory (under OCTOMIND_DATA_DIR or the standard data root, independent of OCTOMIND_CONFIG_PATH). Shared across all projects.
2. Project-local — ./.env in the current working directory. Overrides the user-scope file.

System environment variables are the base; both .env files override them.

Key behaviors:

• .env overrides the system environment. When a variable is defined in both, the .env value wins.
• Project-local .env overrides user-scope .env. A key set in the working directory wins over the same key in the shared config directory.
• Empty values are treated as "not set." A variable whose value is empty (or only whitespace) is reported as NotFound for API-key source detection — but they still overwrite a previous value. Individual providers need not treat empty strings as absent.
• Source tracking. The EnvTracker records whether each variable came from the system environment (System) or the .env file (DotEnv); the credential status rows in octomind config show this source. Tracking compares before/after values, so an identical .env value is still reported as the original environment source.

YOUR_PROVIDER_KEY is the credential you obtain from that provider. .env parsing happens before CLI/config loading; parse errors print a warning and stop the remaining dotenv steps. Set OCTOMIND_DATA_DIR in the launch environment if you want it to select the user-scope .env location.

API Keys

All API keys are read from environment variables for security. Never put API keys in config files — the octomind config --api-key provider:key command is intentionally rejected at runtime ("API keys can no longer be set in config file for security reasons") and tells you to export the matching environment variable instead.

Provider authentication is delegated through providers.rs to the locked octolib 0.35.0 implementation. These names are explicit provider contracts, not a universal uppercase-prefix rule. Keys are read during provider credential checks and requests; URL overrides are read when requests are built, except CLI backend settings, which are captured when that backend is constructed.

Provider credentials

Required unless the row says otherwise; unset credentials do not inherit from another provider.

export OPENROUTER_API_KEY="YOUR_PROVIDER_KEY"
echo "Explain this project" | octomind run --model openrouter:anthropic/claude-sonnet-4 --format plain

OAuth variables

The current CLI session preflight calls get_api_key(), which returns an error when either OAuth access-token variable is present. Thus provider-level OAuth support does not make an OAuth-only octomind run startup work. For the API-key path, remove the conflicting token from both .env and the launching environment:

unset OPENAI_OAUTH_ACCESS_TOKEN ANTHROPIC_OAUTH_ACCESS_TOKEN
octomind config

Provider routing and endpoint overrides

Each URL variable replaces the adapter’s default request URL unless its row says “base URL”. Leave it unset to use the built-in endpoint. There is no generic GOOGLE_API_URL or universal <PREFIX>_API_URL fallback.

The locked DeepSeek, Moonshot, and Together adapters use fixed endpoints; their API URL variables are not read. For your running local service (replace the model with one it serves):

export LOCAL_API_URL="http://127.0.0.1:8080/v1/chat/completions"
octomind run --model local:my-model

CLI meta-provider backend variables

cli:BACKEND/MODEL runs an installed executable. Octomind’s provider credential preflight skips cli; the external program manages its own authentication. The normalized backend name is uppercased in variable names.

export CLI_CODEX_COMMAND="codex"
export CLI_CODEX_REASONING_EFFORT="high"
octomind run --model cli:codex/gpt-5

Octomind Configuration

OCTOMIND_DATA_DIR=/tmp/octomind-demo octomind config
OCTOMIND_CONFIG_PATH=./octomind-config/config.toml octomind config --validate
RUST_LOG=octomind=debug octomind run
OCTOMIND_API_URL=http://127.0.0.1:8000 OCTOMIND_PANEL_URL=http://127.0.0.1:5173 octomind login --no-browser
OCTOMIND_MEDIA_ROOT=/srv/octomind/media octomind server
OCTOMIND_SHARE_URL=http://127.0.0.1:5173 octomind run

For preloading, select actual installed names from session /skill and capability discovery. For example, if code-review and filesystem are installed and eligible:

OCTOMIND_SKILLS=code-review OCTOMIND_CAPABILITIES=filesystem octomind run developer:general

Telemetry

Octomind reports anonymous usage so the CLI can be shaped by evidence rather than guesses. It is on by default and prints nothing — turn it off with DO_NOT_TRACK=1, OCTOMIND_TELEMETRY=0, or telemetry = false in the config. Opting out is local and instant: no request is made to announce it, and nothing is buffered.

What is sent — a start row per invocation, a session row from instrumented session/workflow exit paths, and an error row when a command fails:

• subcommand name and the long flag names used (never their values)
• CLI version, OS, architecture, install source (brew/cargo/docker/source/binary)
• whether the run is interactive, in CI, signed in, or a first run
• session shape: agent tag, provider and model id, duration, turns, tool-call count, token counts, cost, compression count, MCP server count, outcome, resume/sandbox flags, and how many times you interrupted it with Ctrl+C
• per-tool call counts, per-tool failure counts, and per-slash-command counts. Built-in tool names are sent as themselves; every other (MCP) tool is reduced to a fixed category such as ext:github, because MCP tool names come from your config
• provider failure counts by fixed kind (rate_limit, overloaded, auth, context_length, server, timeout, network) — counts only, never the provider's message
• for octomind workflow: the workflow's declared name (the label inside the file, never the path it was loaded from), step count and totals
• a random local install id, generated on your machine, tied to no identity. If you are signed in, the event is attributed to your account.

What is never sent — your code, prompts, model responses, file paths, tool arguments, shell commands, environment values, repository names or remotes, and error messages. Failures are reported only as a fixed slug (network, timeout, io, parse, other).

The exact wire keys are:

Empty/default optional fields are omitted; cost is integer micro-USD.

Everything transmitted is a named field on a struct in src/telemetry.rs; the declared agent/model/workflow identifiers are strings. Local supervisor statistics and learning-pack counters are not part of that wire schema. Events are buffered in memory and sent once at exit behind a 2-second timeout — flush can add up to that timeout to exit, and failures are only debug-logged.

complete and distill skip telemetry initialization. WebSocket has no dedicated session-exit event. Start rows also read CI (truthy by the same rule as DO_NOT_TRACK) and GITHUB_ACTIONS (any present Unicode value, including empty); these set the ci field and do not change session operation.

DO_NOT_TRACK=1 octomind run
OCTOMIND_TELEMETRY=0 octomind run

Installation Script

Variables used by install.sh for automated/CI environments.

OCTOMIND_INSTALL_DIR="$HOME/.local/bin" bash install.sh

Run from a source checkout; GITHUB_TOKEN, GH_TOKEN, and OCTOMIND_VERSION are user-supplied values when needed. These are installer inputs, not reads in the Rust runtime.

OpenRouter-Specific

These attribution headers control how OpenRouter identifies and ranks the app.

You normally do not set these yourself: Octomind auto-sets them to the listed defaults at startup (during the .env load step, which runs unconditionally even when no .env file is present) only if they are not already defined. Export your own value to override the default.

OPENROUTER_APP_TITLE="My Octomind setup" OPENROUTER_HTTP_REFERER="https://example.org" octomind run

Template Variables

Role prompt placeholders and octomind vars are documented in Config Reference; they are not process environment variables.

Webhook Hook Environment Variables

Available to hook scripts when processing incoming webhooks.

For a webhook processing script, the raw body is stdin. This executable body prints a message to inject:

#!/bin/sh
printf 'Webhook %s received at %s\n' "$HOOK_NAME" "$HOOK_PATH"
cat

Configure its path with [[hooks]].script; see the runnable setup in Config Reference.

Local Tool and Guardrail Script Variables

These are child-process contracts set by Octomind, not startup configuration:

Use exported metadata inside the corresponding script, for example a local tool:

#!/bin/sh
printf 'Tool %s in %s\n' "$OCTOMIND_TOOL_NAME" "$OCTOMIND_WORKDIR"

MCP stdio children inherit the process environment; explicit server env entries override inherited values. See MCP Tools.

Dynamic environment names

[[mcp.servers]]
name = "private-api"
type = "http"
url = "http://127.0.0.1:9000/mcp"
headers = { Authorization = "Bearer {{ENV:PRIVATE_API_TOKEN}}" }
timeout_seconds = 30
tools = []
auto_bind = ["developer:general"]

Set PRIVATE_API_TOKEN to your server’s credential before connecting; the key name is chosen by this config.

Runtime and Platform Variables

These inputs are read when resolving a directory, executable, prompt, or image protocol, not as TOML overrides. KITTY_WINDOW_ID presence wins over TERM, which wins over TERM_PROGRAM. There is no Octomind HF_HUB_CACHE or HF_HOME read in src/; the locked octolib Hugging Face loader sets HF_HOME to its shared model cache. Do not rely on those old documented names to relocate Octomind’s embedding weights. Model downloads are separate from the vector cache under OCTOMIND_DATA_DIR/cache/embeddings.

XDG_RUNTIME_DIR=/tmp octomind run --name runtime-demo

On Unix this uses /tmp/octomind with private-directory ownership/permission checks.

Build and test-only variables

These are present in src/ but are not production CLI settings. Setting them does not run a benchmark or test.

Test environment guards also read/save/restore arbitrary test-selected names, including the runtime/provider variables above. Those fixture names and values do not add production configuration options.

export LEARNING_BENCH_SPLIT=holdout
export LEARNING_BENCH_REPORT=/tmp/octomind-learning-report.json

Common questions

• Why did an exported key lose? Both .env files override exports. Check the project file last; even an empty assignment masks the earlier value.
• Why does a custom config path not load its .env? User dotenv loading always uses the standard shared config directory under the data root. OCTOMIND_CONFIG_PATH only selects TOML load/save behavior.
• Why does Bedrock say a key is missing despite config showing AWS set? The status row checks AWS_ACCESS_KEY_ID; the provider requires AWS_BEARER_TOKEN_BEDROCK.
• Why does OAuth fail before the first request? CLI preflight requires get_api_key(); see the OAuth caveat.
• Why does disabling telemetry still leave local files? Telemetry opt-out does not disable session logs, local accounting, compression archives, or learning storage.

Source map

Direct reads: env_source.rs, loading.rs, directories.rs, account.rs, telemetry.rs, client.rs, skill.rs, capability.rs. Provider delegation/preflight: providers.rs, setup.rs. Provider names and variables were checked in the locked octolib 0.35.0 source, src/llm/factory.rs and src/llm/providers/*.rs (including cli/mod.rs); model-cache behavior is in its src/embedding/provider/huggingface/mod.rs and src/storage.rs.

See also

• CLI Reference
• Session Commands
• Config Reference
• Providers Guide