Configuration Reference

This document lists all Agent Sandbox configuration options, environment variables, default values, and priority rules.

Configuration Priority

Configuration is loaded in the following priority order (highest to lowest):

1. Explicit options / arguments (CLI options such as --region; SDK keyword arguments)   ← Highest
2. Process environment variables
3. .env files (./.env, then ~/.abx/.env)
4. ~/.abx/config.toml
5. Built-in defaults                                  ← Lowest

Each key has exactly one environment variable. The first layer that sets that variable wins.

.env files are merged per key. ./.env overrides ~/.abx/.env when both set the same key. A key that the project file does not set still comes from ~/.abx/.env.

A blank or whitespace-only value does not count. It does not hide the next layer.

Credential resolution

Every credential uses that order at the moment it is needed. abx config list shows the winner and labels it (env), (user), (default), or (not set).

Each key has one name. Product settings use ABX_<KEY>. A vendor that already publishes a variable keeps that variable: Alibaba Cloud access keys are ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET, the region is ALIBABA_CLOUD_REGION_ID, ACR settings are ACR_NAMESPACE and the matching ACR_* variables, and the GitHub token is GITHUB_TOKEN. team_id is optional and is not required; its environment variable is ABX_ALICLOUD_EXPRESS_TEAM_ID.

The same chain is what these calls read:

• natural-language abx create (the coding agent)
• abx template install / abx template search (GitHub token)
• abx mcp install (the sandbox API key copied into the editor config)

abx mcp install writes ABX_SANDBOX_API_KEY into the Cursor and Claude config. ABX_SANDBOX_BASE_URL and ALIBABA_CLOUD_REGION_ID are copied into the same file only when the process environment sets them. abx mcp start loads ~/.abx again, so a region saved with abx config set region still applies when the editor starts the server.

abx config list marks a process variable as (env) and either file as (user). The value in the table is the one the command will use.

Environment Variables

Shared with the Python SDK

CLI only: template build and generation

The Python SDK is a runtime client and does not declare these keys; the CLI declares them in src/utils/cli_config_keys.ts.

Each row is the only environment variable for that key. The full chain is in Credential resolution.

CLI display

These variables change what a terminal shows. They are not stored by abx config.

--json, --quiet, --ci, TERM=dumb, and a non-TTY do not draw that header. See While a command is running.

config.toml Configuration

Config file path: ~/.abx/config.toml

[core]
provider = "alicloud-express"

[transport]
sandbox_base_url = "https://api.cn-hangzhou.e2b.fc.aliyuncs.com"
sandbox_domain = "cn-hangzhou.e2b.fc.aliyuncs.com"
http_timeout = 30.0
max_retries = 3

[providers.alicloud-express]
region = "cn-hangzhou"

The top-level shortcuts are fixed in the CLI and have no configuration section.

CLI Configuration Commands

Manage configuration via abx config:

# View all configuration (with source annotations)
abx config list

# Get a single value
abx config get sandbox_api_key

# Set a value
abx config set sandbox_api_key your-new-key
abx config set region cn-beijing
abx config set http_timeout 60

# GitHub token for template downloads (VALUE omitted → masked asterisk prompt)
abx config set github_token
abx config set github_token ghp_xxxxxxxxxxxx

# Clear a single stored value (returns to default / not set)
abx config set region ""
abx config set github_token ""

The region key set here is the persistent default for regional commands. A single invocation can override it with the command-level --region/-r option (accepted by abx list, abx kill --all, the template control-plane commands, and abx mcp deploy). Resolution priority: command --region > ALIBABA_CLOUD_REGION_ID > abx config set region > cn-hangzhou.

Keys Configurable via abx config

Guided Configuration (abx config init)

abx config init

The interactive wizard prompts for: the sandbox API key, the default region, the LLM API key, the ACR namespace (ACR_NAMESPACE), the AccessKey ID, and the AccessKey secret. Press Enter to skip a prompt. Secrets and the namespace are stored in ~/.abx/.env under the one variable for each key; the region goes to ~/.abx/config.toml. Non-TTY environments or --yes never block; the equivalent abx config set commands are printed instead.

AK/SK Authentication Configuration (Experimental)

When access_key_id and access_key_secret are set via abx config set, they are stored in ~/.abx/.env as ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET. Used for AK/SK → API Key token exchange authentication.

Note: This feature is experimental. The token exchange endpoint is pending FC platform confirmation. See Authentication for details.

.env File

The CLI reads both .env files and merges them per key:

1. .env in the current directory (wins when it sets the key)
2. ~/.abx/.env (used for any key the project file does not set)

.env file format. Use the one variable for each key:

ABX_SANDBOX_API_KEY=your-api-key
ALIBABA_CLOUD_REGION_ID=cn-beijing

The abx config set sandbox_api_key <KEY> command saves the API Key to ~/.abx/.env as ABX_SANDBOX_API_KEY (file permissions 600). github_token is stored as GITHUB_TOKEN.

Configuration File Locations Summary

Related SDK documentation

The TransportConfig field table (types, defaults, automatic region derivation), SDK parameter overrides, the in-sandbox server variables (ABX_SERVER_*, ABX_PTY_PORT, ABX_MAX_UPLOAD_SIZE) and the deploy-related LLM variables are documented in the SDK's Configuration Reference in the python-sdk repository.