@hatchet-dev/sandbox

中文文档
0.1.5发布于 2026/11/13MITTypeScriptESM + CJS构建来源已验证近 30 天下载 11.5万

Hatchet 沙盒类型SDK

中文使用文档
文档目录12 节
  1. 安装
  2. 快开始
  3. 供应商
  4. API 密码
  5. hatchet.sandbox
  6. Sandbox
  7. sandbox.files
  8. 错误
  9. 遥测
  10. 你需要的东西
  11. 更改日志
  12. 许可证

@ hatchet-dev/ sandbox (中文(简体) )

npm version License: MIT

运行沙盒从 标签 任务,用于您选择的沙盒供应商.

沙盒是带有外壳的工作空间. 在其中运行命令并读取并撰写其文件. 每次通话都是哈切特任务,与快照相对应. 你可以从任何快照中开始一个新的沙盒,你可以稍后通过它的ID返回到沙盒. 如果你在耐用任务中使用它, 坠机会捡起它留下的地方.

你的密码只跟哈切特说话 沙盒本身运行在一个供应商 你连接你的房客.

安装

pnpm add @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
npm install @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
yarn add @hatchet-dev/sandbox @hatchet-dev/typescript-sdk

惠璶 @hatchet-dev/typescript-sdk 1.3.3.1或较新.

快开始

导入软件包一次 。 它又说 hatchet.sandbox 给哈切特客户端.

import { HatchetClient } from '@hatchet-dev/typescript-sdk/v1';
import '@hatchet-dev/sandbox';

const hatchet = HatchetClient.init();

const session = hatchet.durableTask({
  name: 'agent-session',
  executionTimeout: '1h',
  fn: async (input: { conversationId: string }) => {
    const sandbox = await hatchet.sandbox.create({ id: input.conversationId });
    await sandbox.files.write('haiku.txt', 'an old silent pond');
    const haiku = await sandbox.exec('cat haiku.txt');
    await sandbox.kill();
    return { haiku: haiku.stdout };
  },
});

// later, from anywhere with a Hatchet client
const again = await hatchet.sandbox.connect('conv-42');
await again.exec('cat haiku.txt');

设定 HATCHET_CLIENT_TOKEN 就像你对哈切特客户一样.

供应商

提供商是一个沙盒供应商 与你的哈切特租户相连 曾经配置在仪表板下 Sandboxes 带有供应商的 API 密钥和可选配置值.

目前我们支持下列供应商:

const sandbox = await hatchet.sandbox.create({ provider: 'e2b' });

API 密码

hatchet.sandbox

打电话回返它会做什么
create(opts?)Sandbox开一沙盒.
connect(id, { template? })Sandbox从最新的快照中取出一个沙盒. 停止后再开始 如果ID不存在则丢出.
list({ sandboxId?, metadata? })SandboxInfo[]通过ID或元数据查找沙盒. 所有给定的配对必须匹配.
delete({ sandboxId?, metadata? })string[]删除每个匹配的沙盒及其所有快照和文件,并返回其ID。 需要一个过滤器.

备选方案 create数字 :

选项它会做什么
provider哪个沙盒供应商可以创建, 名称。 当房客有几分钱的时候需要,叉子总是用它的快照.
id自己选个沙盒身份证 小写字母 数字和连字符 它决不能存在.
template图像或模板,以提供者自己的说法. 默认提供者的默认 .
from从这个快照开始 从同一个快照创建出两个沙盒,你有一个叉子.
metadata您可以搜索的标记 list。 。 。 .
inheritParentMetadata与 from,复制沙盒的标签 使快照在新的。 给定的标记 metadata 优先发言.
idleTimeoutMs这么长时间没打电话就把沙盒停了 供养者设出最上.
resources机器大小为 { vcpu, memory, disk }。 。 。 . memory 财务报告和审定财务报表 disk 取若干个MIB或数量,单位如下: '4Gi'。无法遵守字段的提供者会用自己的信息使创建失败.

Sandbox

打电话回返它会做什么
exec(cmd, { timeoutMs? }){ stdout, stderr, exitCode, snapshotId?, timings? }运行 sh -c cmd 在工作区拍个快照 非零退出代码是正常结果,而不是出错. 超时时出站码为124.
kill()void止取沙盒来. 镜头留下,所以 connect 还行.
delete()void停止沙盒并删除每个快照和文件. connect 之后失败 .
sandboxIdstring要使用的标识 connect 等会.
filesFiles下面的文件 API .

每一个结果都有 timings 以毫秒计 claim, (中文(简体) ), restore, (中文(简体) ), exec,以及 checkpoint,则 snapshotId 电话打来的.

sandbox.files

路径与工作空间相对. 指向外面的路径 扔出一个 FilesystemError 有代码 invalid_path。 。 。 .

打电话它会做什么
read(path, { format? })读取文件. format 实值 'text' (违约), 'bytes' (单位:千美元) Uint8Array,或 'blob'。 。 。 .
write(path, data) 或者说 write([{ path, data }, ...])写一个或多个文件. data 可以是弦, ArrayBuffer, (中文(简体) ), Uint8Array,或 Blob。 。 。 .
list(path?, { depth? })列出有名称、路径、类型、大小、模式、权限和修改时间的条目.
exists(path), (中文(简体) ), getInfo(path)检查路径或获得信息.
makeDir(path), (中文(简体) ), rename(from, to), (中文(简体) ), copy(from, to), (中文(简体) ), remove(path)通常的文件操作.
download(url, path, { timeoutMs? })提供者将 https URL 获取到工作空间 。 私人地址和回路地址被拒绝.
upload(path, url, { timeoutMs? })提供者用 HTTP PUT 向 https URL 发送文件. 指定 URL 运行良好 .

read 财务报告和审定财务报表 write 通过Hatchet携带最多2个米B. 提供商拥有一个对象存储台上更大的文件,并且从未通过Hatchet传送过它们;无论用哪种方式,都使用同样的方法.

错误

  • FilesystemError 有一个 code其中: not_found, (中文(简体) ), invalid_path, (中文(简体) ), invalid_url, (中文(简体) ), invalid_content, (中文(简体) ), invalid, (中文(简体) ), is_a_directory, (中文(简体) ), not_a_directory, (中文(简体) ), too_large, (中文(简体) ), staging_failed, (中文(简体) ), transfer_failed。 。 。 .
  • 失败的命令不会丢出 。 看着 exitCode。 。 。 .
  • connect 身份不明,身份不明. create 带有 id 已经存在 扔。 使用 connect 给那个 或者选个新的身份证.
  • hatchet.sandbox.delete 无 sandboxId 或无空 metadata 过滤器在触摸任何东西之前抛出. 元数据匹配是一个子集匹配, 和 list: 过滤器 { a, b } 匹配贴有标签的沙盒 { a, b, c }。 。 。 .

遥测

首先使用SDK打开了Hatchet OpenTeleometry仪器. 如果您已经设置了 OpenTeleometry, 沙盒呼叫会在您的任务跟踪中显示 。 设定 HATCHET_SANDBOX_OTEL=false 把它关掉.

你需要的东西

  • 装有沙盒的Hatchet Cloud租户已启用.
  • 至少有一个沙盒供应商与租户连接, 在仪表板的沙盒下配置了您的 Daytona, E2B, Archil, 或 Freestyle API 键.

更改日志

见 变动情况。 。 。 .

许可证

麻省理工学院. 见 自由主义。 。 。 .

版本与发布记录

@hatchet-dev/sandbox 共发布 8 个版本,首次发布于 2026/10/27;过去 12 个月发布了 8 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.1.5latest2026/11/134 天前
0.1.42026/11/106 天前
0.1.32026/11/098 天前
0.1.22026/11/0611 天前
0.1.12026/10/3018 天前
0.1.02026/10/2720 天前

关于 @hatchet-dev/sandbox 的常见问题

@hatchet-dev/sandbox 是什么?

Hatchet 沙盒类型SDK

如何安装 @hatchet-dev/sandbox?

在项目目录运行 npm install @hatchet-dev/sandbox,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:@hatchet-dev/typescript-sdk(>=1.33.1)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@hatchet-dev/sandbox 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@hatchet-dev/sandbox 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@hatchet-dev/sandbox 可以商用吗?

@hatchet-dev/sandbox 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hatchet-dev/sandbox 的下载量有多少?

根据 npm 官方下载统计,@hatchet-dev/sandbox 在 2026/10/18 – 2026/11/16 这 30 天内被下载 114,899 次,日均约 3,830 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hatchet-dev/sandbox 还在维护吗?

最新版本 0.1.5 发布于 2026/11/13(4 天前);至今共发布 8 个版本,其中过去 12 个月发布了 8 个;首次发布于 2026/10/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。