4 min read

Environment variables

devenv defines and respects the following environment variables:

devenv variables are defined by devenv. The read-only ones are exported into the developer shell so you can reference them from scripts, tasks, and modules. The configurable ones are read by the CLI to change its behavior. Some may mirror and take precedence over a command-line flag.
Externally defined variables are standard, third-party variables that devenv respects but does not define.

devenv variables

`DEVENV_ROOT`

Added in 0.2

Read-only. Points to the root of the project where devenv.nix is located.

`DEVENV_DOTFILE`

Added in 0.1

Read-only. Points to $DEVENV_ROOT/.devenv.

`DEVENV_STATE`

Added in 0.1

Read-only. Points to $DEVENV_DOTFILE/state.

`DEVENV_RUNTIME`

Added in 1.0

Read-only. A short-lived, per-project directory for sockets and other runtime files (e.g. $DEVENV_RUNTIME/postgres), exported into the shell. The path is resolved in this order:

/tmp/devenv-<hash>.

$TMPDIR is deliberately not used, because it can differ between invocations that need to find the same process-manager socket. To relocate runtime files while keeping projects and profiles separate, set $XDG_RUNTIME_DIR.

`DEVENV_PROFILE`

Added in 0.5

Read-only. Points to the Nix store path that has the final profile of packages/scripts provided by devenv. Useful for teaching other programs about /bin, /etc, /var folders. See Package outputs for which outputs of a package are linked into it.

`DEVENV_HOME`

Added in 2.1.3

devenv’s per-user data directory. Stores GC roots, the trust database, cached keys, and other persistent per-user data. Defaults to ~/.local/share/devenv (respecting $XDG_DATA_HOME). Set it to override where this data is stored.

`DEVENV_MAX_JOBS`

Added in 1.11

Maximum number of Nix builds to run concurrently. Mirrors the -j / --max-jobs flag. Defaults to 1/4 of available CPU cores (minimum 1).

`DEVENV_CORES`

Added in 1.11

Number of CPU cores available to each build. Mirrors the -u / --cores flag. Defaults to available cores divided by DEVENV_MAX_JOBS (minimum 1).

`DEVENV_SHELL_TYPE`

Added in 2.1

Shell to use for interactive sessions: bash, zsh, fish, or nu. Mirrors the --shell flag.

`DEVENV_TUI`

Added in 2.0

Enable (true) or disable (false) the interactive terminal interface. Mirrors the --tui / --no-tui flags. Enabled by default when the session is interactive.

`DEVENV_TRACE_TO`

Added in 2.1

Enable tracing to one or more destinations, comma-separated (e.g. pretty:stderr,json:file:/tmp/trace.json). Mirrors the --trace-to flag; run devenv --help for the full syntax.

`DEVENV_TRACE_DEFAULT_TO`

Added in 2.1

A fallback tracing destination, applied only when no tracing is configured explicitly (neither DEVENV_TRACE_TO nor --trace-to). Uses the same comma-separated [format:]destination syntax as DEVENV_TRACE_TO. Set it to an empty string to suppress an inherited default.

`DEVENV_INCLUDE_ENVRC`

Added in 2.1.3

Generate an .envrc file when running devenv init. Mirrors devenv init --include-envrc.

`DEVENV_NO_AI_AGENT`

Added in 2.1

Set to any value to skip AI-agent auto-detection, forcing normal output and the TUI even when running under a detected coding agent.

Externally defined variables

devenv also reads the following externally defined environment variables.

`SHELL`

Detects your default shell dialect and resolves the shell binary to launch for devenv shell and hooks.

`HOME`

Locates your shell rc files and serves as the base for the XDG default paths.

`XDG_RUNTIME_DIR`

Base directory for $DEVENV_RUNTIME. When unset, $DEVENV_RUNTIME falls back to /tmp/devenv-<hash>.

`XDG_DATA_HOME`

Base directory for $DEVENV_HOME (GC roots, trust database, cached keys).

`XDG_CONFIG_HOME`

Locates shell rc files and the Cachix CLI configuration.

`TMPDIR`

Base directory for build artifacts. It never affects $DEVENV_RUNTIME, so sandboxed commands with a different $TMPDIR still find the same running processes.

`CI`

When set, disables the interactive terminal interface by default.

`RUST_LOG`

Sets the level and filter for devenv’s own diagnostic logging (see also --verbose).

`NO_COLOR`

Disables colored output. CLICOLOR and CLICOLOR_FORCE are also honored.

`TERM`

Used to detect terminal color and Unicode capabilities (along with COLORTERM).

`HTTP_PROXY`

Standard proxy configuration for devenv’s outgoing HTTP requests. HTTPS_PROXY, ALL_PROXY, and NO_PROXY (and their lowercase forms) are honored too.

`CACHIX_AUTH_TOKEN`

Authentication token for pulling from and pushing to Cachix binary caches.

`SECRETSPEC_PROVIDER`

Override the provider for the secretspec integration. Mirrored by the --secretspec-provider flag.

!!! tip “New in version 2.2.2”

devenv exports this variable into the development shell only when a provideroverride was explicitly configured. Otherwise, commands use the providerroutes from `secretspec.toml`.

`SECRETSPEC_PROFILE`

Override the profile for the secretspec integration. Mirrored by the --secretspec-profile flag.

Last updated Oct 08, 2026