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: