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.

fix doc

thomashebrarda854b2b74c4f
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 8ed133983..cb4c9907e 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -36,7 +36,7 @@ The main project configuration files are:
In addition to `.pipelex/pipelex.toml`, Pipelex can apply override files at the **project root** (not in `.pipelex/`) for machine- and environment-specific settings:
1. `pipelex_local.toml`
-2. `pipelex_{environment}.toml` (example: `pipelex_dev.toml`)
+2. `pipelex_{environment}.toml` (example: `pipelex_dev.toml`) — selected by the `PIPELEX_ENV` environment variable (see [Selecting the environment](#selecting-the-environment))
3. `pipelex_{run_mode}.toml` (example: `pipelex_normal.toml`; unit tests may use `tests/pipelex_unit_test.toml`)
4. `pipelex_override.toml` (recommended to gitignore)
@@ -63,7 +63,7 @@ The exact loading sequence is:
2. Your project's base configuration (`pipelex.toml` in your project root)
3. Local overrides (`pipelex_local.toml`)
4. Environment-specific overrides (`pipelex_{environment}.toml`)
- - Example environments: dev, staging, prod -> based on the environment variable `ENV` in your .env file
+ - Example environments: `local`, `dev`, `staging`, `prod` — selected by the `PIPELEX_ENV` environment variable (see [Selecting the environment](#selecting-the-environment))
5. Run mode overrides (`pipelex_{run_mode}.toml`)
- Example run modes: normal, unit_test
6. Final overrides (`pipelex_override.toml`) (recommended to put in .gitignore)
@@ -85,6 +85,30 @@ Each subsequent configuration file in this sequence can override settings from t
NB: The run_mode unit_test is used for testing purposes.
+### Selecting the environment
+
+The `pipelex_{environment}.toml` overlay is picked at runtime from the `PIPELEX_ENV` environment variable.
+
+| Value | Overlay file loaded |
+| --------- | --------------------- |
+| `local` | `pipelex_local.toml` *(also loaded as the local override layer; see above)* |
+| `dev` | `pipelex_dev.toml` |
+| `staging` | `pipelex_staging.toml` |
+| `prod` | `pipelex_prod.toml` |
+
+If `PIPELEX_ENV` is unset, Pipelex defaults to `dev`. Any other value raises an error at startup — the accepted values are defined by the `RunEnvironment` enum in `pipelex/system/runtime.py`.
+
+The selected environment is also stamped on OpenTelemetry spans as `deployment.environment`, so it doubles as the environment label for traces and metrics.
+
+Set it the way you set any other env var — for example, in your shell, your `.env` file, your CI configuration, or your container runtime:
+
+```bash
+export PIPELEX_ENV=staging
+```
+
+!!! warning "Renamed in a recent release"
+ This variable used to be called `ENVIRONMENT`. It was renamed to `PIPELEX_ENV` to avoid colliding with unrelated `ENVIRONMENT` variables that some deployment platforms set automatically. Update any shell, CI, or container config that exported `ENVIRONMENT=...` to export `PIPELEX_ENV=...` instead.
+
### Best Practices for Overrides
1. Use the base `pipelex.toml` for default settings
diff --git a/docs/features/configuration.md b/docs/features/configuration.md
index 3a28d22ef..07067f3f2 100644
--- a/docs/features/configuration.md
+++ b/docs/features/configuration.md
@@ -17,7 +17,7 @@ Pipelex uses a layered TOML configuration system that lets you define sensible d
2. **Global overrides** — `~/.pipelex/pipelex.toml` for user-wide settings
3. **Project overrides** — `{project_root}/.pipelex/pipelex.toml` for project-specific settings
4. **Local overrides** — `pipelex_local.toml` (git-ignored) for machine-specific values
-5. **Environment / run-mode-specific** — `pipelex_dev.toml`, `pipelex_prod.toml`, `pipelex_testing.toml`, etc.
+5. **Environment / run-mode-specific** — `pipelex_dev.toml`, `pipelex_prod.toml`, `pipelex_testing.toml`, etc. The environment overlay is selected by the `PIPELEX_ENV` environment variable (accepted values: `local`, `dev`, `staging`, `prod`; defaults to `dev`).
A final `pipelex_override.toml` file can be used for last-resort overrides.