@hatchet-dev/sandbox

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

Hatchet Sandbox TypeScript SDK

原始使用文档
文档目录12 节
  1. Install
  2. Quick start
  3. Providers
  4. API
  5. hatchet.sandbox
  6. Sandbox
  7. sandbox.files
  8. Errors
  9. Telemetry
  10. What you need
  11. Changelog
  12. License

@hatchet-dev/sandbox

npm version License: MIT

Run sandboxes from Hatchet tasks, on the sandbox vendor of your choice.

A sandbox is a workspace with a shell. You run commands in it and read and write its files. Each call is a Hatchet task and corresponds to a snapshot. You can start a new sandbox from any snapshot, and you can come back to a sandbox later by its ID. If you use it inside a durable task, a crash picks up where it left off.

Your code only talks to Hatchet. The sandbox itself runs on a provider you connect to your tenant.

Install

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

You need @hatchet-dev/typescript-sdk 1.33.1 or newer.

Quick start

Import the package once. It adds hatchet.sandbox to the Hatchet client.

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');

Set HATCHET_CLIENT_TOKEN like you would for any Hatchet client.

Providers

A provider is a sandbox vendor connected to your Hatchet tenant, configured once in the dashboard under Sandboxes with the vendor's API key and optional configuration values.

We currently support the following vendors:

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

API

hatchet.sandbox

CallReturnsWhat it does
create(opts?)SandboxStarts a sandbox.
connect(id, { template? })SandboxPicks up a sandbox from its latest snapshot. Starts it again if it was stopped. Throws if the ID does not exist.
list({ sandboxId?, metadata? })SandboxInfo[]Finds sandboxes by ID or by metadata. All given pairs must match.
delete({ sandboxId?, metadata? })string[]Deletes every matching sandbox with all of its snapshots and files, and returns their IDs. One filter is required.

Options for create:

OptionWhat it does
providerWhich sandbox provider to create on, by its name. Needed when the tenant has several; a fork always uses its snapshot's.
idPick your own sandbox ID. Lowercase letters, digits, and hyphens. It must not exist yet.
templateThe image or template, in the provider's own terms. Defaults to the provider's default.
fromStart from this snapshot. Create two sandboxes from the same snapshot and you have a fork.
metadataTags you can search for with list.
inheritParentMetadataWith from, copy the tags of the sandbox that made the snapshot onto the new one. Tags given in metadata take precedence.
idleTimeoutMsStop the sandbox after this long with no calls. The provider sets the maximum.
resourcesMachine size as { vcpu, memory, disk }. memory and disk take a number of MiB or a quantity with a unit like '4Gi'. Providers that cannot honour a field fail the create with their own message.

Sandbox

CallReturnsWhat it does
exec(cmd, { timeoutMs? }){ stdout, stderr, exitCode, snapshotId?, timings? }Runs sh -c cmd in the workspace and takes a snapshot. A non-zero exit code is a normal result, not an error. On timeout the exit code is 124.
kill()voidStops the sandbox. The snapshots stay, so connect still works.
delete()voidStops the sandbox and deletes every snapshot and file stored for it. connect fails afterwards.
sandboxIdstringThe ID to use with connect later.
filesFilesThe file API below.

Each result also has timings in milliseconds for claim, restore, exec, and checkpoint, and the snapshotId the call made.

sandbox.files

Paths are relative to the workspace. A path that points outside it throws a FilesystemError with code invalid_path.

CallWhat it does
read(path, { format? })Reads a file. format is 'text' (default), 'bytes' for a Uint8Array, or 'blob'.
write(path, data) or write([{ path, data }, ...])Writes one file or many. data can be a string, ArrayBuffer, Uint8Array, or Blob.
list(path?, { depth? })Lists entries with name, path, type, size, mode, permissions, and modified time.
exists(path), getInfo(path)Checks a path or gets its info.
makeDir(path), rename(from, to), copy(from, to), remove(path)The usual file operations.
download(url, path, { timeoutMs? })The provider fetches an https URL into the workspace. Private and loopback addresses are refused.
upload(path, url, { timeoutMs? })The provider sends a file to an https URL with HTTP PUT. Presigned URLs work well here.

read and write carry up to 2 MiB through Hatchet. Providers with an object store stage bigger files there and never pass them through Hatchet; you call the same methods either way.

Errors

  • FilesystemError has a code. One of: not_found, invalid_path, invalid_url, invalid_content, invalid, is_a_directory, not_a_directory, too_large, staging_failed, transfer_failed.
  • A command that fails does not throw. Look at exitCode.
  • connect with an unknown ID throws. create with an id that already exists throws too. Use connect for that one, or pick a new ID.
  • hatchet.sandbox.delete without a sandboxId or a non-empty metadata filter throws before touching anything. Metadata matching is a subset match, the same as list: a filter of { a, b } matches a sandbox tagged { a, b, c }.

Telemetry

On first use the SDK turns on the Hatchet OpenTelemetry instrumentor. If you have OpenTelemetry set up, sandbox calls show up as spans in your task's trace. Set HATCHET_SANDBOX_OTEL=false to turn this off.

What you need

  • A Hatchet Cloud tenant with sandboxes enabled.
  • At least one sandbox provider connected to that tenant, configured under Sandboxes in the dashboard with your Daytona, E2B, Archil, or Freestyle API key.

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.

版本与发布记录

@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 Sandbox TypeScript 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 和提交记录判断。