# Environment variables

devenv defines and respects the following environment variables:

* [devenv 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](/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](#externally-defined-variables) are standard, third-party variables that devenv respects but does not define.

## devenv variables

### [`DEVENV_ROOT`](#devenv_root)

**New in version 0.2**

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

### [`DEVENV_DOTFILE`](#devenv_dotfile)

**New in version 0.1**

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

### [`DEVENV_STATE`](#devenv_state)

**New in version 0.1**

**Read-only.** Points to `$DEVENV_DOTFILE/state`.

### [`DEVENV_RUNTIME`](#devenv_runtime)

**New in version 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:

2. `/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`](#devenv_profile)

**New in version 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](/packages/#package-outputs) for which outputs of a package are linked into it.

### [`DEVENV_HOME`](#devenv_home)

**New in version 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`](#devenv_max_jobs)

**New in version 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`](#devenv_cores)

**New in version 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`](#devenv_shell_type)

**New in version 2.1**

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

### [`DEVENV_TUI`](#devenv_tui)

**New in version 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`](#devenv_trace_to)

**New in version 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`](#devenv_trace_default_to)

**New in version 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`](#devenv_trace_to). Set it to an empty string to suppress an inherited default.

### [`DEVENV_INCLUDE_ENVRC`](#devenv_include_envrc)

**New in version 2.1.3**

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

### [`DEVENV_NO_AI_AGENT`](#devenv_no_ai_agent)

**New in version 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`](#shell)

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

### [`HOME`](#home)

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

### [`XDG_RUNTIME_DIR`](#xdg_runtime_dir)

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

### [`XDG_DATA_HOME`](#xdg_data_home)

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

### [`XDG_CONFIG_HOME`](#xdg_config_home)

Locates shell rc files and the Cachix CLI configuration.

### [`TMPDIR`](#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`](#ci)

When set, disables the interactive terminal interface by default.

### [`RUST_LOG`](#rust_log)

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

### [`NO_COLOR`](#no_color)

Disables colored output. `CLICOLOR` and `CLICOLOR_FORCE` are also honored.

### [`TERM`](#term)

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

### [`HTTP_PROXY`](#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`](#cachix_auth_token)

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

### [`SECRETSPEC_PROVIDER`](#secretspec_provider)

Override the provider for the [secretspec integration](/integrations/secretspec/). Mirrored by the `--secretspec-provider` flag.

**Changed in version 2.2.2**

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

### [`SECRETSPEC_PROFILE`](#secretspec_profile)

Override the profile for the [secretspec integration](/integrations/secretspec/). Mirrored by the `--secretspec-profile` flag.