ncode

CLI docs Environment variables

ncode CLI Configure

Environment variables

Most of ncode is set up in Settings. Environment variables are for the first run on a new Mac, for a single launch, and for scripts.

Note Every NCODE_… variable below also works under its older name with SWARM_ in front (SWARM_MODEL, SWARM_THEME, …). When both are set, the NCODE_ one wins.

Provider (first run only)#

These create a provider only when the database has no usable provider yet, and only when a model is given and an endpoint is known; a missing model or endpoint stops the launch with a sentence that says which (NCODE_MODEL is missing., NCODE_BASE_URL is missing (OpenAI-compatible URLs end in /v1).). Afterwards they are ignored: the providers in Settings decide, and environment variables never add providers or change a conversation's model. See the Quickstart.

VariableMeaning
NCODE_PROVIDERopenai (the default, for any OpenAI-compatible endpoint) or anthropic
NCODE_MODELthe model id; OPENAI_MODEL or ANTHROPIC_MODEL also work
NCODE_BASE_URLthe endpoint; OpenAI-compatible URLs end in /v1, Anthropic URLs do not. OPENAI_BASE_URL or ANTHROPIC_BASE_URL also work; with only ANTHROPIC_API_KEY or OPENAI_API_KEY set, the endpoint defaults to https://api.anthropic.com or https://api.openai.com/v1
NCODE_API_KEYthe key; wins over OPENAI_API_KEY or ANTHROPIC_API_KEY. May be empty for a local server
NCODE_EFFORTthe reasoning effort for that first setup (medium if unset), and for this session's chat model while the conversation has no level of its own: the status line shows it and the /effort list and picker mark it. An /effort you set wins for the conversation; /effort default gives it back

Where they are loaded from#

ncode uses what you exported in your shell. It also reads ~/.secrets, or the file named by NCODE_ENV_FILE, but only provider variables, such as NCODE_…, SWARM_…, OPENAI_… and ANTHROPIC_…; a GitHub, npm or other token in the same file never reaches ncode. The file is read one variable at a time: a variable you exported (even an empty one) always wins, and the others are filled from the file. A named NCODE_ENV_FILE that does not exist stops the launch with exit code 2.

VariableMeaning
NCODE_ENV_FILEthe shell file to read instead of ~/.secrets

Session#

VariableMeaningWins over
NCODE_CONVERSATIONlatest (default), new, or a conversation idSettings → Session & startup; the flags --new, --continue and --resume win over it
NCODE_THEMEdark or light/theme and the desktop app's mode
NCODE_MOUSE1 sends mouse and wheel reports to ncode (off by default; the wheel still scrolls through the terminal), 0 keeps them off/mouse
NCODE_KEYMAPvim for vim keys in the composerSettings → Keys & input
NCODE_ASCII1 draws plain ASCII glyphsSettings → Appearance
NCODE_SHELLthe shell agents' commands run inSettings → Agents & limits → Shell

The older name of NCODE_SHELL is SWARM_CODE_SHELL.

Standard variables#

VariableMeaning
NO_COLORa monochrome screen
VISUAL, EDITORthe editor Ctrl+X opens (else vi)
TERM, COLORTERMwhich glyph set the terminal gets (see Terminal, themes and mouse)

Not used by ncode#

SWARM_PROJECT_ROOT is ignored: ncode opens the directory you name, or the one you run it from, so a value left in ~/.secrets does not open one project from everywhere.