On this page
创建沙箱
Sandbox.create() 静态方法是 Deploy 边缘环境中创建隔离 Linux 微虚拟机的主要入口。它返回一个已连接的 Sandbox 实例，您可以使用该实例运行命令、上传文件、暴露 HTTP 端点或请求 SSH 访问。
import { Sandbox } from "@deno/sandbox";
await using sandbox = await Sandbox.create();
from deno_sandbox import DenoDeploy
sdk = DenoDeploy()
with sdk.sandbox.create() as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
from deno_sandbox import AsyncDenoDeploy
sdk = AsyncDenoDeploy()
async with sdk.sandbox.create() as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
默认情况下，这将在最近的 Deploy 区域创建一个临时沙箱，配置为 1280MB RAM，无出站网络访问，生命周期绑定于当前进程。您可以通过传入配置对象来定制该沙箱。
可用选项 Jump to heading
| 选项 | 说明 |
|---|---|
region |
例如 ams 或 ord |
allowNet |
允许沙箱向其发送请求的主机数组。详见 出站网络控制。 |
secrets |
对批准的主机进行出站请求时使用的秘密替换。详见 秘密遮蔽与替换。 |
memoryMb |
为内存密集型任务或资源限制，分配 768 到 4096 MB 的内存。 |
timeout |
沙箱保持存活的时间长度，格式如 (m) 或 (s)，例如 5m。详见 超时 |
labels |
附加任意键值标签，有助于识别和管理沙箱 |
env |
设置沙箱内的初始环境变量。 |
示例配置 Jump to heading
允许向特定 API 发送出站流量 Jump to heading
const sandbox = await Sandbox.create({
allowNet: ["api.openai.com", "api.stripe.com"],
});
sdk = DenoDeploy()
with sdk.sandbox.create(
allow_net=["api.openai.com", "api.stripe.com"]
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
sdk = AsyncDenoDeploy()
async with sdk.sandbox.create(
allow_net=["api.openai.com", "api.stripe.com"]
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
配置批准主机的秘密替换 Jump to heading
const sandbox = await Sandbox.create({
allowNet: ["api.openai.com"],
secrets: {
OPENAI_API_KEY: {
hosts: ["api.openai.com"],
value: process.env.OPENAI_API_KEY,
},
},
});
import os
from deno_sandbox import DenoDeploy
sdk = DenoDeploy()
with sdk.sandbox.create(
allow_net=["api.openai.com"],
secrets={
"OPENAI_API_KEY": {
"hosts": ["api.openai.com"],
"value": os.environ.get("OPENAI_API_KEY"),
}
}
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
import os
from deno_sandbox import AsyncDenoDeploy
sdk = AsyncDenoDeploy()
async with sdk.sandbox.create(
allow_net=["api.openai.com"],
secrets={
"OPENAI_API_KEY": {
"hosts": ["api.openai.com"],
"value": os.environ.get("OPENAI_API_KEY"),
}
}
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
在特定区域运行并分配更多内存 Jump to heading
const sandbox = await Sandbox.create({
region: "ams",
memoryMb: 2048,
});
sdk = DenoDeploy()
with sdk.sandbox.create(
region="ams",
memory_mb=2048
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
sdk = AsyncDenoDeploy()
async with sdk.sandbox.create(
region="ams",
memory_mb=2048
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
保持沙箱存活以便后续检查 Jump to heading
const sandbox = await Sandbox.create({ timeout: "10m" });
const id = sandbox.id;
await sandbox.close(); // 断开连接但保持虚拟机运行
// ...稍后...
const reconnected = await Sandbox.connect({ id });
sdk = DenoDeploy()
with sdk.sandbox.create(timeout="10m") as sandbox:
sandbox_id = sandbox.id
sandbox.close() # disconnect but leave VM running
# ...later...
with sdk.sandbox.connect(sandbox_id) as reconnected:
print(f"Reconnected to {reconnected.id}")
sdk = AsyncDenoDeploy()
async with sdk.sandbox.create(timeout="10m") as sandbox:
sandbox_id = sandbox.id
await sandbox.close() # disconnect but leave VM running
# ...later...
async with sdk.sandbox.connect(sandbox_id) as reconnected:
print(f"Reconnected to {reconnected.id}")
提供默认环境变量 Jump to heading
const sandbox = await Sandbox.create({
env: {
NODE_ENV: "development",
FEATURE_FLAG: "agents",
},
});
sdk = DenoDeploy()
with sdk.sandbox.create(
env={
"NODE_ENV": "development",
"FEATURE_FLAG": "agents",
}
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
sdk = AsyncDenoDeploy()
async with sdk.sandbox.create(
env={
"NODE_ENV": "development",
"FEATURE_FLAG": "agents",
}
) as sandbox:
print(f"Sandbox {sandbox.id} is ready.")
小贴士 Jump to heading
- 将
allowNet设定尽可能严格，以防止数据外泄。 - 使用如
agentId或customerId等元数据键，在 Deploy 控制面板中追踪沙箱。 - 利用
await using（或丢弃最后引用）自动释放沙箱。仅在需要提前终止时调用sandbox.kill()。 - 对于长期运行的服务，代码稳定后建议从沙箱迁移到 Deploy 应用。