E2B SDK Connection Parameters

This topic does not replace the official E2B SDK type definitions. Parameter names, default values, and units may differ across language SDKs. Your business code should follow the type definitions for the specific SDK version you use. This topic only covers the parameters and compatibility boundaries that matter when connecting to FC Agent Sandbox.

Basic configuration

When you use the E2B SDK or E2B CLI to connect to FC Agent Sandbox, you must at least configure the API key, API URL, and domain.

export E2B_API_KEY="<your-api-key>"
export E2B_API_URL="https://api.<region>.e2b.fc.aliyuncs.com"
export E2B_DOMAIN="<region>.e2b.fc.aliyuncs.com"

The <region> value must match the region where FC Agent Sandbox is deployed. Supported <region> values are cn-beijing, cn-shanghai, cn-hangzhou, cn-shenzhen, cn-hongkong, ap-southeast-1, us-east-1, and us-west-1. If the API URL, domain, template, and sandbox are not in the same region, common outcomes include creation failures, connection failures, or templates not being visible.

API keys must be created and managed in the Function Compute console. Do not manage FC Agent Sandbox API keys through the E2B SDK, and do not write API keys into source repositories, logs, screenshots, or frontend pages.

E2B CLI configuration

New E2B CLI versions authenticate with E2B_API_KEY. E2B_ACCESS_TOKEN is a deprecated legacy E2B authentication variable and should not be used in new integration flows.

If the SDK can access FC Agent Sandbox but CLI authentication fails, check the CLI version first, and then verify E2B_API_KEY, E2B_API_URL, and E2B_DOMAIN.

Python SDK common parameters

Python SDKs typically use snake_case parameter names:

• api_key: the FC Agent Sandbox API key, corresponding to E2B_API_KEY.

• api_url: the FC Agent Sandbox API URL, corresponding to E2B_API_URL.

• domain: the sandbox domain suffix, corresponding to E2B_DOMAIN.

• template: the template name or template ID used when creating a sandbox.

• timeout: the sandbox timeout. The unit and default value differ across Python SDK versions. Confirm the type definitions for the specific version you use.

• envs: environment variables injected when creating the sandbox.

• metadata: custom metadata written to the control plane for task IDs, business sources, or agent types.

Example:

import os
from e2b_code_interpreter import Sandbox

sandbox = Sandbox.create(
    template="code-interpreter-v1",
    api_key=os.environ["E2B_API_KEY"],
    api_url=os.environ["E2B_API_URL"],
    domain=os.environ["E2B_DOMAIN"],
    metadata={"task_id": "task-001"},
    envs={"TASK_ID": "task-001"},
)

try:
    result = sandbox.commands.run("python3 -c \"print('hello from sandbox')\"")
    print(result.stdout.strip())
finally:
    sandbox.kill()

TypeScript SDK common parameters

TypeScript SDKs typically use camelCase parameter names:

• apiKey: the FC Agent Sandbox API key, corresponding to E2B_API_KEY.

• apiUrl: the FC Agent Sandbox API URL, corresponding to E2B_API_URL.

• domain: the sandbox domain suffix, corresponding to E2B_DOMAIN.

• template: the template name or template ID used when creating a sandbox. In some call styles, the template is passed as the first argument to Sandbox.create().

• timeoutMs: the sandbox timeout, typically expressed in milliseconds.

• envs: environment variables injected when creating the sandbox.

• metadata: custom metadata written to the control plane.

Example:

import { Sandbox } from "@e2b/code-interpreter";

const sandbox = await Sandbox.create("code-interpreter-v1", {
  apiKey: process.env.E2B_API_KEY,
  apiUrl: process.env.E2B_API_URL,
  domain: process.env.E2B_DOMAIN,
  timeoutMs: 10 * 60 * 1000,
  metadata: { task_id: "task-001" },
  envs: { TASK_ID: "task-001" },
});

try {
  const result = await sandbox.commands.run("python3 -c \"print('hello from sandbox')\"");
  console.log(result.stdout.trim());
} finally {
  await sandbox.kill();
}

Parameter usage recommendations

• Prefer environment variables for apiKey / api_key, apiUrl / api_url, and domain instead of hard-coding regions or credentials in source code.

• metadata is useful for control-plane search, auditing, and correlation. It does not automatically become available inside sandbox processes.

• envs is useful for runtime process input, but it is not a durable storage layer for business state.

• Set timeouts according to actual task duration. Values that are too short can interrupt the task, while values that are too long increase both resource retention and cost risk.

• Call sandbox.kill() when the task finishes. Allowlisted accounts can use pause and resume when they need to preserve the execution scene. Do not treat pause as the default release path.

• When migrating an existing E2B application, replace the API key, API URL, and domain first. Only after the minimal flow for sandbox creation, command execution, file I/O, and cleanup works should you add templates, Code Interpreter, metadata, and environment variables.

Capabilities that should not be treated as connection parameters

The following capabilities should not be treated as part of the default FC Agent Sandbox SDK connection path:

• FC Agent Sandbox API key and access token management: handled through the Function Compute console, not through the E2B SDK.

• Snapshots, Volume, and Team management: not currently part of the FC Agent Sandbox E2B compatibility path.

• Metrics, Logs, and Network Config Update: currently limited capabilities and not suitable as production monitoring, log collection, or network change control plane dependencies.

For the full capability boundary, see E2B SDK-compatible API List and Getting Started / E2B Compatibility.