Environment variables

NexgenK CLI uses environment variables to control a small number of runtime behaviors: relocating the data directory, turning off telemetry, and temporarily switching models without touching the config file.

Important: API keys are not configured here

Credential variables such as NEXGEN_API_KEY, ANTHROPIC_API_KEY, and OPENAI_API_KEY are not read automatically from shell environment variables. Running export NEXGEN_API_KEY=xxx in the terminal does not give any provider its key. They must be written in config.toml under [providers.<name>] or the [providers.<name>.env] sub-table.

The only exceptions are the NEXGEN_MODEL_* family and a provider's api_key_env field, two explicit channels that do read credentials from the shell. See Define a model from environment variables and Provider credential key names.

For background, see Config overrides: provider credentials.

Core paths

NEXGEN_CODE_HOME

Overrides the data root directory; the default is ~/.nexgenk. Once set, the config file, sessions, logs, OAuth credentials, and all other data land under the new path:

export NEXGEN_CODE_HOME="/path/to/custom/nexgenk"

Make sure the directory is writable. Multiple nexgenk instances sharing the same NEXGEN_CODE_HOME will share config and credential files.

For the complete data directory structure, see Data locations.

NEXGEN_DISABLE_TELEMETRY

Set to 1 to turn off anonymous telemetry reporting (also accepts true, yes, y, case-insensitive):

export NEXGEN_DISABLE_TELEMETRY=1

NEXGEN_MODEL_* family

Switch models temporarily without modifying config.toml: when NEXGEN_MODEL_NAME is set, the CLI synthesizes a temporary provider in memory, and the change does not persist after restart. See Define a model from environment variables.

NEXGEN_CODE_CUSTOM_HEADERS

Added

Added in 0.20.2.

Attaches custom HTTP headers to every outbound model request: both LLM chat requests (across all provider protocols) and /models listing requests carry them. Useful when a gateway routes by header, for example to pin a specific cluster:

export NEXGEN_CODE_CUSTOM_HEADERS=$'X-Gateway-Cluster: my-cluster\nX-Custom-Tag: debug'

The format mirrors ANTHROPIC_CUSTOM_HEADERS: newline-separated Name: Value lines. Names and values are trimmed, and lines without a colon are ignored.

Precedence: the Nexgen identity headers (User-Agent, X-Msh-*) and a provider's custom_headers in config.toml (see Config files) override same-named entries here. Authentication is protocol-dependent: on the nexgenk, openai, and openai_responses protocols an exact Authorization entry replaces the generated bearer token, while /models listing requests keep their own authentication. A case variant such as authorization is never treated as the same name. It merges with the real header, which can break requests. Do not use this variable for authentication or other reserved headers. Use custom_headers when headers need to differ per provider.

Provider credential key names (written in config.toml)

The key names below are not read directly from the shell. They are key names written inside the [providers.<name>.env] sub-table of config.toml, serving as fallback values for api_key / base_url. The CLI reads only from the config file, not from process.env.

These conventional names are fixed per provider type. If you would rather keep the key in the shell environment under a name of your choosing, set api_key_env on the provider instead: the CLI then reads the key from that variable on every request.

This design lets you keep familiar key name conventions while centralizing secret management in the config file:

[providers.nexgenk.env]
NEXGEN_API_KEY = "sk-xxx"
NEXGEN_BASE_URL = "https://ia.nexgen.systems/v1"

Key names per provider:

Key	Applicable provider	Default
NEXGEN_API_KEY	Nexgen / Nexgen	None
NEXGEN_BASE_URL	Nexgen / Nexgen	https://ia.nexgen.systems/v1
ANTHROPIC_API_KEY	Anthropic	None
ANTHROPIC_BASE_URL	Anthropic	Follows Anthropic SDK default
OPENAI_API_KEY	OpenAI (openai and openai_responses)	None
OPENAI_BASE_URL	OpenAI (openai and openai_responses)	https://api.openai.com/v1
GOOGLE_API_KEY	Google GenAI, Vertex AI	None
VERTEXAI_API_KEY	Vertex AI	None
GOOGLE_CLOUD_PROJECT	Vertex AI	None
GOOGLE_CLOUD_LOCATION	Vertex AI	None

WARNING

GOOGLE_APPLICATION_CREDENTIALS (path to a service account JSON file) is the only exception that goes through the system environment variable mechanism. It is read by the Google SDK directly via the standard ADC flow; the CLI does not participate. All other key names must be placed in the [providers.<name>.env] sub-table to take effect.

For the full provider type and field reference, see Providers and models.

OAuth and managed services

This group of variables redirects OAuth authentication and managed service endpoints to a self-hosted or test environment. They are not needed for everyday use.

Variable	Purpose	Default
NEXGEN_CODE_OAUTH_HOST	OAuth auth host; highest priority	Falls back to NEXGEN_OAUTH_HOST when unset
NEXGEN_OAUTH_HOST	OAuth auth host; fallback for NEXGEN_CODE_OAUTH_HOST	Falls back to https://ia.nexgen.systems when unset
NEXGEN_CODE_BASE_URL	Managed API base URL used after OAuth login	https://ia.nexgen.systems/v1
NEXGEN_CODE_REGION_MARKER	Install-channel marker and logged-out local region inference	Enabled; set off to disable both and use the mainland-cn default

WARNING

NEXGEN_CODE_BASE_URL (OAuth-managed service, targeting nexgenk.com) and NEXGEN_BASE_URL (direct API key connection, targeting nexgen.ai) are two distinct variables. Use each one in its appropriate context.

Workspace trust

NexgenK trusts the workspace folder on first open: project settings, project MCP servers and .nexgenk/ configuration are active without a trust prompt.

Variable	Purpose	Default
NEXGEN_TRUST_WORKSPACE	Set to 0/false to bring back the trust prompt for folders that have no recorded trust decision	Trusted

Revoking trust (untrust) is recorded and takes effect on the next read, even though folders without a recorded decision are trusted by default.

A folder that was trusted explicitly keeps its record; opting out only affects folders that were never trusted.

Define a model from environment variables (NEXGEN_MODEL_*)

Want to switch models for testing without touching config.toml? When NEXGEN_MODEL_NAME is set, the CLI synthesizes a temporary provider and model alias from the NEXGEN_MODEL_* variables in memory; nothing is written back to the config file. These variables take priority over default_model in config.toml, but the -m <alias> option at startup still has the highest priority.

export NEXGEN_MODEL_NAME="nexgenk-for-coding"
export NEXGEN_MODEL_API_KEY="YOUR_API_KEY"
export NEXGEN_MODEL_BASE_URL="https://api.example.com/v1"
export NEXGEN_MODEL_MAX_CONTEXT_SIZE="262144"
export NEXGEN_MODEL_CAPABILITIES="image_in,thinking"
nexgenk

Complete variable list:

Variable	Required	Purpose	Default
NEXGEN_MODEL_NAME	Yes (also the enable switch)	Model id sent to the API	—
NEXGEN_MODEL_API_KEY	Yes	API key	—
NEXGEN_MODEL_PROVIDER_TYPE	No	Provider type: nexgenk, anthropic, openai	nexgenk
NEXGEN_MODEL_BASE_URL	No	API base URL	Each type has its own default
NEXGEN_MODEL_MAX_CONTEXT_SIZE	No	Maximum context length (tokens)	262144 (256 K)
NEXGEN_MODEL_CAPABILITIES	No	Comma-separated capability tags, unioned with auto-detected capabilities	image_in,thinking
NEXGEN_MODEL_DISPLAY_NAME	No	Name shown in /model	Falls back to NEXGEN_MODEL_NAME
NEXGEN_MODEL_MAX_OUTPUT_SIZE	No	Per-request output cap (anthropic only); when set, overrides the built-in Claude ceiling	Model default
NEXGEN_MODEL_REASONING_KEY	No	Reasoning field name override (openai only)	Auto-detected
NEXGEN_MODEL_THINKING_EFFORT	No	Thinking effort level: low/medium/high/xhigh/max	—
NEXGEN_MODEL_ADAPTIVE_THINKING	No	Force adaptive thinking on or off (anthropic only)	Inferred from model name

If NEXGEN_MODEL_NAME is set but a required variable is missing, startup fails immediately with a clear error message.

Runtime switches

Switches that control the behavior of subsystems such as telemetry, background tasks, and the plugin marketplace:

Variable	Purpose	Valid values
NEXGEN_DISABLE_TELEMETRY	Disable anonymous telemetry reporting	1, true, yes, y (case-insensitive)
NEXGEN_CODE_PASSWORD	Parallel auth credential for nexgenk web, recommended when binding beyond loopback (see Security notes)	Any non-empty string; when unset, only the token is valid
NEXGEN_CODE_SESSION_IDLE_RECLAIM_MS	How long (ms) a nexgenk web session may stay idle before it is unloaded from memory; the session resumes transparently on next access (default 1800000; 0 = never unload)	Non-negative integer; invalid values fail fast
NEXGEN_CODE_BACKGROUND_KEEP_ALIVE_ON_EXIT	Keep background tasks when the session closes; higher priority than config.toml (default: stop them on exit)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_BACKGROUND_MAX_RUNNING_TASKS	Cap on concurrently running background tasks and Tower workers/reviewers; overrides [task] and legacy [background] max_running_tasks; Tower defaults to 256 when no value is configured	Positive integer; invalid values are ignored
NEXGEN_CODE_BACKGROUND_BASH_TASK_TIMEOUT_S	Default timeout (seconds) for background Bash tasks, also used to re-arm foreground commands moved to the background; higher priority than [task] bash_task_timeout_s (0 = no timeout)	Non-negative integer; invalid values are ignored
NEXGEN_CODE_BACKGROUND_PRINT_BACKGROUND_MODE	What nexgenk -p does while background tasks are still pending after the main turn; higher priority than [task] print_background_mode	exit, drain, or steer; invalid values are ignored
NEXGEN_CODE_BACKGROUND_PRINT_WAIT_CEILING_S	Wall-clock ceiling (seconds) for the print-mode drain/steer wait; higher priority than [task] print_wait_ceiling_s	Positive integer; invalid values are ignored
NEXGEN_CODE_BACKGROUND_PRINT_MAX_TURNS	Max number of new turns triggered by background-task completions in print mode; higher priority than [task] print_max_turns	Positive integer; invalid values are ignored
NEXGEN_IMAGE_MAX_EDGE_PX	Longest-edge ceiling (px) for image compression; higher priority than [image] max_edge_px (default 2000)	Positive integer; invalid values are ignored
NEXGEN_IMAGE_READ_BYTE_BUDGET	Per-image byte budget for model-initiated image reads; higher priority than [image] read_byte_budget (default 262144)	Positive integer; invalid values are ignored
NEXGEN_CODE_PLUGIN_MARKETPLACE_URL	Override the marketplace JSON loaded by /plugins; default https://ia.nexgen.systems/plugins/marketplace.json	Also accepts http://, file:// URLs, and local paths
NEXGEN_CODE_AGENT_SWARM_MAX_CONCURRENCY	Cap on AgentSwarm subagents running concurrently during the initial ramp; unset = no cap	Positive integer; invalid values fail fast
NEXGEN_CODE_SUBAGENT_SCOPE_CACHE_SIZE	How many completed subagent scopes stay resident for fast resume; older ones are evicted and rebuilt from persisted state on demand (default 32; 0 or negative = never evict)	Integer; invalid values fail fast
NEXGEN_CODE_SUBAGENT_SCOPE_EVICT_TIMEOUT_MS	Max wall-clock time (ms) a single subagent scope eviction may take before the eviction queue skips it and moves on (default 15000)	Positive integer; invalid values fail fast
NEXGEN_SUBAGENT_TIMEOUT_MS	Max wall-clock time (ms) a single Agent subagent may run; higher priority than [subagent] timeout_ms	Positive integer; invalid values fall back to the config or default
NEXGEN_CODE_SWARM_TIMEOUT_MS	Max wall-clock time (ms) an AgentSwarm subagent may run; higher priority than [swarm] timeout_ms	Positive integer; invalid values fall back to the config or default
NEXGEN_SWARM_ALLOW_AGENT_ENTRY	Allow the agent to turn swarm mode on for the current turn; higher priority than [swarm] allow_agent_entry (default true)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_IDENTITY_NAME	Name the agent calls itself in the system prompt; higher priority than [identity] name, never written back	Any non-empty string; blank values read as unset
NEXGEN_CODE_IDENTITY_SLUG	User-Agent product token and MCP client name; higher priority than [identity] slug; derived from the name when unset	Any non-empty string; normalized to lowercase with non-alphanumeric runs folded to -
NEXGEN_CODE_BUILTIN_PRODUCT_SKILLS	Offer the built-in skills documenting NexgenK itself to the model; higher priority than builtin_product_skills	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_REPEAT_BREAKER	Whether repeating the same tool call many times in a row injects reminders and eventually force-stops the turn. Unset keeps this on	Truthy: 1/true/yes/on; falsy: 0/false/no/off; any other value is ignored
NEXGEN_CODE_SESSION_LOCK	Whether this process takes the cross-process session lock that stops two NexgenK processes from writing the same session at once. Unset keeps it on; turning it off brings back pre-lock behavior, so concurrent writers can interleave the session history	Truthy: 1/true/yes/on; falsy: 0/false/no/off; any other value is ignored
NEXGEN_CODE_EXPERIMENTAL_SUBAGENT_FORK	Experimental fork parameter on Agent/AgentSwarm: start the subagent from a snapshot of the caller's history instead of an empty context; NEXGEN_CODE_EXPERIMENTAL_FLAG=1 also enables it	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_EXPERIMENTAL_TOOL_SELECT	Experimental on-demand tool loading: tools of MCP servers marked deferred: true stay out of the top-level tool list and are loaded via select_tools; also requires the model to declare the dynamically_loaded_tools capability — see MCP	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_EXPERIMENTAL_TOWER	Enable experimental Tower multi-agent coordination and the /tower command; set it before launch. The persistent equivalent is [experimental] tower = true in config.toml; changing that setting in a running CLI requires a restart. NEXGEN_CODE_EXPERIMENTAL_FLAG=1 enables Tower only when [experimental] tower is not set in config.toml; an explicit tower = false takes precedence over the master flag, while this per-feature variable overrides the config	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_WATCH	Attach filesystem watchers that reload config and workspace files; higher priority than [watch] enabled (default true)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_SEARCH_WORKER	Run the global search index in a dedicated worker thread; higher priority than [database] search (default true)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_CODE_PERSISTENCE_MINIDB_READMODEL	Use the minidb-backed read model for session indexing; higher priority than [database] base (default true)	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_MCP_STARTUP_TIMEOUT_MS	Global default connection timeout (ms) for MCP servers; overrides the config file, but mcp.json startupTimeoutMs still wins	Integer from 1 to 2147483647; invalid values are ignored
NEXGEN_MCP_TOOL_TIMEOUT_MS	Global default single tool-call timeout (ms) for MCP servers; overrides the config file, but mcp.json toolTimeoutMs still wins	Integer from 1 to 2147483647; invalid values are ignored
NEXGEN_MCP_RECONNECT_INITIAL_DELAY_MS	Initial delay (ms) before the first automatic reconnect attempt for a workspace-level MCP server that failed to connect or dropped unexpectedly; overrides the config file	Integer from 1 to 2147483647; invalid values are ignored
NEXGEN_MCP_RECONNECT_MAX_DELAY_MS	Cap (ms) for the automatic reconnect backoff delay of workspace-level MCP servers; overrides the config file	Integer from 1 to 2147483647; invalid values are ignored
NEXGEN_CODE_TRUST_WORKSPACE	Mark the current workspace as trusted, equivalent to choosing "Trust this folder" at the interactive trust prompt; takes effect per process and does not write a persistent trust record	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_LOOP_MAX_STEPS_PER_TURN	Max steps per turn for subagents; higher priority than [loop_control] max_steps_per_turn (0 = unlimited). The main agent is never capped	Non-negative integer; invalid values are ignored
NEXGEN_LOOP_MAX_ATTEMPTS_PER_STEP	Max total attempts for a failing step (including the first); higher priority than [loop_control] max_attempts_per_step	Non-negative integer; invalid values are ignored
NEXGEN_CODE_INFINITE_RETRY	Retry failed LLM requests indefinitely; exponential backoff (32 s cap) honoring Retry-After; aborting still cancels immediately	Truthy: 1/true/yes/on; falsy: 0/false/no/off
NEXGEN_TOKEN_COUNTING_STRATEGY	Context token count reported externally; higher priority than [token_counting] strategy	measured+estimated, measured, estimated (case-insensitive); invalid values are ignored
NEXGEN_WEB_SEARCH_BASE_URL	Web search (WebSearch) service API URL; higher priority than the config file; credentials and custom headers not forwarded	Non-blank string; blank values are ignored
NEXGEN_WEB_SEARCH_API_KEY	Web search (WebSearch) service API key; replaces both the configured key and the OAuth credential	Non-blank string; blank values are ignored
NEXGEN_WEB_FETCH_BASE_URL	Web fetch (FetchURL) service API URL; higher priority than the config file; credentials not forwarded. Without an endpoint, signed-in users get the managed Nexgen OAuth fetch service before direct local requests	Non-blank string; blank values are ignored
NEXGEN_WEB_FETCH_API_KEY	Web fetch (FetchURL) service API key; replaces both the configured key and the OAuth credential	Non-blank string; blank values are ignored
NEXGEN_CODE_EXPERIMENTAL_FLAG	Enable all registered experimental features for this process	1, true, yes, on
NEXGEN_SHELL_PATH	Override the Git Bash path on Windows (used when auto-detection fails)	Absolute path
NEXGEN_MODEL_MAX_COMPLETION_TOKENS	Hard cap on max_completion_tokens per LLM step; applies to the nexgenk provider only	Positive integer; 0 or negative disables clamping
NEXGEN_MODEL_TEMPERATURE	Sampling temperature for every request; nexgenk provider only (global, independent of NEXGEN_MODEL_NAME)	Number, e.g. 0.3
NEXGEN_MODEL_TOP_P	Nucleus-sampling top_p for every request; nexgenk provider only (global)	Number, e.g. 0.95
NEXGEN_MODEL_THINKING_EFFORT	Force a thinking effort (thinking.effort), bypassing the model's declared support_efforts; nexgenk provider only	An effort value, e.g. max
NEXGEN_MODEL_THINKING_KEEP	Preserved-thinking passthrough: thinking.keep on nexgenk, a clear_thinking_20251015 edit on anthropic; overrides [thinking] keep	A value the API accepts, e.g. all; an off-value (false/0/no/off/none/null) disables it
NEXGEN_CODE_LLM_HEADERS_TIMEOUT_MS	Max time (ms) an LLM request on the openai / openai-responses / anthropic protocols may wait for the response headers (first byte), replacing the HTTP client's default 300 s headers timeout — raise it for long non-streaming thinking; unset keeps the default; the SDK's own total request timeout (default 10 minutes) still caps each attempt; not supported for google-genai (its SDK exposes no dispatcher option) or behind a SOCKS proxy (requests still go through the proxy)	Positive integer no greater than 2147483647; invalid values fail the request
NEXGEN_CODE_NO_AUTO_UPDATE	Fully disable the update preflight: no check, background install, or prompt. Legacy alias NEXGEN_CLI_NO_AUTO_UPDATE also honored	Truthy: 1/true/yes/on
NEXGEN_DISABLE_CRON	Disable the scheduled-task tool (CronCreate rejects new schedules; existing tasks do not fire)	1 to disable

The NEXGEN_CODE_INFINITE_RETRY, NEXGEN_CODE_IDENTITY_*, and NEXGEN_CODE_BUILTIN_PRODUCT_SKILLS variables are read by the agent-core-v2 engine.

Diagnostic logs

These variables control log level and file rotation, read once at process startup:

Variable	Purpose	Default
NEXGEN_LOG_LEVEL	Log level: off, error, warn, info, debug	info
NEXGEN_LOG_GLOBAL_MAX_BYTES	Maximum bytes per global log file	6291456 (6 MB)
NEXGEN_LOG_GLOBAL_FILES	Number of global log files to retain	5
NEXGEN_LOG_SESSION_MAX_BYTES	Maximum bytes per session log file	5242880 (5 MB)
NEXGEN_LOG_SESSION_FILES	Number of session log files to retain	3

System environment variables

The CLI also reads several standard system variables to detect the runtime environment; it does not modify them:

• HOME: used to resolve the default data path
• VISUAL, EDITOR: external editor command (VISUAL takes precedence)
• PATH: used to locate dependencies such as rg, fd, fdfind, and git; on Windows, Git Bash detection checks each git.exe found on PATH, including package-manager shims such as Scoop
• NO_COLOR, FORCE_COLOR: control color output (following the no-color.org convention)
• CI: when non-empty and not "0", disables theme detection and falls back to the dark theme
• TERM_PROGRAM, TERM, TMUX: detect terminal features and notification support
• DISPLAY, WAYLAND_DISPLAY, XDG_SESSION_TYPE: detect Linux graphical sessions (for clipboard and image features)
• WSL_DISTRO_NAME, WSLENV: detect WSL for the clipboard PowerShell bridge
• LOCALAPPDATA: used on Windows as a fallback when probing for the Git Bash installation path

HTTP proxy

NexgenK honors the standard proxy environment variables for all outbound traffic: model API calls, MCP servers, web tools, telemetry, sign-in, and update checks:

• HTTP_PROXY / http_proxy: proxy for http:// requests
• HTTPS_PROXY / https_proxy: proxy for https:// requests
• ALL_PROXY / all_proxy: fallback proxy used when the scheme-specific variable is unset; this is where a SOCKS proxy is usually set
• NO_PROXY / no_proxy: comma-separated hosts that bypass the proxy

Proxy types and precedence

Both HTTP(S) and SOCKS proxies are supported. A SOCKS proxy is recognized by its scheme: socks5://, socks5h://, socks4://, or socks:// (an alias for socks5://). It is typically set via ALL_PROXY (the form used by tools like Clash and V2RayN). An HTTP(S) proxy takes precedence over ALL_PROXY for HTTP/HTTPS traffic.

Activation conditions and loopback addresses

The proxy is applied only when one of these variables is set; otherwise connections are made directly. Loopback hosts (localhost, 127.0.0.1, ::1) always bypass the proxy, so a local server such as a localhost MCP server keeps working when a proxy is configured. Add your own internal hosts to NO_PROXY to exempt them too.

MCP child processes

Stdio MCP servers that run as Node child processes honor HTTP_PROXY / HTTPS_PROXY / NO_PROXY automatically when the child's Node version supports NODE_USE_ENV_PROXY (Node ≥ 22.21 or ≥ 24.5); SOCKS proxying applies to NexgenK's own traffic only.

Next steps

• Config overrides — how environment variables, CLI options, and the config file interact by priority
• Data locations — directory structure affected by NEXGEN_CODE_HOME
• Providers and models — full connection examples per provider type