This document defines the FC Agent Sandbox compatibility scope for the E2B SDK and E2B CLI. Other getting started documents keep only the minimum integration steps. API boundaries are maintained here.
For connection parameter configuration, see Usage Constraints.
Compatibility overview
| Capability | Status | Notes |
| Sandbox | Compatible (pause and resume requires allowlist access) | Supports create, connect, inspect, timeout updates, pause, kill, upload and download URLs, and port access URLs. |
| Commands | Compatible | Supports command execution, process management, standard input, and PTY. |
| Filesystem | Partially compatible | Supports file read and write, directory management, rename, delete, existence checks, and directory watching. FC Agent Sandbox does not currently support custom file metadata. |
| Code Interpreter | Compatible | Supports code execution, context management, execution outputs, streaming output, and state persistence across runs. Charts are retrieved as files through Filesystem. |
| Template | Compatible | Supports template management, template builds, tags, and aliases. |
| CLI | Partially compatible | Supports the commonly used sandbox and template commands. |
| Metrics | Compatible | Supports viewing CPU and memory metrics. Disk and page-cache fields return placeholder values and are not currently usable. |
| Logs / Network Config Update | Limited | The APIs are callable, but returned results or actual effects are limited. |
| Snapshots / Volume / Team / Access Token | Not currently compatible | These capabilities are not recommended as part of the FC Agent Sandbox integration path. |
Compatible APIs
Sandbox
Pause and resume is currently available only to allowlisted accounts. Complete allowlist enablement before calling sandbox.pause() or connecting to a paused Sandbox.
The following sandbox lifecycle and access capabilities are supported:
Sandbox.create()Sandbox.connect(sandboxId)Sandbox.list()Sandbox.getInfo(sandboxId)Sandbox.kill(sandboxId)Sandbox.setTimeout(sandboxId, ms)sandbox.getInfo()sandbox.isRunning()sandbox.setTimeout(ms)sandbox.pause()sandbox.kill()sandbox.downloadUrl(path)sandbox.uploadUrl(path)sandbox.getHost(port)
Sandbox.connect(sandboxId) can attach to an existing sandbox. If the target sandbox is paused, it is automatically resumed when you connect.
Commands
The following command execution and process management capabilities are supported:
sandbox.commands.run()sandbox.commands.list()sandbox.commands.connect()sandbox.commands.sendStdin()sandbox.commands.kill()
Use the independent sandbox.pty API for interactive terminals and tasks that depend on TTY.
Filesystem
The following filesystem capabilities are supported:
sandbox.files.list()sandbox.files.exists()sandbox.files.getInfo()/sandbox.files.get_info()sandbox.files.read()sandbox.files.write()sandbox.files.makeDir()sandbox.files.remove()sandbox.files.rename()sandbox.files.watchDir()/sandbox.files.watch_dir()
sandbox.files.write() supports text, binary, and streaming content. Directory watching is useful for waiting for agent output files or syncing task artifacts.
FC Agent Sandbox does not currently support attaching custom file metadata through the metadata parameter. For example, the files.write() signature in Python SDK e2b==2.31.0 accepts metadata, but the SDK detects envd 0.5.2 in the sandbox and raises TemplateException: File metadata requires envd 0.6.2 or later. before sending the write request. Regular file reads and writes are unaffected. Do not confuse sandbox control-plane metadata, which remains available for labeling and querying sandboxes, with custom file metadata.
Code Interpreter
The core Code Interpreter capabilities are supported:
sandbox.runCode()/sandbox.run_code()sandbox.createCodeContext()/sandbox.create_code_context()sandbox.listCodeContexts()/sandbox.list_code_contexts()sandbox.restartCodeContext()/sandbox.restart_code_context()sandbox.removeCodeContext()/sandbox.remove_code_context()Execution outputs, including stdout, stderr, execution count, bare expression results, and rich results in
execution.results.stdout, stderr, and result callbacks.
Variable and context state persistence across multiple code executions.
Execution of Python, JavaScript, TypeScript, and Bash through the
languageparameter. Java and R are not supported.
For charts and visualizations, FC Agent Sandbox currently supports the file-based fallback path only: generate image files inside the sandbox and retrieve them through Filesystem or download URLs.
Template
The following template capabilities are supported:
Template CRUD.
Template build.
Template tags.
Template alias.
FC Agent Sandbox currently supports building templates from images. For details, see Build Custom Image Templates.
CLI
FC Agent Sandbox is compatible with the commonly used E2B CLI sandbox commands and extends part of the template management workflow:
| Command | FC Agent Sandbox status | Notes |
sandbox create <template> | Supported | Creates a sandbox and connects to an interactive terminal. The sandbox is automatically terminated after you exit the terminal. |
sandbox list | Supported | Returns running sandboxes by default. Supports --state, --metadata, --limit, and --format. |
sandbox kill | Supported | Supports killing by ID and bulk killing with --all. |
sandbox connect | Supported | Connects to an existing sandbox and opens an interactive terminal. Exiting the terminal does not terminate the sandbox. |
sandbox exec | Supported | Executes a command inside a running sandbox and returns the output to the local terminal. |
sandbox metrics | Supported | Shows CPU and memory metrics for a running sandbox. Metrics currently return at 1-minute granularity. |
template list | FC Agent Sandbox extension | The official E2B CLI documentation does not keep a dedicated page for this command. Use local CLI help as the source of truth. |
New E2B CLI versions authenticate with E2B_API_KEY. For configuration details, see Use FC Agent Sandbox with the CLI.
Metrics
FC Agent Sandbox supports sandbox metrics:
e2b sandbox metrics <sandbox-id>Currently supports CPU and memory metrics. Disk and page-cache fields return placeholder values and should not be used for capacity decisions. Metrics currently return at 1-minute granularity. They are suitable for debugging, resource trend observation, and task troubleshooting. Use the Function Compute console, CloudMonitor, or Simple Log Service as the source of truth for billing, alerting, and capacity governance.
Limited capabilities
Sandbox Logs currently return empty arrays.
Network Config Update currently returns success without applying an actual network change.
These interfaces can preserve SDK invocation compatibility, but they are not suitable as production dependencies for log collection or network change control planes.
Capabilities not currently supported
The following capabilities are not part of the primary E2B-compatible integration path for FC Agent Sandbox:
Snapshots.
Volume API.
Team management.
API key and access token management.
Custom file metadata.
If you need persistent storage or cloud data access, use Alibaba Cloud storage services such as NAS or OSS first. Create and manage API keys in the Function Compute console, not through the E2B SDK. For details, see Create an API Key.
Capabilities such as VPC access, OSS integration, log collection, and monitoring alerts belong to FC Extensions and are not native E2B SDK-compatible interfaces. For details, see FC Extensions Overview.
Migration recommendations
If you already have an E2B-based application, keep the SDK call pattern unchanged first and only replace the API key, API URL, and domain.
Start with
code-interpreter-v1and a minimal sandbox example to verify sandbox creation, command execution, file I/O, and cleanup.If your application depends on high-frequency metrics, logs, Network Config Update, snapshots, volume, or custom file metadata, adjust the design before migration instead of assuming the original E2B path will work unchanged.
In production code, always call
sandbox.kill()explicitly to avoid leaving sandboxes running longer than intended.