Environment Variables Reference

CodeBuddy Code supports environment variables to control its behavior. These variables can be set before startup, or configured in the env field of settings.json to apply to every session.

Tip: Unless otherwise noted, environment variables can also be set in the env field of settings.json, which automatically applies them to every session or rolls out configuration for an entire team.

Exception: CODEBUDDY_IS_SANDBOX is read exclusively from the process environment and is not injected from the env field of settings.json (including project-level settings), preventing a repository from silently escalating privileges. See Sandbox full pass (high risk).

Authentication

Environment Variable	Description
CODEBUDDY_API_KEY	API key. Set this key for model API calls. Always uses this key in non-interactive mode (-p)
CODEBUDDY_AUTH_TOKEN	CodeBuddy platform authentication token for all platform API calls
CODEBUDDY_CUSTOM_HEADERS	Custom HTTP headers. Format: Name: Value, multiple headers separated by newline or \n
CODEBUDDY_PASSTHROUGH_HEADER_PREFIXES	Allowlist of custom header prefixes that callers can pass through on each turn to the official model gateway (via _meta['codebuddy.ai'].customPassthroughHeaders in stream-json / print flows). Comma-separated and case-insensitive (e.g., x-wb-,x-mobile-). Empty by default = feature disabled (security kill switch); this is a security boundary, so choose prefixes that do not overlap with internal X-* header namespaces. Applies only to official models; headers are not sent to third-party/custom models

API Endpoints and Proxy

Environment Variable	Description
CODEBUDDY_BASE_URL	Override the API endpoint address, typically used with CODEBUDDY_API_KEY
CODEBUDDY_INTERNET_ENVIRONMENT	Network environment configuration (internal for China edition, ioa for iOA enterprise edition)
HTTP_PROXY / http_proxy	HTTP proxy server address
HTTPS_PROXY / https_proxy	HTTPS proxy server address
NO_PROXY / no_proxy	List of domains and IPs to bypass proxy (comma-separated, e.g., localhost,.example.com)

Model Configuration

Environment Variable	Description
CODEBUDDY_MODEL	Override the default agent model
CODEBUDDY_SMALL_FAST_MODEL	Override the model for the lite (lightweight, fast) scenario variant; takes priority over the variantModels.lite setting
CODEBUDDY_BIG_SLOW_MODEL	Override the model for the reasoning (enhanced reasoning) scenario variant; takes priority over the variantModels.reasoning setting
CODEBUDDY_CODE_SUBAGENT_MODEL	Blanket override of the model for all built-in sub-agents (highest priority, overrides the subagents setting). To configure per sub-agent, use the /agents panel or settings.json's subagents.agents.<subagent-name>.model
MAX_THINKING_TOKENS	Enable extended thinking and set the token budget for the thinking process. Disabled by default

Relationship between env and settings: Model-related environment variables are for ops/CI-level overrides.

• Built-in sub-agents: CODEBUDDY_CODE_SUBAGENT_MODEL > the model parameter of the current Agent tool call > project-level subagents > user-global subagents > product built-in declaration > main model.

• Scenario variants: corresponding variant env var > project-level variantModels > user-global variantModels > main model's relatedModels > applicable product built-in default > main model.

• CODEBUDDY_CODE_SUBAGENT_MODEL uniformly overrides all sub-agents. To specify individually, use /agents or subagents.agents.<subagent-name>.model; see Sub-Agents for details.

• CODEBUDDY_SMALL_FAST_MODEL only affects lite, CODEBUDDY_BIG_SLOW_MODEL only affects reasoning. The corresponding persistent settings can be managed via /model or variantModels; see Settings for details.

Removing the environment variable restores the lower-priority configuration, which may not directly fall back to the main model.

Bash Tool Configuration

Environment Variable	Description
BASH_DEFAULT_TIMEOUT_MS	Default timeout for long-running bash commands (default: 120000)
BASH_MAX_OUTPUT_LENGTH	Maximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk
BASH_MAX_TIMEOUT_MS	Maximum timeout the model can set for long-running bash commands (default: 600000)
CODEBUDDY_BASH_ASSISTANT_BUDGET_MS	Main conversation response budget (milliseconds, default 0=off). When set to >0, foreground Bash/PowerShell commands in the main session that exceed this duration are automatically converted into background tasks to keep the conversation responsive. Sub-agents are not affected by this budget. This does not apply in -p (print, non-stdio stream-json) non-interactive mode—the process exits with the main turn, so background tasks cannot continue and commands always remain in the foreground until completion. Aligns with Claude Code's ASSISTANT_BLOCKING_BUDGET_MS (official default value is 15000)
CODEBUDDY_BASH_AUTO_BACKGROUND_DISABLED	Set to 1 to disable timeout auto-backgrounding; foreground commands fall back to the old SIGTERM/kill hard-kill behavior on timeout. Only used for debugging or temporary rollback when encountering regressions; keep the default (unset) in normal scenarios. Note: -p (print, non-stdio stream-json) non-interactive mode already disables auto-backgrounding, so this variable is unnecessary there
CODEBUDDY_BASH_BG_MAX_OUTPUT_BYTES	Total byte limit for the on-disk file of stdout+stderr for background bash tasks (default 52428800 = 50MB). When exceeded, the size watchdog fires SIGKILL and marks the task as killed, with a notice injected at the end of stderr. Claude Code in ShellCommand.ts hardcodes the equivalent threshold as a constant; here it is exposed as an env var for operators to tune. Only effective in file fd mode (in pipe mode, child process output is not persisted to disk)
CODEBUDDY_BASH_BG_PIPE_MODE	Set to 1 to force background tasks back to pipe mode (not using file fds), for rollback or debugging. The default (unset) uses file fd mode, which solves the zombie process issue caused by grandchild processes (e.g., spawned via nohup) holding parent pipe fds; the sandbox path automatically falls back to pipe and does not require explicit setting. There is no equivalent toggle in Claude Code; this is a CodeBuddy fallback to remain compatible with legacy sandbox/PTY paths
CODEBUDDY_BG_TASK_RECONCILE	Set to 0 to disable background-task liveness reconciliation. Enabled by default (when unset): every 5 seconds, it checks whether background-task processes have terminated and, after two consecutive confirmations, finalizes the task state and sends a completion notification. This handles cases where the child process has exited but the process termination event was not delivered, which would otherwise leave the task stuck in the running state without a completion notification. Use only for rollback or troubleshooting false positives; keep the default in normal scenarios

Tool Output Externalization

Environment Variable	Description
CODEBUDDY_TOOL_RESULT_THRESHOLD_KB	Size threshold (KB) for tool result externalization. Non-bash tool results exceeding this threshold are saved to disk and replaced with a placeholder (default: 50)

Note: Bash tool output externalization is controlled by BASH_MAX_OUTPUT_LENGTH. When output is truncated due to exceeding that value, the full output is automatically streamed to disk. CODEBUDDY_TOOL_RESULT_THRESHOLD_KB primarily affects large output handling for other tools (e.g., MCP tools). See the Tool Output Externalization section for details.

Tools and Feature Toggles

Environment Variable	Description
CODEBUDDY_DISABLE_HOT_RELOAD	Set to 1 to disable the hot reload system
CODEBUDDY_SKIP_BUILTIN_MARKETPLACE	Set to 1 to skip loading the built-in plugin marketplace
CODEBUDDY_AUTO_UPDATE_THIRD_PARTY_MARKETPLACES	Set to true or 1 to enable automatic updates for third-party plugin marketplaces (default: disabled)
CODEBUDDY_MARKETPLACE_AUTO_UPDATE_INTERVAL_MS	Override the refresh window for plugin marketplace auto-updates (milliseconds), default 86400000 (24 hours). Set to a smaller value (e.g., 3600000 = 1 hour) to shorten the auto-update detection interval, useful for testing/debugging; invalid values (non-numeric or ≤0) fall back to the default
CODEBUDDY_PLUGIN_DIRS	Colon-separated list of local plugin directory paths (equivalent to --plugin-dir). The bin/ directory of each plugin is automatically injected into PATH
CODEBUDDY_DISABLE_EXTENDED_PLUGIN_HOOKS	When set to 1 or true, plugin Hook configurations only accept the command type; configurations containing prompt, agent, or http types are treated as incompatible. Used by hosts to temporarily roll back the plugin Hook contract; unset by default
CODEBUDDY_IMAGE_GEN_ENABLED	Set to false or 0 to disable image generation
CODEBUDDY_BRIEF	Set to 1 / true / yes to enable the SendUserMessage tool (same as --brief) so the agent can send user-facing messages; the tool is hidden when unset
CODEBUDDY_IS_SANDBOX	Process environment only. Set to 1 / true / yes / on to skip HIGH/CRITICAL approvals when used with -y. Setting it alone does not change the default mode. See Sandbox full pass (high risk). Unset by default
CODEBUDDY_IMAGE_EDIT_ENABLED	Set to false or 0 to disable image editing
CODEBUDDY_ARTIFACT_ENABLED	Set to false or 0 to disable the Artifact / ArtifactControl tool (publishes a local single HTML or Markdown file as a shareable public link; Markdown is server-rendered into a styled page; ArtifactControl currently only supports unpublishing). Enabled by default. Evaluation order: under international endpoints (codebuddy.ai / workbuddy.ai / staging-codebuddy.tencent.com), this capability is always off and this variable cannot override it; in all other scenarios, this variable has the highest priority — when unset (including empty values), falls back to the legacy variable CODEBUDDY_SHARE_LINK_ENABLED, then to the cloud-side productFeatures (if either Artifact or ShareLink is explicitly false, the feature is off; when neither is delivered, defaults to true)
CODEBUDDY_SHARE_LINK_ENABLED	Deprecated (kept for compatibility): The former name of CODEBUDDY_ARTIFACT_ENABLED, the toggle from before the ShareLink tool was renamed to Artifact. Semantics are identical to the new variable, which takes priority; only takes effect when the new variable is unset
CODEBUDDY_COMPUTER_USE_ENABLED	Experimental: Set to true or 1 to enable the macOS desktop control tool (screenshot, mouse, keyboard). Available only on macOS, disabled by default. The first invocation of keyboard/mouse actions requires authorizing the terminal in System Settings → Privacy & Security → Accessibility and Screen Recording
CODEBUDDY_PUSH_NOTIFICATION_ENABLED	Set to false or 0 to disable the PushNotification tool (the model can proactively trigger a terminal/desktop notification when long-running or background tasks complete). Enabled by default
CODEBUDDY_REPORT_FINDINGS_ENABLED	Set to false or 0 to disable the ReportFindings tool (used by code review Agents to submit findings as structured fields, rendered as a dedicated list component). Enabled by default
CODEBUDDY_WAIT_FOR_MCP_SERVERS_ENABLED	Set to 0 or false to disable the WaitForMcpServers tool. Enabled by default. In interactive mode, MCP connections are not awaited blockingly; when the LLM needs an MCP tool that is not yet ready, it can proactively call this tool to wait on demand. Set to 0 to disable in WorkBuddy scenarios
CODEBUDDY_DEFERRED_TOOLS_MCP_READY_WAIT_MS	Maximum milliseconds to wait for MCP servers to be ready before rendering deferred tool descriptions, default 2500. Set to 0 to skip waiting entirely — if connections are slow, the "still connecting" hint is immediately baked into the description; increase to give remote MCP servers more time to complete the handshake before the first prompt. Continues immediately once the server is ready; the timeout serves only as an upper bound
CODEBUDDY_DEFER_TOOL_LOADING	Set to false or 0 to disable MCP tool deferred loading
CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS	Set to true or 1 to show full descriptions for all deferred tools
CODEBUDDY_DISABLE_CRON	Set to 1 to disable scheduled tasks
CODEBUDDY_MAIN_AGENT_ENABLED	Master switch for the four main-agent modes. 0/false turns them off (no picker in the Web chip or TUI /agent-mode; the run chain ignores the standing main agent). If unset, reads codebuddy.mainAgent.enabled in settings.json, then defaults to on. Overrides settings
CODEBUDDY_MAIN_AGENT_ALLOW_UNOPTED	Allow ACP hosts that do not declare mainAgentSupport (WorkBuddy Desktop / sidecar) to use mode resolution. Off by default: those hosts always stay native cli. 1/true turns it on (still requires the master switch). Overrides codebuddy.mainAgent.allowUnopted
CODEBUDDY_REPL_ENABLED	REPL master switch. 1/true forces on, 0/false forces off, highest priority. If unset: on by default for ptc / minimal (REPL is their only direct tool; turning it off leaves an empty tool surface); off for Standard / Creator / native WorkBuddy cli. To enable later on WorkBuddy: set CODEBUDDY_REPL_ENABLED=1 in sidecar managedEnv (the tool is already on overlay cli.tools). Do not flip codebuddy.mainAgent.allowUnopted for this — that opts WorkBuddy into PTC mode resolution, it is not a REPL-only switch
CODEBUDDY_REPL_TOOLS_INJECT_BUILTIN	Whether to load built-in tools into the REPL sandbox (top-level globals and tools.*). 1/true forces on, 0/false forces off. If unset: on by default for ptc / minimal (REPL is the only direct tool, so the sandbox must have builtins); off for other modes (including a standard REPL that only turned on CODEBUDDY_REPL_ENABLED), so the model is not induced to call one-shot native tools through REPL. When off, both the skeleton catalog and sandbox injection omit builtins; MCP / bridge orchestration is unchanged
CODEBUDDY_REPL_TOOLS_INJECT_CATALOG	Whether to inject the skeleton tool catalog into the REPL code parameter description. On by default. 0 still preloads tools but hides them from the model until REPL.searchTools / REPL.describeTool
CODEBUDDY_DISABLE_FORK_SUBAGENT	Set to 1 to disable the Agent tool's fork sub-agent mode (subagent_type="fork"). When enabled, the fork-mode section is automatically hidden from the Agent tool description, so the model will not see this feature; if the model still passes subagent_type="fork", the runtime falls back to a custom agent named fork (e.g., one defined by the user at .codebuddy/agents/fork.md), or otherwise rewrites it to a general-purpose regular sub-agent. Useful for host scenarios that need to avoid request amplification caused by recursive fork spawning
CODEBUDDY_DISABLE_BUILTIN_SUBAGENTS	Set to 1 to block only built-in sub-agents (general-purpose/fork/Explore/Plan/statusline-setup), without affecting custom agents, plugin agents, Teams, or other tools (including outbound A2A tools; see ProductFeature.A2AOutbound, which is entirely independent). When enabled, these built-in sub-agent sections are automatically hidden from the Agent tool description. If the model still passes one of these subagent_type values and the host/project has not defined a custom or plugin agent with the same name to override it, the runtime rejects the call and instructs the model to complete the remaining work with its own tools. Unset by default (built-in sub-agents remain available)
CODEBUDDY_A2A_OUTBOUND_ENABLED	Set to 1/true/yes/on to force-enable outbound A2A (A2AGetAgentCard/A2ASendMessage/A2AGetTask/A2ACancelTask) for local development or manual verification without waiting for cloud-side ProductFeature.A2AOutbound configuration. This is enable-only: explicitly setting 0/false is equivalent to leaving it unset and does not force-disable the feature—the cloud configuration remains the authoritative kill switch (operators can still remotely deliver false even if this variable remains in a host process). Evaluation order: if this variable enables the feature, it takes effect immediately and no AbTestService query is made; otherwise (including an empty value), falls back to ProductFeature.A2AOutbound (disabled by default)
CODEBUDDY_A2A_DISCOVERY_PREWAIT_MS	Bounded pre-wait budget in milliseconds for initial outbound A2A discovery (default 2000). When outbound A2A is enabled, the <available_A2A_agents> list in the A2AGetAgentCard tool description is rendered dynamically from discovery results (CODEBUDDY_REMOTE_AGENTS_URL). To make that list available to the first message, the first model request waits at most this long for discovery to complete (localhost discovery is usually much faster). A timeout or cancellation abandons the wait and continues; reactive refresh adds the list once discovery eventually completes—so this variable only affects whether the first turn sees the results, not correctness. Set to 0 to disable the wait (discovery still runs in the background, so the first turn may initially render an empty list). Discovery fetches are single-flight and the pre-wait never causes an extra network request
CODEBUDDY_A2A_WAIT_IDLE_TIMEOUT_MS	Timeout in milliseconds for inbound A2A SendMessage to wait for the session to become idle (default 600000, or 10 minutes). Before execution is submitted, an A2A request waits until the current session has no run in flight—in mixed mode (--a2a --input-format stream-json), that run is usually an ongoing human conversation turn, so the default is intentionally generous. This timeout is a failure safeguard rather than the normal path: with stdio transport, callers have no HTTP timeout to rely on, so an upper bound prevents a stuck session from hanging an A2A caller forever. On timeout, that SendMessage returns a failed Task. Only positive values are accepted; invalid values fall back to the default
CODEBUDDY_A2A_CONTEXT_TTL_MS	Validity period in milliseconds for outbound A2A conversation continuity (default 86400000, or 24 hours). A2ASendMessage remembers the last contextId for each discovery source + remote Agent and automatically includes it in later calls from the same session, keeping multi-turn conversations in the same remote context. This record is persisted with the session and remains available after --resume. A remote endpoint may reclaim expired contexts and, per the A2A specification, must reject an unknown contextId rather than silently creating one. Once this local TTL expires, CodeBuddy proactively drops the old ID and starts a new context, preventing every subsequent call from failing against an invalid ID. The timer is based on last use rather than creation, so continuously active conversations do not expire mid-session. Non-positive integers or unparsable values fall back to the default (fail open; a bad environment variable must not silently disable continuity)
CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS	Set to 1 / true to disable background tasks for the Agent, Bash, and PowerShell tools (run_in_background=true). When enabled, the run_in_background parameter is hidden from these tools' schemas so the model will not see it; even if historical/cached tool calls or direct callers pass this parameter, the runtime falls back to synchronous (Agent) / foreground (Bash, PowerShell) execution. Suitable for request-response SDK / one-shot task scenarios—where the main process exits immediately after the main turn ends and any background agent/background command results cannot flow back to the final response. Aligns with Claude Code's CLAUDE_CODE_DISABLE_BACKGROUND_TASKS (which also governs Agent + Bash + PowerShell). Unset by default (background tasks remain available). Independent from the print-mode guard (which always blocks background execution under -p). Also refuses Multitask: --agent multitask / --multitask exits non-zero; /multitask, session/set_config_option (configId=multitask), and the dialect-specific session/set_multitask fail; initialize.multitaskSupport is false; resume with standing key multitask does not restamp the coordinator (avoids locking the tool surface)
CODEBUDDY_A2A_DISCOVERY_TTL_MS	Cache validity period in milliseconds for outbound A2A Agent Card discovery results (default 43200000). Every A2A tool execution checks freshness; successful results are reused while valid, the first call after expiry refreshes on demand, and concurrent calls share a single fetch. A change to the discovery URL invalidates the cache immediately; a successful empty list is cached as well. Set to 0 to refresh on every sequential tool execution (concurrent calls are still single-flight); empty, negative, or non-finite values fall back to the default
CODEBUDDY_A2A_INPUT_REQUIRED_TIMEOUT_MS	Timeout in milliseconds for an inbound A2A Task to wait for a caller response after entering input-required (default 600000, or 10 minutes). When the timeout expires, the original execution is terminated and the Task is marked as failed, releasing the session reservation and event bus so a disconnected caller cannot occupy a standalone or mixed session forever. Only positive values are accepted; invalid values fall back to the default
CODEBUDDY_REHYDRATE_IMAGE_BLOB_REFS	Set to true to rehydrate image blob references to full base64 data in -p mode streaming output. Useful for downstream integrations that need direct access to image data
CODEBUDDY_SKILL_DESC_MAX_OVERRIDES	Override the per-entry character limit for Skill tool descriptions by skill name (default 150). Format: a JSON object mapping skill names to character limits, for example {"tencent-docs-routing":300,"tencent-pptx":300}. An override completely replaces that skill's default limit (it may raise or lower it) and is no longer subject to a second proportional truncation under the total Skill character budget. As a result, explicit overrides remain effective even when a built-in skill changes source from bundled to plugin after a marketplace update. The configuration applies equally to all sources, including built-ins. Skill names are JSON keys, so plugin skill names containing colons (such as plugin:skill) are supported naturally. Values must be positive integers (non-positive integers, decimals, and numeric strings are skipped), and dangerous keys such as __proto__/constructor/prototype are ignored. Invalid JSON or a non-object top level causes the entire value to be ignored with a warning. When unset, all skills use their default limits and behavior is unchanged

Sandbox full pass (high risk)

CODEBUDDY_IS_SANDBOX turns -y inside an isolated sandbox into a true full pass by skipping confirmations for HIGH/CRITICAL dangerous commands. It is intentionally an environment variable rather than a CLI argument: granting unrestricted permissions is high risk and must be explicitly declared by the launching process, following common sandbox design and preventing codebuddy -y from being mistaken for unconditional approval bypass.

export CODEBUDDY_IS_SANDBOX=1
codebuddy -y
# Or in one line
export CODEBUDDY_IS_SANDBOX=1 && cbc -y

⚠️ Risk notice

• Once enabled, the agent can execute dangerous commands without confirmation (such as deleting files or changing system state), potentially causing data loss, system damage, or credential and data exposure through prompt injection.
• Use only in trusted isolated sandboxes, containers, VMs, or environments without internet access. Do not enable it for everyday local development, on shared machines, or in environments with access to production credentials.
• It is read exclusively from the process environment and is not injected from the env field of settings.json (including project-level settings), preventing a repository from silently escalating privileges.
• Setting it alone, without -y / bypassPermissions, does not change the default permission mode.
• The visible mode remains bypassPermissions (the TUI label is unchanged, but shown in red); it is not renamed to fullAccess.
• permissions.disableBypassPermissionsMode: "disable" still applies: once bypass mode is disabled, this variable cannot enable full pass.
• Explicit deny rules still have the highest priority.

The -y / --dangerously-skip-permissions description in codebuddy -h also points to this variable.

Context and Memory

Environment Variable	Description
CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDE	Set the context capacity percentage for triggering auto-compaction (1-100). Default is determined by product configuration (typically 70-92%). Use a lower value (e.g., 50) to compact earlier
CODEBUDDY_PRE_MESSAGE_COMPACT	Force-control the pre-message compaction toggle. true/1 to enable, false/0 to disable. Takes priority over the product configuration's enablePreMessageCompact and the ContextSummaryAgent toggle
CODEBUDDY_PRE_MESSAGE_COMPACT_PCT	Set the context capacity percentage for pre-message compaction check (1-100). Default is 10%. When context exceeds this threshold, it is automatically compacted before processing the user's new message
CODEBUDDY_DISABLE_AUTO_MEMORY	Set to 1 to disable auto memory, set to 0 to enable
CODEBUDDY_MEMORY_ENABLED	Set to true or 1 to enable memory functionality
CODEBUDDY_TYPED_MEMORY_ENABLED	Set to true or 1 to enable typed memory mode
CODEBUDDY_TEAM_MEMORY_ENABLED	Set to true or 1 to enable team memory mode
CODEBUDDY_USER_ID	User ID for team memory mode

MCP (Model Context Protocol)

Environment Variable	Description
MCP_TIMEOUT	Timeout for MCP server connections (milliseconds)
MCP_TOOL_TIMEOUT	Timeout for MCP tool execution (milliseconds)
MAX_MCP_OUTPUT_TOKENS	Maximum tokens allowed in MCP tool responses (default: 20000)
CODEBUDDY_DISABLE_MCP_LARGE_OUTPUT_FILES	When set to 1, MCP oversized responses are not persisted to disk (skipping the ~/.codebuddy/projects/.../tool-results/ files), always falling back to content truncation

Performance and Output

Environment Variable	Description
CODEBUDDY_CODE_MAX_OUTPUT_TOKENS	Set the maximum output tokens for most requests
CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS	Override the default token limit for file reads (default: 20000)
CODEBUDDY_STREAM_TIMEOUT_MS	Maximum silent time allowed between two data chunks in a streaming response (milliseconds) (default: 1200000, or 20 minutes). Structurally decoupled from the first-token timeout and independently configurable; lower this value to detect dead connections sooner on gateways or proxy paths prone to half-open connections. The first-token timeout is unaffected
CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS	Maximum time to wait for the first model output (milliseconds) (default: 1200000, i.e., 20 minutes). Slow first-token emission due to long-context prefill is a legitimate scenario
CODEBUDDY_MAX_RETRIES	Maximum backoff retry count for model request failures that occur "before generation starts" (429 / 5xx / request timeout / lock timeout) (default: 8, max: 15, auto-clamped when exceeded). Retries use exponential backoff + jitter and respect the server's retry-after; they strictly occur before streaming content is produced and do not resend already-produced content. Quota-exhaustion errors are not retried (handled by model fallback instead)
CODEBUDDY_RETRY_WATCHDOG	Set to 1 / true / yes to enable infinite retry mode for unattended / CI scenarios. Only applies to the "before generation starts" failures above; single backoff is capped at 5 minutes. Off by default
CODEBUDDY_SESSION_MAX_ITEMS	Maximum number of history messages to replay during session/load (default: 1000). Stops reading the JSONL in reverse when the threshold is reached and a user message is encountered. Increase (e.g., 2000 or more) when very long sessions need to be supported (such as sandbox scenarios); zero/negative/non-numeric values fall back to the default

Filesystem and Configuration

Environment Variable	Description
CODEBUDDY_CONFIG_DIR	Custom location for CodeBuddy Code to store configuration and data files
CODEBUDDY_CODE_DEBUG_LOGS_DIR	Debug log directory
CODEBUDDY_SANDBOX_IMAGE	Container sandbox image (default: node:20-alpine)
USE_BUILTIN_RIPGREP	Set to 0 to use system-installed rg instead of the one bundled with CodeBuddy Code

Shell Configuration

Environment Variable	Description
CODEBUDDY_CODE_SHELL	Override automatic shell detection. Supported values: bash, zsh, sh, powershell
CODEBUDDY_CODE_SHELL_PREFIX	Command prefix wrapping all shell commands (e.g., for logging or auditing)
CODEBUDDY_CODE_GIT_BASH_PATH	Explicitly specify the Git Bash path on Windows; startup fails if the specified path is invalid
CODEBUDDY_SKIP_GIT_BASH_CHECK	Set to 1 to skip the Windows Git Bash detection and prompt at startup (useful when the upstream already manages the shell)
CODEBUDDY_DISABLE_CHILD_PROCESS_CONTAINMENT	Startup toggle for cleaning up descendant processes when CodeBuddy exits on Windows. 1 / true disables containment; unset / empty / 0 / false enables it. Read only at startup, so restart the CLI (including prewarmed processes) after changing it. macOS/Linux are unaffected
CODEBUDDY_INTERNAL_DAEMON_CHANNEL	One-time internal IPC marker used by the Windows daemon supervisor. It is consumed and removed at startup, is not a user configuration option, and is not passed to regular child processes
CODEBUDDY_POWERSHELL_PATH	Explicitly specify the PowerShell executable path (takes priority over auto-detection)
CODEBUDDY_USE_POWERSHELL_TOOL	Control PowerShell tool enablement. Enabled by default on Windows, set to 0 to disable
CODEBUDDY_ENV_FILE	Path to an environment file that is automatically sourced before executing each shell command
CODEBUDDY_DISABLE_SHELL_SNAPSHOT	Set to 1 to disable shell environment snapshots on all platforms (helpful when bash profile loading is slow)
CODEBUDDY_ENABLE_SHELL_SNAPSHOT	On Windows without Git Bash, snapshots are skipped by default; set to 1 to force enable (usually not needed)

UI and Interaction

Environment Variable	Description
CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE	Set to 1 to disable automatic terminal title updates
CODEBUDDY_INCLUDE_PROMPT_SUGGESTION	Explicitly enable prompt suggestions, overriding the headless default (off) and promptSuggestionEnabled=false configuration
CODEBUDDY_PROMPT_SUGGESTION_DISABLED	Set to 1 / true to disable prompt suggestions, takes priority over CODEBUDDY_INCLUDE_PROMPT_SUGGESTION
CODEBUDDY_ENABLE_ASK_USER_FOR_STRUCTURED_INPUT	Set to 1 / true to enable the AskUserForStructuredInput tool (disabled by default); takes effect only in ACP or stream-json mode when the client declares the elicitation.form capability
IS_DEMO	Set to true to enable demo mode: hides email and organization

Security and Authentication

Environment Variable	Description
CODEBUDDY_CODE_CLIENT_CERT	mTLS client certificate file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY	mTLS client private key file path ⚠️ Not yet supported
CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASE	Passphrase for the mTLS encrypted private key (optional) ⚠️ Not yet supported

Telemetry and Reporting

Environment Variable	Description
DISABLE_TELEMETRY	Set to 1 to disable telemetry
DISABLE_ERROR_REPORTING	Set to 1 to disable error reporting
DISABLE_AUTOUPDATER	Set to 1 to disable auto-updates
DISABLE_FEEDBACK_COMMAND	Set to 1 to disable the /feedback command

OpenTelemetry Custom Reporting (traces)

CodeBuddy Code supports reporting internal traces to your own Collector via the OTLP protocol. Environment variables follow the OpenTelemetry specification. For detailed usage, see Monitoring.

Environment Variable	Description
CODEBUDDY_CODE_ENABLE_TELEMETRY	Set to 1 to enable OTel custom reporting; the legacy alias CLAUDE_CODE_ENABLE_TELEMETRY is also accepted for backward compatibility
OTEL_TRACES_EXPORTER	otlp (default) / console (output to logs, useful for debugging) / none (off)
OTEL_EXPORTER_OTLP_ENDPOINT	Generic OTLP endpoint; the tool automatically appends /v1/traces
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	Traces-specific endpoint, used as a complete URL; takes priority over the generic variable
OTEL_EXPORTER_OTLP_HEADERS	OTLP request headers in the format k1=v1,k2=v2; values support URL encoding
OTEL_EXPORTER_OTLP_TRACES_HEADERS	Traces-specific request headers; takes priority over the generic variable
OTEL_EXPORTER_OTLP_PROTOCOL	Only http/protobuf (default) is supported; other values (such as grpc, http/json) fall back and emit a warning
OTEL_SERVICE_NAME	Override the default service.name
OTEL_RESOURCE_ATTRIBUTES	Resource attributes in the format k1=v1,k2=v2; merged into the trace resource

When DISABLE_TELEMETRY=1, OTel reporting is turned off regardless of the variables above.

Tasks and Background Work

Environment Variable	Description
CODEBUDDY_DISABLE_BACKGROUND_TASKS	Set to 1 to disable all background task functionality

Daemon Mode

Environment Variable	Description
CODEBUDDY_DAEMON_ALLOW_SLEEP	Set to 1 or true to disable the daemon's sleep prevention (allows the system to enter idle sleep normally). Auto-reconnect after wake is not affected
CODEBUDDY_DAEMON_AUTO_CONNECT_CHANNELS	Set to 0 or false to disable automatic channel connection (WeChat/WeCom) on daemon startup. Can also be configured via daemonAutoConnectChannels: false in settings.json. Individual instances can set autoConnect: false in instances.json
CODEBUDDY_DAEMON_RESTORE_CHANNELS	Set by the system during daemon auto-restart, containing the list of channels to restore (comma-separated, e.g., wechat:abc,wecom:default). Users typically do not need to set this manually

Agent Execution Control

Environment Variable	Description
CODEBUDDY_CODE_MAX_TURNS	Maximum execution turns for the main Agent. Priority: CLI --max-turns > this environment variable > default (500)
CODEBUDDY_CODE_SUBAGENT_MAX_TURNS	Maximum execution turns for sub-Agents. Priority: CLI --max-turns > this environment variable > model dynamically passed max_turns > default (500)
CODEBUDDY_CODE_MAX_SUBAGENTS_PER_SESSION	Per-session sub-agent spawn budget limit (positive integer, default 200, adjustable up or down, cannot be disabled). Nested spawns share the same budget; when the limit is exceeded, the Agent tool returns an error and suggests using its own tools to complete the remaining work; resets after /clear creates a new session
CODEBUDDY_CODE_DISABLE_AUTO_MEMORY	Set to a truthy value to disable agent-level persistent memory (the frontmatter memory field no longer injects memory paragraphs). Unset by default (enabled)
CODEBUDDY_SUBAGENT_PERMISSION_MODE	Default permission mode for sub-agents/team members (e.g., bypassPermissions, acceptEdits, default, plan). Priority: Agent tool mode parameter > CLI --subagent-permission-mode > this environment variable > Settings permissions.subagentPermissionMode > mapping table default
CODEBUDDY_TEAM_IDLE_DETECTION_DISABLED	Set to 1 to disable teammate idle awareness (enabled by default). When disabled, "wait for teammate idle"-type APIs return true immediately without blocking, and progress snapshots are no longer recorded
CODEBUDDY_TEAM_SHUTDOWN_GRACEFUL_TIMEOUT_MS	Fallback timeout (in milliseconds) for graceful team member shutdown, default 15000. After this duration without a response from the teammate, the process is forcibly terminated. Set to 0 to disable the forced fallback (pure wait for response)

Gateway and Remote Access

Environment Variable	Description
CODEBUDDY_GATEWAY_AUTH	Gateway authentication mode (password or none). Highest priority, overrides --auth and settings gateway.auth. --serve defaults to password; setting to none disables authentication, allowing any process on the same machine to execute commands and read/write files via this service. Only recommended in isolated environments or CI
CODEBUDDY_GATEWAY_BASE_PATH	Public URL path prefix for the Gateway Web UI (e.g. /cnb-5gg-1k09dqp5v-001). --base-path wins. Unset or / means site root. When set, the printed Web UI link, login redirect, Cookie Path, and in-page /api /assets requests all include this prefix
CODEBUDDY_GATEWAY_PASSWORD	Gateway access password. When unset, a random password is automatically generated on first startup and written to settings
CODEBUDDY_GATEWAY_FORCE_TUNNEL	Set to 1 to force tunnel mode
CODEBUDDY_DISABLE_REQUEST_VALIDATION	Set to 1 to disable Gateway custom request header validation (X-CodeBuddy-Request). See HTTP API Security
CODEBUDDY_CODE_CORS_ORIGINS	Additional CORS allowed origins (comma-separated). Supports exact origins, *.domain subdomain wildcards, and * for all. E.g., https://*.example.com,https://specific.com. When unset, if the service is bound to 0.0.0.0 (--host 0.0.0.0), all origins are automatically allowed
SERVER__HOST	Listen address for --serve mode (default: 127.0.0.1)
SERVER__PORT	Listen port for --serve mode; set to 0 for a kernel-assigned port — the variable is updated to the actual listening port once the server is bound

WeCom Integration

Environment Variable	Description
CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN	WeCom Customer Service Token
CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY	WeCom Customer Service Encryption Key
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID	WeCom Customer Service Corp ID
CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET	WeCom Customer Service Corp Secret
CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME	WeCom Customer Service Account Name
CODEBUDDY_GATEWAY_WECOM_TOKEN	WeCom Token
CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY	WeCom Encryption Key
CODEBUDDY_GATEWAY_WECOM_CORP_ID	WeCom Corp ID
CODEBUDDY_GATEWAY_WECOM_CORP_SECRET	WeCom Corp Secret
CODEBUDDY_GATEWAY_WECOM_AGENT_ID	WeCom Agent ID

Channel Auto-Connect

Environment Variable	Description
CODEBUDDY_CHANNEL_AUTO_CONNECT	Set to 1 or true to automatically connect all configured channels (WeCom + WeChat) on startup
CODEBUDDY_WECOM_AUTO_CONNECT	Set to 1 or true to automatically connect all configured WeCom bot instances on startup
CODEBUDDY_WECHAT_AUTO_CONNECT	Set to 1 or true to automatically connect all configured WeChat bot instances on startup
CODEBUDDY_WECOM_BOT_ID	WeCom AI Assistant Bot ID. When set, a default instance is automatically created and appears in the /remote-control list
CODEBUDDY_WECOM_BOT_SECRET	WeCom AI Assistant Secret. Must be used together with CODEBUDDY_WECOM_BOT_ID
CODEBUDDY_WECOM_STREAMING_DEFAULT	Global default streaming toggle for WeCom bots (1/0 or true/false); bots without an explicit setting inherit this value
CODEBUDDY_WECOM_CARDS_DEFAULT	Global default permission/suggestion card toggle for WeCom bots (1/0 or true/false); bots without an explicit setting inherit this value

Tip: CODEBUDDY_CHANNEL_AUTO_CONNECT is the master toggle, while CODEBUDDY_WECOM_AUTO_CONNECT and CODEBUDDY_WECHAT_AUTO_CONNECT are per-type toggles. Any one of the three being set will take effect. Works in all modes (interactive, --serve, daemon).

Debugging and Diagnostics

Environment Variable	Description
CODEBUDDY_DEBUG	Set to 1/true/yes/on to enable debug mode (equivalent to --debug)
CODEBUDDY_DEBUG_SDK	Set to 1/true/yes/on to enable SDK debugging
CODEBUDDY_DEBUG_REQUEST	Set to 1 to enable request debugging
CODEBUDDY_STARTUP_PROFILE	Set to 1 to save Markdown and JSON startup profiling reports automatically. See Startup Profiling
CODEBUDDY_CODE_HEAP_SNAPSHOT_NEAR_LIMIT_PCT	OOM forensics (off by default). When enabled, if the process heap crosses the V8 heap limit high-water mark, a heap snapshot is automatically written to ~/.codebuddy/diagnostics/<date>/oom-nearlimit-<pid>-<ts>.heapsnapshot (written only once per process). Values: on/true/1 for the default 85% threshold; 0.9 or 90 for a custom threshold; unset / 0 / off / false to disable. ⚠️ Snapshot files are ~1.5× the heapUsed at that time (multi-GB heaps produce multi-GB files); only enable when troubleshooting OOM. See Troubleshooting · OOM
CBC_HEAP_SNAPSHOT_ON_WORKFLOW_END	Set to 1 to write a heap snapshot after each workflow (e.g., ultracode) completes, saved to ~/.codebuddy/diagnostics/<date>/. Off by default (consumes disk); only enable when troubleshooting workflow memory leaks

E2E Testing (Record/Replay)

Record/replay functionality for model responses in E2E tests. In record mode, real model responses are captured; in replay mode, recorded files are used in place of real API calls.

Environment Variable	Description
CODEBUDDY_RECORD_DIR	Record mode: directory where recording files are saved. When set, model responses are saved to recording.jsonl in this directory
CODEBUDDY_REPLAY_DIR	Replay mode: directory from which recording files are read. When set, responses are replayed from recording.jsonl without requiring a real API
CODEBUDDY_REPLAY_SPEED	Replay speed multiplier. 0 means no delay (instant return), 1 means replay at original timing intervals (default: 1)
CODEBUDDY_REPLAY_STRICT	Set to 1 to enable strict mode: throws an error when recordings are exhausted instead of falling through to the real API

Note: CODEBUDDY_RECORD_DIR and CODEBUDDY_REPLAY_DIR are mutually exclusive and cannot be set at the same time.

Miscellaneous

Environment Variable	Description
SLASH_COMMAND_TOOL_CHAR_BUDGET	Maximum character count for slash command tool metadata (default: 15000)
CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS	Interval for refreshing credentials (milliseconds) (default: 300000)

Usage Examples

Basic Authentication Configuration

# Set API key
export CODEBUDDY_API_KEY="your-api-key"

# Set proxy server
export HTTP_PROXY="http://proxy.example.com:8080"
export HTTPS_PROXY="https://proxy.example.com:8080"

# Set proxy bypass list
export NO_PROXY="localhost,127.0.0.1,.internal.example.com"

# Set custom headers (multiple headers separated by \n)
export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1\nX-Another-Header: value2"

# Start CodeBuddy
codebuddy

Using Third-Party Model Services

# Use a custom API endpoint
export CODEBUDDY_API_KEY="your-api-key"
export CODEBUDDY_BASE_URL="https://api.example.com/v1"
codebuddy --model your-model-name

Connecting to DeepSeek Example

To connect to any third-party model service compatible with the Anthropic protocol (such as DeepSeek), you only need to configure the Base URL, API Key, and model variables — no additional models.json modifications are required:

# Endpoint and key
export CODEBUDDY_BASE_URL="https://api.deepseek.com"
export CODEBUDDY_API_KEY="<your-deepseek-api-key>"

# Default model for the main Agent
export CODEBUDDY_MODEL="deepseek-v4-pro"

# Large model used for complex reasoning
export CODEBUDDY_BIG_SLOW_MODEL="deepseek-v4-pro"

# Small model for background/lightweight tasks
export CODEBUDDY_SMALL_FAST_MODEL="deepseek-v4-flash"

# Ops-level blanket override for all sub-agents.
# When unset, per-invocation, per-sub-agent settings, and product built-in orchestration are used.
export CODEBUDDY_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

# Optionally specify the main model explicitly via --model at startup
codebuddy --model deepseek-v4-pro

Tip: The variables above can also be written into the env field of settings.json so they automatically apply to each session, making team-wide configuration easier.

China Edition Configuration

# Set China edition environment identifier
export CODEBUDDY_INTERNET_ENVIRONMENT=internal

# Set API key
export CODEBUDDY_API_KEY="your-api-key"

# Start CodeBuddy
codebuddy

Enabling Advanced Features

# Enable auto memory
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

# Enable extended thinking
export MAX_THINKING_TOKENS="10000"

# Run in non-interactive mode (-y may still prompt for HIGH/CRITICAL actions)
codebuddy -p -y "your query"

# Sandbox full pass (high risk: isolated containers / VMs without internet access only)
export CODEBUDDY_IS_SANDBOX=1
codebuddy -p -y "your query"

Debugging and Profiling

# Enable debug mode
export CODEBUDDY_DEBUG="1"

# Enable startup profiling
export CODEBUDDY_STARTUP_PROFILE="1"

# Start CodeBuddy
codebuddy

Configuring in settings.json

Environment variables can also be set in the env field of settings.json:

Exception: CODEBUDDY_IS_SANDBOX is not injected from here. It must be set in the launching process environment, for example, export CODEBUDDY_IS_SANDBOX=1 && codebuddy -y. See Sandbox full pass (high risk).

{
  "env": {
    "CODEBUDDY_API_KEY": "your-api-key",
    "HTTPS_PROXY": "https://proxy.example.com:8080",
    "MAX_THINKING_TOKENS": "10000",
    "CODEBUDDY_DISABLE_AUTO_MEMORY": "0"
  }
}

Tool Output Externalization Mechanism

When tool execution produces output exceeding the threshold, CodeBuddy Code automatically saves the full output to disk and sends only truncated content with a file path pointer to the model, which can read the full content on demand.

Data Flow

Shell output
  ├─→ OutputSpiller (full output streamed to disk)
  └─→ TruncateBuffer (head + tail retained in memory, ~30KB)
                          ↓
                  Truncation detected → generate placeholder (~2KB preview + file path)
                          ↓
                  Model receives placeholder, can read full file via Read tool on demand

Data Size at Each Stage (using 1.3MB output as example)

Stage	Content	Size
Disk file (OutputSpiller)	Full raw output	1,355,099 bytes
Memory buffer (TruncateBuffer)	head 6KB + tail 24KB	~30KB
Sent to model (placeholder)	File path + preview	~2KB

Storage Directory

Tool output files are stored in the project data directory:

~/.codebuddy/projects/{projectDir}/
  └── {sessionId}/
      ├── tool-results/                          ← Main session tool results
      │   ├── {callId}.txt
      │   └── ...
      └── subagents/                             ← Sub-agent data
          ├── agent-{agentId}.jsonl              ← Sub-agent conversation history
          └── agent-{agentId}/
              └── tool-results/                  ← Sub-agent tool results
                  ├── {callId}.txt
                  └── ...

Related Environment Variables

Environment Variable	Scope	Default
BASH_MAX_OUTPUT_LENGTH	Bash tool memory retention, triggers disk externalization when exceeded	30000
CODEBUDDY_TOOL_RESULT_THRESHOLD_KB	Session-level externalization threshold for non-bash tools (e.g., MCP)	50

See Also

• Settings - Configure environment variables and other settings in settings.json
• CLI Reference - Complete list of command-line arguments, including -y and CODEBUDDY_IS_SANDBOX
• Permission Modes - bypassPermissions and sandbox full pass
• MCP Setup - MCP server configuration
• Sub-Agents - Sub-agent storage directory documentation