Configuration Reference

Note: The abx commands shown on this page are provided by the Node.js CLI in the cli repository (npm install -g @agent-sandbox/cli). CLI-specific documentation (CLI design, tutorial, reference) lives there too; this repository documents the Python SDK (agent-sandbox) and the container-side runtime (agent-sandbox-server).

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. Code parameters (sandbox_api_key=, sandbox_base_url=, provider=, ...)   ← Highest
2. Process environment variables
3. ./.env                  (project file)
4. ~/.abx/.env             (user file)
5. ~/.abx/config.toml
6. Provider / built-in defaults                                           ← Lowest

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

Both .env files are separate layers, so ./.env beats ~/.abx/.env per 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 the layers above 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, and the GitHub token is GITHUB_TOKEN. Template build (ACR_*, team_id) and template generation (ABX_LLM_*) settings belong to the abx CLI and are listed in its configuration reference; the Python SDK does not read them.

The same chain is what these calls read:

• Sandbox.create and the other SDK clients (load_config)
• 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.

Provider scoping

The generic keys sandbox_api_key, sandbox_base_url and sandbox_domain belong to the built-in provider alicloud-express. A provider plugin receives them only when its manifest lists them under [core] inherit and you consented to that when you installed it. Without this rule, switching ABX_PROVIDER would silently send your Alibaba Cloud key to a third-party process. LLM, GitHub and MCP keys are never delivered to a provider. Plugin-specific credentials are provider-scoped keys (ABX_<PROVIDER>_API_KEY, or [providers.<id>] in config.toml).

Resolving for provider P never reads ABX_<Q>_* or [providers.Q] for another provider Q.

Environment Variables

Each row is the only environment variable for that key. abx config set writes that same name.

Sandbox connection and tuning

Alibaba Cloud Express Edition (alicloud-express)

GitHub, templates, MCP

Keys marked "environment only" are read from the same layers but cannot be written with abx config set.

The SDK field for the sandbox key is sandbox_api_key. The SDK field for the base URL is sandbox_base_url. The SDK field for the data-plane host is sandbox_domain.

One name per key

A key is read from its one environment variable and stored under that same name. abx config set sandbox_api_key writes ABX_SANDBOX_API_KEY to ~/.abx/.env. abx config set sandbox_base_url writes sandbox_base_url in [transport]. abx config set github_token writes GITHUB_TOKEN. abx config set region writes region for the built-in provider; the environment variable for that key is ALIBABA_CLOUD_REGION_ID.

Server-Side Environment Variables

The following environment variables are used for in-sandbox Server configuration:

Build, deploy and template-generation keys

The ACR_*, team_id and ABX_LLM_* keys are declared by the abx CLI, which is the only component that builds or generates templates. The Python SDK is a runtime client and neither declares nor reads them.

config.toml Configuration

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

[core]
provider = "alicloud-express"   # default provider (abx provider default NAME)

[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"

[providers.my-cloud]            # a plugin's own scoped keys
endpoint = "https://sandbox.my-cloud.example"   # key declared by that plugin

[shortcuts]
init = "template init"          # command path, not "abx template init"
ps   = "sandbox process list"

Lookup order for a key inside config.toml: [providers.<id>].<key>, then [transport].<key>. The key name in the file is the config key in the tables above.

[shortcuts] (top-level command aliases) is read only by the abx CLI and ignored by the SDK. Its rules (the value has no abx prefix, a bad line is skipped at startup) are in the CLI reference.

TransportConfig Fields

The constructor and load_config(...) take these field names.

Automatic Region Derivation

When the base URL is not set by an argument or a process environment variable, but a region is, the built-in provider derives:

sandbox_base_url = "https://api.{region}.e2b.fc.aliyuncs.com"
sandbox_domain   = "{region}.e2b.fc.aliyuncs.com"

Values read from .env files or config.toml count as defaults, so a base URL stored there is kept and the other value is still derived from the region. This is the historical behaviour and is unchanged. Providers other than alicloud-express have no region derivation unless their manifest declares one.

Inspecting the result

from agent_sandbox.transport.config import explain_config

explain_config()   # {"sandbox_api_key": {"value": "****3dc1", "source": "environ", "name": "ABX_SANDBOX_API_KEY", "secret": True}, ...}

explain_config() tells you which layer (override, environ, dotenv, toml, derived, default) and which variable decided each key; secrets are masked. The name is the one environment variable for that key.

SDK Parameter Override

Pass parameters directly in code (highest priority):

from agent_sandbox.api.sandbox import Sandbox

sandbox = await Sandbox.create(
    sandbox_api_key="REPLACE_ME",
    sandbox_base_url="https://api.cn-beijing.e2b.fc.aliyuncs.com",
    access_key_id="REPLACE_ME",
    access_key_secret="REPLACE_ME",
)

# Pick another provider for this call; options are provider-scoped
sandbox = await Sandbox.create(provider="my-cloud", provider_options={"endpoint": "https://sandbox.my-cloud.example"})

See Providers.

.env File

The SDK reads both .env files. Each is its own layer, so they merge 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
ABX_PROVIDER=alicloud-express

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. Access keys are stored as ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET.

Configuration File Locations Summary

Related: the abx CLI

Reading and writing this configuration from the command line is a CLI feature: abx config list|get|set|init, the keys accepted by abx config get|set, and the ABX_ACTIVITY_LINES display variable. They are documented in the CLI repository: CLI Configuration; provider-aware keys are in its Providers and credentials CLI spec.