@hatchet-dev/sandbox
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
| Call | Returns | What it does |
|---|---|---|
create(opts?) | Sandbox | Starts a sandbox. |
connect(id, { template? }) | Sandbox | Picks 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:
| Option | What it does |
|---|---|
provider | Which sandbox provider to create on, by its name. Needed when the tenant has several; a fork always uses its snapshot's. |
id | Pick your own sandbox ID. Lowercase letters, digits, and hyphens. It must not exist yet. |
template | The image or template, in the provider's own terms. Defaults to the provider's default. |
from | Start from this snapshot. Create two sandboxes from the same snapshot and you have a fork. |
metadata | Tags you can search for with list. |
inheritParentMetadata | With from, copy the tags of the sandbox that made the snapshot onto the new one. Tags given in metadata take precedence. |
idleTimeoutMs | Stop the sandbox after this long with no calls. The provider sets the maximum. |
resources | Machine 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
| Call | Returns | What 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() | void | Stops the sandbox. The snapshots stay, so connect still works. |
delete() | void | Stops the sandbox and deletes every snapshot and file stored for it. connect fails afterwards. |
sandboxId | string | The ID to use with connect later. |
files | Files | The 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.
| Call | What 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
FilesystemErrorhas acode. 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. connectwith an unknown ID throws.createwith anidthat already exists throws too. Useconnectfor that one, or pick a new ID.hatchet.sandbox.deletewithout asandboxIdor a non-emptymetadatafilter throws before touching anything. Metadata matching is a subset match, the same aslist: 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.