close: document env var policy
This commit is contained in:
parent
9bc7920ab5
commit
d1bc1d41b9
|
|
@ -1,94 +1,94 @@
|
|||
# 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.
|
||||
INSOMNIA では、プロセス境界で本当に必要な場合を除き、環境変数の利用を避ける。新しい ambient な入力を増やすより、明示的な profile / manifest / config file / typed secret reference / CLI argument を優先する。
|
||||
|
||||
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.
|
||||
それでも、ユーザー設定や runtime directory の発見、package resource の発見、開発・テスト用 override、外部 provider の credential 慣習との互換のために、一部の環境変数はサポートしている。この文書に載せた環境変数は公開 surface として扱う。
|
||||
|
||||
## 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.
|
||||
- 同じ情報を profile、manifest、config、CLI input で明示的に渡せるなら、便利ショートカットとして新しい環境変数を追加しない。
|
||||
- 永続的な project state を環境変数に置かない。解決済みの状態は適切な store に保存する。
|
||||
- 通常の TUI / Pod runtime は `.env` ファイルを暗黙に load しない。example が局所的に `dotenv` を使うことはあっても、application startup が project の `.env` を勝手に読むべきではない。
|
||||
- 生の secret value を generated log、work item、trace output、docs に出さない。環境変数名の記述はよいが、値は書かない。
|
||||
- path/location 用の環境変数、provider credential 用の環境変数、test/build-only の環境変数を混ぜない。
|
||||
- test が process environment を変更する必要がある場合は、guard で直列化し、元の値を復元する。Rust の process environment は global state である。
|
||||
|
||||
## Supported runtime variables
|
||||
## サポートしている runtime 環境変数
|
||||
|
||||
### Core config/data/resource paths
|
||||
### Core config / data / resource path
|
||||
|
||||
These are resolved by `manifest::paths` and form the main application path contract.
|
||||
これらは `manifest::paths` で解決される、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. |
|
||||
| `INSOMNIA_HOME` | Insomnia 管理下の config / data / runtime path の sandbox/root override。 | config は `$INSOMNIA_HOME/config`、data は `$INSOMNIA_HOME`、runtime は `$INSOMNIA_HOME/run` になる。test や isolated run で使う。 |
|
||||
| `INSOMNIA_CONFIG_DIR` | 明示的な user config directory。 | 最優先の config override。`profiles.toml`、prompt override、model/provider override などを置く。 |
|
||||
| `INSOMNIA_DATA_DIR` | 明示的な persistent data directory。 | 最優先の data override。session と Pod metadata を置く。 |
|
||||
| `INSOMNIA_RESOURCE_DIR` | 明示的な bundled resource directory。 | 主に packaging / development の resource lookup 用。通常の installed package では `share/insomnia/resources` を使う。 |
|
||||
| `XDG_CONFIG_HOME` | XDG config fallback。 | `INSOMNIA_CONFIG_DIR` と `INSOMNIA_HOME` が未設定の場合に `$XDG_CONFIG_HOME/insomnia` を使う。 |
|
||||
| `HOME` | 最終的な user config / data fallback。 | `$HOME/.config/insomnia`、`$HOME/.insomnia`、`$HOME/.insomnia/run` の fallback に使う。 |
|
||||
|
||||
Empty path env values are generally treated as unset by `manifest::paths`.
|
||||
空の path 環境変数は、`manifest::paths` では原則として unset 相当に扱う。
|
||||
|
||||
### Runtime/socket/registry paths
|
||||
### Runtime / socket / registry path
|
||||
|
||||
| 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. |
|
||||
| `INSOMNIA_RUNTIME_DIR` | socket、pid/status file、live Pod registry file 用の明示的な runtime directory。 | 最優先の runtime override。test や isolated run でよく使う。 |
|
||||
| `XDG_RUNTIME_DIR` | runtime fallback。 | `INSOMNIA_RUNTIME_DIR` と `INSOMNIA_HOME` が未設定の場合に `$XDG_RUNTIME_DIR/insomnia` を使う。 |
|
||||
|
||||
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.
|
||||
Runtime state は durable authority ではない。replay / restore の durable source は session log と Pod metadata であり、socket や live registry file は runtime mirror / hint である。
|
||||
|
||||
### 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. |
|
||||
| `INSOMNIA_POD_COMMAND` | Pod runtime subprocess の起動 executable を差し替える開発・テスト用 override。 | default runtime command は現在の `insomnia` executable に `pod` prefix argument を付けたもの。この override は executable-only で、shell parse せず、`pod` prefix argument も自動付与しない。 |
|
||||
|
||||
Do not use this as normal user configuration. It exists for tests, development wrappers, and narrow debugging cases.
|
||||
これは通常の user configuration として使わない。test、development wrapper、狭い debugging 用の escape hatch である。
|
||||
|
||||
## Credentials and external auth
|
||||
## Credential と外部 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.
|
||||
Provider credential は、現在は manifest / profile / catalog の設定から env var 名を明示的に参照できる。これは「ambient な provider 自動発見」ではなく、設定で選んだ環境変数名を読む仕組みである。
|
||||
|
||||
| Variable / pattern | Purpose | Notes |
|
||||
| 変数 / pattern | 用途 | 備考 |
|
||||
| --- | --- | --- |
|
||||
| `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`. |
|
||||
| `INSOMNIA_API_KEY_ANTHROPIC` | custom env が指定されていない場合の Anthropic API key の default env 名。 | provider auth resolution で使う。 |
|
||||
| `INSOMNIA_API_KEY_OPENAI` | OpenAI / OpenAI Responses API key の default env 名。 | provider auth resolution で使う。 |
|
||||
| `INSOMNIA_API_KEY_GEMINI` | Gemini API key の default env 名。 | provider auth resolution で使う。 |
|
||||
| `INSOMNIA_API_KEY_OPENROUTER` | builtin OpenRouter provider の auth hint。 | bundled provider catalog 由来。 |
|
||||
| custom `model.auth.env` value | manifest / profile ごとの API key env 名。 | 明示的な config が変数名を選ぶ。`auth.env` と `auth.file` が両方ある場合は env が優先される。 |
|
||||
| `BRAVE_SEARCH_API_KEY` または custom `web.search.api_key_env` | Brave WebSearch key。 | WebSearch は configured env 名だけを読み、missing / empty の場合は fail closed する。 |
|
||||
| `CODEX_HOME` | Codex OAuth `auth.json` の場所。 | 外部互換用の入力。fallback は `$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.
|
||||
Credential env var は interoperability のために許容しているが、長期的に望ましい secret mechanism ではない。現時点では適切なら `auth.file` を優先し、今後は typed secret reference へ寄せる。credential UX のために implicit `.env` loading を追加しないこと。project secret を漏らしやすく、profile ごとの credential model とも相性が悪い。
|
||||
|
||||
## Build, examples, and test-only variables
|
||||
## Build / example / test-only 変数
|
||||
|
||||
These are not normal application configuration.
|
||||
これらは通常の application configuration ではない。
|
||||
|
||||
| Variable | Context | Notes |
|
||||
| 変数 | Context | 備考 |
|
||||
| --- | --- | --- |
|
||||
| `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. |
|
||||
| `CARGO_MANIFEST_DIR`, `OUT_DIR` | build / test resource lookup。 | build script や fixture/resource lookup で使う。 |
|
||||
| `PATH` | test / dev command lookup。 | helper executable を探す場合だけ使う。 |
|
||||
| `TMPDIR` | shell script / test。 | `tickets.sh` が temporary file に使う。 |
|
||||
| `RUST_LOG` | example / dev diagnostics。 | example CLI が tracing setup 経由で読む場合がある。 |
|
||||
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY` などの provider example vars | `llm-worker` や Pod example / fixture recorder。 | example code が `dotenv::dotenv().ok()` を呼ぶことがある。通常の `insomnia` runtime startup には適用されない。 |
|
||||
| `INSOMNIA_TEST_*` | test only。 | user-facing configuration にしてはいけない。 |
|
||||
|
||||
## Deprecated or intentionally absent surfaces
|
||||
## deprecated または意図的に存在しない surface
|
||||
|
||||
- `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.
|
||||
- `INSOMNIA_USER_MANIFEST` は通常の profile-based Pod/TUI startup の一部ではない。one-file manifest の debug / compatibility path には `insomnia pod --manifest <PATH>` を使う。
|
||||
- ambient `.insomnia/manifest.toml` discovery は通常の fresh startup の一部ではない。
|
||||
- `insomnia-pod` は installed command ではない。Pod runtime は `insomnia pod ...` から起動する。
|
||||
- 通常 runtime は `.env` ファイルを load しない。
|
||||
|
||||
## 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.
|
||||
1. test env mutation を shared guard に集約し、unsafe な `set_var` / `remove_var` call を一箇所に閉じ込めて直列化する。
|
||||
2. path resolution は `manifest::paths` に集約し、path precedence rule を別の場所で重複実装しない。
|
||||
3. credential source は resolved config 上で明示し、process-env convention を増やすより typed secret reference へ寄せる。
|
||||
4. 空の env value は、変数 category に応じて unset / invalid のどちらとして扱うかを一貫させ、新しい supported variable を追加する場合は挙動を文書化する。
|
||||
5. 外部 process integration が env inheritance / filtering を必要とする場合は、ambient な inherited process state に頼らず、明示的な policy boundary として設計する。
|
||||
|
|
|
|||
|
|
@ -2,12 +2,12 @@
|
|||
id: 20260531-082646-document-env-var-policy
|
||||
slug: document-env-var-policy
|
||||
title: Docs: document environment variable policy
|
||||
status: open
|
||||
status: closed
|
||||
kind: task
|
||||
priority: P2
|
||||
labels: [docs, config, security]
|
||||
created_at: 2026-05-31T08:26:46Z
|
||||
updated_at: 2026-05-31T08:26:46Z
|
||||
updated_at: 2026-05-31T08:29:40Z
|
||||
assignee: null
|
||||
legacy_ticket: null
|
||||
---
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
Documented the environment-variable policy and current supported surface.
|
||||
|
||||
Implementation:
|
||||
- Added `docs/environment.md`.
|
||||
- Stated the preferred design rule: avoid new environment variables when profile/manifest/config/CLI/typed secret references are better.
|
||||
- Documented core path variables, runtime/socket variables, the Pod runtime command override, credential env references, external compatibility variables, and build/test/example-only variables.
|
||||
- Clarified that normal runtime does not implicitly load `.env` files.
|
||||
- Added cleanup direction for shared test env guards, keeping path resolution centralized, and moving toward typed secret references.
|
||||
- Linked the new page from `docs/nix.md` and installed it in the Nix package docs.
|
||||
|
||||
Validation:
|
||||
- `./tickets.sh doctor`
|
||||
- `git diff --check`
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
<!-- event: create author: tickets.sh at: 2026-05-31T08:26:46Z -->
|
||||
|
||||
## Created
|
||||
|
||||
Created by tickets.sh create.
|
||||
|
||||
---
|
||||
|
||||
<!-- event: close author: hare at: 2026-05-31T08:29:40Z status: closed -->
|
||||
|
||||
## Closed
|
||||
|
||||
Documented the environment-variable policy and current supported surface.
|
||||
|
||||
Implementation:
|
||||
- Added `docs/environment.md`.
|
||||
- Stated the preferred design rule: avoid new environment variables when profile/manifest/config/CLI/typed secret references are better.
|
||||
- Documented core path variables, runtime/socket variables, the Pod runtime command override, credential env references, external compatibility variables, and build/test/example-only variables.
|
||||
- Clarified that normal runtime does not implicitly load `.env` files.
|
||||
- Added cleanup direction for shared test env guards, keeping path resolution centralized, and moving toward typed secret references.
|
||||
- Linked the new page from `docs/nix.md` and installed it in the Nix package docs.
|
||||
|
||||
Validation:
|
||||
- `./tickets.sh doctor`
|
||||
- `git diff --check`
|
||||
|
||||
|
||||
---
|
||||
|
|
@ -1,7 +0,0 @@
|
|||
<!-- event: create author: tickets.sh at: 2026-05-31T08:26:46Z -->
|
||||
|
||||
## Created
|
||||
|
||||
Created by tickets.sh create.
|
||||
|
||||
---
|
||||
Loading…
Reference in New Issue
Block a user