Download Neox CLI
Get started

Configuration

Three layers — user, project and environment variables; most settings can be changed from CLI commands or desktop settings.

Neox configuration has three layers: user-level (shared by all projects), project-level (one project directory only) and environment variables (this run only, handy for CI or quick overrides).

User-level

The desktop app and the CLI use the same directory on every platform:

PlatformPath
macOS / Linux~/.neox/
Windows%USERPROFILE%\\.neox\\

Files you may touch:

~/.neox/
  ├── config.json         models / providers / MCP / preferences
  ├── INSTRUCTIONS.md     global agent instructions (optional)
  ├── skills/             global skills
  ├── agents/             custom subagent roles
  ├── keybindings.json    CLI key bindings (optional)
  └── logs/               logs

The same directory also holds encrypted credential files that Neox manages itself — don't edit them. Back up config.json before editing it by hand.

Project-level

In the project root:

<project>/
  ├── .neox/
  │   ├── INSTRUCTIONS.md   project agent instructions
  │   ├── skills/           project skills
  │   ├── agents/           project subagent roles
  │   └── mcp.json          project MCP config
  └── NEOX.md               same as .neox/INSTRUCTIONS.md

Instruction files can also be AGENTS.md, CLAUDE.md and others — see Rules for the lookup order. A repository's mcp.json must be approved before it connects; see MCP.

Common settings

Most settings have a ready-made entry point, so you rarely need to edit files:

TaskCLIDesktop
Add a bring-your-own-key providerneox provider add or /providerSettings → Models → Providers
Switch model/modelThe model menu in the input box
Approval level/approvalSettings → Agent → Permissions
MCPneox mcp ... or /mcpSettings → Agent → MCP

In config.json the approval level is approvalMode: auto (ask only for risky actions, the default), manual (ask every step) or dangerous (never ask).

Environment variables

# Logs and debugging
NEOX_DEBUG=1                          # more verbose debug output
NEOX_DUMP_LLM_PAYLOAD=1               # write each turn's full request to ~/.neox/logs/llm-requests/

# CLI behavior
NEOX_NON_INTERACTIVE=1                # non-interactive
NEOX_DISABLE_AUTO_UPDATE_CHECK=1      # don't check for updates
NEOX_THEME=slate                      # colors: neox / slate / warm / mono / nord / neon
NEOX_BG=dark                          # force a light / dark background

# Running commands
NEOX_OS_SANDBOX=on                    # OS sandbox (macOS Seatbelt / Linux bubblewrap / Windows AppContainer)
NEOX_BASH_DEFAULT_TIMEOUT_MS=120000   # foreground wait; longer commands move to the background
NEOX_BASH_MAX_TIMEOUT_MS=600000       # hard ceiling
NEOX_DISABLE_FG_ADOPT=1               # never move to the background

# Subagents
NEOX_MAX_AGENT_THREAD_DEPTH=3         # max subagent nesting depth
NEOX_MAX_CONCURRENT_AGENTS=3          # max subagents running at once

# Background service
NEOX_USE_DAEMON=1                     # connect the CLI to the background service; see the Daemon page