--- title: Sandbox description: TypeScript SDK - Sandbox API reference --- Create and control a microVM sandbox: boot it from an image, run commands, stream logs and metrics, then shut it down. See [Overview](/sandboxes/overview) for configuration examples and [Lifecycle](/sandboxes/lifecycle) for state management.

Static7

Sandbox.builder()configure a new sandbox Sandbox.get()handle to an existing one Sandbox.list()all sandboxes Sandbox.listWith()filter by labels Sandbox.start()restart a stopped one Sandbox.startDetached()restart detached Sandbox.remove()delete a stopped one

Instance20

sandbox.exec()run a command sandbox.shell()run a shell script sandbox.attach()attach to a foreground process sandbox.fs()read / write files sandbox.ssh()ssh into the guest sandbox.config()full configuration sandbox.logs()captured output sandbox.logStream()stream captured output sandbox.metrics()resource snapshot sandbox.metricsStream()stream metrics sandbox.stop()graceful shutdown sandbox.stopWithTimeout()stop with custom timeout sandbox.requestStop()stop without waiting sandbox.kill()force terminate sandbox.killWithTimeout()force kill with timeout sandbox.requestKill()kill without waiting sandbox.requestDrain()graceful drain sandbox.waitUntilStopped()block until it exits sandbox.detach()release, keep running [Symbol.asyncDispose]()auto-stop on scope exit

Builder · SandboxBuilder47

.image() .memory() .cpus() .port() .volume() .env() .secret() .init() .patch() .detached() .create() .build() + 35 more in the SandboxBuilder section

Types

SandboxConfig SandboxHandle SandboxMetrics SandboxStatus SandboxStopResult MetricsStream LogEntry LogStream LogReadOptions LogStreamOptions LogSource LogLevel PullPolicy PullProgress PullProgressCreate PatchBuilder
The TypeScript SDK uses a **builder-only** entry point. Start every new sandbox from `Sandbox.builder(name)` and chain configuration calls before terminating with `.create()`. Use `.detached(true)` before `.create()` for detached/background mode. Sandbox names must be non-empty and no longer than 128 UTF-8 bytes. `libkrunfw` selection is process-level, not per sandbox. To use a custom library, call `setRuntimeLibkrunfwPath(path)` before creating local sandboxes, set `MSB_LIBKRUNFW_PATH`, or configure `paths.libkrunfw`.

Typical flow

```typescript import { Sandbox } from "microsandbox"; await using sandbox = await Sandbox.builder("api") // 1. configure .image("python") .memory(1024) .create(); // 2. boot the microVM const out = await sandbox.exec("python", ["-V"]); // 3. run console.log(out.stdout); await sandbox.stop(); // 4. shut down ``` ## Static methods --- #### Sandbox.builder()
static
```typescript static builder(name: string): SandboxBuilder ``` Begin building a new sandbox. Configure it with chainable setters, then call `.create()` to boot it. Sandbox names must be non-empty and no longer than 128 UTF-8 bytes. See [`SandboxBuilder`](#sandboxbuilder) for all available options.

Parameters

namestring
Sandbox name, up to 128 UTF-8 bytes.

Returns

SandboxBuilder
Fluent builder for configuring the sandbox.
```typescript await using sandbox = await Sandbox.builder("api") .image("python") .create(); ``` --- #### Sandbox.get()
staticasync
```typescript static get(name: string): Promise ``` Get a live handle to an existing sandbox (running or stopped). The handle provides status, configuration, and lifecycle control without requiring a full connection to the guest agent.

Parameters

namestring
Sandbox name, up to 128 UTF-8 bytes.

Returns

Promise<SandboxHandle>
Live handle with status and lifecycle control.
```typescript const handle = await Sandbox.get("api"); console.log(handle.status); ``` --- #### Sandbox.list()
staticasync
```typescript static list(): Promise ``` List all sandboxes (running, stopped, and crashed). Handles returned from `list()` are read-only - call [`Sandbox.get(name)`](#sandbox-get) to get a live handle for lifecycle calls.

Returns

Promise<SandboxHandle[]>
All sandboxes (read-only handles).
```typescript for (const h of await Sandbox.list()) { console.log(`${h.name} — ${h.status}`); } ``` --- #### Sandbox.listWith()
staticasync
```typescript static listWith(filter: { labels?: Record }): Promise ``` List sandboxes filtered to those carrying all of the given labels (AND-matched). Like [`list()`](#sandbox-list), the returned handles are read-only.

Parameters

filter{ labels?: Record<string, string> }
Labels that a sandbox must all carry to be included.

Returns

Matching sandboxes (read-only handles).
```typescript const workers = await Sandbox.listWith({ labels: { role: "worker" } }); ``` --- #### Sandbox.remove()
staticasync
```typescript static remove(name: string): Promise ``` Delete a stopped sandbox and all its state from disk (configuration, logs, runtime directory). Fails if the sandbox is still running - stop it first.

Parameters

namestring
Sandbox name, up to 128 UTF-8 bytes.
```typescript await Sandbox.remove("api"); ``` --- #### Sandbox.start()
staticasync
```typescript static start(name: string): Promise ``` Restart a previously stopped sandbox. The VM reboots using the persisted configuration. The sandbox enters attached mode - it stops when the binding goes out of scope (via `await using`) or when [`stop()`](#sandbox-stop) is called.

Parameters

namestring
Name of a stopped sandbox, up to 128 UTF-8 bytes.

Returns

Running sandbox.
```typescript await using sandbox = await Sandbox.start("api"); ``` --- #### Sandbox.startDetached()
staticasync
```typescript static startDetached(name: string): Promise ``` Restart a stopped sandbox in detached mode. The sandbox survives after your process exits.

Parameters

namestring
Name of a stopped sandbox, up to 128 UTF-8 bytes.

Returns

Running sandbox.
```typescript const sandbox = await Sandbox.startDetached("worker"); ``` --- ## Instance methods A running `Sandbox` also exposes two read-only properties: `name` (`string`, the sandbox name) and `ownsLifecycle` (`boolean`, `true` in attached mode where the auto-disposer stops the sandbox, `false` in detached mode). Command execution (`exec`, `execWith`, `execStream`, `execStreamWith`, `shell`, `shellStream`) and foreground attachment (`attach`, `attachWith`, `attachShell`) live on the [Execution](/sdk/typescript/execution) page. --- #### sandbox.config()
instanceasync
```typescript config(): Promise ``` Get the full configuration the sandbox was created with - image, cpus, memory, env, mounts, and the rest. The shape mirrors [`SandboxBuilder.build()`](#build).

Returns

Sandbox configuration.
```typescript const config = await sandbox.config(); console.log(`${config.memoryMib} MiB`); ``` --- #### sandbox.detach()
instanceasync
```typescript detach(): Promise ``` Release the handle without stopping the sandbox. The sandbox continues running as a background process. Reconnect later with [`Sandbox.get()`](#sandbox-get). ```typescript await sandbox.detach(); // keeps running in the background ``` --- #### sandbox.fs()
instance
```typescript fs(): SandboxFsOps ``` Get a filesystem handle for reading and writing files inside the running sandbox. See [Filesystem](/sdk/typescript/filesystem) for API details.

Returns

Filesystem handle.
```typescript await sandbox.fs().writeFile("/tmp/hello.txt", "hi"); ``` --- #### sandbox.kill()
instanceasync
```typescript kill(): Promise ``` Force-terminate the sandbox and wait until stopped state is observed. No graceful shutdown - use when the sandbox is unresponsive. Pending writes that the workload hasn't `fsync`'d may be lost, same durability semantics as a sudden power loss on a physical machine. Prefer [`stop()`](#sandbox-stop) for graceful shutdown that gives the workload a chance to flush. ```typescript await sandbox.kill(); // no graceful shutdown ``` --- #### sandbox.killWithTimeout()
instanceasync
```typescript killWithTimeout(timeoutMs: number): Promise ``` Force-terminate the sandbox and wait up to `timeoutMs` for stopped-state observation.

Parameters

timeoutMsnumber
Milliseconds to wait for the stopped state to be observed.
```typescript await sandbox.killWithTimeout(2000); ``` --- #### sandbox.logs()
instanceasync
```typescript logs(opts?: LogReadOptions): Promise ``` Read captured output from the sandbox's `exec.log`. Backed by an on-disk JSON Lines file the runtime writes via the relay tap. Works on running and stopped sandboxes alike - there is no protocol traffic. The same method is available on [`SandboxHandle`](#sandboxhandle) for callers that don't want to start the sandbox first. The default sources are `"stdout"`, `"stderr"`, and `"output"` (PTY-merged). Pass `"system"` to also include synthetic lifecycle markers and runtime/kernel diagnostic lines, or `"all"` for every source.

Parameters

Filters: tail, since, until, sources. Omit for the default user-program sources.

Returns

Matching entries in chronological order.
```typescript import { Sandbox } from "microsandbox"; const handle = await Sandbox.get("web"); // Default — all user-program output, regardless of pipe/pty mode const entries = await handle.logs(); for (const e of entries) { const source = e.source === "stdout" ? "OUT" : e.source === "stderr" ? "ERR" : e.source === "output" ? "PTY" : "SYS"; console.log( `[${e.timestamp.toISOString()}] ${source} ${e.sessionId}: ${e.text().trimEnd()}` ); } // Filtered: last 50 entries from the past hour, including system lines const recent = await handle.logs({ tail: 50, since: new Date(Date.now() - 60 * 60 * 1000), sources: ["stdout", "stderr", "output", "system"], }); ``` --- #### sandbox.logStream()
instanceasync
```typescript logStream(opts?: LogStreamOptions): Promise ``` Stream captured output as it appears, with optional follow. Backed by the same on-disk `exec.log` as [`logs()`](#sandbox-logs), but yields entries lazily. Pass `{ follow: true }` to keep the stream open past current EOF and pick up new entries as they are written; otherwise the stream drains the current contents and ends. Each yielded [`LogEntry`](#logentry) carries an opaque `cursor` that can be passed back via [`LogStreamOptions.fromCursor`](#logstreamoptions) to resume.

Parameters

Filters plus follow and resume controls (since, fromCursor).

Returns

Async iterable of log entries.
```typescript await using stream = await sandbox.logStream({ follow: true }); for await (const e of stream) { console.log(e.text().trimEnd()); } ``` --- #### sandbox.metrics()
instanceasync
```typescript metrics(): Promise ``` Get a point-in-time snapshot of the sandbox's resource usage: CPU, memory, disk I/O, network I/O, optional upper disk usage, and uptime.

Returns

Resource metrics.
```typescript const m = await sandbox.metrics(); console.log(`cpu ${m.cpuPercent.toFixed(1)}% · mem ${Math.round(m.memoryBytes / 1048576)} MiB`); ``` --- #### sandbox.metricsStream()
instanceasync
```typescript metricsStream(intervalMs: number): Promise ``` Stream resource metrics at a regular interval. The returned [`MetricsStream`](#metricsstream) supports both `recv()` and `for await...of`.

Parameters

intervalMsnumber
Milliseconds between metric snapshots.

Returns

Async stream yielding a snapshot each interval.
```typescript await using stream = await sandbox.metricsStream(1000); for await (const snapshot of stream) { console.log(`${snapshot.cpuPercent.toFixed(1)}%`); } ``` --- #### sandbox.requestDrain()
instanceasync
```typescript requestDrain(): Promise ``` Request a graceful drain and return once the request is sent. Existing commands run to completion, but new `exec` calls are rejected. The sandbox transitions to `stopped` when all in-flight commands finish. Use [`waitUntilStopped()`](#sandbox-waituntilstopped) when the caller needs stopped-state observation. Useful for zero-downtime rotation of worker sandboxes. ```typescript await sandbox.requestDrain(); await sandbox.waitUntilStopped(); ``` --- #### sandbox.requestKill()
instanceasync
```typescript requestKill(): Promise ``` Request force termination and return once the signal is sent, without waiting for the stopped state to be observed. ```typescript await sandbox.requestKill(); ``` --- #### sandbox.requestStop()
instanceasync
```typescript requestStop(): Promise ``` Request graceful shutdown and return once the request is sent, without waiting for the stopped state to be observed. ```typescript await sandbox.requestStop(); ``` --- #### sandbox.ssh()
instance
```typescript ssh(): SandboxSshOps ``` Get an SSH handle for opening interactive sessions and port forwards into the running guest. See [SSH](/sdk/typescript/ssh) for API details.

Returns

SSH handle.
--- #### sandbox.stop()
instanceasync
```typescript stop(): Promise ``` Gracefully shut down the sandbox and wait until stopped state is observed. Lets the sandbox finish writing any pending data to disk before it exits, so files written inside the sandbox aren't lost across a later restart. Waits up to 10_000 ms for a clean exit; if the sandbox is still running after that, it is force-killed. ```typescript await sandbox.stop(); ``` --- #### sandbox.stopWithTimeout()
instanceasync
```typescript stopWithTimeout(timeoutMs: number): Promise ``` Gracefully shut down the sandbox with an explicit observation timeout before force-kill escalation. `0` force-kills immediately. Resolves successfully either way - it does not throw on timeout expiry.

Parameters

timeoutMsnumber
Milliseconds to wait for a clean exit before force-killing. 0 skips the grace period.
```typescript await sandbox.stopWithTimeout(5000); ``` --- #### sandbox.waitUntilStopped()
instanceasync
```typescript waitUntilStopped(): Promise ``` Block until the sandbox is observed in a terminal non-running state, without triggering a stop or kill request.

Returns

Terminal status, exit code, and signal that were observed.
```typescript const result = await sandbox.waitUntilStopped(); console.log(result.status, result.exitCode); ``` --- #### sandbox.[Symbol.asyncDispose]()
instanceasync
```typescript [Symbol.asyncDispose](): Promise ``` Implements `AsyncDisposable` so the sandbox can be used with `await using`. When the binding goes out of scope, the sandbox is stopped (best-effort) - but only if `ownsLifecycle` is `true`. ```typescript { await using sandbox = await Sandbox.builder("api").image("python").create(); await sandbox.exec("python", ["-V"]); } // sandbox.stop() runs here, automatically ``` --- ## SandboxBuilder Fluent builder for configuring a sandbox before creation. Obtained via [`Sandbox.builder(name)`](#sandbox-builder). Every setter returns the same builder so calls chain. Examples are shown on the methods where usage is non-obvious; simple setters are demonstrated by the [Typical flow](#typical-flow) above. --- #### .build()
builderasync
```typescript build(): Promise ``` Materialize the [`SandboxConfig`](#sandboxconfig) without booting the sandbox. Validates the configuration and consumes the builder. For booting, use [`create`](#create) instead - it builds internally.

Returns

Validated, ready-to-boot configuration.
--- #### .cpus()
builder
```typescript cpus(n: number): this ``` Set the number of virtual CPUs. This is a limit, not a reservation.

Parameters

nnumber
Number of vCPUs.
--- #### .create()
builderasync
```typescript create(): Promise ``` Build and boot the sandbox. By default the sandbox is attached - it stops when the `await using` binding goes out of scope. Call [`detached(true)`](#detached) first for background mode.

Returns

Running sandbox.
```typescript const sandbox = await Sandbox.builder("worker") .image("python") .detached(true) .create(); await sandbox.detach(); ``` --- #### .createWithPullProgress()
builderasync
```typescript createWithPullProgress(): Promise ``` Build and boot while streaming image pull progress. Returns a [`PullProgressCreate`](#pullprogresscreate) that yields [`PullProgress`](#pullprogress) events as the image is resolved, downloaded, and materialized; call `awaitSandbox()` after iteration to obtain the live sandbox.

Returns

Async iterable creation handle.
```typescript const creation = await Sandbox.builder("demo") .image("alpine") .createWithPullProgress(); for await (const ev of creation) { if (ev.kind === "layerDownloadProgress") { console.log(`${ev.layerIndex}: ${ev.downloadedBytes}/${ev.totalBytes}`); } } const sandbox = await creation.awaitSandbox(); ``` --- #### .detached()
builder
```typescript detached(enabled: boolean): this ``` Create in detached/background mode when `true`. A detached sandbox survives after your process exits and does not auto-stop on `await using` scope exit.

Parameters

enabledboolean
Whether to boot in detached mode.
--- #### .disableMetricsSample()
builder
```typescript disableMetricsSample(): this ``` Disable periodic background metrics sampling for this sandbox. --- #### .disableNetwork()
builder
```typescript disableNetwork(): this ``` Fully disable networking. No network interface is created. --- #### .entrypoint()
builder
```typescript entrypoint(cmd: string[]): this ``` Override the OCI image's stored ENTRYPOINT. Consulted by `msb exec` / `msb run` (CLI command resolution), **not** by [`sandbox.exec`](/sdk/typescript/execution) / [`sandbox.shell`](/sdk/typescript/execution) - those pass `cmd` literally to the guest agent. Use this when configuring a sandbox via the SDK for later CLI attachment.

Parameters

cmdstring[]
Entrypoint command and arguments.
--- #### .env()
builder
```typescript env(key: string, value: string): this ``` Set an environment variable visible to all commands. Can be called multiple times. Per-command env vars (via `execWith`) are merged on top.

Parameters

keystring
Variable name.
valuestring
Variable value.
--- #### .envs()
builder
```typescript envs(vars: Record): this ``` Add many environment variables at once.

Parameters

varsRecord<string, string>
Map of variable names to values.
--- #### .ephemeral()
builder
```typescript ephemeral(enabled: boolean): this ``` When `true`, the sandbox and all its persisted state are removed automatically once it stops, rather than left on disk for restart.

Parameters

enabledboolean
Whether the sandbox is ephemeral.
--- #### .fromSnapshot()
builder
```typescript fromSnapshot(pathOrName: string): this ``` Boot from a previously captured snapshot instead of a fresh image. The image reference and upper-layer source are pinned from the snapshot manifest. See [Snapshots](/sdk/typescript/snapshots).

Parameters

pathOrNamestring
Snapshot name or filesystem path.
--- #### .hostname()
builder
```typescript hostname(name: string): this ``` Set the guest hostname.

Parameters

namestring
Hostname.
--- #### .libkrunfwPath()
builderdeprecated
```typescript libkrunfwPath(path: string): this ``` Deprecated compatibility alias for older builder chains. This sets the same process-level override as `setRuntimeLibkrunfwPath(path)` and returns the builder; it is not a per-sandbox setting.

Parameters

pathstring
Path to the libkrunfw shared library.
--- #### .idleTimeout()
builder
```typescript idleTimeout(secs: number): this ``` Auto-drain the sandbox after this many seconds of inactivity (no active exec sessions). Enforced on the host side.

Parameters

secsnumber
Idle timeout in seconds.
--- #### .image()
builder
```typescript image(src: string): this ``` Set the root filesystem source. Accepts OCI image names (`"alpine"`), local directory paths, or disk image paths. The format is auto-detected. **Required** unless [`fromSnapshot`](#fromsnapshot) is used.

Parameters

srcstring
OCI image name, local directory path, or disk image path.
--- #### .imageWith()
builder
```typescript imageWith(configure: (b: ImageBuilder) => ImageBuilder): this ``` Configure an explicit rootfs source. Use this for OCI-only settings such as the writable overlay upper size, or for disk images when the filesystem type can't be auto-detected.

Parameters

configure(b: ImageBuilder) => ImageBuilder
Configure the rootfs source.
```typescript const sandbox = await Sandbox.builder("worker") .imageWith((i) => i.oci("python:3.12").upperSize(8192)) .create(); ``` --- #### .init()
builder
```typescript init(cmd: string, args?: string[]): this ``` Hand off PID 1 inside the guest to `cmd` after agentd finishes its boot-time setup. `cmd` is either an absolute path inside the guest rootfs or the literal `"auto"`, which honors a known image ENTRYPOINT init then falls back to probing common init paths. See [Custom init system](/sandboxes/customize#custom-init-system). For init binaries that need extra env, use [`initWith`](#initwith).

Parameters

cmdstring
Absolute path inside the guest, or "auto".
argsstring[]?
Optional argv for the init binary.
```typescript const sandbox = await Sandbox.builder("worker") .image("jrei/systemd-debian:12") .init("auto") .create(); ``` --- #### .initWith()
builder
```typescript initWith(cmd: string, configure: (b: InitOptionsBuilder) => InitOptionsBuilder): this ``` Like [`init`](#init), but with a closure-builder for argv and env vars. The builder exposes `.arg`, `.args`, `.env`, and `.envs`. Calling `init` or `initWith` more than once overwrites.

Parameters

cmdstring
Absolute path to the init binary inside the guest.
configure(b: InitOptionsBuilder) => InitOptionsBuilder
Closure populating argv and env.
```typescript const sandbox = await Sandbox.builder("worker") .image("jrei/systemd-debian:12") .initWith("/lib/systemd/systemd", (i) => i.args(["--unit=multi-user.target"]).env("container", "microsandbox")) .create(); ``` --- #### .label()
builder
```typescript label(key: string, value: string): this ``` Attach a single label to the sandbox. Labels can be matched later with [`Sandbox.listWith()`](#sandbox-listwith).

Parameters

keystring
Label key.
valuestring
Label value.
--- #### .labels()
builder
```typescript labels(labels: Record): this ``` Attach many labels at once.

Parameters

labelsRecord<string, string>
Map of label keys to values.
#### .logLevel()
builder
```typescript logLevel(level: LogLevel): this ``` Override the sandbox process's log verbosity.

Parameters

Log level.
--- #### .maxDuration()
builder
```typescript maxDuration(secs: number): this ``` Set the maximum sandbox lifetime in seconds. When exceeded, the sandbox is drained and stopped. Enforced on the host side - the guest cannot override it.

Parameters

secsnumber
Maximum lifetime in seconds.
--- #### .memory()
builder
```typescript memory(mib: number): this ``` Set the guest memory size in MiB. Physical pages are only allocated as the guest touches them, so this is a limit, not an upfront reservation.

Parameters

mibnumber
Memory in MiB.
--- #### .metricsSampleIntervalMs()
builder
```typescript metricsSampleIntervalMs(ms: number): this ``` Set the interval, in milliseconds, at which the host samples background metrics for this sandbox.

Parameters

msnumber
Sampling interval in milliseconds.
--- #### .network()
builder
```typescript network(configure: (b: NetworkBuilder) => NetworkBuilder): this ``` Configure DNS, TLS, policy, and secrets. See [Networking](/sdk/typescript/networking) for the full builder API.

Parameters

Configure the network.
--- #### .patch()
builder
```typescript patch(configure: (b: PatchBuilder) => PatchBuilder): this ``` Modify the rootfs before the VM boots. Patches go into the writable layer - the base image is untouched. See [`PatchBuilder`](#patchbuilder) for the operations.

Parameters

Configure rootfs patches.
```typescript const sandbox = await Sandbox.builder("worker") .image("python") .patch((p) => p.text("/etc/app.conf", "mode=prod\n", { mode: 0o644 })) .create(); ``` --- #### .port()
builder
```typescript port(host: number, guest: number): this ``` Publish a TCP port from the sandbox to the host. The default host bind address is `127.0.0.1`. For an explicit bind address, use [`portBind`](#portbind).

Parameters

hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .portBind()
builder
```typescript portBind(bind: string, host: number, guest: number): this ``` Publish a TCP port on a specific host bind address, such as `"0.0.0.0"`.

Parameters

bindstring
Host bind address.
hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .portUdp()
builder
```typescript portUdp(host: number, guest: number): this ``` Publish a UDP port. The default host bind address is `127.0.0.1`.

Parameters

hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .portUdpBind()
builder
```typescript portUdpBind(bind: string, host: number, guest: number): this ``` Publish a UDP port on a specific host bind address.

Parameters

bindstring
Host bind address.
hostnumber
Port on the host.
guestnumber
Port inside the sandbox.
--- #### .pullPolicy()
builder
```typescript pullPolicy(policy: PullPolicy): this ``` Control when the OCI image is pulled from the registry.

Parameters

Pull behavior.
--- #### .quietLogs()
builder
```typescript quietLogs(): this ``` Suppress sandbox process log output. --- #### .registry()
builder
```typescript registry(configure: (b: RegistryBuilder) => RegistryBuilder): this ``` Configure the OCI registry connection: authentication, insecure transport, and CA certificates.

Parameters

configure(b: RegistryBuilder) => RegistryBuilder
Configure the registry.
```typescript const sandbox = await Sandbox.builder("worker") .image("registry.internal/app:latest") .registry((r) => r.auth("user", "token")) .create(); ``` --- #### .replace()
builder
```typescript replace(): this ``` If a sandbox with the same name already exists, stop it (10s SIGTERM grace, then SIGKILL), remove it, and create a fresh one. Without this, creation fails on name conflict. --- #### .replaceWithTimeout()
builder
```typescript replaceWithTimeout(timeoutMs: number): this ``` Same as [`replace()`](#replace) with a custom SIGTERM timeout in milliseconds. `0` skips SIGTERM and force-kills immediately. Implies `replace()`.

Parameters

timeoutMsnumber
Milliseconds to wait after SIGTERM before escalating to SIGKILL.
--- #### .rlimit()
builder
```typescript rlimit(resource: string, limit: number): this ``` Set a guest resource limit (a soft and hard limit at the same value). For separate soft/hard values, use [`rlimitRange`](#rlimitrange).

Parameters

resourcestring
Resource name, e.g. "nofile".
limitnumber
Limit value applied to both soft and hard.
--- #### .rlimitRange()
builder
```typescript rlimitRange(resource: string, soft: number, hard: number): this ``` Set a guest resource limit with explicit soft and hard values.

Parameters

resourcestring
Resource name, e.g. "nofile".
softnumber
Soft limit.
hardnumber
Hard limit.
--- #### .script()
builder
```typescript script(name: string, content: string): this ``` Add a named script at `/.msb/scripts/` inside the guest. Scripts are added to `PATH` and can be called by name via `exec()` or `shell()`.

Parameters

namestring
Script name (becomes the filename).
contentstring
Script content.
--- #### .scripts()
builder
```typescript scripts(scripts: Record): this ``` Add many named scripts at once.

Parameters

scriptsRecord<string, string>
Map of script names to contents.
--- #### .security()
builder
```typescript security(profile: "default" | "restricted"): this ``` Set the in-guest security profile.

Parameters

profile"default" | "restricted"
Security profile.
--- #### .secret()
builder
```typescript secret(configure: (b: SecretBuilder) => SecretBuilder): this ``` Add a secret with full configuration. See [Secrets](/sdk/typescript/secrets) for the builder API. Automatically enables TLS interception.

Parameters

Configure the secret.
--- #### .secretEnv()
builder
```typescript secretEnv(envVar: string, value: string, allowedHost: string): this ``` Auto-placeholder shorthand for adding a header-injected secret. Generates a `$MSB_` placeholder usable in headers.

Parameters

envVarstring
Environment variable name (non-empty, no = or NUL).
valuestring
Secret value.
allowedHoststring
Allowed destination host.
--- #### .shell()
builder
```typescript shell(shell: string): this ``` Set the shell binary used by [`sandbox.shell()`](/sdk/typescript/execution).

Parameters

shellstring
Shell path (e.g. "/bin/bash").
--- #### .user()
builder
```typescript user(user: string): this ``` Set the default guest user for all commands.

Parameters

userstring
User name or UID.
--- #### .volume()
builder
```typescript volume(guest: string, configure: (b: MountBuilder) => MountBuilder): this ``` Add a volume mount. See [Volumes](/sdk/typescript/volumes) for mount types.

Parameters

gueststring
Mount point inside the sandbox.
Configure the mount.
--- #### .workdir()
builder
```typescript workdir(path: string): this ``` Set the default working directory for all commands.

Parameters

pathstring
Absolute path inside the guest.
--- ## PatchBuilder Fluent builder for the ordered list of pre-boot rootfs patches. Used in `SandboxBuilder.patch(p => p...)`. Each method appends one operation; calls are chainable. By default a method that targets a path already present in the image errors at boot; pass `{ replace: true }` on the operation to allow overwriting. `mkdir` and `remove` are idempotent. See [Patches](/sandboxes/customize#patches) for conceptual context. --- #### .append()
builder
```typescript append(path: string, content: string): this ``` Append `content` to an existing file at `path`. If the file lives in a lower image layer, it's copied up first.

Parameters

pathstring
Absolute path inside the guest.
contentstring
Text to append.
--- #### .copyDir()
builder
```typescript copyDir(src: string, dst: string, opts?: { replace?: boolean }): this ``` Recursively copy a host directory at `src` into the guest rootfs at `dst`.

Parameters

srcstring
Host source directory.
dststring
Absolute destination path inside the guest.
opts.replaceboolean
When true, overwrite an existing path at dst.
--- #### .copyFile()
builder
```typescript copyFile(src: string, dst: string, opts?: { mode?: number; replace?: boolean }): this ``` Copy a single host file at `src` into the guest rootfs at `dst`.

Parameters

srcstring
Host source file.
dststring
Absolute destination path inside the guest.
opts.modenumber
File mode, e.g. 0o644. Omit to keep the source mode.
opts.replaceboolean
When true, overwrite an existing path at dst.
--- #### .file()
builder
```typescript file(path: string, content: Buffer, opts?: { mode?: number; replace?: boolean }): this ``` Write raw bytes at `path`.

Parameters

pathstring
Absolute path inside the guest.
contentBuffer
Raw byte content.
opts.modenumber
File mode, e.g. 0o644.
opts.replaceboolean
When true, overwrite an existing path.
--- #### .mkdir()
builder
```typescript mkdir(path: string, opts?: { mode?: number }): this ``` Create a directory at `path`. Idempotent: a no-op if the directory already exists.

Parameters

pathstring
Absolute path inside the guest.
opts.modenumber
Directory mode, e.g. 0o755.
--- #### .remove()
builder
```typescript remove(path: string): this ``` Delete a file or directory at `path`. Idempotent: a no-op if the path doesn't exist.

Parameters

pathstring
Absolute path inside the guest.
--- #### .symlink()
builder
```typescript symlink(target: string, link: string, opts?: { replace?: boolean }): this ``` Create a symlink at `link` pointing to `target`.

Parameters

targetstring
What the symlink points to (literal symlink target text).
linkstring
Absolute path of the symlink itself.
opts.replaceboolean
When true, overwrite an existing path at link.
--- #### .text()
builder
```typescript text(path: string, content: string, opts?: { mode?: number; replace?: boolean }): this ``` Write UTF-8 text content at `path`.

Parameters

pathstring
Absolute path inside the guest.
contentstring
Text content.
opts.modenumber
File mode, e.g. 0o644.
opts.replaceboolean
When true, overwrite an existing path.
--- ## Types ### LogEntry
class

Returned by logs() · logStream()

A class wrapping one captured log entry from `exec.log`. Bytes are exposed via `data`; use `text()` for a UTF-8-lossy decode. | Property / Method | Type | Description | |-------------------|------|-------------| | timestamp | `Date` | Wall-clock capture time on the host | | source | [`LogSource`](#logsource) | Where the chunk came from | | sessionId | `number \| null` | Relay-monotonic session id; `null` for `"system"` entries | | data | `Uint8Array` | The captured chunk's bytes (UTF-8 lossy decoded by default) | | cursor | `string` | Opaque resume token; pass to [`LogStreamOptions.fromCursor`](#logstreamoptions) to resume | | `text()` | `string` | Convenience: UTF-8 decode of `data` (lossy - invalid bytes are replaced) | ### LogLevel
union

Used by logLevel()

Sandbox process log verbosity. String literal type. | Value | Description | |-------|-------------| | `"error"` | Errors only | | `"warn"` | Warnings and errors only | | `"info"` | Info and higher | | `"debug"` | Debug and higher | | `"trace"` | Most verbose - all diagnostic output | ### LogReadOptions
interface

Used by logs()

Filters passed to [`logs()`](#sandbox-logs). All fields optional. Omit the argument entirely for the default sources (`stdout` + `stderr` + `output`). | Field | Type | Description | |-------|------|-------------| | tail | `number?` | Show only the last N entries after other filters apply | | since | `Date?` | Inclusive lower bound on entry timestamp | | until | `Date?` | Exclusive upper bound on entry timestamp | | sources | `ReadonlyArray<`[`LogSource`](#logsource)` \| "all">?` | Sources to include. Omit = `["stdout", "stderr", "output"]`. Add `"system"` or pass `"all"` to merge runtime/kernel diagnostics. | ### LogStream
class

Returned by logStream()

An async iterable of [`LogEntry`](#logentry) values. Drain it with `for await...of` or call `recv()` directly. Implements `AsyncDisposable`, so it works with `await using`. | Method | Returns | Description | |--------|---------|-------------| | `recv()` | `Promise<`[`LogEntry`](#logentry)` \| null>` | Receive the next entry. Returns `null` when the stream ends. | | `[Symbol.asyncIterator]()` | `AsyncIterator<`[`LogEntry`](#logentry)`>` | Use with `for await...of` | | `[Symbol.asyncDispose]()` | `Promise` | Stop iterating; safe to use with `await using` | ### LogStreamOptions
interface

Used by logStream()

Options passed to [`logStream()`](#sandbox-logstream). All fields optional. `since` and `fromCursor` are mutually exclusive - passing both rejects at the boundary. | Field | Type | Description | |-------|------|-------------| | sources | `ReadonlyArray<`[`LogSource`](#logsource)` \| "all">?` | Same shape as [`LogReadOptions.sources`](#logreadoptions) | | since | `Date?` | Start at the first entry whose timestamp is `>= since`. Mutually exclusive with `fromCursor`. | | fromCursor | `string?` | Resume strictly after the entry whose [`LogEntry.cursor`](#logentry) matches. Mutually exclusive with `since`. | | until | `Date?` | Stop emitting at the first entry whose timestamp is `>= until` | | follow | `boolean?` | When `true`, keep the stream open past current EOF and yield new entries as they are written. Defaults to `false`. | ### LogSource
union

Used by LogEntry.source · LogReadOptions.sources

Tag indicating where a captured log entry came from. String literal type: ```typescript type LogSource = "stdout" | "stderr" | "output" | "system"; ``` | Value | Description | |-------|-------------| | `"stdout"` | Captured from a session's stdout (pipe mode - streams stayed separated) | | `"stderr"` | Captured from a session's stderr (pipe mode) | | `"output"` | Captured from a session running in PTY mode. PTY allocation merges stdout and stderr at the kernel level inside the guest, so they arrive as a single stream - tagged `"output"` rather than mislabelled as `"stdout"`. | | `"system"` | Synthetic entry: lifecycle markers in `exec.log` plus runtime/kernel diagnostic lines merged in at read time when `"system"` is requested. | ### MetricsStream
class

Returned by metricsStream()

Async stream for receiving periodic metrics snapshots. Implements `AsyncDisposable`, so it works with `await using`. | Method | Returns | Description | |--------|---------|-------------| | `recv()` | `Promise<`[`SandboxMetrics`](#sandboxmetrics)` \| null>` | Receive the next snapshot. Returns `null` when the stream ends. | | `[Symbol.asyncIterator]()` | `AsyncIterator<`[`SandboxMetrics`](#sandboxmetrics)`>` | Use with `for await...of` | | `[Symbol.asyncDispose]()` | `Promise` | Stop iterating; safe to use with `await using` | ### PullPolicy
union

Used by pullPolicy()

Controls when the SDK fetches an OCI image from the registry. String literal type. | Value | Description | |-------|-------------| | `"always"` | Pull the image every time, even if cached locally | | `"if-missing"` | Pull only if the image is not already cached. This is the default. | | `"never"` | Never pull; fail if the image is not cached locally | ### PullProgress
union

Yielded by PullProgressCreate

Image pull and materialize progress event emitted by [`PullProgressCreate`](#pullprogresscreate). A discriminated union. Narrow on `kind` to access variant-specific fields. | `kind` value | Additional fields | |--------------|-------------------| | `"resolving"` | `reference: string` | | `"resolved"` | `reference: string`, `manifestDigest: string`, `layerCount: number`, `totalDownloadBytes?: number` | | `"layerDownloadProgress"` | `layerIndex: number`, `digest: string`, `downloadedBytes: number`, `totalBytes?: number` | | `"layerDownloadComplete"` | `layerIndex: number`, `digest: string`, `downloadedBytes: number` | | `"layerDownloadVerifying"` | `layerIndex: number`, `digest: string` | | `"layerMaterializeStarted"` | `layerIndex: number`, `diffId: string` | | `"layerMaterializeProgress"` | `layerIndex: number`, `bytesRead: number`, `totalBytes: number` | | `"layerMaterializeWriting"` | `layerIndex: number` | | `"layerMaterializeComplete"` | `layerIndex: number`, `diffId: string` | | `"stitchMergingTrees"` | `layerCount: number` | | `"stitchWritingFsmeta"` | (none) | | `"stitchWritingVmdk"` | (none) | | `"stitchComplete"` | (none) | | `"complete"` | `reference: string`, `layerCount: number` | `totalDownloadBytes` and `totalBytes` on the `"resolved"` / `"layerDownloadProgress"` variants may be absent if the manifest omits sizes. ### PullProgressCreate
class

Returned by createWithPullProgress()

Async iterable creation handle returned by [`createWithPullProgress()`](#createwithpullprogress). Yields [`PullProgress`](#pullprogress) events as the image is resolved, downloaded, and materialized. Call `awaitSandbox()` after iteration to obtain the live sandbox. | Method / Property | Returns | Description | |-------------------|---------|-------------| | progress | `NapiPullProgressStream` | The underlying progress event stream | | `[Symbol.asyncIterator]()` | `AsyncIterator<`[`PullProgress`](#pullprogress)`>` | Use with `for await...of` | | `awaitSandbox()` | `Promise<`[`Sandbox`](#instance-methods)`>` | Resolve the underlying creation task and return the running sandbox | ### SandboxConfig
type

Returned by config() · build()

Configuration object produced by [`build()`](#build) and returned by [`config()`](#sandbox-config). You generally should not construct this by hand; use the builder. | Field | Type | Description | |-------|------|-------------| | name | `string` | Sandbox name, up to 128 UTF-8 bytes | | image | `RootfsSource` | OCI / bind / disk discriminated union | | cpus | `number \| null` | Virtual CPUs | | memoryMib | `number \| null` | Guest memory in MiB | | logLevel | [`LogLevel`](#loglevel)` \| null` | Log verbosity | | quietLogs | `boolean` | Suppress log output | | workdir | `string \| null` | Default working directory | | shell | `string \| null` | Shell binary | | securityProfile | `"default" \| "restricted"` | In-guest security profile | | entrypoint | `string[] \| null` | Override image entrypoint | | cmd | `string[] \| null` | Override image cmd | | hostname | `string \| null` | Guest hostname | | user | `string \| null` | Default guest user | | env | `Array` | Environment variables | | scripts | `Array` | Named scripts | | mounts | `VolumeMount[]` | Volume mounts | | patches | `Patch[]` | Rootfs modifications applied before boot | | pullPolicy | [`PullPolicy`](#pullpolicy)` \| null` | Image pull behavior | | replace | `boolean` | Replace existing sandbox with same name | | replaceWithTimeoutMs | `number` | Milliseconds to wait after `SIGTERM` before escalating to `SIGKILL` (default `10000`; `0` skips `SIGTERM`) | | maxDurationSecs | `number \| null` | Maximum sandbox lifetime | | idleTimeoutSecs | `number \| null` | Stop after idle time | | portsTcp | `Array` | TCP host→guest mappings | | portsUdp | `Array` | UDP host→guest mappings | | registry | `RegistryConfig \| null` | Registry connection settings | | network | `NetworkConfig \| null` | Network configuration | | disableNetwork | `boolean` | Disable networking entirely | | secrets | `SecretEntry[]` | Secret entries (top-level) | ### SandboxHandle
class

Returned by Sandbox.get() · Sandbox.list() · Sandbox.listWith()

A lightweight handle to an existing sandbox (running or stopped). Obtained via [`Sandbox.get()`](#sandbox-get), [`Sandbox.list()`](#sandbox-list), or [`Sandbox.listWith()`](#sandbox-listwith). Provides status, configuration, and lifecycle control without an active connection to the guest agent. Handles from `Sandbox.get(name)` are **live** - they expose lifecycle methods (`start`, `stop`, `kill`, `connect`, etc). Handles in the arrays returned by `Sandbox.list()` / `Sandbox.listWith()` are **read-only**: calling lifecycle methods on them throws. Use `Sandbox.get(name)` to upgrade to a live handle. | Property / Method | Type | Description | |-------------------|------|-------------| | name | `string` | Sandbox name, up to 128 UTF-8 bytes | | status | [`SandboxStatus`](#sandboxstatus) | Current status | | configJson | `string` | Raw JSON configuration | | createdAt | `Date \| null` | Creation timestamp | | updatedAt | `Date \| null` | Last update timestamp | | config() | [`SandboxConfig`](#sandboxconfig) | Parsed configuration | | refresh() | `Promise<`[`SandboxHandle`](#sandboxhandle)`>` | Re-read the handle's state from the database | | metrics() | `Promise<`[`SandboxMetrics`](#sandboxmetrics)`>` | Point-in-time resource metrics | | logs() | `Promise<`[`LogEntry`](#logentry)`[]>` | Read captured `exec.log` (works without starting) | | logStream() | `Promise<`[`LogStream`](#logstream)`>` | Stream captured `exec.log`, with optional follow | | start() | `Promise<`[`Sandbox`](#instance-methods)`>` | Start in attached mode | | startDetached() | `Promise<`[`Sandbox`](#instance-methods)`>` | Start in detached mode | | connect() | `Promise<`[`Sandbox`](#instance-methods)`>` | Connect to a running sandbox without taking ownership. Returns an error if it doesn't respond within 10_000 ms | | connectWithTimeout(timeoutMs) | `Promise<`[`Sandbox`](#instance-methods)`>` | Same as `connect()` with an explicit timeout in milliseconds | | stop() | `Promise` | Gracefully shut down. Waits up to 10_000 ms for pending writes to flush, then force-kills | | stopWithTimeout(timeoutMs) | `Promise` | Same as `stop()` with an explicit timeout in milliseconds; `0` force-kills immediately | | requestStop() | `Promise` | Request graceful shutdown without waiting | | kill() | `Promise` | Force terminate and wait until stopped state is observed | | killWithTimeout(timeoutMs) | `Promise` | Same as `kill()` with an explicit observation timeout | | requestKill() | `Promise` | Request force termination without waiting | | requestDrain() | `Promise` | Request graceful drain without waiting | | waitUntilStopped() | `Promise<`[`SandboxStopResult`](#sandboxstopresult)`>` | Block until the sandbox reaches terminal state | | remove() | `Promise` | Delete sandbox and state | | snapshot(name) | `Promise` | Snapshot this stopped sandbox under a bare name. See [Snapshots](/sdk/typescript/snapshots) | | snapshotTo(path) | `Promise` | Snapshot this stopped sandbox to an explicit filesystem path | ### SandboxMetrics
interface

Returned by metrics() · yielded by MetricsStream

Point-in-time resource usage snapshot. | Field | Type | Description | |-------|------|-------------| | cpuPercent | `number` | CPU usage as a percentage | | vcpuTimeNs | `number` | Cumulative vCPU time in nanoseconds | | memoryBytes | `number` | Current memory usage in bytes | | memoryAvailableBytes | `number \| null` | Guest-visible available memory in bytes when reported | | memoryHostResidentBytes | `number \| null` | Host-resident memory backing the guest in bytes when reported | | memoryLimitBytes | `number` | Memory limit in bytes | | diskReadBytes | `number` | Total bytes read from disk since boot | | diskWriteBytes | `number` | Total bytes written to disk since boot | | netRxBytes | `number` | Total bytes received over the network since boot | | netTxBytes | `number` | Total bytes sent over the network since boot | | upperUsedBytes | `number \| null` | Guest-visible OCI upper filesystem used bytes when the protected reporter is available and fresh | | upperFreeBytes | `number \| null` | Guest-visible OCI upper filesystem free bytes when the protected reporter is available and fresh | | upperHostAllocatedBytes | `number \| null` | Host-allocated bytes for the writable OCI upper image when available | | uptimeMs | `number` | Time since the sandbox was created (ms) | | timestamp | `Date` | When this measurement was taken | ### SandboxStopResult
interface

Returned by waitUntilStopped()

Observed terminal sandbox state returned by [`waitUntilStopped()`](#sandbox-waituntilstopped). | Field | Type | Description | |-------|------|-------------| | name | `string` | Sandbox name | | status | [`SandboxStatus`](#sandboxstatus) | Terminal status that was observed | | exitCode | `number \| null` | Process exit code when it is available | | signal | `number \| null` | Terminating signal when the process was killed | | observedAt | `Date` | When the terminal state was observed | | source | `string \| null` | Origin of the observation when reported | ### SandboxStatus
union

Used by SandboxHandle.status · SandboxStopResult.status

Current lifecycle state of a sandbox. String literal type. | Value | Description | |-------|-------------| | `"running"` | Guest agent is ready; `exec`, `shell`, `fs` work | | `"stopped"` | VM shut down; configuration persisted; can be restarted | | `"crashed"` | VM exited unexpectedly (kernel panic, OOM, etc.) | | `"draining"` | Graceful shutdown in progress; existing commands finish, new ones rejected |