Skip to content

Build AI methods with your coding agent, then run them anywhere: as an MCP for chatbots, as a webapp for people, or via API for your software.

feature/Pipelex-home-env · L-261005-01ba02 (#1344)

Louis Choquel55a0edf0eab6
diff --git a/.drift/acks/cli-docs.toml b/.drift/acks/cli-docs.toml
index a22ff21e0..d1fc591de 100644
--- a/.drift/acks/cli-docs.toml
+++ b/.drift/acks/cli-docs.toml
@@ -1,12 +1,12 @@
contract = "cli-docs"
-digest = "sha256:2de1c86f2f5885be4f34f5552593d5eb842879d96efd6673aaf979ed0ca5f028"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-04T21:23:47Z"
-rationale = "clean-pass: only a code comment in doctor_cmd.py changed, no CLI surface or behaviour change; docs need no update"
+digest = "sha256:731ea2ebe457df66277ad5a8175682faa7153284fa7f88e5ea22a68efc744b54"
+reviewed_by = "Claude (Opus 5.5)"
+reviewed_at = "2026-10-05T16:08:22Z"
+rationale = "clean-pass: pipelex init now escapes the target directory and the credentials path before printing them as Rich markup, so a bracketed PIPELEX_HOME prints verbatim; no flag, help text or documented output changed, and docs/tools/cli/init.md already names the home configuration directory."
[trigger_files]
"pipelex/cli/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
-"pipelex/cli/_cli.py" = "blob:3f2021d5b86d6d097732b0d85cceea4d23a91927"
+"pipelex/cli/_cli.py" = "blob:b976c272f1b0358788c0a7add965e09950ce06e2"
"pipelex/cli/agent_cli/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/_agent_cli.py" = "blob:9241b520ba209867c37330551101bdd5d262ac88"
"pipelex/cli/agent_cli/commands/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -18,12 +18,12 @@ rationale = "clean-pass: only a code comment in doctor_cmd.py changed, no CLI su
"pipelex/cli/agent_cli/commands/codegen/app.py" = "blob:56130b89fe9efec5ad3d014ed6bc16bef1bd1645"
"pipelex/cli/agent_cli/commands/codegen/check_cmd.py" = "blob:9e8beb084a9f04f39e8acca9e6ae2554d40cb667"
"pipelex/cli/agent_cli/commands/codegen/types_cmd.py" = "blob:5da4131cb459383ab4007c2cdb15f3cfde74510f"
-"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:9bfdb8c24a39a859665d2a9ff6b57883da0bd666"
+"pipelex/cli/agent_cli/commands/doctor_cmd.py" = "blob:ad2de92b98c2ab4a26e74d6154da1f594b5820b6"
"pipelex/cli/agent_cli/commands/fix/__init__.py" = "blob:65662c86f17f610ad55ecfc3e27a022b9aa26e8b"
"pipelex/cli/agent_cli/commands/fix/app.py" = "blob:e6190d9bde6a05755c04bd21806f699461038ac0"
"pipelex/cli/agent_cli/commands/fix/bundle_cmd.py" = "blob:cfd9e645986636c44c02a6a04a0fc67ed60d444b"
"pipelex/cli/agent_cli/commands/fmt_cmd.py" = "blob:97d6fb6c328e0b718b1293bd6b73cba03edcb7dc"
-"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:9d574ad51d472b265875136c195b6457ea9d794b"
+"pipelex/cli/agent_cli/commands/init_cmd.py" = "blob:535f77e3bdac38b77c35125ea48b5f2b47eb9b3f"
"pipelex/cli/agent_cli/commands/inputs/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/agent_cli/commands/inputs/_inputs_core.py" = "blob:4161029643f3a302de54fa637d2676521e10d873"
"pipelex/cli/agent_cli/commands/inputs/app.py" = "blob:7e19284687b334c684fb03381a8d9d20af1aa152"
@@ -31,7 +31,7 @@ rationale = "clean-pass: only a code comment in doctor_cmd.py changed, no CLI su
"pipelex/cli/agent_cli/commands/inputs/method_cmd.py" = "blob:604e91b2e65d951fd9a6eeed924a01f04fe2096f"
"pipelex/cli/agent_cli/commands/inputs/pipe_cmd.py" = "blob:5c9c233b00d626599dea4907b148b4f08cdd58a0"
"pipelex/cli/agent_cli/commands/lint_cmd.py" = "blob:91ad9cb4d618ba4c0b7da366cde2f74f38d350df"
-"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:ce733b78df03e65c3c8a10d46b27b57c05ec054c"
+"pipelex/cli/agent_cli/commands/migrate_cmd.py" = "blob:128de81f63aee55a9901e1df7a11ce15a402c536"
"pipelex/cli/agent_cli/commands/models_cmd.py" = "blob:f48a921fa89d8275c585b3e15f135f5585ac01aa"
"pipelex/cli/agent_cli/commands/plxt_passthrough.py" = "blob:a1c530d110482485ce462f199b9e79fac29f8896"
"pipelex/cli/agent_cli/commands/run/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
@@ -83,15 +83,15 @@ rationale = "clean-pass: only a code comment in doctor_cmd.py changed, no CLI su
"pipelex/cli/commands/graph_cmd.py" = "blob:d54737af7efc9ab9bbf3f978050d017af0e27a41"
"pipelex/cli/commands/init/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/init/backends.py" = "blob:04a1a06f1003ed0c7157ec4ca6c8659e4e09fe6b"
-"pipelex/cli/commands/init/command.py" = "blob:d6810258bdbdf912af026f667f4f013d06ec8ade"
+"pipelex/cli/commands/init/command.py" = "blob:f17d58fe1813d4bb9552cc418914ea4aebae2d2a"
"pipelex/cli/commands/init/config_files.py" = "blob:c13be6b8d2a8b211ce9ef0f4889ee131ffc3d2d8"
-"pipelex/cli/commands/init/credentials.py" = "blob:36dcc33599a2749b7d63bf214363a4b6fd6698e8"
+"pipelex/cli/commands/init/credentials.py" = "blob:a9c3ee9e8bdcc5d0f3148f055ab6e2ff34a940fc"
"pipelex/cli/commands/init/ide_extension.py" = "blob:9f0ec1494c07062246ecc906bc55b7f2cf95c715"
"pipelex/cli/commands/init/routing.py" = "blob:c73927deb99804556cb545cdaa6eabf8d1fc3450"
-"pipelex/cli/commands/init/telemetry.py" = "blob:17314182dbfa8e1a25f439f10eea9808b9fb6d33"
+"pipelex/cli/commands/init/telemetry.py" = "blob:07a33b6540e1fc4146d0777463c93abd4ea70231"
"pipelex/cli/commands/init/ui/__init__.py" = "blob:e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
"pipelex/cli/commands/init/ui/backends_ui.py" = "blob:a5250ebf7f2865da6ca12fc292b75fa7f5e8a690"
-"pipelex/cli/commands/init/ui/general_ui.py" = "blob:6fdc9cb429a5da261013679aae19afa10344770e"
+"pipelex/cli/commands/init/ui/general_ui.py" = "blob:4496bb2b88cf42e09efa4b6ba44c592373a314c6"
"pipelex/cli/commands/init/ui/routing_ui.py" = "blob:640bd0d11d1879ead83fd9f3d1736d2735c1abfa"
"pipelex/cli/commands/init/ui/types.py" = "blob:e263802d8e9c9f9687435de1eb992afa5336544f"
"pipelex/cli/commands/migrate_cmd.py" = "blob:897f9cbf93acace8f61091a9924895f0fda76443"
diff --git a/.drift/acks/config-docs.toml b/.drift/acks/config-docs.toml
index fa48d2a7a..0396483dc 100644
--- a/.drift/acks/config-docs.toml
+++ b/.drift/acks/config-docs.toml
@@ -1,8 +1,8 @@
contract = "config-docs"
-digest = "sha256:308ed837087ad1f5a71409cc3c53f78681fb8a5bb009e57fe0b8877999460add"
-reviewed_by = "Louis Choquel"
-reviewed_at = "2026-10-04T21:04:16Z"
-rationale = "clean-pass: merging dev into this branch combines dev's comment change on the deferred engine import in config_surface.py with this branch's removal of the pipelex-service-config surface id; docs/configuration, configs.py and config_cogt.py carry no pipelex_service or remote-config mention, and the ledgers directory holds no service ledger"
+digest = "sha256:fe956b25829d41bf434d926476489cac06a8c37bb712451d5315f6fcb9bb3711"
+reviewed_by = "Claude (Opus 5.5)"
+reviewed_at = "2026-10-05T16:08:21Z"
+rationale = "real-catch: ensure_global_config_exists now fills the home configuration directory from the kit when it exists but is empty, not only when it is missing; docs/configuration/index.md says so in the PIPELEX_HOME section, and the config_loader docstrings now name the home directory instead of crediting Path.home. No setting, default or load order moved."
[trigger_files]
"pipelex/cogt/config_cogt.py" = "blob:02f71cb4a6b01aebda59c2e31f262ef9c865e17b"
@@ -13,7 +13,7 @@ rationale = "clean-pass: merging dev into this branch combines dev's comment cha
"pipelex/pipelex.toml" = "blob:cb3431d9d8a3265121d730eaef34cfbe5e8c4cbf"
"pipelex/system/configuration/__init__.py" = "blob:8b137891791fe96927ad78e64b0aad7bded08bdc"
"pipelex/system/configuration/config_check.py" = "blob:2d5de29aba3d2ce205d3d82b4623f37b53108332"
-"pipelex/system/configuration/config_loader.py" = "blob:b1940ff11d9be7f9b8e113ec564d041ec53bb0ce"
+"pipelex/system/configuration/config_loader.py" = "blob:131f611530646e777ba705808ea164f088229fa5"
"pipelex/system/configuration/config_model.py" = "blob:83b29dc6e93393c9b98c4353636caf0135c80339"
"pipelex/system/configuration/config_root.py" = "blob:c7d43851270912d17413cfc6a511247d3c7cc160"
"pipelex/system/configuration/config_surface.py" = "blob:dc6c877564254aa97ce0b20fd29118def31c957c"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 33f613480..82c6c8497 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,11 @@
# Changelog
+## [Unreleased]
+
+### Added
+
+- **`PIPELEX_HOME` relocates the home configuration directory**: when set and not empty, it names the directory Pipelex uses in place of `~/.pipelex`, for the configuration layers, the inference files and their overrides, the credentials `.env`, the first-boot copy of the kit, `pipelex init`, `pipelex doctor`, `pipelex update`, `pipelex migrate` and the agent CLI's `--global`. It must be in the process environment before Pipelex is imported, a relative value is resolved against the working directory at import, and a `PIPELEX_HOME` line in a `.env` file is ignored. The first boot now fills the home directory from the kit when it exists but is empty, as it already did when it was missing, so an empty volume mount or a `mktemp -d` works as it is.
+
## [v0.74.0] - 2026-10-05
### Added
diff --git a/docs/configuration/config-technical/inference-backend-config.md b/docs/configuration/config-technical/inference-backend-config.md
index 2fadeb3fa..830b1b477 100644
--- a/docs/configuration/config-technical/inference-backend-config.md
+++ b/docs/configuration/config-technical/inference-backend-config.md
@@ -524,7 +524,7 @@ Both files are optional and git-ignored: `pipelex init` writes the rule into `.p
Where a file lives decides its reach. The base file resolves as before — the project's copy if it has one, otherwise the global one — and the overrides merge over it in this order:
1. the base `backends.toml` / `routing_profiles.toml`
-2. `~/.pipelex/inference/<file>_override.toml` — the global override, applied in every project on the machine
+2. `~/.pipelex/inference/<file>_override.toml` — the global override, applied in every project on the machine (under the directory `PIPELEX_HOME` names, when it is set: see [the home configuration directory](../index.md#the-home-configuration-directory-pipelex_home))
3. `{project}/.pipelex/inference/<file>_override.toml` — the project override, which wins
The global override reaches a project that carries its own tracked base, which is the point: one edit under `~/.pipelex/inference/` and every project follows. Deleting the override files restores the shipped default.
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index a43de89c9..e5274f253 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -14,18 +14,33 @@ Pipelex uses a TOML-based configuration system with **shipped defaults** plus **
You can create the configuration files by running:
```bash
-pipelex init config # creates the global config at ~/.pipelex/
+pipelex init config # creates the global config at ~/.pipelex/ (or in PIPELEX_HOME)
pipelex init config --local # creates the project config at {project_root}/.pipelex/
```
!!! important "Configuration Setup Notes"
- 1. By default `pipelex init config` targets the **global** `~/.pipelex/` directory; pass `--local` to create the project-level `.pipelex/` instead.
+ 1. By default `pipelex init config` targets the **global** `~/.pipelex/` directory, or the one `PIPELEX_HOME` names (see [below](#the-home-configuration-directory-pipelex_home)); pass `--local` to create the project-level `.pipelex/` instead.
2. `pipelex init config` creates a **template** configuration file with sample settings. It does not include all possible configuration options - it's meant as a starting point.
3. Running `pipelex init config` will **overwrite** your existing `pipelex.toml` file without warning. Make sure to backup your configuration before running this command.
- 4. Credentials (`~/.pipelex/.env`) and the onboarding state file always remain in the global `~/.pipelex/` directory regardless of `--local` — only config, inference, and telemetry files are written to the project `.pipelex/`.
+ 4. Credentials (the `.env` in `~/.pipelex/`) always remain in the global directory regardless of `--local` — only config, inference, and telemetry files are written to the project `.pipelex/`.
For a complete list of all possible configuration options, refer to the configuration group documentation below.
+## The home configuration directory: `PIPELEX_HOME`
+
+The global layer lives in `~/.pipelex/` unless the `PIPELEX_HOME` environment variable names another directory. The variable names the directory itself, the equivalent of `~/.pipelex`, not its parent, so it can be any directory whatever its name:
+
+```bash
+export PIPELEX_HOME=/path/to/ci/pipelex-home
+```
+
+Everything that reads or writes the global layer follows it: its `pipelex.toml` and override files, the inference files and their personal overrides, the credentials in its `.env`, the telemetry configuration, `pipelex init`, `pipelex doctor`, `pipelex update`, `pipelex migrate`, and the agent CLI's `--global` flag. The first boot fills the directory from the kit's templates when it does not exist or is empty, as it does for `~/.pipelex/`, so a fresh `mktemp -d` or an empty volume mount works as it is; a directory with anything in it is left alone. A `~` is expanded, a relative path resolves against the working directory at the moment Pipelex is imported, and an empty value counts as unset.
+
+It is meant for any process that should not share the machine's settings: a test run or a CI job that commits a configuration of its own, a container, or a checkout that must not read the developer's personal backends. A project's own `.pipelex/` keeps winning over it, exactly as it wins over `~/.pipelex/`.
+
+!!! warning "Set it before Pipelex is imported"
+ The home directory's `.env` is loaded when Pipelex is first imported, so `PIPELEX_HOME` has to be in the process environment by then: set it in the shell, the make target, the CI job or the container image. Set later, from a test fixture or from code that runs after something has imported Pipelex, it moves the configuration files but not the credentials already loaded from the old `.env`. A `.env` file cannot set it either: the home `.env` is found through it, so Pipelex discards a `PIPELEX_HOME` line in the home `.env` or the project's `.env`, and the process keeps the value it was started with.
+
## Where to edit configuration in a project
The main project configuration files are:
@@ -68,7 +83,7 @@ Pipelex uses a sophisticated configuration override system that loads and merges
The exact loading sequence is (later wins, per leaf key):
1. Base configuration from the installed Pipelex package (`pipelex.toml`)
-2. Global base configuration (`~/.pipelex/pipelex.toml`)
+2. Global base configuration (`~/.pipelex/pipelex.toml`, or `pipelex.toml` in the directory `PIPELEX_HOME` names)
3. Global override sequence, from `~/.pipelex/`: `pipelex_local.toml`, `pipelex_{environment}.toml`, `pipelex_{run_mode}.toml`, `pipelex_override.toml`, `pipelex_temporary_override.toml`
4. Your project's base configuration (`{project_root}/.pipelex/pipelex.toml`)
5. Project override sequence, from the project's `.pipelex/`: the same five files as step 3
diff --git a/docs/contribute/configuration-defaults-and-overrides.md b/docs/contribute/configuration-defaults-and-overrides.md
index 71fc23042..2d875f6cb 100644
--- a/docs/contribute/configuration-defaults-and-overrides.md
+++ b/docs/contribute/configuration-defaults-and-overrides.md
@@ -13,7 +13,7 @@ For the user-facing configuration guide, see [Configuration Overview](../configu
Pipelex configuration is merged in layers:
- **Shipped defaults**: maintained by the Pipelex project and used as the baseline by the installed package.
-- **Global config** (`~/.pipelex/`): machine-wide settings for a developer, applied to every project on the machine.
+- **Global config** (`~/.pipelex/`, or the directory `PIPELEX_HOME` names): machine-wide settings for a developer, applied to every project on the machine. One resolver, `get_pipelex_home_dir()` in `pipelex/system/environment.py`, locates it; `ConfigLoader.global_config_dir` and the import-time `.env` load both ask it, and a unit test refuses any other join of `Path.home()` with `.pipelex`.
- **Project config** (`{project_root}/.pipelex/`): per-project settings, edited by teams using Pipelex.
- **Override files** at each level (`pipelex_local.toml`, `pipelex_{environment}.toml`, `pipelex_{run_mode}.toml`, `pipelex_override.toml`, `pipelex_temporary_override.toml`): optional, typically gitignored, used for personal or ephemeral tweaks.
diff --git a/docs/features/configuration.md b/docs/features/configuration.md
index 529cef2d6..049b632ea 100644
--- a/docs/features/configuration.md
+++ b/docs/features/configuration.md
@@ -14,7 +14,7 @@ Pipelex uses a layered TOML configuration system that lets you define sensible d
## Configuration Levels
1. **Package defaults** — Built into Pipelex (`pipelex.toml` in the package)
-2. **Global tier** — `~/.pipelex/` for user-wide settings: the base `pipelex.toml`, then its override sequence
+2. **Global tier** — `~/.pipelex/` for user-wide settings, or the directory the `PIPELEX_HOME` environment variable names (see [the home configuration directory](../configuration/index.md#the-home-configuration-directory-pipelex_home)): the base `pipelex.toml`, then its override sequence
3. **Project tier** — `{project_root}/.pipelex/` for project-specific settings: the base `pipelex.toml`, then the same override sequence
Within each tier, the base `pipelex.toml` is followed by an override sequence, merged in order (later wins per key):
diff --git a/docs/tools/cli/init.md b/docs/tools/cli/init.md
index 3b856e1ae..c11ccc751 100644
--- a/docs/tools/cli/init.md
+++ b/docs/tools/cli/init.md
@@ -13,7 +13,7 @@ pipelex init [FOCUS]
pipelex init --local [FOCUS]
```
-By default, `pipelex init` writes to the global config directory at `~/.pipelex/`. Use `--local` to create a project-level `.pipelex/` directory at the detected project root. Credentials always remain in the global `~/.pipelex/` directory regardless of `--local`.
+By default, `pipelex init` writes to the home configuration directory (`~/.pipelex/`, or `PIPELEX_HOME`; see [Configuration](../../configuration/index.md#the-home-configuration-directory-pipelex_home)). Use `--local` to create a project-level `.pipelex/` directory at the detected project root. Credentials always remain in the home configuration directory regardless of `--local`.
!!! note "Config updates not yet supported"
The `pipelex init` command always performs a full reset of the configuration. Incremental config updates will be supported in a future release.
@@ -87,7 +87,7 @@ pipelex-agent init [--config/-c JSON] [--global/-g]
**Target directory:**
- **Default:** project-level `.pipelex/` at the detected project root (looks for `.git`, `pyproject.toml`, etc.). Errors out if no project root is found.
-- **`--global`/`-g`:** forces `~/.pipelex/`.
+- **`--global`/`-g`:** forces the home configuration directory (`~/.pipelex/`, or `PIPELEX_HOME`).
**Config JSON schema:**
diff --git a/docs/tools/cli/migrate.md b/docs/tools/cli/migrate.md
index bdfb2e48b..523482e35 100644
--- a/docs/tools/cli/migrate.md
+++ b/docs/tools/cli/migrate.md
@@ -19,7 +19,7 @@ pipelex migrate --yes # apply without asking
Two directories, and only those:
-- the global `~/.pipelex/`
+- the home configuration directory (`~/.pipelex/`, or `PIPELEX_HOME`; see [Configuration](../../configuration/index.md#the-home-configuration-directory-pipelex_home))
- the project `.pipelex/`, when the current directory is inside a project that has one
Within each, it looks at the configuration files themselves — `pipelex.toml` and its `pipelex_*.toml` tiers, `telemetry.toml` and its tiers — and at the inference backend definitions in `inference/backends/`.
diff --git a/docs/tools/cli/update.md b/docs/tools/cli/update.md
index b2634628f..3ca664078 100644
--- a/docs/tools/cli/update.md
+++ b/docs/tools/cli/update.md
@@ -36,7 +36,7 @@ Pipelex manages two areas of an install, each tracked by its own small JSON mani
- the model deck, `~/.pipelex/inference/deck/` (or `.pipelex/inference/deck/` for a project-local install);
- the backends directory, `~/.pipelex/inference/backends/` (or `.pipelex/inference/backends/`), where only `internal.toml` is managed.
-Each area is found the way the runtime finds it: a project's `.pipelex/` directory wins when it has one, and the global `~/.pipelex/` one is used otherwise, so the command refreshes the files your runs actually read. A manifest stores the kit version that produced the install and a SHA-256 of each managed file at install time.
+Each area is found the way the runtime finds it: a project's `.pipelex/` directory wins when it has one, and the home configuration directory (`~/.pipelex/`, or `PIPELEX_HOME`; see [Configuration](../../configuration/index.md#the-home-configuration-directory-pipelex_home)) is used otherwise, so the command refreshes the files your runs actually read. A manifest stores the kit version that produced the install and a SHA-256 of each managed file at install time.
On `update`, Pipelex compares three states for each area — what the kit ships, what is on disk, what the manifest recorded — and produces a per-file plan:
diff --git a/docs/under-the-hood/init-cli-flows.md b/docs/under-the-hood/init-cli-flows.md
index 7860999d9..e443cdfb9 100644
--- a/docs/under-the-hood/init-cli-flows.md
+++ b/docs/under-the-hood/init-cli-flows.md
@@ -52,10 +52,10 @@ All commands except `agreement` and `credentials` perform a **full reset** (over
| `deck/*.toml` | Inference step | Project or global | `.pipelex/inference/deck/` |
| `routing_profiles.toml` | Inference step | Project or global | `.pipelex/inference/routing_profiles.toml` |
| `telemetry.toml` | Telemetry step | Project or global | `.pipelex/telemetry.toml` |
-| `.env` | Credentials step | **Always global** | `~/.pipelex/.env` (mode 0600) |
+| `.env` | Credentials step | **Always global** | `~/.pipelex/.env`, or `.env` under `PIPELEX_HOME` (mode 0600) |
!!! info "Project vs global"
- Most files are written to the target directory chosen at init time (project `.pipelex/` or global `~/.pipelex/`). The exception is `.env` (credentials), which is **always** written to and read from `~/.pipelex/`.
+ Most files are written to the target directory chosen at init time (project `.pipelex/` or global `~/.pipelex/`). The exception is `.env` (credentials), which is **always** written to and read from the global directory. Wherever this page says `~/.pipelex/`, the `PIPELEX_HOME` environment variable relocates it ([Configuration](../configuration/index.md#the-home-configuration-directory-pipelex_home)).
---
@@ -286,7 +286,7 @@ The `ConfigLoader` (singleton: `config_manager`) resolves where configuration fi
| Property | Path | When it exists |
|----------|------|----------------|
-| `global_config_dir` | `~/.pipelex/` | Always (created on first use) |
+| `global_config_dir` | `~/.pipelex/`, or `PIPELEX_HOME` | Always (created on first use) |
| `project_config_dir` | `{project_root}/.pipelex/` | Only if the directory exists on disk |
| `pipelex_config_dir` | Project if exists, else global | Always (backward-compat alias) |
@@ -319,7 +319,7 @@ This means a project-level file **wins** over the global one, but only if it act
### Global Config Bootstrap
-`ensure_global_config_exists()` creates `~/.pipelex/` with kit template files on first use (called automatically during `load_config()`). It skips all `GIT_IGNORED_CONFIG_FILES` (files like `pipelex_override.toml`) and `.DS_Store` — these are never part of the bootstrap copy.
+`ensure_global_config_exists()` creates the home configuration directory (`~/.pipelex/`, or `PIPELEX_HOME`) with kit template files on first use, and fills it the same way when it exists but is empty (called automatically during `load_config()`). It skips all `GIT_IGNORED_CONFIG_FILES` (files like `pipelex_override.toml`) and `.DS_Store` — these are never part of the bootstrap copy.
### Config Loading Chain
@@ -345,7 +345,7 @@ This means a project-level file **wins** over the global one, but only if it act
| Flag | Target |
|------|--------|
| Default (no flag) | `{project_root}/.pipelex/` — project root detected via `find_project_root()` |
-| `--global` / `-g` | `~/.pipelex/` |
+| `--global` / `-g` | `~/.pipelex/`, or `PIPELEX_HOME` |
If no project root is found and `--global` is not set, the command fails with an error.
diff --git a/pipelex/cli/_cli.py b/pipelex/cli/_cli.py
index 3f2021d5b..b976c272f 100644
--- a/pipelex/cli/_cli.py
+++ b/pipelex/cli/_cli.py
@@ -170,10 +170,18 @@ def init_command(
),
] = InitFocus.ALL,
local: Annotated[
- bool, typer.Option("--local", "-l", help="Create project-level .pipelex/ at the detected project root instead of global ~/.pipelex/")
+ bool,
+ typer.Option(
+ "--local",
+ "-l",
+ help=(
+ "Create project-level .pipelex/ at the detected project root instead of the home configuration directory "
+ "(~/.pipelex/, or PIPELEX_HOME)"
+ ),
+ ),
] = False,
) -> None:
- """Initialize Pipelex configuration in ~/.pipelex (global) or project .pipelex (--local).
+ """Initialize Pipelex configuration in the home configuration directory (~/.pipelex, or PIPELEX_HOME) or project .pipelex (--local).
Focus options:
@@ -181,7 +189,7 @@ def init_command(
config Reset configuration files and prompt for missing API keys
- credentials Prompt for missing API keys only (reads enabled backends, saves to ~/.pipelex/.env)
+ credentials Prompt for missing API keys only (reads enabled backends, saves to the .env in the home configuration directory)
inference Reset inference backends selection and prompt for missing API keys
@@ -223,7 +231,9 @@ def migrate_command(
dry_run: Annotated[bool, typer.Option("--dry-run", help="Report what would change and write nothing")] = False,
yes: Annotated[bool, typer.Option("--yes", "-y", help="Apply without the interactive confirmation")] = False,
) -> None:
- """Bring the configuration files in ~/.pipelex/ and the project .pipelex/ up to the current schema.
+ """Bring the configuration files in the home configuration directory and the project .pipelex/ up to the current schema.
+
+ The home configuration directory is ~/.pipelex/, or the directory PIPELEX_HOME names.
Runs on a configuration that cannot load — it needs the migration ledger, the applier and the
filesystem, and nothing else. Every file it rewrites is backed up beside itself first.
diff --git a/pipelex/cli/agent_cli/CLAUDE.md b/pipelex/cli/agent_cli/CLAUDE.md
index 152fc0c80..d21c1a25a 100644
--- a/pipelex/cli/agent_cli/CLAUDE.md
+++ b/pipelex/cli/agent_cli/CLAUDE.md
@@ -82,7 +82,7 @@ commands/
| Command | Does |
|---------|------|
-| `init` | Initializes Pipelex configuration (non-interactive). Defaults to project `.pipelex/` at detected project root. Use `--global`/`-g` to target `~/.pipelex/`. Accepts `--config`/`-c` with inline JSON or file path for backends and routing (via `primary_backend`); telemetry is seeded from a template, not `--config`. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
+| `init` | Initializes Pipelex configuration (non-interactive). Defaults to project `.pipelex/` at detected project root. Use `--global`/`-g` to target the home configuration directory (`~/.pipelex/`, or `PIPELEX_HOME`). Accepts `--config`/`-c` with inline JSON or file path for backends and routing (via `primary_backend`); telemetry is seeded from a template, not `--config`. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `run` | Executes a pipeline (pipe\|bundle\|method subcommands), returns main_stuff + working_memory. Graph visualizations on by default (`--no-graph` to disable). `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `validate` | Dry-runs pipes/bundles/methods (pipe\|bundle\|method subcommands), returns validation status per pipe. Bundle subcommand supports `--graph` for graph visualization (with `--graph-format` for the graph renderer). `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `fix` | Applies deterministic safe fixes to a bundle file or directory (`fix bundle`) and re-validates until valid, out of fixes, or max iterations. Supports `--allow-signatures`, `--select`, `--ignore`, `--max-iterations`, and `-L/--library-dir`. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
@@ -92,7 +92,7 @@ commands/
| `codegen` | Agent mirror of the bare `pipelex codegen` family (types\|check subcommands). `types --target <flavor>` resolves the closure into the normalized crate and writes stamped typed artifacts + `codegen.lock` (write-if-changed); `check` is the offline drift check (pure hashing, no Pipelex boot — exit 0 current, 1 drift as a structured `CodegenDriftError` with `drifts[]`, 2 no/unreadable lock). Both: `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). |
| `models` | Lists available model presets, aliases, and waterfalls. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) |
| `check-model` | Validates a model reference and suggests alternatives if invalid. `--type`/`-t` for model category, `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value) |
-| `migrate` | Migrates this machine's configuration files (global `~/.pipelex/` and project `.pipelex/`, non-recursively) to the current schema by replaying each surface's ledger. Does **not** boot — it is the command for a configuration that cannot load. Writes only with `--yes`; `--dry-run` plans and is the default; the two together are refused with exit 2. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json`. The verdict is the structured `needs_attention`, not the exit code. |
+| `migrate` | Migrates this machine's configuration files (the home configuration directory, `~/.pipelex/` or `PIPELEX_HOME`, and project `.pipelex/`, non-recursively) to the current schema by replaying each surface's ledger. Does **not** boot — it is the command for a configuration that cannot load. Writes only with `--yes`; `--dry-run` plans and is the default; the two together are refused with exit 2. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json`. The verdict is the structured `needs_attention`, not the exit code. |
| `doctor` | Checks config, credentials, models health. `--global`/`-g` for global dir. `--format markdown\|json` (success, default: markdown) + `--error-format markdown\|json` (errors, defaults to `--format`'s value). The telemetry check carries a `finding` (`healthy`/`not_found`/`unparseable`/`out_of_date`/`invalid`) beside its `healthy` and `message`; branch on that, and note `out_of_date` is `pipelex migrate`'s and never `pipelex init telemetry`'s — a reset would discard the settings the migration keeps — and that it means the migration would actually rewrite that file, so a file it would only report on is `invalid`. `checks.pending_migrations` is the machine-wide half: a `finding` (`up_to_date`/`pending`/`needs_attention`/`unavailable`) plus `migratable_files` and `attention_files`. It is the only channel a machine has for a pending migration — a tolerated boot warns a person and this CLI silences logging — and it is **not** scoped by `--global`, because it answers for `pipelex migrate`, which walks both directories. `checks.plugins` is present once the runtime setup ran, which discovers the plugins the way boot does: `healthy` and `message`, not healthy when the plugin registry did not build, in which case the message names the plugin error. `checks.secrets_provider` is present once the runtime setup ran, which builds the provider `[runtime.secrets] method` selects before the sink, as boot does: `healthy` and `message`, not healthy when the method names no registered provider, when its factory raised or when the registry did not build. It is built even when logging was configured before the doctor ran, since `checks.models` resolves the backends' credentials through it, and when it did not build the models check says it could not run; a provider that raises on a lookup is reported in `checks.models` rather than failing the command. `checks.log_sink` is present once the runtime setup ran: `healthy` and `message`, not healthy when `[runtime.log] sink` names no registered sink, when the configured sink failed to install (a `${…}` placeholder in its settings that does not resolve among the causes), when the secrets provider did not build, in which case the sink is not attempted, or when the registry did not build. The message says why, and says where the report's own lines went: onto the console sink on stderr, which the doctor installs in place of the one that failed, or onto a sink already recorded, which it leaves alone rather than installing over — a sink is recorded before the held records are replayed, so a failed installation does not always leave nothing behind. The fourth case is its own: a sink that was installed and then failed while the records held since logging was configured were replayed through it, where the report runs on that sink, which stays installed, and the message says what it raised. A failure the `secrets_provider` and `log_sink` messages quote is scrubbed with the log redaction patterns, the configured `extra_patterns` included, because the envelope reaches its reader without passing through any sink, and so is a failure of the backends' setup that the `models` message quotes, where a secrets provider's own text can appear; the backend-file findings and the gateway and plugin-registry failures it quotes are Pipelex's own text and are quoted as raised. |
## Key Patterns
diff --git a/pipelex/cli/agent_cli/commands/doctor_cmd.py b/pipelex/cli/agent_cli/commands/doctor_cmd.py
index 9bfdb8c24..ad2de92b9 100644
--- a/pipelex/cli/agent_cli/commands/doctor_cmd.py
+++ b/pipelex/cli/agent_cli/commands/doctor_cmd.py
@@ -197,7 +197,7 @@ def agent_doctor_cmd(
typer.Option(
"--global",
"-g",
- help="Force checking the global ~/.pipelex/ directory.",
+ help="Force checking the home configuration directory (~/.pipelex/, or PIPELEX_HOME).",
),
] = False,
output_format: Annotated[
@@ -217,8 +217,8 @@ def agent_doctor_cmd(
Default output is markdown; use --format json for structured JSON.
- Target directory: auto-detects project .pipelex/ if present, else ~/.pipelex/.
- Use --global/-g to force checking the global ~/.pipelex/ directory.
+ Target directory: auto-detects project .pipelex/ if present, else the home configuration directory (~/.pipelex/, or PIPELEX_HOME).
+ Use --global/-g to force checking it.
"""
# The doctor configures logging and installs a sink for its own report; once the report is out,
# it releases them, so an ``otlp`` sink's exporter and the hook it registered at exit go with the
@@ -238,7 +238,7 @@ def _do_agent_doctor_cmd(*, global_: bool, output_format: CliOutputFormat, error
# any third-party log line.
silence_logging_for_agent_cli()
try:
- # When --global, force checking ~/.pipelex/ only; otherwise use layered resolution
+ # When --global, force checking the home configuration directory only; otherwise use layered resolution
config_dir = config_manager.global_config_dir if global_ else None
# Gather config location info (override for --global flag)
diff --git a/pipelex/cli/agent_cli/commands/init_cmd.py b/pipelex/cli/agent_cli/commands/init_cmd.py
index 9d574ad51..535f77e3b 100644
--- a/pipelex/cli/agent_cli/commands/init_cmd.py
+++ b/pipelex/cli/agent_cli/commands/init_cmd.py
@@ -76,7 +76,7 @@ def _resolve_target_dir(*, global_: bool) -> Path:
"""Resolve the target directory for initialization.
Args:
- global_: If True, force global ~/.pipelex/ directory.
+ global_: If True, force the home configuration directory (~/.pipelex/, or PIPELEX_HOME).
Returns:
Absolute path to the target config directory.
@@ -88,7 +88,7 @@ def _resolve_target_dir(*, global_: bool) -> Path:
if project_root is None:
agent_error(
"No project root found (no .git, pyproject.toml, etc. in parent directories). "
- "Use --global/-g to target the global ~/.pipelex/ directory.",
+ "Use --global/-g to target the home configuration directory (~/.pipelex/, or PIPELEX_HOME).",
error_type="ArgumentError",
)
return project_root / ".pipelex"
@@ -148,7 +148,7 @@ def _copy_telemetry_template(target_dir: Path, *, for_project: bool) -> None:
Args:
target_dir: Target config directory (e.g. .pipelex/).
for_project: True when targeting a project's `.pipelex/`; False when
- targeting the global `~/.pipelex/`.
+ targeting the home configuration directory.
"""
template_name = TELEMETRY_PROJECT_TEMPLATE_FILE_NAME if for_project else TELEMETRY_CONFIG_FILE_NAME
template_path = Path(str(get_kit_configs_dir())) / template_name
@@ -313,7 +313,7 @@ def agent_init_cmd(
typer.Option(
"--global",
"-g",
- help="Force global ~/.pipelex/ directory.",
+ help="Force the home configuration directory (~/.pipelex/, or PIPELEX_HOME).",
),
] = False,
output_format: Annotated[
@@ -332,7 +332,7 @@ def agent_init_cmd(
health, and 'pipelex init credentials' if needed.
Target directory: project .pipelex/ at detected project root by default.
- Use --global/-g to force global ~/.pipelex/.
+ Use --global/-g to force the home configuration directory (~/.pipelex/, or PIPELEX_HOME).
Config JSON schema::
diff --git a/pipelex/cli/agent_cli/commands/migrate_cmd.py b/pipelex/cli/agent_cli/commands/migrate_cmd.py
index ce733b78d..128de81f6 100644
--- a/pipelex/cli/agent_cli/commands/migrate_cmd.py
+++ b/pipelex/cli/agent_cli/commands/migrate_cmd.py
@@ -57,7 +57,7 @@ def agent_migrate_cmd(
) -> None:
"""Migrate this machine's Pipelex configuration files to the current schema.
- Walks the global ``~/.pipelex/`` and the project ``.pipelex/``, replays each configuration
+ Walks the home configuration directory (``~/.pipelex/``, or ``PIPELEX_HOME``) and the project ``.pipelex/``, replays each configuration
surface's ledger over every file it claims, and — with ``--yes`` — rewrites what changed,
backing up each original beside itself.
"""
diff --git a/pipelex/cli/commands/init/command.py b/pipelex/cli/commands/init/command.py
index d6810258b..f17d58fe1 100644
--- a/pipelex/cli/commands/init/command.py
+++ b/pipelex/cli/commands/init/command.py
@@ -152,7 +152,7 @@ def execute_initialization(
is_first_time_backends_setup: Whether backends.toml didn't exist before this run.
target_config_dir: Explicit target .pipelex directory. If None, uses config_manager.pipelex_config_dir.
for_project: True when initializing a project's .pipelex/; False when initializing
- the global ~/.pipelex/. Selects which telemetry template gets copied.
+ the home configuration directory. Selects which telemetry template gets copied.
"""
# Step 1: Initialize config if needed
@@ -271,7 +271,8 @@ def init_cmd(
Args:
focus: What to initialize - 'all', 'config', 'credentials', 'inference', 'routing', or 'telemetry'
skip_confirmation: If True, skip the confirmation prompt (used when called from doctor --fix)
- local: If True, create project-level .pipelex/ at the detected project root. Otherwise, create global ~/.pipelex/.
+ local: If True, create project-level .pipelex/ at the detected project root.
+ Otherwise, create the home configuration directory (~/.pipelex/, or PIPELEX_HOME).
"""
console = get_console()
@@ -299,9 +300,9 @@ def init_cmd(
else:
target_config_dir = Path.cwd() / ".pipelex"
else:
- # Default: create global config at ~/.pipelex/
+ # Default: create the global config in the home configuration directory
target_config_dir = config_manager.global_config_dir
- console.print(f"[dim]Target directory: {target_config_dir}[/dim]")
+ console.print(f"[dim]Target directory: {escape(str(target_config_dir))}[/dim]")
pipelex_config_dir = target_config_dir
telemetry_config_path = pipelex_config_dir / TELEMETRY_CONFIG_FILE_NAME
diff --git a/pipelex/cli/commands/init/credentials.py b/pipelex/cli/commands/init/credentials.py
index 36dcc3359..a9c3ee9e8 100644
--- a/pipelex/cli/commands/init/credentials.py
+++ b/pipelex/cli/commands/init/credentials.py
@@ -15,7 +15,7 @@ from pipelex.tools.misc.toml_utils import load_toml_from_path
def get_global_env_path() -> Path:
- """Return the path to the global credentials file (~/.pipelex/.env)."""
+ """Return the path to the credentials file in the home configuration directory (`~/.pipelex/.env`, or under `PIPELEX_HOME`)."""
return config_manager.global_config_dir / ".env"
@@ -101,7 +101,7 @@ def get_required_vars_for_enabled_backends(backends_toml_path: Path) -> dict[str
def prompt_credentials(*, console: Console, backends_toml_path: Path) -> None:
- """Prompt the user for missing credentials and persist them to ~/.pipelex/.env.
+ """Prompt the user for missing credentials and persist them to the `.env` in the home configuration directory.
Reads the backends.toml to find which env vars are needed by enabled backends,
checks which are already set, and prompts only for missing ones.
@@ -145,7 +145,7 @@ def prompt_credentials(*, console: Console, backends_toml_path: Path) -> None:
if collected_count > 0:
write_env_file(global_env_path, entries=entries)
console.print()
- console.print(f"[green]Saved {collected_count} credential(s) to {global_env_path}[/green]")
+ console.print(f"[green]Saved {collected_count} credential(s) to {escape(str(global_env_path))}[/green]")
else:
console.print()
console.print("[dim]No credentials entered. You can set them later by running:[/dim] [cyan]pipelex init credentials[/cyan]")
diff --git a/pipelex/cli/commands/init/telemetry.py b/pipelex/cli/commands/init/telemetry.py
index 17314182d..07a33b654 100644
--- a/pipelex/cli/commands/init/telemetry.py
+++ b/pipelex/cli/commands/init/telemetry.py
@@ -13,15 +13,16 @@ def setup_telemetry(*, console: Console, telemetry_config_path: Path, for_projec
"""Set up telemetry configuration by copying the appropriate kit template.
The global template (`telemetry.toml`) carries active defaults and seeds
- `~/.pipelex/telemetry.toml`. The project template (`telemetry.project.toml`)
- is fully commented out so a project's `.pipelex/telemetry.toml` does not
- override the user's global telemetry settings during layered loading.
+ `telemetry.toml` in the home configuration directory (`~/.pipelex/`, or
+ `PIPELEX_HOME`). The project template (`telemetry.project.toml`) is fully
+ commented out so a project's `.pipelex/telemetry.toml` does not override
+ the user's global telemetry settings during layered loading.
Args:
console: Rich Console instance for user interaction.
telemetry_config_path: Path to save the telemetry configuration.
for_project: True when targeting a project's `.pipelex/`; False when
- targeting the global `~/.pipelex/`.
+ targeting the home configuration directory.
"""
telemetry_config_path.parent.mkdir(parents=True, exist_ok=True)
diff --git a/pipelex/cli/commands/init/ui/general_ui.py b/pipelex/cli/commands/init/ui/general_ui.py
index 6fdc9cb42..4496bb2b8 100644
--- a/pipelex/cli/commands/init/ui/general_ui.py
+++ b/pipelex/cli/commands/init/ui/general_ui.py
@@ -1,7 +1,10 @@
"""General UI components for the init command."""
+from rich.markup import escape
from rich.panel import Panel
+from pipelex.cli.commands.init.credentials import get_global_env_path
+
def build_initialization_panel(
*,
@@ -27,6 +30,7 @@ def build_initialization_panel(
"""
# Build message based on what's being initialized
message_parts: list[str] = []
+ credentials_file = escape(str(get_global_env_path()))
if reset:
if needs_config:
message_parts.append("• [yellow]Reset and reconfigure[/yellow] configuration files in [cyan].pipelex/[/cyan]")
@@ -34,7 +38,7 @@ def build_initialization_panel(
message_parts.append("• [yellow]Reset and reconfigure[/yellow] inference backends")
message_parts.append("• Suggest IDE extension for [cyan].mthds[/cyan] syntax highlighting")
if check_credentials:
- message_parts.append("• Prompt for missing API keys (saved to [cyan]~/.pipelex/.env[/cyan])")
+ message_parts.append(f"• Prompt for missing API keys (saved to [cyan]{credentials_file}[/cyan])")
if needs_routing:
message_parts.append("• [yellow]Reset and reconfigure[/yellow] routing profile")
if needs_telemetry:
@@ -46,7 +50,7 @@ def build_initialization_panel(
message_parts.append("• Ask you to choose your inference backends")
message_parts.append("• Suggest IDE extension for [cyan].mthds[/cyan] syntax highlighting")
if check_credentials:
- message_parts.append("• Prompt for missing API keys (saved to [cyan]~/.pipelex/.env[/cyan])")
+ message_parts.append(f"• Prompt for missing API keys (saved to [cyan]{credentials_file}[/cyan])")
if needs_routing:
message_parts.append("• Ask you to configure your routing profile")
if needs_telemetry:
diff --git a/pipelex/pipelex.py b/pipelex/pipelex.py
index c6512c6ae..aec180ba6 100644
--- a/pipelex/pipelex.py
+++ b/pipelex/pipelex.py
@@ -291,9 +291,9 @@ class Pipelex(RuntimeBoot):
to this directory (package defaults + this directory) instead of following
project/global layering. Note the limit: it scopes *that load* and nothing else. The
inference files — backends, routing profiles and the model deck — still resolve through
- the layered paths, and the onboarding state is read from the global
- config dir outright. So this does not fully isolate a boot from the surrounding
- project.
+ the layered paths, and the credentials `.env` is the home directory's. So this does
+ not fully isolate a boot from the surrounding project; `PIPELEX_HOME` is how a
+ process keeps the machine's home configuration out.
config_overrides: Optional dict deep-merged on top of all TOML config layers
as the highest-priority override. Useful for tests that need specific
config without editing TOML files.
diff --git a/pipelex/system/configuration/config_loader.py b/pipelex/system/configuration/config_loader.py
index b1940ff11..131f61153 100644
--- a/pipelex/system/configuration/config_loader.py
+++ b/pipelex/system/configuration/config_loader.py
@@ -10,6 +10,7 @@ from pipelex.system.configuration.config_surface import (
stale_configuration_warning,
strip_reserved_meta,
)
+from pipelex.system.environment import CONFIG_DIR_NAME, get_pipelex_home_dir
from pipelex.system.exceptions import ConfigValidationError
from pipelex.system.runtime import runtime_manager
from pipelex.tools.misc.json_utils import deep_update
@@ -43,7 +44,6 @@ def pydantic_error_behind(*, config_error: Exception) -> ValidationError | None:
return cause if isinstance(cause, ValidationError) else None
-CONFIG_DIR_NAME = ".pipelex"
CONFIG_NAME = "pipelex.toml"
PROJECT_ROOT_MARKERS: frozenset[str] = frozenset({CONFIG_DIR_NAME, ".git", "pyproject.toml", "setup.py", "setup.cfg", "package.json", ".hg"})
@@ -107,8 +107,12 @@ class ConfigLoader:
@property
def global_config_dir(self) -> Path:
- """Get the global config directory at ~/.pipelex."""
- return Path.home() / CONFIG_DIR_NAME
+ """The home configuration directory: ``~/.pipelex``, or the directory ``PIPELEX_HOME`` names.
+
+ Every reader of the home layer goes through this property, so the variable moves all of
+ them together; ``get_pipelex_home_dir`` is the resolver behind it.
+ """
+ return get_pipelex_home_dir()
@property
def project_root(self) -> Path | None:
@@ -172,9 +176,8 @@ class ConfigLoader:
resolved directly under that directory.
Otherwise, the project .pipelex/ directory is checked first; if the file
- exists there it wins, otherwise the global ~/.pipelex/ is used.
- This works on all platforms (macOS, Linux, Windows) because Path.home()
- returns the correct home directory everywhere.
+ exists there it wins, otherwise the home configuration directory is used
+ (`global_config_dir`: ~/.pipelex/, or the directory PIPELEX_HOME names).
Args:
relative_path: Path relative to the .pipelex directory (e.g. "telemetry.toml",
@@ -250,10 +253,11 @@ class ConfigLoader:
Without ``config_dir`` the sequence is::
- [resolved base, ~/.pipelex/inference/<override>, <project>/.pipelex/inference/<override>]
+ [resolved base, <home>/inference/<override>, <project>/.pipelex/inference/<override>]
The base keeps today's winner-takes-all resolution — a project's file if it has one, else
the global one — and the overrides layer over whichever was picked, global then project.
+ ``<home>`` is the home configuration directory, ``~/.pipelex`` unless ``PIPELEX_HOME`` names another.
That order is deliberately not ``pipelex.toml``'s, where a project base beats a global
override: a global inference override exists so that one machine-wide choice ("run on this
backend") reaches every project on the machine, and every project carries a tracked
@@ -286,9 +290,13 @@ class ConfigLoader:
return self.resolve_config_file(f"{INFERENCE_DIR_NAME}/{MODEL_DECKS_DIR_NAME}")
def ensure_global_config_exists(self) -> None:
- """Create the global ~/.pipelex/ directory with kit template files if it doesn't exist."""
+ """Create the home configuration directory with kit template files if it doesn't exist or is empty.
+
+ An empty directory is what `mktemp -d` or a fresh volume mount gives for `PIPELEX_HOME`, and it
+ holds nothing to keep. A directory with anything in it is left exactly as it is.
+ """
global_dir = self.global_config_dir
- if global_dir.is_dir():
+ if global_dir.is_dir() and any(global_dir.iterdir()):
return
from pipelex.kit.paths import GIT_IGNORED_CONFIG_FILES, get_kit_configs_dir # ruff: ignore[import-outside-top-level]
@@ -386,7 +394,7 @@ class ConfigLoader:
1. Packaged default: ``{package_dir}/{name}.toml`` — the plugin's bundled
default, shipped inside its own distribution.
- 2. Global override sequence from ``~/.pipelex/``:
+ 2. Global override sequence from the home configuration directory (``~/.pipelex/``, or ``PIPELEX_HOME``):
``{name}_{environment}.toml`` then ``{name}_override.toml``.
3. Project override sequence from ``{project_root}/.pipelex/`` (same two
files), when a project dir is found and distinct from the global dir.
@@ -432,8 +440,8 @@ class ConfigLoader:
(later wins per leaf key):
1. Package defaults (pipelex/pipelex.toml)
- 2. Global base (~/.pipelex/pipelex.toml)
- 3. Global override sequence (from ~/.pipelex/):
+ 2. Global base (pipelex.toml in the home configuration directory, ~/.pipelex/ or PIPELEX_HOME)
+ 3. Global override sequence (from the same directory):
- pipelex_local.toml
- pipelex_{environment}.toml
- pipelex_{run_mode}.toml (omitted under unit testing — see below)
diff --git a/pipelex/system/environment.py b/pipelex/system/environment.py
index a29a86ea2..23a9543bf 100644
--- a/pipelex/system/environment.py
+++ b/pipelex/system/environment.py
@@ -6,18 +6,61 @@ from dotenv import load_dotenv
from pipelex.system.exceptions import EnvVarNotFoundError
from pipelex.tools.misc.placeholder import value_is_placeholder
-# Load global credentials first (~/.pipelex/.env)
-_global_env_path = Path.home() / ".pipelex" / ".env"
-if _global_env_path.is_file():
- load_dotenv(dotenv_path=str(_global_env_path), override=True)
+# The name of a configuration directory, in the user's home directory and in a project
+CONFIG_DIR_NAME = ".pipelex"
-# Load project-level .env second (overrides global)
-load_dotenv(dotenv_path=".env", override=True)
+# Environment variable relocating the home configuration directory, which is ~/.pipelex otherwise
+PIPELEX_HOME_ENV_KEY = "PIPELEX_HOME"
# Environment variable for specifying library directories (PATH-style, colon-separated on Unix, semicolon on Windows)
PIPELEXPATH_ENV_KEY = "PIPELEXPATH"
+def get_pipelex_home_dir() -> Path:
+ """The home configuration directory: `PIPELEX_HOME` when it is set and not empty, else `~/.pipelex`.
+
+ This is the one place that locates it. The `.env` loaded below asks, and so does
+ `ConfigLoader.global_config_dir`, through which every other reader goes, so the variable moves
+ the configuration layers, the inference files and their overrides, the first-boot copy of the
+ kit, `pipelex init` and `pipelex doctor` with `--global`, and `pipelex migrate` together.
+
+ The variable names the directory itself, the equivalent of `~/.pipelex`, not its parent. `~` is
+ expanded and a relative value resolves against the working directory.
+ """
+ configured_home = os.environ.get(PIPELEX_HOME_ENV_KEY)
+ if not configured_home:
+ return Path.home() / CONFIG_DIR_NAME
+ return Path(configured_home).expanduser().resolve()
+
+
+def _load_dotenv_files() -> None:
+ """Load the home `.env`, then the project's `.env` from the working directory, which wins.
+
+ `PIPELEX_HOME` is read from the process environment only. The home `.env` is found through it,
+ so a `.env` that set it would leave the process reading its configuration from one directory and
+ its credentials from another: whatever either file says about it is discarded. A relative value
+ is pinned to the absolute path it resolves to at import, so that a later change of directory, or
+ a subprocess started from elsewhere, finds the same home directory as this load did.
+ """
+ configured_home = os.environ.get(PIPELEX_HOME_ENV_KEY)
+ home_dir = get_pipelex_home_dir()
+ if configured_home and not Path(configured_home).is_absolute():
+ configured_home = str(home_dir)
+
+ home_env_path = home_dir / ".env"
+ if home_env_path.is_file():
+ load_dotenv(dotenv_path=str(home_env_path), override=True)
+ load_dotenv(dotenv_path=".env", override=True)
+
+ if configured_home is None:
+ os.environ.pop(PIPELEX_HOME_ENV_KEY, None)
+ else:
+ os.environ[PIPELEX_HOME_ENV_KEY] = configured_home
+
+
+_load_dotenv_files()
+
+
def get_required_env(key: str) -> str:
value = os.getenv(key)
if not value:
diff --git a/tests/conftest.py b/tests/conftest.py
index 2a6cbac42..6ae824dcd 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -9,6 +9,7 @@ from pytest_mock import MockerFixture
from pipelex import log
from pipelex.interpreter_hub import clear_current_library, get_current_library_id_or_none, get_library_manager, set_current_library
from pipelex.pipelex import Pipelex
+from pipelex.system.environment import PIPELEX_HOME_ENV_KEY
from pipelex.system.job_metadata import JobMetadata, RunMetadata
from pipelex.system.runtime import IntegrationMode, runtime_manager
from pipelex.system.telemetry.telemetry_manager_abstract import TelemetryManagerAbstract
@@ -74,6 +75,18 @@ def reset_pipelex_config_fixture():
Pipelex.teardown_if_needed()
+def no_pipelex_home(monkeypatch: pytest.MonkeyPatch) -> None:
+ """Unset `PIPELEX_HOME` for a test that stands in a home directory of its own.
+
+ A test that fakes `Path.home()` or `HOME` is asserting about the default `~/.pipelex`, and a
+ `PIPELEX_HOME` exported in the developer's shell would move the home configuration directory
+ away from the one it faked. A module of such tests opts in with
+ `pytestmark = pytest.mark.usefixtures("no_pipelex_home")`.
+ """
+ monkeypatch.delenv(PIPELEX_HOME_ENV_KEY, raising=False)
+
+
@pytest.fixture(scope="class")
def load_test_library() -> Generator[Callable[[list[Path]], None], None, None]:
library_id = None
diff --git a/tests/unit/pipelex/cli/test_doctor_config_checks.py b/tests/unit/pipelex/cli/test_doctor_config_checks.py
index f178ff5ff..d093728f1 100644
--- a/tests/unit/pipelex/cli/test_doctor_config_checks.py
+++ b/tests/unit/pipelex/cli/test_doctor_config_checks.py
@@ -26,6 +26,9 @@ from pipelex.tools.misc.exceptions import TomlError
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+# Some cases stand in a home directory of their own by patching `Path.home`, which `PIPELEX_HOME` would bypass
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
class _TinyModel(BaseModel):
value: int
diff --git a/tests/unit/pipelex/cli/test_doctor_pending_migrations.py b/tests/unit/pipelex/cli/test_doctor_pending_migrations.py
index 970460e62..eb627c9ab 100644
--- a/tests/unit/pipelex/cli/test_doctor_pending_migrations.py
+++ b/tests/unit/pipelex/cli/test_doctor_pending_migrations.py
@@ -32,6 +32,9 @@ from pipelex.system.configuration.config_surface import TELEMETRY_CONFIG_SURFACE
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
# A realistic PostHog project key, at the path the shipped entry moves. The old flat format is
# exactly where a real one would be, which makes this the right specimen for the rendering rule.
PLANTED_KEY = "phc_L1VE_telemetry_key_that_must_never_be_rendered"
diff --git a/tests/unit/pipelex/cli/test_init_credentials.py b/tests/unit/pipelex/cli/test_init_credentials.py
index 8c97af22c..69954f86b 100644
--- a/tests/unit/pipelex/cli/test_init_credentials.py
+++ b/tests/unit/pipelex/cli/test_init_credentials.py
@@ -6,6 +6,8 @@ import os
import stat
from typing import TYPE_CHECKING
+from rich.console import Console
+
from pipelex.cli.commands.init.credentials import (
get_required_vars_for_enabled_backends,
prompt_credentials,
@@ -165,6 +167,22 @@ class TestInitCredentials:
# Cleanup
os.environ.pop("OPENAI_API_KEY", None)
+ def test_prompt_credentials_names_a_bracketed_home_directory_verbatim(self, tmp_path: Path, mocker: MockerFixture) -> None:
+ """The home directory can be any path `PIPELEX_HOME` names, so it is printed as text, never read as Rich markup."""
+ backends_toml = tmp_path / "backends.toml"
+ backends_toml.write_text('[openai]\nenabled = true\napi_key = "${OPENAI_API_KEY}"\n')
+ mocker.patch.dict(os.environ, {}, clear=False)
+ os.environ.pop("OPENAI_API_KEY", None)
+ home_dir = tmp_path / "[ci]" / "home"
+ mocker.patch("pipelex.cli.commands.init.credentials.config_manager", global_config_dir=home_dir)
+ mocker.patch("pipelex.cli.commands.init.credentials.Prompt.ask", return_value="sk-test-value")
+ console = Console(record=True, width=1000)
+
+ prompt_credentials(console=console, backends_toml_path=backends_toml)
+
+ assert str(home_dir / ".env") in console.export_text()
+ os.environ.pop("OPENAI_API_KEY", None)
+
def test_prompt_credentials_skips_empty_input(self, tmp_path: Path, mocker: MockerFixture) -> None:
"""Empty input skips the credential and doesn't write it."""
backends_toml = tmp_path / "backends.toml"
diff --git a/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py b/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py
index 19c47deed..8afbfb711 100644
--- a/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py
+++ b/tests/unit/pipelex/cogt/model_backends/test_backend_boot_tolerance.py
@@ -38,15 +38,18 @@ from pipelex.kit.paths import get_kit_configs_dir
from pipelex.system.configuration.config_loader import (
BACKENDS_DIR_NAME,
BACKENDS_FILE_NAME,
- CONFIG_DIR_NAME,
INFERENCE_DIR_NAME,
ROUTING_PROFILES_FILE_NAME,
)
+from pipelex.system.environment import CONFIG_DIR_NAME
from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
# Two backends, both with a literal key: what is under test is the *shape* of the per-backend files,
# and a `${VAR}` here would make every case below depend on the machine's environment instead.
BACKENDS_TOML = """
diff --git a/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.py b/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.py
index 74d61ce50..f7f8de5a9 100644
--- a/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.py
+++ b/tests/unit/pipelex/cogt/models/test_inference_config_overrides_end_to_end.py
@@ -17,12 +17,16 @@ import pytest
from pipelex.cogt.models.model_manager import ModelManager
from pipelex.kit.paths import get_kit_configs_dir
from pipelex.plugins.plugin_model_declarations import PluginModelDeclarations
-from pipelex.system.configuration.config_loader import CONFIG_DIR_NAME, INFERENCE_DIR_NAME
+from pipelex.system.configuration.config_loader import INFERENCE_DIR_NAME
+from pipelex.system.environment import CONFIG_DIR_NAME
from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
# Ollama needs no credential, so whether it loads depends on the override alone.
OLLAMA_OFF_OVERRIDE = "[ollama]\nenabled = false\n"
ANTHROPIC_PROFILE_OVERRIDE = 'active = "all_anthropic"\n'
diff --git a/tests/unit/pipelex/core/test_validation_report.py b/tests/unit/pipelex/core/test_validation_report.py
index 2a7ad6ce6..f536a6670 100644
--- a/tests/unit/pipelex/core/test_validation_report.py
+++ b/tests/unit/pipelex/core/test_validation_report.py
@@ -42,6 +42,9 @@ from pipelex.system.exceptions import ConfigValidationError
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
#: The shipped `telemetry-config@2` entry is about a real flat document the package carries, so a
#: stale machine can be built out of our own files rather than out of an invented schema change.
TELEMETRY_ENTRY_ID = "telemetry-config@2"
diff --git a/tests/unit/pipelex/system/configuration/test_boot_tolerance.py b/tests/unit/pipelex/system/configuration/test_boot_tolerance.py
index c9c5eaec5..82599a1a0 100644
--- a/tests/unit/pipelex/system/configuration/test_boot_tolerance.py
+++ b/tests/unit/pipelex/system/configuration/test_boot_tolerance.py
@@ -55,6 +55,9 @@ if TYPE_CHECKING:
from pipelex.migration.plan import MigrationPlan
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
+
def old_shape_telemetry_document() -> str:
"""The flat pre-`[custom_posthog]` document the shipped entry is about, read from the package."""
path = pre_history_document_path(migration_dir=packaged_migration_dir(), surface_id=TELEMETRY_CONFIG_SURFACE_ID, schema_version=2)
diff --git a/tests/unit/pipelex/system/pipelex_home/conftest.py b/tests/unit/pipelex/system/pipelex_home/conftest.py
new file mode 100644
index 000000000..0d9d39e9e
--- /dev/null
+++ b/tests/unit/pipelex/system/pipelex_home/conftest.py
@@ -0,0 +1,37 @@
+"""Fixtures shared by the `PIPELEX_HOME` tests that run in this process.
+
+`decoy_home` sets `HOME` to a directory holding a `.pipelex/` of its own, so that "nothing under the
+real home is read" is a claim about a directory the test controls rather than about the developer's
+machine.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.system.environment import PIPELEX_HOME_ENV_KEY
+
+
+def decoy_home(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ """A home directory whose `.pipelex/` holds a full configuration that no relocated read may touch."""
+ home = tmp_path / "decoy-home"
+ decoy_config_dir = home / ".pipelex"
+ (decoy_config_dir / "inference").mkdir(parents=True)
+ (decoy_config_dir / "pipelex.toml").write_text("[decoy_marker]\nseen = true\n", encoding="utf-8")
+ (decoy_config_dir / "inference" / "backends.toml").write_text("[decoy]\n", encoding="utf-8")
+ (decoy_config_dir / "inference" / "routing_profiles.toml").write_text("[decoy]\n", encoding="utf-8")
+ monkeypatch.setenv("HOME", str(home))
+ monkeypatch.setenv("USERPROFILE", str(home))
+ monkeypatch.delenv(PIPELEX_HOME_ENV_KEY, raising=False)
+ return home
+
+
+def project_dir(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ """An empty project, the working directory, with a `.pipelex/` that carries no inference files."""
+ project = tmp_path / "project"
+ (project / ".git").mkdir(parents=True)
+ (project / ".pipelex").mkdir()
+ monkeypatch.chdir(project)
+ return project
diff --git a/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_dotenv_at_import.py b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_dotenv_at_import.py
new file mode 100644
index 000000000..f0ef8d080
--- /dev/null
+++ b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_dotenv_at_import.py
@@ -0,0 +1,143 @@
+"""The `.env` loaded at import comes from the directory `PIPELEX_HOME` names, and no `.env` can move it.
+
+These cases run in a **subprocess**: the file is loaded once, when `pipelex.system.environment` is
+first imported, so only a fresh interpreter can show which one a process loads.
+"""
+
+import json
+import os
+import subprocess # ruff: ignore[suspicious-subprocess-import]
+import sys
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from pipelex.system.environment import PIPELEX_HOME_ENV_KEY
+
+#: Wall-clock bound on each import subprocess, so an import that hangs presents as a failure.
+SUBPROCESS_TIMEOUT_SECONDS = 120
+
+
+#: Imports the environment module in a fresh interpreter and reports what it loaded.
+_IMPORT_SCRIPT = textwrap.dedent(
+ """
+ import json
+ import os
+ import sys
+
+ from pipelex.system.configuration.config_loader import ConfigLoader
+ from pipelex.system.environment import get_pipelex_home_dir
+
+ print(json.dumps({
+ "sentinels": {name: os.environ.get(name) for name in sys.argv[1:]},
+ "pipelex_home_env": os.environ.get("PIPELEX_HOME"),
+ "home_dir": str(get_pipelex_home_dir()),
+ "global_config_dir": str(ConfigLoader().global_config_dir),
+ }))
+ """
+)
+
+DECOY_SENTINEL = "PIPELEX_HOME_TEST_DECOY_SENTINEL"
+RELOCATED_SENTINEL = "PIPELEX_HOME_TEST_RELOCATED_SENTINEL"
+PROJECT_SENTINEL = "PIPELEX_HOME_TEST_PROJECT_SENTINEL"
+SENTINELS = (DECOY_SENTINEL, RELOCATED_SENTINEL, PROJECT_SENTINEL)
+
+
+def _import_in_a_fresh_interpreter(*, home: Path, working_dir: Path, pipelex_home: str | None) -> dict[str, object]:
+ env = {name: value for name, value in os.environ.items() if name != PIPELEX_HOME_ENV_KEY and name not in SENTINELS}
+ env["HOME"] = str(home)
+ env["USERPROFILE"] = str(home)
+ if pipelex_home is not None:
+ env[PIPELEX_HOME_ENV_KEY] = pipelex_home
+ try:
+ result = subprocess.run( # ruff: ignore[subprocess-without-shell-equals-true]
+ [sys.executable, "-c", _IMPORT_SCRIPT, *SENTINELS],
+ capture_output=True,
+ text=True,
+ check=False,
+ timeout=SUBPROCESS_TIMEOUT_SECONDS,
+ env=env,
+ cwd=working_dir,
+ )
+ except subprocess.TimeoutExpired as exc:
+ msg = f"importing pipelex did not finish within {SUBPROCESS_TIMEOUT_SECONDS}s"
+ raise AssertionError(msg) from exc
+ assert result.returncode == 0, f"stdout={result.stdout}\nstderr={result.stderr}"
+ report: dict[str, object] = json.loads(result.stdout.strip().splitlines()[-1])
+ return report
+
+
+class TestTheDotenvLoadedAtImport:
+ @pytest.fixture
+ def homes(self, tmp_path: Path) -> tuple[Path, Path]:
+ """A decoy home whose `.pipelex/.env` sets one sentinel, and a relocated home whose `.env` sets another."""
+ decoy = tmp_path / "decoy-home"
+ (decoy / ".pipelex").mkdir(parents=True)
+ (decoy / ".pipelex" / ".env").write_text(f"{DECOY_SENTINEL}=from-the-real-home\n", encoding="utf-8")
+ relocated = tmp_path / "relocated-home"
+ relocated.mkdir()
+ (relocated / ".env").write_text(f"{RELOCATED_SENTINEL}=from-the-relocated-home\n", encoding="utf-8")
+ return decoy, relocated
+
+ @pytest.fixture
+ def empty_working_dir(self, tmp_path: Path) -> Path:
+ working_dir = tmp_path / "cwd"
+ working_dir.mkdir()
+ return working_dir
+
+ def test_without_the_variable_the_home_dotenv_is_loaded(self, homes: tuple[Path, Path], empty_working_dir: Path) -> None:
+ """The control: the decoy really is a home whose `.env` an import loads, so its absence below means something."""
+ decoy, _ = homes
+
+ report = _import_in_a_fresh_interpreter(home=decoy, working_dir=empty_working_dir, pipelex_home=None)
+
+ assert report["sentinels"] == {DECOY_SENTINEL: "from-the-real-home", RELOCATED_SENTINEL: None, PROJECT_SENTINEL: None}
+ assert report["home_dir"] == str(decoy / ".pipelex")
+
+ def test_the_relocated_dotenv_is_loaded_and_the_real_one_is_not(self, homes: tuple[Path, Path], empty_working_dir: Path) -> None:
+ decoy, relocated = homes
+
+ report = _import_in_a_fresh_interpreter(home=decoy, working_dir=empty_working_dir, pipelex_home=str(relocated))
+
+ assert report["sentinels"] == {DECOY_SENTINEL: None, RELOCATED_SENTINEL: "from-the-relocated-home", PROJECT_SENTINEL: None}
+ assert report["home_dir"] == str(relocated.resolve())
+ assert report["global_config_dir"] == str(relocated.resolve())
+
+ def test_a_relative_value_is_pinned_at_import(self, homes: tuple[Path, Path], tmp_path: Path) -> None:
+ """Resolved once against the import's working directory and written back, so a later `chdir` or a subprocess agrees."""
+ decoy, relocated = homes
+
+ report = _import_in_a_fresh_interpreter(home=decoy, working_dir=tmp_path, pipelex_home=relocated.name)
+
+ assert report["sentinels"] == {DECOY_SENTINEL: None, RELOCATED_SENTINEL: "from-the-relocated-home", PROJECT_SENTINEL: None}
+ assert report["pipelex_home_env"] == str(relocated.resolve())
+
+ def test_a_dotenv_file_cannot_move_the_home_directory(self, homes: tuple[Path, Path], empty_working_dir: Path, tmp_path: Path) -> None:
+ """The home `.env` is found through the variable, so a `.env` that set it would split the process in two.
+
+ Both files try here: the relocated home's `.env` and the project's. The process keeps the value it was
+ started with, so the configuration is read from the same directory the `.env` came from.
+ """
+ decoy, relocated = homes
+ elsewhere = tmp_path / "elsewhere"
+ with (relocated / ".env").open("a", encoding="utf-8") as home_dotenv:
+ home_dotenv.write(f"{PIPELEX_HOME_ENV_KEY}={elsewhere}\n")
+ (empty_working_dir / ".env").write_text(f"{PROJECT_SENTINEL}=from-the-project\n{PIPELEX_HOME_ENV_KEY}={elsewhere}\n", encoding="utf-8")
+
+ report = _import_in_a_fresh_interpreter(home=decoy, working_dir=empty_working_dir, pipelex_home=str(relocated))
+
+ assert report["sentinels"] == {DECOY_SENTINEL: None, RELOCATED_SENTINEL: "from-the-relocated-home", PROJECT_SENTINEL: "from-the-project"}
+ assert report["pipelex_home_env"] == str(relocated)
+ assert report["global_config_dir"] == str(relocated.resolve())
+
+ def test_a_dotenv_file_cannot_set_the_variable_when_the_process_did_not(
+ self, homes: tuple[Path, Path], empty_working_dir: Path, tmp_path: Path
+ ) -> None:
+ decoy, _ = homes
+ (empty_working_dir / ".env").write_text(f"{PIPELEX_HOME_ENV_KEY}={tmp_path / 'elsewhere'}\n", encoding="utf-8")
+
+ report = _import_in_a_fresh_interpreter(home=decoy, working_dir=empty_working_dir, pipelex_home=None)
+
+ assert report["pipelex_home_env"] is None
+ assert report["global_config_dir"] == str(decoy / ".pipelex")
diff --git a/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_one_resolver.py b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_one_resolver.py
new file mode 100644
index 000000000..e05e64ef2
--- /dev/null
+++ b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_one_resolver.py
@@ -0,0 +1,85 @@
+"""Nothing but `get_pipelex_home_dir` locates the home configuration directory, so `PIPELEX_HOME` moves it everywhere."""
+
+import ast
+import textwrap
+from pathlib import Path
+
+#: The one function allowed to join the user's home directory with `.pipelex`.
+RESOLVER_SITE = ("pipelex/system/environment.py", "get_pipelex_home_dir")
+
+REPO_ROOT = Path(__file__).resolve().parents[5]
+
+#: The source trees the guard sweeps: the library and the API server member.
+SWEPT_SOURCE_ROOTS = ("pipelex", "api/pipelex_api")
+
+
+def _joins_the_home_directory_with_dot_pipelex(node: ast.AST) -> bool:
+ """Whether `node` is `Path.home() / ".pipelex"` (or `/ CONFIG_DIR_NAME`), `Path.home().joinpath(".pipelex")`, or a `~/.pipelex` literal."""
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
+ return node.value.replace("\\", "/").startswith("~/.pipelex")
+ if isinstance(node, ast.BinOp) and isinstance(node.op, ast.Div):
+ return _is_home_call(node.left) and _names_dot_pipelex(node.right)
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == "joinpath":
+ return _is_home_call(node.func.value) and bool(node.args) and _names_dot_pipelex(node.args[0])
+ return False
+
+
+def _is_home_call(node: ast.AST) -> bool:
+ return isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) and node.func.attr == "home"
+
+
+def _names_dot_pipelex(node: ast.AST) -> bool:
+ if isinstance(node, ast.Constant) and isinstance(node.value, str):
+ return node.value.replace("\\", "/").split("/")[0] == ".pipelex"
+ return isinstance(node, ast.Name) and node.id == "CONFIG_DIR_NAME"
+
+
+def _offending_joins(*, source: str, relative_path: str) -> list[str]:
+ """The joins in one module outside the resolver, docstrings excluded (they describe the default, they do not compute it)."""
+ tree = ast.parse(source)
+ docstrings = {
+ id(body[0].value)
+ for owner in ast.walk(tree)
+ if isinstance(owner, (ast.Module, ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef))
+ and (body := owner.body)
+ and isinstance(body[0], ast.Expr)
+ and isinstance(body[0].value, ast.Constant)
+ }
+ allowed: set[int] = set()
+ if relative_path == RESOLVER_SITE[0]:
+ for owner in ast.walk(tree):
+ if isinstance(owner, ast.FunctionDef) and owner.name == RESOLVER_SITE[1]:
+ allowed.update(id(inner) for inner in ast.walk(owner))
+ return [
+ f"{relative_path}:{getattr(node, 'lineno', '?')}"
+ for node in ast.walk(tree)
+ if id(node) not in docstrings and id(node) not in allowed and _joins_the_home_directory_with_dot_pipelex(node)
+ ]
+
+
+class TestOneResolver:
+ def test_the_detector_sees_every_spelling(self) -> None:
+ """The control: without it, a detector that matched nothing would leave the sweep below green forever."""
+ source = textwrap.dedent(
+ """
+ from pathlib import Path
+ a = Path.home() / ".pipelex"
+ b = Path.home() / CONFIG_DIR_NAME
+ c = Path.home() / ".pipelex" / ".env"
+ d = Path.home().joinpath(".pipelex")
+ e = Path("~/.pipelex").expanduser()
+ """
+ )
+ assert len(_offending_joins(source=source, relative_path="pipelex/somewhere.py")) == 5
+
+ def test_nothing_but_the_resolver_joins_the_home_directory_with_dot_pipelex(self) -> None:
+ offenders: list[str] = []
+ for source_root in SWEPT_SOURCE_ROOTS:
+ for module_path in sorted((REPO_ROOT / source_root).rglob("*.py")):
+ relative_path = module_path.relative_to(REPO_ROOT).as_posix()
+ offenders.extend(_offending_joins(source=module_path.read_text(encoding="utf-8"), relative_path=relative_path))
+ assert not offenders, (
+ f"only `{RESOLVER_SITE[0]}::{RESOLVER_SITE[1]}` may locate the home configuration directory, so that "
+ f"`PIPELEX_HOME` moves it everywhere. Ask `get_pipelex_home_dir()` or `config_manager.global_config_dir` instead: "
+ f"{offenders}"
+ )
diff --git a/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_readers.py b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_readers.py
new file mode 100644
index 000000000..36e4c6772
--- /dev/null
+++ b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_readers.py
@@ -0,0 +1,116 @@
+"""Every reader of the home configuration directory follows `PIPELEX_HOME`, through `ConfigLoader.global_config_dir`.
+
+The configuration layers, the inference files and their overrides, the first-boot copy of the kit,
+`existing_config_dirs` (and so `pipelex migrate`) and the `pipelex init` panel all move with it, and
+none of them reads the decoy home that `decoy_home` stands in for the real one.
+"""
+
+from pathlib import Path
+
+import pytest
+from rich.console import Console
+
+from pipelex.cli.commands.init.ui.general_ui import build_initialization_panel
+from pipelex.system.configuration.config_loader import ConfigLoader
+from pipelex.system.environment import PIPELEX_HOME_ENV_KEY
+
+
+def _relocated_home(tmp_path: Path) -> Path:
+ """A relocated home directory with its own configuration, named unlike `.pipelex` on purpose."""
+ relocated = tmp_path / "relocated-home"
+ (relocated / "inference").mkdir(parents=True)
+ (relocated / "pipelex.toml").write_text("[relocated_marker]\nseen = true\n", encoding="utf-8")
+ (relocated / "inference" / "backends.toml").write_text("[relocated]\n", encoding="utf-8")
+ (relocated / "inference" / "routing_profiles.toml").write_text("[relocated]\n", encoding="utf-8")
+ return relocated
+
+
+def _is_under(path: Path, directory: Path) -> bool:
+ return path.resolve().is_relative_to(directory.resolve())
+
+
[email protected]("decoy_home", "project_dir")
+class TestEveryReaderFollows:
+ @pytest.fixture
+ def relocated(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
+ relocated = _relocated_home(tmp_path)
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, str(relocated))
+ return relocated.resolve()
+
+ def test_the_configuration_layers_read_the_relocated_home_and_never_the_real_one(self, relocated: Path, decoy_home: Path) -> None:
+ loader = ConfigLoader()
+
+ home_layers = [path for path in loader.config_file_paths() if not _is_under(path, loader.pipelex_root_dir)]
+ assert relocated / "pipelex.toml" in home_layers
+ assert not [path for path in home_layers if _is_under(path, decoy_home)]
+
+ merged = loader.load_config()
+ assert merged.get("relocated_marker") == {"seen": True}
+ assert "decoy_marker" not in merged
+
+ def test_the_inference_files_fall_back_to_the_relocated_home(self, relocated: Path) -> None:
+ loader = ConfigLoader()
+
+ assert loader.backends_file_path == relocated / "inference" / "backends.toml"
+ assert loader.routing_profiles_file_path == relocated / "inference" / "routing_profiles.toml"
+ assert loader.backends_dir_path == relocated / "inference" / "backends"
+ assert loader.model_decks_dir_path == relocated / "inference" / "deck"
+
+ def test_the_inference_overrides_layer_from_the_relocated_home(self, relocated: Path, project_dir: Path, decoy_home: Path) -> None:
+ loader = ConfigLoader()
+
+ assert loader.backends_file_paths() == [
+ relocated / "inference" / "backends.toml",
+ relocated / "inference" / "backends_override.toml",
+ (project_dir / ".pipelex" / "inference" / "backends_override.toml").resolve(),
+ ]
+ assert loader.routing_profiles_file_paths()[1] == relocated / "inference" / "routing_profiles_override.toml"
+ every_path = loader.backends_file_paths() + loader.routing_profiles_file_paths()
+ assert not [path for path in every_path if _is_under(path, decoy_home)]
+
+ def test_existing_config_dirs_list_the_relocated_home_and_not_the_real_one(self, relocated: Path, project_dir: Path) -> None:
+ assert ConfigLoader().existing_config_dirs == [relocated, (project_dir / ".pipelex").resolve()]
+
+ def test_the_relocated_home_is_listed_once_when_it_is_the_project_directory(self, project_dir: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, str(project_dir / ".pipelex"))
+ loader = ConfigLoader()
+
+ assert loader.existing_config_dirs == [(project_dir / ".pipelex").resolve()]
+ assert loader.backends_file_paths().count((project_dir / ".pipelex" / "inference" / "backends_override.toml").resolve()) == 1
+
+ def test_the_first_boot_creates_the_relocated_home_from_the_kit(self, decoy_home: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ not_yet_there = tmp_path / "fresh" / "nested" / "home"
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, str(not_yet_there))
+ (decoy_home / ".pipelex").rename(decoy_home / "moved-away")
+
+ ConfigLoader().ensure_global_config_exists()
+
+ assert (not_yet_there / "pipelex.toml").is_file()
+ assert (not_yet_there / "inference" / "backends.toml").is_file()
+ assert not (decoy_home / ".pipelex").exists()
+
+ def test_the_first_boot_seeds_an_existing_empty_relocated_home(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ """An empty directory is what `mktemp -d` and a fresh volume mount give, and it holds nothing to keep."""
+ empty_home = tmp_path / "empty-home"
+ empty_home.mkdir()
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, str(empty_home))
+
+ ConfigLoader().ensure_global_config_exists()
+
+ assert (empty_home / "pipelex.toml").is_file()
+ assert (empty_home / "inference" / "backends.toml").is_file()
+
+ def test_the_first_boot_leaves_a_relocated_home_with_files_alone(self, relocated: Path) -> None:
+ ConfigLoader().ensure_global_config_exists()
+
+ assert (relocated / "pipelex.toml").read_text(encoding="utf-8") == "[relocated_marker]\nseen = true\n"
+ assert not (relocated / "telemetry.toml").exists()
+
+ def test_pipelex_init_says_where_it_will_save_the_credentials(self, relocated: Path) -> None:
+ panel = build_initialization_panel(
+ needs_config=False, needs_inference=False, needs_routing=False, needs_telemetry=False, reset=False, check_credentials=True
+ )
+ console = Console(record=True, width=1000)
+ console.print(panel)
+
+ assert str(relocated / ".env") in console.export_text()
diff --git a/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_resolver.py b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_resolver.py
new file mode 100644
index 000000000..558b7e776
--- /dev/null
+++ b/tests/unit/pipelex/system/pipelex_home/test_pipelex_home_resolver.py
@@ -0,0 +1,40 @@
+"""`get_pipelex_home_dir` is `~/.pipelex` unless `PIPELEX_HOME` names another directory, and `global_config_dir` agrees."""
+
+from pathlib import Path
+
+import pytest
+
+from pipelex.system.configuration.config_loader import ConfigLoader
+from pipelex.system.environment import PIPELEX_HOME_ENV_KEY, get_pipelex_home_dir
+
+
+class TestTheResolver:
+ def test_unset_is_the_dot_pipelex_directory_in_the_home_directory(self, decoy_home: Path) -> None:
+ assert get_pipelex_home_dir() == decoy_home / ".pipelex"
+ assert ConfigLoader().global_config_dir == decoy_home / ".pipelex"
+
+ def test_empty_counts_as_unset(self, decoy_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, "")
+
+ assert get_pipelex_home_dir() == decoy_home / ".pipelex"
+ assert ConfigLoader().global_config_dir == decoy_home / ".pipelex"
+
+ @pytest.mark.usefixtures("decoy_home")
+ def test_an_absolute_value_names_the_directory_itself(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ relocated = tmp_path / "anywhere" / "my-home"
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, str(relocated))
+
+ assert get_pipelex_home_dir() == relocated.resolve()
+ assert ConfigLoader().global_config_dir == relocated.resolve()
+
+ def test_a_tilde_value_expands_against_the_home_directory(self, decoy_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, "~/elsewhere/pipelex-home")
+
+ assert get_pipelex_home_dir() == (decoy_home / "elsewhere" / "pipelex-home").resolve()
+
+ @pytest.mark.usefixtures("decoy_home")
+ def test_a_relative_value_resolves_against_the_working_directory(self, project_dir: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv(PIPELEX_HOME_ENV_KEY, "config/home")
+
+ assert get_pipelex_home_dir() == (project_dir / "config" / "home").resolve()
+ assert get_pipelex_home_dir().is_absolute()
diff --git a/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py b/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py
index 1038a2303..01acfe382 100644
--- a/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py
+++ b/tests/unit/pipelex/system/telemetry/test_load_telemetry_config.py
@@ -21,6 +21,9 @@ if TYPE_CHECKING:
from pytest_mock import MockerFixture
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
+
class TestLoadTelemetryConfigLayering:
"""Cover global → project layering for telemetry.toml and telemetry_override.toml."""
diff --git a/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py b/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py
index e4039bd5a..c0e93ad2a 100644
--- a/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py
+++ b/tests/unit/pipelex/system/telemetry/test_telemetry_stale_remedy.py
@@ -33,6 +33,9 @@ from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
# A realistic PostHog project key, planted in the file the error is raised about. The old flat
# format is exactly where a user's real one would be, which is what makes it the right specimen
# for the rendering rule on this channel.
diff --git a/tests/unit/pipelex/system/test_config_resolution.py b/tests/unit/pipelex/system/test_config_resolution.py
index 08ed70009..bcb87462e 100644
--- a/tests/unit/pipelex/system/test_config_resolution.py
+++ b/tests/unit/pipelex/system/test_config_resolution.py
@@ -12,6 +12,8 @@ if TYPE_CHECKING:
from pipelex.system.configuration.config_loader import ConfigLoader
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
class TestConfigResolution:
"""Test the hierarchical config resolution in ConfigLoader."""
diff --git a/tests/unit/pipelex/system/test_load_config_layering.py b/tests/unit/pipelex/system/test_load_config_layering.py
index e1e92c20c..96d406f32 100644
--- a/tests/unit/pipelex/system/test_load_config_layering.py
+++ b/tests/unit/pipelex/system/test_load_config_layering.py
@@ -18,6 +18,9 @@ if TYPE_CHECKING:
from pytest_mock import MockerFixture
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
+
class TestLoadConfigLayering:
"""Cover the four-layer merge: package → global base → global override → project base → project override."""
diff --git a/tests/unit/pipelex/test_runtime_boot_closure.py b/tests/unit/pipelex/test_runtime_boot_closure.py
index 0d7ce2a19..9bc3a0999 100644
--- a/tests/unit/pipelex/test_runtime_boot_closure.py
+++ b/tests/unit/pipelex/test_runtime_boot_closure.py
@@ -32,8 +32,12 @@ import sys
import textwrap
from pathlib import Path
+import pytest
+
from tests.unit.pipelex.test_kernel_layer_import_closure import INTERPRETER_PACKAGES
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
#: Wall-clock bound on the booted-runtime subprocess, matching the import-closure harness: a boot
#: that deadlocks must present as a failure, not as a hung suite
#: (`docs/agents/debugging-hanging-pytest-runs.md`).
diff --git a/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py b/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py
index f9c3d2da1..bb6add43a 100644
--- a/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py
+++ b/tests/unit/pipelex/test_runtime_boot_stale_backend_error.py
@@ -42,12 +42,16 @@ import pytest
from pipelex.cogt.model_backends.backend_library import InferenceBackendLibrary
from pipelex.kit.paths import get_kit_configs_dir
from pipelex.runtime_boot import BACKEND_LIBRARY_REFUSED, BootComponent, RuntimeBoot
-from pipelex.system.configuration.config_loader import BACKENDS_DIR_NAME, CONFIG_DIR_NAME, INFERENCE_DIR_NAME
+from pipelex.system.configuration.config_loader import BACKENDS_DIR_NAME, INFERENCE_DIR_NAME
+from pipelex.system.environment import CONFIG_DIR_NAME
from pipelex.tools.secrets.env_secrets_provider import EnvSecretsProvider
if TYPE_CHECKING:
from pytest_mock import MockerFixture
+
+pytestmark = pytest.mark.usefixtures("no_pipelex_home")
+
RETIRED_KEY = "prompting_target"
"""What `#1104` removed, and what the ledger entry explains."""