Reference·Environment variablesIndex

Environment variables

Every environment variable the nodecode binary and the installers read, by purpose.

Updated Oct 6, 2026

A variable applies to the one process that reads it. For lasting settings use Config.

Home

Variable	Meaning
`NODECODE_HOME`	The home: the folder that holds config, store and cells. Default `~/.nodecode/`.

The binary picks the home in this order.

The binary sets NODECODE_HOME for every child process it starts.

Variable	Meaning	Default
`NODECODE_PROVIDER`	Provider id. Outranks `general.default_model`.	`openai-completions`
`NODECODE_MODEL`	Model id. Outranks `general.default_model`.	The build's model
`NODECODE_ENDPOINT`	Full endpoint URL. Outranks every `base_url`.	None
`NODECODE_API_KEY`	API key. Outranks `providers.<id>.api_key`. A leading `!` runs a shell command.	None
`NODECODE_REASONING_EFFORT`	`off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`.	None
`NODECODE_TEMPERATURE`	Sampling temperature, a number.	Not sent
`NODECODE_TOP_P`	Nucleus sampling bound, a number.	Not sent
`NODECODE_MAX_TOKENS`	Output token limit, an integer.	Not sent
`NODECODE_TOOL_CHOICE`	`auto`, `none` or `required`.	Not sent
`NODECODE_CONTEXT_TOKENS`	Context window in tokens, an integer. Outranks every other source.	None
`NODECODE_MODELS_CATALOG`	Path of the models.dev catalog cache.	`~/.cache/nodecode/models.dev/api.json`

Read after the config and auth.json, in this order.

Variable	Used for
`<ID>_API_KEY`	The provider with that id. The id is uppercased, `-` becomes `_`.
`OPENAI_API_KEY`	Any provider on `openai-completions` or `openai-responses`.
`ANTHROPIC_API_KEY`	Any provider on `anthropic`.
`GOOGLE_API_KEY`	Any provider on `google`.
`ANTHROPIC_AUTH_TOKEN`	The provider id `anthropic` only.

The gateway is the local server shells attach to.

Variable	Meaning
`NODECODE_GATEWAY_OPERATOR_TOKEN`	The operator token. Read first.
`NODECODE_OPERATOR_TOKEN`	The operator token. Read second.

Both outrank the operator-token file and gateway.operator_token.

Variable	Meaning	Default
`NODECODE_BASE_URL`	The release host.	The host the build was installed from, else `https://preview.nodecode.ai/dl`
`NODECODE_HUB_INDEX`	Address of Nodecode's cell index.	`https://preview.nodecode.ai/dl/cells/index.json`
`NODECODE_COMMUNITY_INDEX`	Address of the community cell index.	`https://nodecode.ai/cells/community.json`

Variable	Meaning
`NODECODE_PHASE_LOG`	A file path. Nodecode appends one timed line per boot phase.
`NODECODE_QA`	`0`, `off`, `never` or `false` stops every send of the qa cell.
`NODECODE_HANDOVER`	Internal. Set by a profile switch for the next process.

Some config keys hold the name of a variable. Nodecode reads the secret from that variable.

Variable	Used for
`XDG_CACHE_HOME`	The cache root. Default `~/.cache/`.
`LOCALAPPDATA`	Windows: the cache root.
`XDG_CONFIG_HOME`	Linux: where the gateway's systemd unit is written.
`XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `XDG_DATA_HOME`, `PATH`, `HOME`	Copied into the background gateway's unit.
`TMPDIR`	Where an `--ephemeral` store is created.
`TERM`, `COLORTERM`, `WT_SESSION`, `TERM_PROGRAM`	Colour depth detection. `TERM=dumb` gives no colour.
`NO_COLOR`	Any value limits the shell to 16 colours.
`TMUX`	Wraps clipboard sequences for tmux. `TERM=screen...` does the same for screen.
`WAYLAND_DISPLAY`, `DISPLAY`	Linux: a link opens with `xdg-open` only when one is set.
`NOTIFY_SOCKET`	Linux: readiness messages to systemd.
`JOURNAL_STREAM`	Tells Nodecode its logs go to the journal.
`USER`	The layer folder's name when git has no `user.name`. Windows: `USERNAME`.
`ProgramFiles`, `LOCALAPPDATA`	Windows: where to look for Git's `sh.exe`.

install.sh, for Linux and macOS:

Variable	Meaning	Default
`NODECODE_VERSION`	Install this version.	The version the channel names
`NODECODE_CHANNEL`	The release channel to read.	`stable`
`NODECODE_BASE_URL`	Fetch from this host.	`https://preview.nodecode.ai/dl`
`NODECODE_HOME`	The install folder.	`~/.local/share/nodecode`
`NODECODE_STAGE`	`full`, `stage` or `link`.	`full`

install.ps1, for Windows:

Variable	Meaning	Default
`NODECODE_VERSION`	Install this version.	The version the channel names
`NODECODE_CHANNEL`	The release channel to read.	`stable`
`NODECODE_BASE_URL`	Fetch from this host.	`https://preview.nodecode.ai/dl`
`NODECODE_INSTALL_DIR`	The install folder.	`%LOCALAPPDATA%\Programs\nodecode`
`NODECODE_STAGE`	`full`, `stage` or `link`.	`full`
`NODECODE_NO_MODIFY_PATH`	Any value leaves the user PATH alone.	Unset

`NODECODE_STAGE`	Does
`full`	Downloads, lays out the version and points `current` at it.
`stage`	Lays out the version. `current` does not move.
`link`	Points `current` at a version already laid out. No download.