Skip to content

authentication.md

Latest commit

 

History

History
169 lines (105 loc) · 8.5 KB

authentication.md

File metadata and controls

169 lines (105 loc) · 8.5 KB
Raw

Authentication

This guide describes asynchronous ProviderSandbox provider extensions. Root Sandbox and AsyncSandbox follow the pinned standard migration contract; see Migrate from E2B.

For current SDK installation, use the installation guide.

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

Sandbox runtime requests require an API Key. AK/SK (Alibaba Cloud AccessKey) can explicitly prepare that key for Express, and authenticates native control-plane operations; see permissions.

Credentials belong to a provider. The built-in provider is Alibaba Cloud Express Edition (阿里云极速版), id alicloud-express, and it is the default. The sandbox key is ABX_SANDBOX_API_KEY. Alibaba Cloud access keys use the official names ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET. The region is ALIBABA_CLOUD_REGION_ID. Each key has one name.

Authentication Overview

Agent Sandbox provides three authentication paths for different scenarios:

  • API Key mode: The most common approach. Accesses the platform API via the Authorization: Bearer {api_key} header. Suitable for personal development, CI/CD, SDK calls, and most other scenarios.
  • AK/SK control plane: Used by official template/image/ACR operations. Preparation requires explicit consent; see permissions.
  • envd internal authentication: After sandbox creation, the SDK communicates with the in-sandbox envd service using envdAccessToken (obtained from the creation response). This is an internal mechanism managed automatically by the SDK — no manual handling required.

API Key Authentication

API Key is the most common authentication method, sent to the platform API via the Authorization: Bearer {api_key} header.

Configuration Methods

1. Environment variable (wins over ~/.abx)

export ABX_SANDBOX_API_KEY="your-api-key"

Set ABX_SANDBOX_API_KEY. That is the only environment variable for the sandbox API key.

2. Persisted file (~/.abx/.env)

The SDK also reads ~/.abx/.env, which the abx CLI writes (abx config set sandbox_api_key ..., file mode 600; see the CLI Authentication guide). The key is stored as ABX_SANDBOX_API_KEY. Access keys are stored as ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET.

3. .env file

Create a .env file in the project root directory:

ABX_SANDBOX_API_KEY=your-api-key

The SDK reads both .env files as separate layers. ./.env wins for a key it sets. A key it omits still comes from ~/.abx/.env.

  1. .env in the current directory
  2. ~/.abx/.env

4. config.toml file

Prefer ~/.abx/.env (mode 600) for the sandbox API key. abx config set sandbox_api_key writes ABX_SANDBOX_API_KEY there. Non-secret connection settings belong in ~/.abx/config.toml:

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

5. Code parameter (wins over the environment and over ~/.abx)

from agent_sandbox import ProviderSandbox as Sandbox

# Pass directly when creating
sandbox = await Sandbox.create(sandbox_api_key="your-api-key")

# Pass directly when connecting
sandbox = await Sandbox.connect("sbx-xxxx", sandbox_api_key="your-api-key")

AK/SK managed authentication

Express AK/SK-only clients use a key prepared by the shared provider engine. Explicitly call prepare_api_key(confirm=True) or prepare_api_key_sync(confirm=True) before first use or renewal. SDK calls never prompt or silently create credentials. Permissions, policy and examples.

Configuration Priority Chain

Credentials are resolved in the following priority order (highest to lowest):

flowchart TD
    A["1. Code parameters (sandbox_api_key= / access_key_id=)"] --> B["2. Process environment"]
    B --> C["3. ./.env (per key; missing keys fall through)"]
    C --> D["4. ~/.abx (.env, then config.toml)"]
    D --> E["5. Built-in default, or InvalidAPIKeyError E1001 when a sandbox key is required"]
Loading

The GitHub token and the region use this same chain. A blank or whitespace-only value is skipped. Each key has one environment variable. The names and defaults are listed in Credential resolution.

Credentials and providers

The generic sandbox key (sandbox_api_key, environment variable ABX_SANDBOX_API_KEY) and the Alibaba Cloud AK/SK belong to the built-in provider. If you switch to a provider plugin, the plugin does not receive them unless its manifest asks for them and you consented at install time. A plugin has its own scoped credential keys, for example ABX_MY_CLOUD_API_KEY for a provider my-cloud. This prevents a key for one cloud from being sent to another.

Every plugin option follows one rule: the canonical name is ABX_<PROVIDER_ID>_<FIELD> (dashes become underscores), and a manifest may add the vendor's own variable as an alias with env = [...]. Secret fields (secret = true) live only in the environment or .env files (mode 0600) and are refused on the command line; other fields can also live under [providers.<id>] in config.toml. OpenSandbox uses ABX_OPENSANDBOX_API_KEY and ABX_OPENSANDBOX_BASE_URL; OPEN_SANDBOX_API_KEY and OPEN_SANDBOX_DOMAIN are its declared native aliases, and the canonical name wins when both are set. A plugin that declares [core] inherit = ["sandbox_api_key"] receives the generic key only after you consent at install time, and abx provider info <id> shows that list under "Inherits".

AK/SK-managed preparation requires explicit consent. When both are configured, runtime calls use the API key:

  • If both sandbox_api_key and access_key_id are provided, API Key is used
  • If both ABX_SANDBOX_API_KEY and ALICLOUD_ACCESS_KEY_ID are set, ABX_SANDBOX_API_KEY is used

Credential storage

abx config set sandbox_api_key saves the key as ABX_SANDBOX_API_KEY in ~/.abx/.env with owner-only permissions. The SDK reads that file; environment variables and the project's .env can override it as described above. Non-secret defaults are stored in ~/.abx/config.toml. Keep credential files out of version control. For CI, supply credentials through the job's secret environment.

envd Authentication (In-Sandbox Communication)

After sandbox creation, communication with the in-sandbox envd service uses envdAccessToken (obtained from the creation response). This is an internal mechanism managed automatically by the SDK — no manual handling required.

envd authentication requires the following HTTP headers (set automatically by the SDK):

Header Value
X-Access-Token envdAccessToken
E2b-Sandbox-Id Sandbox ID
E2b-Sandbox-Port 49983
Authorization Basic dXNlcjo= (base64 of "user:")

Common Issues

InvalidAPIKeyError (E1001)

[E1001] API key cannot be empty
  Suggestion: Check your ABX_SANDBOX_API_KEY environment variable or pass sandbox_api_key.

Solution: Ensure a valid API Key is configured via any of the methods above.

InvalidCredentialsError (E1003)

[E1003] AccessKey ID and Secret cannot be empty
  Suggestion: Check ALICLOUD_ACCESS_KEY_ID and ALICLOUD_ACCESS_KEY_SECRET environment variables.

Solution: Ensure both AK ID and AK Secret are set.

TokenExpiredError (E1002)

[E1002] envdAccessToken not available. Sandbox may not be created or connected.

Solution: Check that the system clock is accurate. Reconnect to obtain a valid envd token, or inspect an explicitly configured custom exchange. API keys are not automatically minted or refreshed.

Related: the abx CLI

Setting credentials from the command line (abx config set / list / get, abx create --env) is documented in the CLI repository: CLI Authentication.