Environment variables

Nexrall Code (CLI and VS Code) reads its configuration from environment variables, all prefixed NEXRALL_. They cover authentication, safety, context management, sub-agents, and low-level timeouts. Most have sensible defaults — you only set one when you need to change a behavior.

The two you'll actually use day-to-day are NEXRALL_TOKEN (CI auth) and, rarely, NEXRALL_ALLOW_DESTRUCTIVE (headless safety).

Authentication & API

Variable	Purpose
NEXRALL_TOKEN	Bearer token for non-interactive use (CI, scripts). Always takes precedence over a saved interactive login.
NEXRALL_CLOUD_PAT	Fine-grained GitHub token for nex cloud — clone, push and PR. Preferred over --pat (argv is visible in ps and shell history); the server keeps it only for the session's lifetime.
NEXRALL_API_BASE	Override the API endpoint.
NEXRALL_ALLOW_API_OVERRIDE	Set to 1 to allow NEXRALL_API_BASE to point at a remote host. Guarded because this variable receives your auth token — redirecting it to a host you don't control would leak it.
NEXRALL_BILLING_TEAM	Pin a run's billing target: a numeric team id, or personal (0 / null too) to force the personal wallet. Overrides the account's saved choice for that run — see Billing & teams. With NEXRALL_TOKEN, unset already means personal.

Safety

Variable	Purpose
NEXRALL_ALLOW_DESTRUCTIVE	Set to 1 to permit irreversible operations (drop table, force-push, terraform destroy) in headless mode, where there's no one to confirm. Blocked by default.
NEXRALL_SECURITY_LINT	Set to 0 to disable the security lint pass that flags suspicious patterns in tool results.
NEXRALL_TEST_INTEGRITY	Set to 0 to disable the guard that flags weakening a test to make it pass.
NEXRALL_CROSSFILE_CHECK	Set to 0 to disable cross-file breakage detection (warns when a renamed/removed export is still referenced elsewhere).
NEXRALL_ALLOW_ELIDED_WRITE	Set to 1 to permit edits that elide existing code behind a placeholder (// rest unchanged). Refused by default.
NEXRALL_AUTO_CLASSIFIER	Set to 0 to turn off the auto-mode safety classifier — beats the autoMode.classifier setting. See Permissions → Auto-mode classifier.

Context & compaction

Variable	Purpose
NEXRALL_AUTO_COMPACT	Set to 0 to disable automatic history summarization near the context limit.
NEXRALL_AUTO_CONTINUE	Set to 0 to stop the agent from continuing on its own mid-task.
NEXRALL_COMPACT_THRESHOLD	Fraction of the context window that triggers compaction (default 0.8 — summarize when the prompt exceeds ~80%).
NEXRALL_PRUNE_THRESHOLD	Fraction that triggers pruning older history (default 0.35).
NEXRALL_COMPACT_WINDOW	An explicit cap, in tokens (min 50000), on the context window auto-compaction sizes itself against — the autoCompactWindow setting is the same knob; default: the selected model's own window.
NEXRALL_MAX_ITERATIONS	Cap on agent-loop iterations per turn.

Sub-agents & parallelism

Variable	Purpose
NEXRALL_MAX_SUBAGENTS_PER_SESSION	Cap on how many sub-agents a session may spawn.
NEXRALL_MAX_SUBAGENT_DEPTH	Cap on sub-agent nesting depth.
NEXRALL_MAX_CONCURRENT_SUBTASKS	How many sub-agents may run in parallel.
NEXRALL_SUBTASK_TIMEOUT_MS	Timeout for a single sub-task.

State, memory & sessions

Variable	Purpose
NEXRALL_MEMORY_DIR	Override where persistent memory lives.
NEXRALL_CHECKPOINT_DIR	Override where file checkpoints (for /rewind) are stored.
NEXRALL_CLI_SESSIONS_DIR	Override where saved CLI sessions live.
NEXRALL_EVENTS	Set to off to stop recording a session's event stream (the JSONL record other clients read — see Sessions).
NEXRALL_MCP_AUTH_FILE	Override where MCP OAuth tokens are stored (default ~/.nexrall/mcp-auth.json, mode 0600).
NEXRALL_TRUST_WORKSPACE	Set to 1 to skip the workspace-trust prompt for a given run (e.g. in CI or automated pty tests).
NEXRALL_CLI_BG_DIR	Where --bg job output lives (default ~/.nexrall/cli-bg).
NEXRALL_CLI_HISTORY_FILE	The prompt-history file behind Ctrl+R (default ~/.nexrall/cli-history.jsonl).
NEXRALL_CLI_RECENTS_FILE	The recently-used commands the / menu leads with (default ~/.nexrall/cli-recents.json).
NEXRALL_CLI_CONTEXT_DIR	Where /pin and /exclude state lives, one file per project (default ~/.nexrall/cli-context).
NEXRALL_DEBUG_DIR	Where --debug logs are written (default ~/.nexrall/debug).
NEXRALL_LOCKS_DIR	Cross-process lock files (default ~/.nexrall/locks) — nex doctor --fix cleans stale ones here.
NEXRALL_PEERS_DIR	The peer registry sessions use to find and message each other (default ~/.nexrall/peers).
NEXRALL_SHARED_TASKS_DIR	The shared task board (nex tasks, create_shared_task; default ~/.nexrall/peers/tasks).
NEXRALL_AGENT_TRANSCRIPTS_DIR	Sub-agent transcripts — the agent_… rows in nex agents (default ~/.nexrall/agent-transcripts).
NEXRALL_THEMES_DIR	Where named theme files resolve from (default ~/.nexrall/themes; see Configuration).
NEXRALL_MANAGED_SETTINGS	Path of the managed (read-only, organization) settings file — overrides the platform default location. See Configuration.

Timeouts & retry

Variable	Purpose
NEXRALL_FIRST_EVENT_TIMEOUT_MS	How long to wait for the first streaming event before giving up.
NEXRALL_HEADER_TIMEOUT_MS	Timeout for the response headers.
NEXRALL_MAX_RETRY_MS	Backoff ceiling when retrying a failed request.
NEXRALL_PROGRESS_TIMEOUT_MS	How long to wait for progress before a turn is considered stalled.
NEXRALL_VERIFY_NUDGE	Tunes the nudge that asks the agent to verify its own work before finishing.

Network (fetch)

Variable	Purpose
NEXRALL_ALLOW_LOCAL_FETCH	Set to 1 to allow fetch_url to reach localhost addresses.
NEXRALL_FETCH_BLOCKLIST	Hosts/paths the fetch tool refuses to touch.

Telemetry (OTLP export)

Off by default — see Usage export & telemetry.

Variable	Purpose
NEXRALL_ENABLE_TELEMETRY	Set to 1 to turn the live export on; every variable below is inert until it is set.
OTEL_EXPORTER_OTLP_ENDPOINT	Collector base URL (default http://localhost:4318; /v1/logs and /v1/metrics are appended). Per-signal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT / ..._METRICS_ENDPOINT win; NEXRALL_OTEL_ENDPOINT takes the base slot.
OTEL_EXPORTER_OTLP_HEADERS	Extra headers, key=value pairs (per-signal OTEL_EXPORTER_OTLP_LOGS_HEADERS / ..._METRICS_HEADERS merge over them).
OTEL_EXPORTER_OTLP_PROTOCOL	Only http/json is supported; anything else disables that signal with a note.
OTEL_LOGS_EXPORTER / OTEL_METRICS_EXPORTER	otlp (default) · console (print to stderr, no network) · none (off).
OTEL_LOGS_EXPORT_INTERVAL / OTEL_METRIC_EXPORT_INTERVAL	Export cadence in ms (defaults 5000 / 60000; below 250 falls back to the default).
NEXRALL_OTEL_LOG_PROMPTS	Set to 1 to include prompt text (OTEL_LOG_USER_PROMPTS accepted as the Claude Code-compatible fallback).
NEXRALL_OTEL_LOG_TOOL_DETAILS	Set to 1 to include tool details (target, outputs).

Endpoint overrides

Variable	Purpose
NEXRALL_WS_URL	Base URL of the socket.io relay behind /share (default https://api.nexrall.com).
NEXRALL_WEB_URL	Base URL used when building the /share watch link (default https://app.nexrall.com).

Accessibility

Variable	Purpose
NEXRALL_AX_SCREEN_READER	Set to 1 for screen-reader mode; set to 0 to force it OFF even when the axScreenReader setting is on.
NEXRALL_AX_STARTUP_QUIET_MS	How long the first render waits after the mode's confirmation line. Default 3000; capped at 10 minutes; 0 renders immediately. Any key ends the wait early.

Injected into hooks (read-only)

These are set automatically on the subprocess that runs a hook — you don't set them yourself:

Variable	Value
NEXRALL_HOOK_PHASE	The hook phase being run (PreToolUse / PostToolUse).
NEXRALL_TOOL_NAME	The tool being invoked.
NEXRALL_TOOL_INPUT	The tool's input, JSON-encoded.
NEXRALL_AGENT_NAME	The sub-agent's type (e.g. explorer), on SubagentStop runs.

The worktreeHooks commands (create / enter / exit) get their own three — NEXRALL_WORKTREE_NAME, NEXRALL_WORKTREE_PATH and NEXRALL_MAIN_CHECKOUT — see Configuration.

Feature toggles & UI

Variable	Purpose
NEXRALL_PROMPT_SUGGESTIONS	Set to 0 to turn the ghost next-prompt suggestions off — same as "promptSuggestions": false. Each shown suggestion is one small billed request.
NEXRALL_AUTO_RECAP	Set to 0 to skip the one-line recap when a session is resumed — same as "autoRecap": false.
NEXRALL_EDITOR	Pins the editor /open launches — beats the host-terminal detection and $VISUAL / $EDITOR.
NEXRALL_RG_PATH	Path to the ripgrep binary the file-search tools run.
NEXRALL_THEME_BG	light / dark — what "theme": "auto" resolves to when the terminal does not report its background (COLORFGBG).

Next steps

• Configuration — the .nexrall/ directory and settings.json hierarchy.
• Permissions — modes and allow/ask/deny rules.
• Hooks — where the injected variables above are used.