本文說明雲沙箱資料面圍繞 E2B SDK / CLI 相容的主要能力邊界。這裡的“API”指 E2B SDK 對象方法和 E2B CLI 命令，不是雲沙箱原生控制面 OpenAPI。雲沙箱未提供獨立的資料面 SDK；Team、API Key、Quota 等資源管理能力可通過原生 OpenAPI、阿里雲 SDK 或阿里雲 CLI 調用，詳情參見阿里雲 SDK & API 說明。
閱讀本文時需要注意三點：
方法名和參數形態以當前使用的 E2B SDK 版本為準。Python 和 TypeScript 的命名風格可能不同。
標記為“相容”的能力，仍需要結合帳號配額、地區、模板狀態和 SDK 版本驗證。
標記為“受限”或“暫不相容”的能力，不應作為生產接入主路徑。
Sandbox
Sandbox 是雲沙箱的核心對象。當前主路徑是通過 E2B SDK 建立、串連、查詢、暫停、恢複、設定逾時和終止 Sandbox。
相容能力：
建立 Sandbox：
Sandbox.create()。串連已有 Sandbox：
Sandbox.connect(sandboxId)。查詢 Sandbox 列表：
Sandbox.list()。查詢 Sandbox 資訊：
Sandbox.getInfo(sandboxId)、sandbox.getInfo()。判斷運行狀態：
sandbox.isRunning()。設定逾時時間：
Sandbox.setTimeout(sandboxId, ms)、sandbox.setTimeout(ms)。暫停 Sandbox（需先開通白名單）：
sandbox.pause()。終止 Sandbox：
Sandbox.kill(sandboxId)、sandbox.kill()。擷取檔案上傳 / 下載地址：
sandbox.uploadUrl(path)、sandbox.downloadUrl(path)。擷取連接埠訪問地址：
sandbox.getHost(port)。建立快照：
sandbox.createSnapshot(name)。
使用建議：
業務代碼應在
try/finally中釋放 Sandbox，避免任務異常時資源持續佔用。Sandbox.connect(sandboxId)適合恢複或接管已有 Sandbox。目標 Sandbox 已終止、逾時回收或不屬於當前帳號 / 地區時，串連會失敗。連接埠訪問能力適合預覽臨時 Web 服務，不應直接替代正式 API Gateway、鑒權和流量治理。
Commands
Commands 用於在 Sandbox 內執行命令、管理後台進程和處理輸入輸出。
相容能力：
執行命令：
sandbox.commands.run()。查詢命令 / 進程列表：
sandbox.commands.list()。串連後台命令：
sandbox.commands.connect()。向命令發送標準輸入：
sandbox.commands.sendStdin()。終止命令：
sandbox.commands.kill()。互動式終端：使用獨立的
sandbox.ptyAPI。
使用建議：
普通批處理命令優先使用
commands.run()；只有互動式 CLI、彩色輸出、進度條或依賴 TTY 判斷的命令才使用sandbox.pty。長任務建議設定命令級逾時，並處理 stdout / stderr，避免業務側只等待最終結果。
不要把未經校正的使用者輸入直接拼接進 shell 命令。
Filesystem
Filesystem 用於在 Sandbox 生命週期內讀寫檔案和管理目錄。
相容能力：
列出目錄：
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()。
使用建議：
雲沙箱當前不支援檔案自訂中繼資料。即使 SDK 的
files.write()方法簽名接受metadata，調用仍可能因 Sandbox 的envd版本低於0.6.2而在請求發送前失敗。普通檔案讀寫不受影響。目錄監聽可用於等待檔案產生或同步任務產物。只等待單個檔案時，也可以使用
exists()做有限次數輪詢。Sandbox 本地檔案系統適合任務臨時檔案，不應作為長期持久化儲存。
跨 Sandbox 保留、共用或長期儲存的資料，應寫入 NAS、OSS 等外部儲存。
處理使用者上傳路徑時，應限制可寫目錄和檔案大小，避免路徑穿越和資源耗盡。
Code Interpreter
Code Interpreter 用於執行程式碼片段，並在多次執行之間保持上下文。
相容能力：
執行代碼：
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()。擷取執行輸出，包括 stdout、stderr、execution count、運算式結果和
execution.results富結果。stdout、stderr 和結果回調。
通過
language參數執行 Python、JavaScript、TypeScript 和 Bash。不支援 Java 和 R。在同一 Context 內保持變數和執行狀態。
使用建議：
資料分析、代碼解譯器和 Notebook 風格任務適合使用 Code Interpreter。
如果任務更接近固定指令碼執行，直接使用 Commands 更容易做審計、逾時控制和輸出校正。
不要預設允許代碼訪問任意路徑、任意網路或無限資源。
Templates
Templates 用於沉澱可複用運行環境。當前主路徑是複用內建模板或構建自訂模板，再通過 SDK / CLI 建立 Sandbox。
相容能力：
查詢範本。
建立 / 更新 / 刪除模板。
構建模板。
使用標籤、版本或別名系統管理範本。
基於模板建立 Sandbox。
使用建議：
生產環境應固定模板名稱、版本或別名，避免“latest”類引用造成不可控變更。
語言運行時、系統依賴、基礎 CLI 和穩定業務 SDK 應前置到模板中，減少每次 Sandbox 啟動後的臨時安裝。
模板構建依賴鏡像倉庫、網路和帳號許可權；構建失敗時應先排查這些基礎條件，再排查 SDK 參數。
CLI
雲沙箱相容 E2B CLI 的常用調試和管理命令。CLI 適合本地驗證、排障和輕量管理，不建議作為生產系統的主控制面。
相容命令：
查看模板：
e2b template list。建立 Sandbox：
e2b sandbox create。查看 Sandbox：
e2b sandbox list。終止 Sandbox：
e2b sandbox kill <sandbox-id>。串連 Sandbox：
e2b sandbox connect <sandbox-id>。執行命令：
e2b sandbox exec <sandbox-id> <command>。查看指標：
e2b sandbox metrics <sandbox-id>。
配置要求：
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"E2B_ACCESS_TOKEN 是 E2B 已廢棄的舊認證變數。新版本 E2B CLI 應使用 E2B_API_KEY，不要在新接入流程中依賴 E2B_ACCESS_TOKEN。
CLI 命令參數可能隨 E2B CLI 版本變化。命令列為與文檔不一致時，先執行 e2b --version 和對應命令的 --help，確認本機 CLI 版本和參數形態。
受限能力
以下 E2B SDK 能力當前用於保持調用相容或返回佔位結果，不適合作為生產依賴：
Sandbox Logs：可能返回空結果，不應用於正式日誌採集。
Network Config Update：可能返回成功但不執行實際網路變更，不應用於動態網路治理。
Sandbox Metrics 當前支援查看 CPU、記憶體指標；磁碟/頁緩衝欄位會返回佔位值，不建議用於容量判斷。指標按 1 分鐘粒度返回。計費、警示和容量治理應以Function Compute控制台、CloudMonitor或Log Service中的正式資料為準。
如果業務需要日誌、網路變更、VPC 接入或雲上儲存訪問，應按雲沙箱當前開放能力和阿里雲基礎設施方案單獨設計，不要直接照搬 E2B 對應 API。
暫不相容能力
以下能力當前不屬於雲沙箱 E2B 相容主路徑：
Volume API。
Team 管理。
API Key / Access Token 管理。
E2B 託管 MCP Gateway。
E2B 自訂網域名、代理隧道、Bring Your Own Cloud 等平台側能力。
Snapshot 已支援（需先開通白名單），使用說明參見快照（Snapshot）。遷移已有 E2B 應用時，應先識別是否依賴上述能力。如果依賴，需要先調整架構或確認雲沙箱是否已有替代方案，再進入開發接入。