Sandbox

TypeScript SDK - Sandbox API reference

See Overview for configuration examples and Lifecycle for state management.

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() or .createDetached().

import { Sandbox } from "microsandbox";

await using sandbox = await Sandbox.builder("demo")
  .image("alpine")
  .cpus(1)
  .memory(512)
  .create();

Static methods

---

Sandbox.builder()

static builder(name: string): SandboxBuilder

Begin building a new sandbox. Configure it with chainable setters, then call .create() or .createDetached() to boot it.

Parameters

Name	Type	Description
name	string	Sandbox name

Returns

Type	Description
SandboxBuilder	Fluent builder

---

Sandbox.get()

static get(name: string): Promise<SandboxHandle>

Get a handle to an existing sandbox (running or stopped). The handle provides status, configuration, and lifecycle control.

Parameters

Name	Type	Description
name	string	Sandbox name

Returns

Type	Description
SandboxHandle	Handle with status and lifecycle control

---

Sandbox.list()

static list(): Promise<SandboxHandle[]>

List all sandboxes (running, stopped, and crashed). Handles returned from list() are read-only — call Sandbox.get(name) to get a live handle for lifecycle calls.

Returns

Type	Description
SandboxHandle[]	All sandboxes (read-only handles)

---

Sandbox.remove()

static remove(name: string): Promise<void>

Delete a stopped sandbox and all its state from disk. Fails if the sandbox is still running.

Parameters

Name	Type	Description
name	string	Sandbox name

---

Sandbox.start()

static start(name: string): Promise<Sandbox>

Restart a previously stopped sandbox. The VM reboots using the persisted configuration.

Parameters

Name	Type	Description
name	string	Name of a stopped sandbox

Returns

Type	Description
Sandbox	Running sandbox

---

Sandbox.startDetached()

static startDetached(name: string): Promise<Sandbox>

Restart a stopped sandbox in detached mode.

Parameters

Name	Type	Description
name	string	Name of a stopped sandbox

Returns

Type	Description
Sandbox	Running sandbox

---

Instance properties

---

name

readonly name: string

Sandbox name.

---

config

readonly config: Readonly<SandboxConfig>

The frozen configuration the sandbox was built with.

---

ownsLifecycle

readonly ownsLifecycle: boolean

Whether this handle owns the sandbox lifecycle. true in attached mode (the auto-disposer will stop the sandbox), false in detached mode.

---

Instance methods

---

detach()

detach(): Promise<void>

Release the handle without stopping the sandbox. Reconnect later with Sandbox.get().

---

drain()

drain(): Promise<void>

Start a graceful drain. Existing commands run to completion, new exec calls are rejected.

---

fs()

fs(): SandboxFs

Get a filesystem handle for reading and writing files inside the running sandbox. See Filesystem for the full API.

Returns

Type	Description
SandboxFs	Filesystem handle

---

kill()

kill(): Promise<void>

Force-terminate the sandbox immediately. No graceful shutdown.

---

metrics()

metrics(): Promise<SandboxMetrics>

Get a point-in-time snapshot of the sandbox’s resource usage.

Returns

Type	Description
SandboxMetrics	CPU, memory, disk, network metrics

---

metricsStream()

metricsStream(intervalMs: number): Promise<MetricsStream>

Stream resource metrics at a regular interval. The returned stream supports both recv() and for await...of.

Parameters

Name	Type	Description
intervalMs	number	Milliseconds between metric snapshots

Returns

Type	Description
MetricsStream	Async stream of metrics

---

removePersisted()

removePersisted(): Promise<void>

Remove the sandbox and all its persisted state from disk.

---

stop()

stop(): Promise<void>

Gracefully shut down the sandbox.

---

stopAndWait()

stopAndWait(): Promise<ExitStatus>

Stop the sandbox and wait for the exit status.

Returns

Type	Description
ExitStatus	Exit code and success flag

---

wait()

wait(): Promise<ExitStatus>

Block until the sandbox exits on its own.

Returns

Type	Description
ExitStatus	Exit code and success flag

---

[Symbol.asyncDispose]()

[Symbol.asyncDispose](): Promise<void>

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.

---

Types

SandboxBuilder

Fluent configuration builder returned by Sandbox.builder(name). Every setter returns the same builder so calls can be chained.

Method	Description
image(src)	OCI image ("alpine"), local rootfs path, or a RootfsSource. Required.
cpus(n)	Virtual CPUs
memory(mib)	Guest memory in MiB
logLevel(level)	Override log verbosity
quietLogs()	Suppress log output
workdir(path)	Default working directory for commands
shell(shell)	Shell binary used by sandbox.shell(...)
entrypoint(iter)	Override the image entrypoint
hostname(name)	Guest hostname
user(user)	Default guest user
pullPolicy(policy)	Image pull behavior
libkrunfwPath(path)	Override the bundled libkrunfw shared library
env(key, value)	Add a single env var
envs(record | iter)	Add many env vars
script(name, content)	Mount a script at /.msb/scripts/<name>
scripts(record | iter)	Mount many scripts
replace()	Replace any existing sandbox with the same name
maxDuration(secs)	Maximum sandbox lifetime
idleTimeout(secs)	Stop the sandbox after this many idle seconds
volume(guestPath, m => ...)	Mount a volume — see Volumes
patch(p => ...)	Modify the rootfs before boot — see Snapshots
addPatch(patch)	Append a pre-built Patch
registry(r => r.auth(...).insecure().caCertsPath(...))	Configure the OCI registry
port(host, guest)	Publish a TCP port
portUdp(host, guest)	Publish a UDP port
disableNetwork()	Disable networking entirely
network(n => ...)	Configure DNS / TLS / policy / secrets — see Networking
secret(s => ...)	Add a secret via SecretBuilder
secretEnv(envVar, value, allowedHost)	Auto-placeholder shorthand. Generates $MSB_<ENV_VAR>.
build(): SandboxConfig	Materialize without booting
create(): Promise<Sandbox>	Build and boot in attached mode
createDetached(): Promise<Sandbox>	Build and boot in detached mode

LogLevel

Sandbox process log verbosity.

Value	Description
'debug'	Debug and higher
'error'	Errors only
'info'	Info and higher
'trace'	Most verbose - all diagnostic output
'warn'	Warnings and errors only

MetricsStream

Async stream for receiving periodic metrics snapshots.

Method	Returns	Description
[Symbol.asyncIterator]	AsyncIterator<SandboxMetrics>	Use with for await...of
recv()	Promise<SandboxMetrics | null>	Receive next snapshot. Returns null when the stream ends.
[Symbol.asyncDispose]()	Promise<void>	Stop iterating; safe to use with await using.

PullPolicy

Controls when the SDK fetches an OCI image from the registry.

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

SandboxConfig

Frozen configuration object — produced by SandboxBuilder.build() and exposed as the config property on a Sandbox. You generally should not construct this by hand; use the builder.

Field	Type	Description
name	string	Sandbox name
image	RootfsSource	OCI / bind / disk discriminated union
cpus	number | null	Virtual CPUs
memoryMib	number | null	Guest memory in MiB
logLevel	LogLevel | null	Log verbosity
quietLogs	boolean	Suppress log output
workdir	string | null	Default working directory
shell	string | null	Shell binary
entrypoint	string[] | null	Override image entrypoint
cmd	string[] | null	Override image cmd
hostname	string | null	Guest hostname
user	string | null	Default guest user
libkrunfwPath	string | null	Custom libkrunfw path
env	Array<readonly [string, string]>	Environment variables
scripts	Array<readonly [string, string]>	Named scripts
mounts	VolumeMount[]	Volume mounts
patches	Patch[]	Rootfs modifications applied before boot
pullPolicy	PullPolicy | null	Image pull behavior
replace	boolean	Replace existing sandbox with same name
maxDurationSecs	number | null	Maximum sandbox lifetime
idleTimeoutSecs	number | null	Stop after idle time
portsTcp	Array<readonly [number, number]>	TCP host→guest mappings
portsUdp	Array<readonly [number, number]>	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

A lightweight handle to an existing sandbox (running or stopped). Obtained via Sandbox.get() or Sandbox.list().

Handles from Sandbox.get(name) are live — they expose lifecycle methods (start, stop, kill, connect, etc). Handles in the array returned by Sandbox.list() 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
status	SandboxStatus	Current status
configJson	string	Raw JSON configuration
createdAt	Date | null	Creation timestamp
updatedAt	Date | null	Last update timestamp
metrics()	Promise<SandboxMetrics>	Point-in-time resource metrics
start()	Promise<Sandbox>	Start in attached mode
startDetached()	Promise<Sandbox>	Start in detached mode
connect()	Promise<Sandbox>	Connect to a running sandbox without taking ownership
stop()	Promise<void>	Graceful shutdown
kill()	Promise<void>	Force terminate
remove()	Promise<void>	Delete sandbox and state

SandboxMetrics

Point-in-time resource usage snapshot.

Field	Type	Description
cpuPercent	number	CPU usage as a percentage
diskReadBytes	number	Total bytes read from disk since boot
diskWriteBytes	number	Total bytes written to disk since boot
memoryBytes	number	Current memory usage in bytes
memoryLimitBytes	number	Memory limit in bytes
netRxBytes	number	Total bytes received over the network since boot
netTxBytes	number	Total bytes sent over the network since boot
timestamp	Date	When this measurement was taken
uptimeMs	number	Time since the sandbox was created (ms)

SandboxStatus

Value	Description
'crashed'	VM exited unexpectedly
'draining'	Graceful shutdown in progress
'running'	Guest agent is ready
'stopped'	VM shut down; can be restarted