# 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`](./settings.md#available-settings) to apply to every session.

> **Tip**: All 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.

## 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` |

## 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` | Small, fast model used for background tasks |
| `CODEBUDDY_BIG_SLOW_MODEL` | Large model used for complex reasoning tasks |
| `CODEBUDDY_CODE_SUBAGENT_MODEL` | Model used by sub-agents |
| `MAX_THINKING_TOKENS` | Enable extended thinking and set the token budget for the thinking process. Disabled by default |

## 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) |

## 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](#tool-output-externalization-mechanism) 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_IMAGE_GEN_ENABLED` | Set to `false` or `0` to disable image generation |
| `CODEBUDDY_IMAGE_EDIT_ENABLED` | Set to `false` or `0` to disable image editing |
| `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 |

## 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_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) |

## 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 between two data chunks in streaming responses (milliseconds) (default: 120000) |
| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | Maximum time to wait for the first model output (milliseconds) (default: 120000) |

## 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`, `cmd` |
| `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 |
| `CODEBUDDY_ENV_FILE` | Path to an environment file that is automatically sourced before executing each shell command |

## UI and Interaction

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates |
| `CODEBUDDY_PROMPT_SUGGESTION_DISABLED` | Set to `true` to disable prompt suggestions |
| `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 |

## Tasks and Background Work

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

## 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) |

## Gateway and Remote Access

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_GATEWAY_AUTH` | Gateway authentication mode (`password` or `none`) |
| `CODEBUDDY_GATEWAY_PASSWORD` | Gateway access password |
| `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | Set to `1` to force tunnel mode |
| `SERVER__HOST` | Listen address for `--serve` mode (default: `127.0.0.1`) |
| `SERVER__PORT` | Listen port for `--serve` mode |

## 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 |

## Debugging and Diagnostics

| Environment Variable | Description |
|---------|------|
| `CODEBUDDY_DEBUG` | Set to `1` to enable debug mode |
| `CODEBUDDY_DEBUG_REQUEST` | Set to `1` to enable request debugging |
| `CODEBUDDY_STARTUP_PROFILE` | Set to `1` to enable startup profiling |

## 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

```bash
# 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

```bash
# 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
```

### China Edition Configuration

```bash
# 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

```bash
# Enable auto memory
export CODEBUDDY_DISABLE_AUTO_MEMORY="0"

# Enable extended thinking
export MAX_THINKING_TOKENS="10000"

# Run in non-interactive mode
codebuddy -p -y "your query"
```

### Debugging and Profiling

```bash
# 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`:

```json
{
  "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](./settings.md) - Configure environment variables and other settings in `settings.json`
- [CLI Reference](./cli-reference.md) - Complete list of command-line arguments
- [MCP Setup](./mcp.md) - MCP server configuration
- [Sub-Agents](./sub-agents.md) - Sub-agent storage directory documentation
