95 lines
7.4 KiB
Markdown
95 lines
7.4 KiB
Markdown
# Environment variable policy
|
|
|
|
INSOMNIA should avoid environment variables unless the process boundary genuinely requires them. Prefer explicit profile/manifest fields, config files under the resolved config directory, typed secret references, or CLI arguments over adding another ambient process-global input.
|
|
|
|
Environment variables are still supported for a small number of boundaries: locating user/config/runtime directories, package resource discovery, development/runtime overrides, and compatibility with external credential conventions. Treat those variables as a public surface once documented here.
|
|
|
|
## Principles
|
|
|
|
- Do not add a new environment variable as a convenience shortcut when an explicit profile, manifest, config, or CLI input can carry the same information.
|
|
- Do not use environment variables for durable project state. Persist resolved state in the appropriate store instead.
|
|
- Do not implicitly load `.env` files in normal TUI/Pod runtime. Examples may opt into `dotenv` locally, but application startup must not silently read project `.env` files.
|
|
- Do not put raw secret values in generated logs, work items, trace output, or docs. Environment-variable names are okay to document; values are not.
|
|
- Keep path/location variables separate from provider credentials and from test/build-only variables.
|
|
- When tests must mutate process environment, serialize and restore mutations through a guard. Rust process environment is global state.
|
|
|
|
## Supported runtime variables
|
|
|
|
### Core config/data/resource paths
|
|
|
|
These are resolved by `manifest::paths` and form the main application path contract.
|
|
|
|
| Variable | Purpose | Notes |
|
|
| --- | --- | --- |
|
|
| `INSOMNIA_HOME` | Sandbox/root override for Insomnia-managed config, data, and runtime paths. | Expands to `$INSOMNIA_HOME/config`, `$INSOMNIA_HOME`, and `$INSOMNIA_HOME/run` for config/data/runtime respectively. Useful for tests and isolated runs. |
|
|
| `INSOMNIA_CONFIG_DIR` | Explicit user config directory. | Highest-priority config override. Contains `profiles.toml`, prompt overrides, model/provider overrides, etc. |
|
|
| `INSOMNIA_DATA_DIR` | Explicit persistent data directory. | Highest-priority data override. Contains sessions and Pod metadata. |
|
|
| `INSOMNIA_RESOURCE_DIR` | Explicit bundled resource directory. | Mainly for packaging/dev resource lookup. Normal installed packages use `share/insomnia/resources`. |
|
|
| `XDG_CONFIG_HOME` | XDG config fallback. | Used as `$XDG_CONFIG_HOME/insomnia` when `INSOMNIA_CONFIG_DIR` and `INSOMNIA_HOME` are unset. |
|
|
| `HOME` | Final user config/data fallback. | Used for `$HOME/.config/insomnia`, `$HOME/.insomnia`, and `$HOME/.insomnia/run` fallbacks. |
|
|
|
|
Empty path env values are generally treated as unset by `manifest::paths`.
|
|
|
|
### Runtime/socket/registry paths
|
|
|
|
| Variable | Purpose | Notes |
|
|
| --- | --- | --- |
|
|
| `INSOMNIA_RUNTIME_DIR` | Explicit runtime directory for sockets, pid/status files, and live Pod registry files. | Highest-priority runtime override. Frequently used by tests and isolated runs. |
|
|
| `XDG_RUNTIME_DIR` | Runtime fallback. | Used as `$XDG_RUNTIME_DIR/insomnia` when `INSOMNIA_RUNTIME_DIR` and `INSOMNIA_HOME` are unset. |
|
|
|
|
Runtime state is not durable authority. Session logs and Pod metadata remain the durable sources for replay/restore; sockets and live registry files are runtime mirrors/hints.
|
|
|
|
### Pod runtime command override
|
|
|
|
| Variable | Purpose | Notes |
|
|
| --- | --- | --- |
|
|
| `INSOMNIA_POD_COMMAND` | Development/test override for the executable used to launch Pod runtime subprocesses. | The default runtime command is the current `insomnia` executable plus the `pod` prefix argument. This override is executable-only: it is not shell-parsed, and no `pod` prefix arg is added. |
|
|
|
|
Do not use this as normal user configuration. It exists for tests, development wrappers, and narrow debugging cases.
|
|
|
|
## Credentials and external auth
|
|
|
|
Provider credentials may currently be referenced by env var name in manifest/profile/catalog configuration. This is an explicit reference, not ambient provider discovery.
|
|
|
|
| Variable / pattern | Purpose | Notes |
|
|
| --- | --- | --- |
|
|
| `INSOMNIA_API_KEY_ANTHROPIC` | Default Anthropic API key env name for `AuthRef::ApiKey` when no custom env is specified. | Used by provider auth resolution. |
|
|
| `INSOMNIA_API_KEY_OPENAI` | Default OpenAI/OpenAI Responses API key env name. | Used by provider auth resolution. |
|
|
| `INSOMNIA_API_KEY_GEMINI` | Default Gemini API key env name. | Used by provider auth resolution. |
|
|
| `INSOMNIA_API_KEY_OPENROUTER` | Builtin OpenRouter provider auth hint. | Comes from bundled provider catalog. |
|
|
| Custom `model.auth.env` values | Per-manifest/profile API key env name. | Explicit config chooses the variable name; env wins over `auth.file` when both are present. |
|
|
| `BRAVE_SEARCH_API_KEY` or custom `web.search.api_key_env` | Brave WebSearch key. | WebSearch reads only the configured env name and fails closed if missing/empty. |
|
|
| `CODEX_HOME` | Location of Codex OAuth `auth.json`. | External compatibility input; falls back to `$HOME/.codex`. |
|
|
|
|
Credential env vars are tolerated for interoperability, but they are not the preferred long-term secret mechanism. Prefer `auth.file` today where suitable, and typed secret references as they become implemented. Do not add implicit `.env` loading to solve credential UX; it makes project secrets too easy to leak and does not model profile-specific credentials cleanly.
|
|
|
|
## Build, examples, and test-only variables
|
|
|
|
These are not normal application configuration.
|
|
|
|
| Variable | Context | Notes |
|
|
| --- | --- | --- |
|
|
| `CARGO_MANIFEST_DIR`, `OUT_DIR` | Build/test resource lookup. | Used by build scripts and fixture/resource lookup. |
|
|
| `PATH` | Tests/dev command lookup. | Used only where locating helper executables. |
|
|
| `TMPDIR` | Shell scripts/tests. | `tickets.sh` uses it for temporary files. |
|
|
| `RUST_LOG` | Examples/dev diagnostics. | Example CLIs may honor it through tracing setup. |
|
|
| Provider example vars such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` | `llm-worker` and Pod examples/fixture recorders. | Example code may call `dotenv::dotenv().ok()`. This does not apply to normal `insomnia` runtime startup. |
|
|
| `INSOMNIA_TEST_*` | Tests only. | Must not become user-facing configuration. |
|
|
|
|
## Deprecated or intentionally absent surfaces
|
|
|
|
- `INSOMNIA_USER_MANIFEST` is not part of normal profile-based Pod/TUI startup. Use `insomnia pod --manifest <PATH>` for the one-file manifest debug/compatibility path.
|
|
- Ambient `.insomnia/manifest.toml` discovery is not part of normal fresh startup.
|
|
- `insomnia-pod` is not an installed command; Pod runtime is reached through `insomnia pod ...`.
|
|
- `.env` files are not loaded by the normal runtime.
|
|
|
|
## Cleanup direction
|
|
|
|
When touching environment-variable-related code, prefer these improvements:
|
|
|
|
1. Centralize test env mutation behind a shared guard so unsafe `set_var` / `remove_var` calls stay contained and serialized.
|
|
2. Keep path resolution in `manifest::paths`; avoid duplicating path precedence rules elsewhere.
|
|
3. Make credential sources explicit in resolved config and move toward typed secret references instead of adding more process-env conventions.
|
|
4. Treat empty env values consistently as unset/invalid according to the variable's category, and document the behavior when adding a new supported variable.
|
|
5. If an external process integration needs env inheritance/filtering, design that as an explicit policy boundary rather than relying on ambient inherited process state.
|