@hatchet-dev/sandbox 0.0.1 → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `@hatchet-dev/sandbox`, the TypeScript SDK. The provider has its own changelog at the repository root.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Each release reads its notes from the matching section here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-27
+
+### Added
+
+- `hatchet.sandbox.create`, `connect`, and `list` on the Hatchet client, by importing `@hatchet-dev/sandbox`.
+- `Sandbox.exec` with `timeoutMs`, returning stdout, stderr, exit code, and per-step timings; `Sandbox.kill`.
+- `Sandbox.files`: read, write, writeFiles, list, exists, getInfo, makeDir, rename, copy, remove, download, upload. Files over 2 MiB are staged through the provider's object store on presigned URLs.
+- `create({ id, template, from, metadata, idleTimeoutMs })` for caller-chosen ids, images, forks, and expiry.
+- Every call is a Hatchet task run, and a durable step inside a durable task.
+- OpenTelemetry instrumentation, off with `BRICKIE_OTEL=false`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Hatchet Technologies Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,129 @@
 # @hatchet-dev/sandbox
 
-Placeholder package for Hatchet Sandbox.
+<div align="center">
+
+[![npm version](https://img.shields.io/npm/v/%40hatchet-dev%2Fsandbox)](https://www.npmjs.com/package/@hatchet-dev/sandbox)
+[![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+Run agent sandboxes from [Hatchet](https://hatchet.run) tasks.
+
+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. Each call that changes files takes 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.
+
+## Install
+
+```bash
+pnpm add @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
+```
+
+```bash
+npm install @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
+```
+
+```bash
+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.
+
+```ts
+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');
+```
+
+Your app only talks to Hatchet. A brickie provider, connected to the same tenant, runs the sandboxes. Set `HATCHET_CLIENT_TOKEN` like you would for any Hatchet client. That is all the app needs.
+
+## 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. |
+
+Options for `create`:
+
+| Option | What it does |
+|---|---|
+| `id` | Pick your own sandbox ID. Lowercase letters, digits, and hyphens. It must not exist yet. |
+| `template` | The container image. Defaults to the provider's image. |
+| `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`. |
+| `idleTimeoutMs` | Remove the sandbox after this long with no calls. The provider sets the maximum. |
+
+### `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` | Removes the sandbox. The snapshots stay, so `connect` still works. |
+| `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. |
+
+The sandbox itself does not need network access for any of this.
+
+`read` and `write` carry up to 2 MiB through Hatchet. Bigger files go through the provider's object store (`--object-store` on the provider: S3, GCS, Azure Blob, or a local folder) and never pass 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.
+
+## 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 `BRICKIE_OTEL=false` to turn this off.
+
+## What you need
+
+- A Hatchet tenant. Hatchet Cloud, or a self-hosted Hatchet v0.110.0 or newer with gRPC operators turned on.
+- A brickie provider connected to that tenant. It is one binary, `brickie worker`. Get it from [github.com/hatchet-dev/brickie](https://github.com/hatchet-dev/brickie).
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/hatchet-dev/brickie/blob/main/sdks/typescript/CHANGELOG.md).
+
+## License
+
+MIT. See [LICENSE](https://github.com/hatchet-dev/brickie/blob/main/LICENSE).

package/dist/files.d.ts

@@ -0,0 +1,93 @@
+import type { JsonObject } from '@hatchet-dev/typescript-sdk/v1';
+export type FileType = 'file' | 'dir' | 'symlink';
+export interface EntryInfo {
+    name: string;
+    path: string;
+    type: FileType;
+    size: number;
+    mode: number;
+    permissions: string;
+    modifiedTime?: Date;
+    symlinkTarget?: string;
+}
+export type FileData = string | ArrayBuffer | Uint8Array | Blob;
+export interface WriteEntry {
+    path: string;
+    data: FileData;
+}
+export interface ReadOpts {
+    format?: 'text' | 'bytes' | 'blob';
+}
+export interface TransferOpts {
+    /** Give up after this long. */
+    timeoutMs?: number;
+}
+export interface ListOpts {
+    depth?: number;
+}
+export type FilesystemErrorCode = 'staging_failed' | 'not_found' | 'invalid_path' | 'invalid_url' | 'invalid_content' | 'invalid' | 'is_a_directory' | 'not_a_directory' | 'too_large' | 'transfer_failed';
+/** Thrown for caller mistakes such as a missing file or a path outside the workspace. */
+export declare class FilesystemError extends Error {
+    readonly code: FilesystemErrorCode;
+    constructor(code: FilesystemErrorCode, message: string);
+}
+type RawEntry = Omit<EntryInfo, 'modifiedTime'> & {
+    modifiedTime?: string;
+};
+interface FsOutput extends JsonObject {
+    content?: string;
+    stagedKey?: string;
+    url?: string;
+    putUrl?: string;
+    getUrl?: string;
+    entry?: RawEntry | null;
+    entries?: RawEntry[];
+    created?: boolean;
+    error?: {
+        code: FilesystemErrorCode;
+        message: string;
+    };
+}
+/** @internal */
+export type FsTurn = (fn: string, input: JsonObject) => Promise<FsOutput>;
+/** File operations on a sandbox workspace. Paths are relative to the workspace. Each call is one Hatchet task. */
+export declare class Files {
+    private readonly turn;
+    /** @internal */
+    constructor(turn: FsTurn);
+    private call;
+    /** Reads a file as text (default), bytes, or a Blob. Files over the provider's `--max-file-bytes` (2 MiB) come through the provider's object store instead of Hatchet. */
+    read(path: string, opts?: ReadOpts & {
+        format?: 'text';
+    }): Promise<string>;
+    read(path: string, opts: ReadOpts & {
+        format: 'bytes';
+    }): Promise<Uint8Array>;
+    read(path: string, opts: ReadOpts & {
+        format: 'blob';
+    }): Promise<Blob>;
+    /** Writes one file or several. Parent directories are created. Bytes are stored exactly. Files over 2 MiB go through the provider's object store instead of Hatchet. */
+    write(path: string, data: FileData): Promise<EntryInfo>;
+    write(files: WriteEntry[]): Promise<EntryInfo[]>;
+    /** Writes several files in one task. */
+    writeFiles(files: WriteEntry[]): Promise<EntryInfo[]>;
+    /** Lists a directory. `depth` 1 (default) is the directory itself; higher values recurse. No snapshot is made. */
+    list(path?: string, opts?: ListOpts): Promise<EntryInfo[]>;
+    /** True if the path exists. No snapshot is made. */
+    exists(path: string): Promise<boolean>;
+    /** Metadata of a file or directory. Throws `FilesystemError` with code `not_found` if absent. */
+    getInfo(path: string): Promise<EntryInfo>;
+    /** Creates a directory and its parents. Returns false if it already existed. */
+    makeDir(path: string): Promise<boolean>;
+    /** Renames or moves a file or directory. */
+    rename(oldPath: string, newPath: string): Promise<EntryInfo>;
+    /** Copies a file or directory tree. */
+    copy(srcPath: string, dstPath: string): Promise<EntryInfo>;
+    /** Deletes a file or directory tree. */
+    remove(path: string): Promise<void>;
+    /** The provider fetches an https URL into the workspace. The sandbox needs no network. Private and loopback addresses are refused. */
+    download(url: string, path: string, opts?: TransferOpts): Promise<EntryInfo>;
+    /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
+    upload(path: string, url: string, opts?: TransferOpts): Promise<void>;
+}
+export {};

package/dist/files.js

@@ -0,0 +1,170 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Files = exports.FilesystemError = void 0;
+const fs = __importStar(require("node:fs/promises"));
+/** Thrown for caller mistakes such as a missing file or a path outside the workspace. */
+class FilesystemError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FilesystemError';
+    }
+}
+exports.FilesystemError = FilesystemError;
+const toEntry = (e) => ({
+    ...e,
+    modifiedTime: e.modifiedTime ? new Date(e.modifiedTime) : undefined,
+});
+const STAGE_OVER_BYTES = 2 << 20;
+async function toBytes(data) {
+    if (typeof data === 'string')
+        return Buffer.from(data, 'utf8');
+    if (data instanceof Blob)
+        return Buffer.from(await data.arrayBuffer());
+    if (data instanceof Uint8Array)
+        return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    return Buffer.from(data);
+}
+async function putStaged(url, bytes) {
+    if (url.startsWith('file://')) {
+        await fs.writeFile(decodeURIComponent(url.slice('file://'.length)), bytes);
+        return;
+    }
+    const res = await fetch(url, { method: 'PUT', body: new Uint8Array(bytes), headers: { 'Content-Type': 'application/octet-stream' } });
+    if (!res.ok)
+        throw new FilesystemError('staging_failed', `stage upload failed: HTTP ${res.status}`);
+}
+async function getStaged(url) {
+    if (url.startsWith('file://')) {
+        const path = decodeURIComponent(url.slice('file://'.length));
+        const bytes = await fs.readFile(path);
+        await fs.rm(path, { force: true });
+        return bytes;
+    }
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new FilesystemError('staging_failed', `stage download failed: HTTP ${res.status}`);
+    return Buffer.from(await res.arrayBuffer());
+}
+/** File operations on a sandbox workspace. Paths are relative to the workspace. Each call is one Hatchet task. */
+class Files {
+    turn;
+    /** @internal */
+    constructor(turn) {
+        this.turn = turn;
+    }
+    async call(fn, input) {
+        const out = await this.turn(`$fs.${fn}`, input);
+        if (out.error)
+            throw new FilesystemError(out.error.code, out.error.message);
+        return out;
+    }
+    async read(path, opts = {}) {
+        const out = await this.call('read', { path });
+        const bytes = out.url ? await getStaged(out.url) : Buffer.from(out.content ?? '', 'base64');
+        if (opts.format === 'bytes')
+            return new Uint8Array(bytes);
+        if (opts.format === 'blob')
+            return new Blob([new Uint8Array(bytes)]);
+        return bytes.toString('utf8');
+    }
+    async write(pathOrFiles, data) {
+        if (typeof pathOrFiles !== 'string')
+            return this.writeFiles(pathOrFiles);
+        const [entry] = await this.writeFiles([{ path: pathOrFiles, data: data ?? '' }]);
+        return entry;
+    }
+    /** Writes several files in one task. */
+    async writeFiles(files) {
+        const encoded = await Promise.all(files.map(async (f) => {
+            const bytes = await toBytes(f.data);
+            if (bytes.length <= STAGE_OVER_BYTES)
+                return { path: f.path, content: bytes.toString('base64') };
+            const { stagedKey, putUrl } = await this.call('presign', {});
+            await putStaged(putUrl, bytes);
+            return { path: f.path, stagedKey: stagedKey };
+        }));
+        const { entries = [] } = await this.call('write', { files: encoded });
+        return entries.map(toEntry);
+    }
+    /** Lists a directory. `depth` 1 (default) is the directory itself; higher values recurse. No snapshot is made. */
+    async list(path = '.', opts = {}) {
+        const { entries = [] } = await this.call('list', { path, depth: opts.depth ?? 1 });
+        return entries.map(toEntry);
+    }
+    /** True if the path exists. No snapshot is made. */
+    async exists(path) {
+        const { entry } = await this.call('stat', { path });
+        return entry != null;
+    }
+    /** Metadata of a file or directory. Throws `FilesystemError` with code `not_found` if absent. */
+    async getInfo(path) {
+        const { entry } = await this.call('stat', { path });
+        if (!entry)
+            throw new FilesystemError('not_found', `${path} does not exist`);
+        return toEntry(entry);
+    }
+    /** Creates a directory and its parents. Returns false if it already existed. */
+    async makeDir(path) {
+        const { created } = await this.call('mkdir', { path });
+        return created === true;
+    }
+    /** Renames or moves a file or directory. */
+    async rename(oldPath, newPath) {
+        const { entry } = await this.call('rename', { path: oldPath, newPath });
+        return toEntry(entry);
+    }
+    /** Copies a file or directory tree. */
+    async copy(srcPath, dstPath) {
+        const { entry } = await this.call('copy', { path: srcPath, newPath: dstPath });
+        return toEntry(entry);
+    }
+    /** Deletes a file or directory tree. */
+    async remove(path) {
+        await this.call('remove', { path });
+    }
+    /** The provider fetches an https URL into the workspace. The sandbox needs no network. Private and loopback addresses are refused. */
+    async download(url, path, opts = {}) {
+        const { entry } = await this.call('download', { url, path, ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+        return toEntry(entry);
+    }
+    /** The provider sends a workspace file to an https URL with HTTP PUT, for example a presigned URL. */
+    async upload(path, url, opts = {}) {
+        await this.call('upload', { path, url, ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+    }
+}
+exports.Files = Files;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Sandbox, type SandboxNamespace, type SandboxOpts, type ConnectOpts, type ExecOpts, type SandboxListOpts, type SandboxInfo, type CommandResult, type Timings, } from './sandbox.js';
+export { Files, FilesystemError, type FilesystemErrorCode, type EntryInfo, type FileType, type FileData, type WriteEntry, type ReadOpts, type ListOpts, type TransferOpts, } from './files.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesystemError = exports.Files = exports.Sandbox = void 0;
+var sandbox_js_1 = require("./sandbox.js");
+Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return sandbox_js_1.Sandbox; } });
+var files_js_1 = require("./files.js");
+Object.defineProperty(exports, "Files", { enumerable: true, get: function () { return files_js_1.Files; } });
+Object.defineProperty(exports, "FilesystemError", { enumerable: true, get: function () { return files_js_1.FilesystemError; } });

package/dist/otel.d.ts

@@ -0,0 +1 @@
+export declare function setupTelemetry(): Promise<void>;

package/dist/otel.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setupTelemetry = setupTelemetry;
+let telemetryStarted = false;
+async function setupTelemetry() {
+    if (telemetryStarted || process.env.BRICKIE_OTEL === 'false') {
+        return;
+    }
+    telemetryStarted = true;
+    try {
+        const [{ registerInstrumentations }, { HatchetInstrumentor }] = await Promise.all([
+            import('@opentelemetry/instrumentation'),
+            import('@hatchet-dev/typescript-sdk/opentelemetry/index.js'),
+        ]);
+        registerInstrumentations({ instrumentations: [new HatchetInstrumentor()] });
+    }
+    catch (err) {
+        console.error(`brickie: opentelemetry disabled: ${err.message}`);
+    }
+}

package/dist/sandbox.d.ts

@@ -0,0 +1,83 @@
+import { HatchetClient } from '@hatchet-dev/typescript-sdk/v1';
+import { Files } from './files.js';
+export interface Timings {
+    /** Snapshot made after this turn. Absent for turns that do not change the workspace. */
+    snapshotId?: string;
+    /** Milliseconds per phase: `claim`, `restore`, `exec`, `checkpoint`. */
+    timings?: Record<string, number>;
+}
+export interface CommandResult extends Timings {
+    stdout: string;
+    stderr: string;
+    /** A non-zero code is a normal result, not an error. */
+    exitCode: number;
+}
+export interface SandboxOpts {
+    /** Sandbox ID to use instead of a generated one. Lowercase letters, digits, and hyphens; must be new on the provider. */
+    id?: string;
+    /** Container image. Defaults to the provider's image. */
+    template?: string;
+    /** Snapshot to start from. Two sandboxes with the same `from` are a fork. */
+    from?: string;
+    /** Key-value tags, used to find the sandbox again with {@link SandboxNamespace.list}. */
+    metadata?: Record<string, string>;
+    /** Milliseconds without a turn before the provider removes the sandbox. Capped by the provider. */
+    idleTimeoutMs?: number;
+}
+export interface ExecOpts {
+    /** Kill the command after this long. The result then has `exitCode` 124. */
+    timeoutMs?: number;
+}
+export interface ConnectOpts {
+    /** Image to use if the sandbox has to be started again. Defaults to the provider's image. */
+    template?: string;
+}
+export interface SandboxListOpts {
+    /** Only the sandbox with this ID. */
+    sandboxId?: string;
+    /** Only sandboxes whose metadata contains every one of these pairs. */
+    metadata?: Record<string, string>;
+}
+export interface SandboxInfo {
+    sandboxId: string;
+    metadata?: Record<string, string>;
+    /** True while the sandbox is running. A sandbox that is not live is started again by `connect`. */
+    live: boolean;
+    latestSnapshot?: string;
+    createdAt: Date;
+    lastUsed?: Date;
+}
+/** One sandbox. Every method is one `brickie-sandbox` Hatchet task. */
+export declare class Sandbox {
+    private readonly run;
+    readonly sandboxId: string;
+    private readonly template?;
+    /** File operations on the workspace. */
+    readonly files: Files;
+    private constructor();
+    /** Starts a new sandbox. Prefer `hatchet.sandbox.create`. */
+    static create(client: HatchetClient, opts?: SandboxOpts): Promise<Sandbox>;
+    /** Attaches to a sandbox by ID. Prefer `hatchet.sandbox.connect`. */
+    static connect(client: HatchetClient, sandboxId: string, opts?: ConnectOpts): Promise<Sandbox>;
+    /** Lists sandboxes on the provider. Prefer `hatchet.sandbox.list`. */
+    static list(client: HatchetClient, opts?: SandboxListOpts): Promise<SandboxInfo[]>;
+    /** Runs a shell command with `sh -c` in the workspace and makes a snapshot. A timeout gives `exitCode` 124, not an error. */
+    exec(cmd: string, opts?: ExecOpts): Promise<CommandResult>;
+    /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
+    kill(): Promise<void>;
+    private turn;
+}
+/** `hatchet.sandbox`, added to `HatchetClient` by importing `@hatchet-dev/sandbox`. */
+export interface SandboxNamespace {
+    /** Starts a new sandbox. Inside a durable task this is a durable step. */
+    create(opts?: SandboxOpts): Promise<Sandbox>;
+    /** Attaches to a sandbox by ID. If it is not running, the provider starts it from its latest snapshot. */
+    connect(sandboxId: string, opts?: ConnectOpts): Promise<Sandbox>;
+    /** Lists sandboxes the provider knows, filtered by ID or metadata. */
+    list(opts?: SandboxListOpts): Promise<SandboxInfo[]>;
+}
+declare module '@hatchet-dev/typescript-sdk/v1' {
+    interface HatchetClient {
+        readonly sandbox: SandboxNamespace;
+    }
+}

package/dist/sandbox.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sandbox = void 0;
+const v1_1 = require("@hatchet-dev/typescript-sdk/v1");
+const files_js_1 = require("./files.js");
+const otel_js_1 = require("./otel.js");
+const SANDBOX_TASK_NAME = 'brickie-sandbox';
+function turnRunner(client) {
+    const task = client.workflow({ name: SANDBOX_TASK_NAME });
+    return async (input) => {
+        const result = await task.run(input, {
+            additionalMetadata: {
+                'brickie.fn': input.fn,
+                ...(input.sandboxId ? { 'brickie.sandbox': input.sandboxId } : {}),
+                ...(input.image ? { 'brickie.image': input.image } : {}),
+                ...(input.snapshotId ? { 'brickie.from': input.snapshotId } : {}),
+            },
+        });
+        return result[SANDBOX_TASK_NAME] ?? result;
+    };
+}
+/** One sandbox. Every method is one `brickie-sandbox` Hatchet task. */
+class Sandbox {
+    run;
+    sandboxId;
+    template;
+    /** File operations on the workspace. */
+    files;
+    constructor(run, sandboxId, template) {
+        this.run = run;
+        this.sandboxId = sandboxId;
+        this.template = template;
+        this.files = new files_js_1.Files((fn, input) => this.turn(fn, input));
+    }
+    /** Starts a new sandbox. Prefer `hatchet.sandbox.create`. */
+    static async create(client, opts = {}) {
+        void (0, otel_js_1.setupTelemetry)();
+        const run = turnRunner(client);
+        const created = await run({
+            fn: '$create',
+            input: {},
+            ...(opts.id ? { sandboxId: opts.id } : {}),
+            ...(opts.template ? { image: opts.template } : {}),
+            ...(opts.from ? { snapshotId: opts.from } : {}),
+            ...(opts.metadata ? { metadata: opts.metadata } : {}),
+            ...(opts.idleTimeoutMs ? { idleTtlMs: opts.idleTimeoutMs } : {}),
+        });
+        return new Sandbox(run, created.sandboxId, opts.template);
+    }
+    /** Attaches to a sandbox by ID. Prefer `hatchet.sandbox.connect`. */
+    static async connect(client, sandboxId, opts = {}) {
+        void (0, otel_js_1.setupTelemetry)();
+        const run = turnRunner(client);
+        await run({ fn: '$connect', input: {}, sandboxId, ...(opts.template ? { image: opts.template } : {}) });
+        return new Sandbox(run, sandboxId, opts.template);
+    }
+    /** Lists sandboxes on the provider. Prefer `hatchet.sandbox.list`. */
+    static async list(client, opts = {}) {
+        const result = await turnRunner(client)({
+            fn: '$list',
+            input: { ...(opts.sandboxId ? { sandboxId: opts.sandboxId } : {}), ...(opts.metadata ? { metadata: opts.metadata } : {}) },
+        });
+        const raw = (result.output.sandboxes ?? []);
+        return raw.map((s) => ({ ...s, createdAt: new Date(s.createdAt), lastUsed: s.lastUsed ? new Date(s.lastUsed) : undefined }));
+    }
+    /** Runs a shell command with `sh -c` in the workspace and makes a snapshot. A timeout gives `exitCode` 124, not an error. */
+    async exec(cmd, opts = {}) {
+        return this.turn('$command', { cmd, ...(opts.timeoutMs ? { timeoutMs: opts.timeoutMs } : {}) });
+    }
+    /** Removes the sandbox. Its snapshots stay; `connect` can bring it back. */
+    async kill() {
+        await this.turn('$destroy', {});
+    }
+    async turn(fn, input) {
+        const result = await this.run({
+            sandboxId: this.sandboxId,
+            ...(this.template ? { image: this.template } : {}),
+            fn,
+            input,
+        });
+        return { ...result.output, snapshotId: result.snapshotId, timings: result.timings };
+    }
+}
+exports.Sandbox = Sandbox;
+Object.defineProperty(v1_1.HatchetClient.prototype, 'sandbox', {
+    configurable: true,
+    get() {
+        return {
+            create: (opts) => Sandbox.create(this, opts),
+            connect: (sandboxId, opts) => Sandbox.connect(this, sandboxId, opts),
+            list: (opts) => Sandbox.list(this, opts),
+        };
+    },
+});

package/package.json

@@ -1,14 +1,45 @@
 {
   "name": "@hatchet-dev/sandbox",
-  "version": "0.0.1",
-  "description": "Hatchet Sandbox SDK",
+  "version": "0.1.0",
+  "description": "Hatchet Sandbox TypeScript SDK",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/hatchet-dev/hatchet.git"
+    "url": "git+https://github.com/hatchet-dev/brickie.git",
+    "directory": "sdks/typescript"
   },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
-  "main": "index.js"
-}
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/core": "^2.0.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.221.0",
+    "@opentelemetry/instrumentation": "^0.221.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0"
+  },
+  "peerDependencies": {
+    "@hatchet-dev/typescript-sdk": ">=1.33.1"
+  },
+  "devDependencies": {
+    "@hatchet-dev/typescript-sdk": "^1.33.1",
+    "@types/node": "^24.0.0",
+    "typedoc": "^0.28.0",
+    "typescript": "^5.9.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc",
+    "docs": "typedoc"
+  }
+}

package/index.js

@@ -1 +0,0 @@
-module.exports = {};