# 沙箱 API (/docs/api/native/sandbox)



## 基础地址 [#基础地址]

<ApiBaseDomain prefix="/sandbox/v1" />

## 接入 [#接入]

<QuickstartTabs snippets="{&#x22;curl&#x22;:&#x22;curl https://api-origin.invalid/sandbox/v1/sandboxes \\\n  -H \&#x22;X-API-Key: $PRAXIS_API_KEY\&#x22; \\\n  -H \&#x22;Content-Type: application/json\&#x22; \\\n  -d '{\&#x22;templateID\&#x22;:\&#x22;node22\&#x22;,\&#x22;timeout\&#x22;:300}'&#x22;,&#x22;python&#x22;:&#x22;import os\n\nimport requests\n\napi_key = os.environ[\&#x22;PRAXIS_API_KEY\&#x22;]\n\n# Call /sandbox/v1 directly over HTTP.\nresp = requests.post(\n    \&#x22;https://api-origin.invalid/sandbox/v1/sandboxes\&#x22;,\n    headers={\&#x22;X-API-Key\&#x22;: api_key},\n    json={\&#x22;templateID\&#x22;: \&#x22;node22\&#x22;, \&#x22;timeout\&#x22;: 300},\n)\nprint(resp.status_code, resp.text)&#x22;,&#x22;typescript&#x22;:&#x22;\n\nconst apiKey = process.env.PRAXIS_API_KEY;\n\n// Call /sandbox/v1 directly over HTTP.\nconst resp = await fetch(`https://api-origin.invalid/sandbox/v1/sandboxes`, {\n  method: \&#x22;POST\&#x22;,\n  headers: { \&#x22;X-API-Key\&#x22;: apiKey, \&#x22;Content-Type\&#x22;: \&#x22;application/json\&#x22; },\n  body: JSON.stringify({ templateID: \&#x22;node22\&#x22;, timeout: 300 }),\n});\nconsole.log(resp.status, await resp.text());&#x22;}" />

## HTTP 与 SDK 接入 [#http-与-sdk-接入]

用 HTTP 直接调用 `/sandbox/v1`，请求携带 `X-API-Key`。官方 E2B SDK 请使用 [E2B 兼容接口](/docs/api/compatible/e2b)，不能只修改 API 地址来调用这里的接口。

HTTP 基础地址：<ApiOriginInline text="https://api-origin.invalid/sandbox/v1" />。

## 端点 [#端点]

| 方法     | 路径                                                                                                            | 说明      | 支持   |
| ------ | ------------------------------------------------------------------------------------------------------------- | ------- | ---- |
| POST   | [`/v1/sandboxes`](/docs/api/native/sandbox/createSandbox)                                                     | 创建沙箱    | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/upgrade`](/docs/api/native/sandbox/upgradeSandbox)                                | 升级为完整沙箱 | ● 支持 |
| GET    | [`/v1/sandboxes`](/docs/api/native/sandbox/listSandboxes)                                                     | 列出沙箱    | ● 支持 |
| GET    | [`/v1/sandboxes/{sandboxID}`](/docs/api/native/sandbox/getSandbox)                                            | 读取沙箱    | ● 支持 |
| PATCH  | [`/v1/sandboxes/{sandboxID}`](/docs/api/native/sandbox/renameSandbox)                                         | 重命名沙箱   | ● 支持 |
| GET    | [`/v1/sandboxes/{sandboxID}/metrics`](/docs/api/native/sandbox/getSandboxMetrics)                             | 沙箱指标    | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/timeout`](/docs/api/native/sandbox/setSandboxTimeout)                             | 设置超时    | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/pause`](/docs/api/native/sandbox/pauseSandbox)                                    | 暂停沙箱    | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/connect`](/docs/api/native/sandbox/connectSandbox)                                | 连接沙箱    | ● 支持 |
| DELETE | [`/v1/sandboxes/{sandboxID}`](/docs/api/native/sandbox/killSandbox)                                           | 终止沙箱    | ● 支持 |
| GET    | [`/v1/templates`](/docs/api/native/sandbox/listTemplates)                                                     | 列出模板    | ● 支持 |
| POST   | [`/v1/volumes`](/docs/api/native/sandbox/createVolume)                                                        | 创建卷     | ● 支持 |
| GET    | [`/v1/volumes`](/docs/api/native/sandbox/listVolumes)                                                         | 列出卷     | ● 支持 |
| GET    | [`/v1/volumes/{volumeID}`](/docs/api/native/sandbox/getVolume)                                                | 读取卷     | ● 支持 |
| DELETE | [`/v1/volumes/{volumeID}`](/docs/api/native/sandbox/deleteVolume)                                             | 删除卷     | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/fork`](/docs/api/native/sandbox/forkSandbox)                                      | 复制沙箱    | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/snapshots`](/docs/api/native/sandbox/createSnapshot)                              | 创建快照    | ● 支持 |
| GET    | [`/v1/snapshots`](/docs/api/native/sandbox/listSnapshots)                                                     | 列出快照    | ● 支持 |
| DELETE | [`/v1/snapshots/{snapshotID}`](/docs/api/native/sandbox/deleteSnapshot)                                       | 删除快照    | ● 支持 |
| PUT    | [`/v1/sandboxes/{sandboxID}/network`](/docs/api/native/sandbox/updateSandboxNetwork)                          | 更新网络策略  | ● 支持 |
| GET    | [`/v1/sandboxes/{sandboxID}/logs`](/docs/api/native/sandbox/getSandboxLogs)                                   | 读取沙箱日志  | ● 支持 |
| POST   | [`/v1/sandboxes/{sandboxID}/extend`](/docs/api/native/sandbox/extendSandbox)                                  | 延长沙箱    | ● 支持 |
| GET    | [`/v1/sandboxes/{sandboxID}/processes`](/docs/api/native/sandbox/listObservedProcesses)                       | 列出进程    | ● 支持 |
| GET    | [`/v1/sandboxes/{sandboxID}/processes/{processID}/output`](/docs/api/native/sandbox/getObservedProcessOutput) | 读取输出    | ● 支持 |

## 与官方的差异 [#与官方的差异]

* 快照使用本平台 snap\_ 开头的 ID，可作为创建沙箱的 templateID。旧供应商句柄不再接受。暂停的沙箱用「连接沙箱」恢复运行。
* 仅提供本页声明的端点，webhooks 等未采纳的端点返回 404。
* <a href="/docs/api/native/sandbox/createSandbox">创建沙箱</a>：平台暂未提供 E2B 默认的 base 模板：不带模板参数的 Sandbox.create() 会返回 404，请显式指定模板（可用模板见「列出模板」）。

参数与字段的权威定义以 [E2B 官方文档](https://docs.e2b.dev/api-reference)为准。

错误按 E2B 格式返回，参见[错误](/docs/api/errors)；额度与响应头参见[限流](/docs/api/rate-limits)。