Environment variables

Choose the right kind of configurationCopy Anchor Link

Use an environment variable when a value belongs to the machine or process rather than the project: a secret, a cloud credential, a proxy, a CI-only value, or a temporary override. For example:

export ANTHROPIC_API_KEY="sk-ant-..."
omp

For one invocation, put the assignment before the command instead of exporting it:

PI_SLOW_MODEL="openai/gpt-5.5:high" omp

Environment variables are not YAML settings and are not CLI flags:

• Use ~/.omp/agent/config.yml or project settings for persistent omp behavior that should be reviewed with the rest of the configuration.
• Use omp flags for an explicit one-run choice. Where a flag and an environment variable control the same value, the flag wins; for example, --slow wins over PI_SLOW_MODEL.
• Use the variables on this page in the shell or a .env file. Do not put export PI_FOO=... inside config.yml, and do not expect a YAML key named PI_FOO to work.

There is no universal “environment always beats YAML” rule. Some variables are fallbacks, while others explicitly override the corresponding setting. Each table below says which behavior applies.

When a row says truthy, omp's shared flag parser accepts 1, y, true, yes, or on in the listed lower- or uppercase forms. Some subsystems normalize case or require one exact value; those rows spell that out.

For providers with an interactive login, /login is usually safer than keeping OAuth tokens in shell startup files. Treat every API key, token, cookie, client key, and credential file as a secret.

Where omp gets environment valuesCopy Anchor Link

At startup, omp keeps the first non-empty value it finds in this order:

1. The environment inherited from the shell that launched omp.
2. $PWD/.env in the launch directory.
3. The active agent .env: normally ~/.omp/agent/.env, or ~/.omp/profiles/<name>/agent/.env for a named profile.
4. The active config-root .env: normally ~/.omp/.env, or ~/.omp/profiles/<name>/.env for a named profile.
5. ~/.env.

Bun may preload its supported launch-directory files—such as .env.local, .env.<NODE_ENV>, and .env.<NODE_ENV>.local—before omp runs. Values loaded that way already appear in the inherited process environment and therefore have the first source's priority.

PI_CONFIG_DIR changes the .omp root name. PI_CODING_AGENT_DIR changes the default profile's agent directory; named profiles ignore it.

Inside a parsed .env file, an OMP_FOO key is also copied to PI_FOO, and the copied value wins over a same-file PI_FOO. This compatibility rule applies only to .env files, not to variables inherited from the parent shell.

Restart omp after changing a .env file. Environment changes are not hot-reloaded.

.env syntaxCopy Anchor Link

Names must match [A-Za-z_][A-Za-z0-9_]*. Blank lines and # comments are allowed; export is optional. Single, double, and backtick quotes are accepted.

# ~/.omp/.env
export ANTHROPIC_API_KEY="sk-ant-..."
PI_SLOW_MODEL='anthropic/claude-opus-4-8:high'
PI_NOTIFICATIONS=off

OMP's own parser keeps values literal. The launch-directory .env can be loaded by Bun before omp starts, so Bun-supported expansion may already have happened there; do not rely on expansion in the other .env files.

Provider credentialsCopy Anchor Link

export OPENAI_API_KEY="$CI_OPENAI_API_KEY"
export PI_SLOW_MODEL="openai/gpt-5.5:high"
omp -p "Review this change for correctness"

export OMP_AUTH_BROKER_URL="https://broker.example.net:8765"
export OMP_AUTH_BROKER_TOKEN="..."
omp

Network, proxy, and endpoint configurationCopy Anchor Link

export PI_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1,.internal.example"

export OLLAMA_BASE_URL="http://gpu-box.local:11434"
export OLLAMA_CONTEXT_LENGTH=32768
omp

Web searchCopy Anchor Link

These variables make a search provider available or refine its endpoint. /login can store credentials for providers that support it.

export BRAVE_API_KEY="..."
omp -p "Find the current release notes and summarize the breaking changes"

Models, execution, and session behaviorCopy Anchor Link

Eval runtimesCopy Anchor Link

These environment gates override eval.py, eval.js, eval.rb, and eval.jl. The standard truthy values are 1, y, true, yes, and on in the recognized casing; any other defined value is false.

Subagents and operation limitsCopy Anchor Link

Editing, shell, and imagesCopy Anchor Link

Storage, profiles, and compatibility pathsCopy Anchor Link

PWD, HOME, XDG_CONFIG_HOME, APPDATA, SHELL, and ComSpec also participate in normal operating-system path and shell discovery; they are not omp-specific settings.

Memory backendsCopy Anchor Link

HindsightCopy Anchor Link

Every HINDSIGHT_* value below overrides its matching hindsight.* YAML setting. Empty strings are ignored. Booleans are case-insensitive: only true, 1, and yes mean true. Invalid integers and enum values are ignored.

MnemopiCopy Anchor Link

Terminal and browser behaviorCopy Anchor Link

Most terminal identity variables are set by the terminal itself. Set the omp-specific controls only to work around detection problems.

Auto-detected terminal signals include COLORTERM, TERM, COLORFGBG, TERM_PROGRAM, TERM_PROGRAM_VERSION, TERMINAL_EMULATOR, WT_SESSION, TMUX_PANE, CMUX_SURFACE_ID, KITTY_WINDOW_ID, WEZTERM_PANE, TERM_SESSION_ID, ZELLIJ_PANE_ID, and ZELLIJ_SESSION_NAME. OMP also respects NO_COLOR; on Linux it detects clipboard/display support from DISPLAY, WAYLAND_DISPLAY, WSL_DISTRO_NAME, WSL_INTEROP, and TERMUX_VERSION.

Diagnostics and advanced controlsCopy Anchor Link

Startup, provider, and commit diagnosticsCopy Anchor Link

Codex and stream transportCopy Anchor Link

Compatibility user agentsCopy Anchor Link

GitLab Duo workflowCopy Anchor Link

OpenTelemetry exportCopy Anchor Link

OMP starts OTLP export only when at least one signal endpoint is configured.

TroubleshootingCopy Anchor Link

A value in .env appears to be ignored

• Check the launch shell first: an existing non-empty value wins over every .env file.
• Confirm the file is in the launch directory, active profile directory, config root, or home location listed above.
• Restart omp. Values are loaded once at startup.
• Remember that named profiles use ~/.omp/profiles/<name>/... and ignore PI_CODING_AGENT_DIR.

A YAML setting and environment variable disagree

Read the row for that variable. Some env values are explicit overrides (PI_TINY_DEVICE, Hindsight variables), some are fallbacks (LITELLM_BASE_URL), and some are superseded by CLI flags (PI_SLOW_MODEL). Use omp config get <setting> to inspect YAML; use env | sort in your shell to inspect inherited environment values.

Authentication still fails

Prefer /login for supported OAuth providers. Otherwise verify the exact provider-specific name above, remove whitespace, and make sure a generic key such as GITHUB_TOKEN is not being used where a provider-specific token such as COPILOT_GITHUB_TOKEN is required.

A secret was committed or printed

Revoke and rotate it immediately. Removing it from the latest file is not enough because it remains in history and logs. Keep credential-bearing .env files out of version control and restrict their permissions, for example chmod 600 ~/.omp/.env.

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.