# Environment variables

**An environment variable is a setting you give a program from the shell,** for example `NIRO_LOCAL_PARSE_WORKERS=4 niro build`. Most people need none of these. Each one below has a default that works.

**For the background watcher, set them where PM2 can see them.** The watcher is started by PM2, and it receives only the variables on a short list plus every `NIRO_LOCAL_*` and `LC_*` variable. Set a variable, then run `niro service install` again. The short list includes the proxy variables `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` and `NODE_USE_ENV_PROXY`, and the certificate variables `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE` and `SSL_CERT_DIR`, so that a watcher behind a company proxy can upload.

## For the `niro` command

| Variable | What it does | Default |
| --- | --- | --- |
| `NIRO_API_URL` | The account service address | `https://aiorchestrator.niroai.dev` |
| `NIRO_BILLING_URL` | The licence and engine-download service | `https://billing.cloud.niroai.dev` |
| `NIRO_AUDIT_URL` | Where the coverage audit is sent | `https://audit.cloud.niroai.dev` |
| `NIRO_MCP_SERVER_URL` | Where the tool-usage record is sent | `https://aiassistant.niroai.dev` |
| `NIRO_AUDIT_API_KEY` | A key the coverage audit upload signs with, instead of your sign-in. The audit still reads your plan through your `niro login` sign-in first, and sends nothing without it. The background watcher is never given this key | none |
| `NIRO_API_KEY` | Used in the same way when `NIRO_AUDIT_API_KEY` is not set. The watcher is never given it either | none |
| `NIRO_LOCAL_BIN` | Use this engine program instead of the downloaded one. It is never replaced by an upgrade | none |
| `NIRO_ENGINE_HOME` | Where the downloaded engine is kept | `~/.niro/bin` |
| `NIRO_TOOL_TIMEOUT_MS` | How long an agent's tool call may take | 120000 (2 minutes) |
| `NIRO_LOCAL_CALL_TIMEOUT_MS` | How long one call to the engine may take | 30000 |
| `NIRO_LOCAL_START_TIMEOUT_MS` | How long the engine may take to start | 30000 |
| `NIRO_LOCAL_BUILD_SETTLE_MS` | How long a folder must be quiet before the watcher rebuilds it | 3000 |
| `NIRO_LOCAL_RECHECK_MS` | How often the watcher checks for missed changes | 300000 (5 minutes) |
| `NIRO_LOCAL_RECONCILE_MS` | How often the watcher checks the list of folders and worktrees | 30000 |
| `NIRO_LOCAL_TASK_COMPLETE` | Set to `0` to turn the end-of-task Niro line off | on |
| `NO_COLOR`, `FORCE_COLOR` | Turn colour off, or force it on (`FORCE_COLOR=1`) or off (`0`) | automatic |
| `TERM=dumb` | Turns off the spinner and progress bar | none |
| `PM2_HOME` | Where PM2 keeps its files | `~/.pm2` |
| `CODEX_HOME` | Where Codex keeps its settings | `~/.codex` |

Also read, for rarer cases:

| Variable | Default |
| --- | --- |
| `NIRO_ENGINE_LOCK_WAIT_MS` | 300000 |
| `NIRO_ENGINE_LOCK_STALE_MS` | 600000 |
| `NIRO_LEASE_TIMEOUT_MS` | 15000 |
| `NIRO_LEASE_RETRY_MS` | 60000 |
| `NIRO_LEASE_MIN_RENEW_MS` | 5000 |
| `NIRO_LOCAL_LIST_TIMEOUT_MS` | 20000 |
| `NIRO_DELETE_SETTLE_MS` | 5000 |
| `NIRO_MISSING_CONFIRM_MS` | 24 hours |

## For the local engine

| Variable | What it does | Default |
| --- | --- | --- |
| `NIRO_LOCAL_HOME` | The engine's folder, holding the graph | `~/.niro-local` |
| `NIRO_LOCAL_MAX_FILE_BYTES` | The largest source file read | 2097152 (2 MB) |
| `NIRO_LOCAL_PARSE_TIMEOUT_SECONDS` | How long a file over 256 KB may take to read | 20 |
| `NIRO_LOCAL_PARSE_WORKERS` | Worker processes for reading files | the number of processor cores, up to 8 |
| `NIRO_LOCAL_PARSE_POOL_MIN_FILES` | The fewest files for which workers are used | 200 |
| `NIRO_LOCAL_BUILD_LOCK_WAIT` | How long a second build waits for the first, in seconds | 120 |
| `NIRO_LOCAL_MISSING_FOLDER_DAYS` | Days before the graph of a folder missing from disk is removed (0 turns this off) | 14 |
| `NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS` | Idle days before a temporary project is removed (0 turns this off) | 14 |
| `NIRO_LOCAL_MAX_ANSWER_CHARS` | The longest `code_grep` or `get_source_code` answer, in characters | 20000 |
| `NIRO_LOCAL_SEARCH_MAX_BYTES` | The largest file `code_grep` and `get_source_code` read | 8 MB |
| `NIRO_LOCAL_STRICT_MAX_BYTES` | The largest config or text file those two tools read | 256 KB |
| `NIRO_LOCAL_FRESHNESS_BUDGET` | Seconds spent checking whether an answer's files changed since the build | 1.0 |
| `NIRO_LOCAL_WAL_LIMIT_MB` | The size the graph's write-ahead file is trimmed to | 64 |
| `NIRO_LOCAL_MAX_GIT_INDEX_BYTES` | The largest `.git/index` read | 128 MB |
| `NIRO_LOCAL_MAX_GIT_INDEX_SECONDS` | How long reading `.git/index` may take | 5.0 |
| `NIRO_LOCAL_GIT_INDEX_CACHE_BYTES` | Memory kept for git's file lists | 64 MB |
| `NIRO_LOCAL_CASE_INSENSITIVE_GIT_HOSTS` | Extra git hosts whose names ignore letter case, when counting repositories | none |
| `NIRO_LOCAL_ALWAYS_LOAD_TOOLS` | Set to `0` so agents may load Niro's tools on demand | on |
| `NIRO_LOCAL_TURN_REMINDER` | `1` forces the reminder in answers on, `0` forces it off | automatic |
| `NIRO_LOCAL_JOURNAL_IDLE_SECONDS` | Quiet time before a tool-usage session is ready to send | 300 |
| `NIRO_LOCAL_REDACT_FILE_SECONDS` | How long masking one file may take, for a whole-repository push | 10 |

The engine reads on-and-off values as `1`, `true`, `yes` or `on` (on) and `0`, `false`, `no` or `off` (off). For most variables, a value it cannot read is ignored with a warning, and the default is used.

**Seven variables are read as plain numbers. A value that is not a number stops the engine with an error:** `NIRO_LOCAL_MAX_FILE_BYTES`, `NIRO_LOCAL_MAX_ANSWER_CHARS`, `NIRO_LOCAL_SEARCH_MAX_BYTES`, `NIRO_LOCAL_STRICT_MAX_BYTES`, `NIRO_LOCAL_FRESHNESS_BUDGET`, `NIRO_LOCAL_BUILD_LOCK_WAIT` and `NIRO_LOCAL_JOURNAL_IDLE_SECONDS`.

## Do not set

These are set by `niro` itself, or are for Niro's developers:

- `NIRO_LOCAL_LEASE_FD_IN`, `NIRO_LOCAL_LEASE_FD_OUT`

- `NIRO_START_BOOTSTRAPPED`, `NIRO_UPGRADE_HANDOVER`, `NIRO_OUTPUT_PREFIX`

- `NIRO_MCP_MODE`, `NIRO_MCP_TRANSPORT`, `NIRO_DISABLE_ROUTING`

- `NIRO_LOCAL_LEASE_PUBLIC_KEY`, `NIRO_LOCAL_LEASE_KEY_ID`

- `NIRO_LOCAL_FAST_PATH`, `NIRO_LOCAL_CHANGES_ONLY_WRITE`, `NIRO_LOCAL_SQL_PLAN_CHECK`, `NIRO_LOCAL_C_UNIQUE_DEFINITION_FALLBACK`