Sandbox - microsandbox

See Overview for configuration examples and Lifecycle for state management.

Static methods

Sandbox.create()

@staticmethod
async def create(name_or_config: str | dict, **kwargs) -> Sandbox

Create and boot a sandbox. The first argument is either a name (str) or a full config (dict). Keyword arguments provide individual config fields. Pulls the image if needed, boots the VM, starts the guest agent, and waits until it is ready to accept commands. Parameters

Name	Type	Description
name_or_config	`str \| dict`	Sandbox name or full configuration dict
image	`str \| ImageSource`	OCI image, local path, or disk image (required)
cpus	`int`	Virtual CPUs (default `1`)
memory	`int`	Guest memory in MiB (default `512`)
workdir	`str`	Default working directory for commands
shell	`str`	Shell for `shell()` calls (default `"/bin/sh"`)
hostname	`str`	Guest hostname
user	`str`	Default guest user
entrypoint	`list[str]`	Override image entrypoint
replace	`bool`	Replace existing sandbox with same name
max_duration	`float`	Maximum sandbox lifetime in seconds
idle_timeout	`float`	Idle timeout in seconds
env	`dict[str, str]`	Environment variables visible to all commands
scripts	`dict[str, str]`	Named scripts mounted at `/.msb/scripts/`
pull_policy	`str \| PullPolicy`	Image pull behavior
log_level	`str \| LogLevel`	Override log verbosity
registry_auth	`RegistryAuth`	Private registry credentials
volumes	`dict[str, dict]`	Volume mounts. See Volumes.
patches	`list[PatchConfig]`	Rootfs modifications applied before boot
ports	`dict[int, int]`	Port mappings (`host_port: guest_port`)
network	`Network`	Network policy and configuration
secrets	`list[SecretEntry]`	Secret injection
detached	`bool`	If `True`, sandbox survives after your process exits

Returns

Type	Description
`Sandbox`	Running sandbox

Sandbox.create_with_progress()

@staticmethod
def create_with_progress(name_or_config: str | dict, **kwargs) -> PullSession

Same parameters as Sandbox.create() but returns a PullSession that lets you track image pull progress before the sandbox is ready. This method is synchronous (not awaitable) — the async work happens through the PullSession. Parameters Same as Sandbox.create(). Returns

Type	Description
`PullSession`	Session for tracking pull progress and obtaining the final sandbox

Sandbox.start()

@staticmethod
async def start(name: str, *, detached: bool = False) -> Sandbox

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

Name	Type	Description
name	`str`	Name of a stopped sandbox
detached	`bool`	If `True`, sandbox survives after your process exits (default `False`)

Returns

Type	Description
`Sandbox`	Running sandbox

Sandbox.get()

@staticmethod
async def get(name: str) -> SandboxHandle

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

Name	Type	Description
name	`str`	Sandbox name

Returns

Type	Description
`SandboxHandle`	Handle with status and lifecycle control

Sandbox.list()

@staticmethod
async def list() -> list[SandboxHandle]

List all sandboxes (running, stopped, and crashed). Returns

Type	Description
`list[SandboxHandle]`	All sandboxes

Sandbox.remove()

@staticmethod
async def remove(name: str) -> None

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

Name	Type	Description
name	`str`	Sandbox name

Instance properties

name

@property
async def name(self) -> str

Sandbox name. This is an async property — use await sb.name.

owns_lifecycle

@property
async def owns_lifecycle(self) -> bool

Whether this handle owns the sandbox lifecycle. True in attached mode, False in detached mode. This is an async property — use await sb.owns_lifecycle.

fs

@property
def fs(self) -> SandboxFs

Get a filesystem handle for reading and writing files inside the running sandbox. This is a synchronous property — use sb.fs (no await). See Filesystem for the full API. Returns

Type	Description
`SandboxFs`	Filesystem handle

Instance methods

attach()

async def attach(cmd: str, args_or_options: list[str] | ExecOptions | None = None) -> int

Bridge your terminal directly to a process inside the sandbox for a fully interactive PTY session. Parameters

Name	Type	Description
cmd	`str`	Command to run
args_or_options	`list[str] \| ExecOptions \| None`	Command arguments or execution options

Returns

Type	Description
`int`	Exit code of the process

attach_shell()

async def attach_shell() -> int

Attach to the sandbox’s default shell. Returns

Type	Description
`int`	Exit code

detach()

async def detach() -> None

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

drain()

async def drain() -> None

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

exec()

async def exec(cmd: str, args_or_options: list[str] | ExecOptions | None = None) -> ExecOutput

Run a command inside the sandbox and wait for it to complete. Collects all stdout and stderr into memory and returns them along with the exit code. For long-running processes or large output, use exec_stream() instead. Parameters

Name	Type	Description
cmd	`str`	Command to execute (e.g. `"python"`, `"/usr/bin/node"`)
args_or_options	`list[str] \| ExecOptions \| None`	Command arguments (e.g. `["-c", "print('hello')"]`) or `ExecOptions`

Returns

Type	Description
`ExecOutput`	Collected stdout, stderr, and exit status

exec_stream()

async def exec_stream(cmd: str, args_or_options: list[str] | ExecOptions | None = None) -> ExecHandle

Run a command with streaming output. Returns a handle that emits stdout, stderr, and exit events as they happen, rather than buffering everything. Parameters

Name	Type	Description
cmd	`str`	Command to execute
args_or_options	`list[str] \| ExecOptions \| None`	Command arguments or `ExecOptions`

Returns

Type	Description
`ExecHandle`	Streaming handle for receiving events and controlling the process

kill()

async def kill() -> None

Force-terminate the sandbox immediately (SIGKILL). No graceful shutdown.

metrics()

async def metrics() -> SandboxMetrics

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

Type	Description
`SandboxMetrics`	CPU, memory, disk, network metrics

metrics_stream()

async def metrics_stream(interval: float = 1.0) -> MetricsStream

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

Name	Type	Description
interval	`float`	Seconds between metric snapshots (default `1.0`)

Returns

Type	Description
`MetricsStream`	Async stream of metrics

remove_persisted()

async def remove_persisted() -> None

Remove the sandbox and all its persisted state from disk.

shell()

async def shell(script: str) -> ExecOutput

Run a command through the sandbox’s configured shell (defaults to /bin/sh). Shell syntax like pipes, redirects, and && chains works. Parameters

Name	Type	Description
script	`str`	Shell command string (e.g. `"ls -la /app && echo done"`)

Returns

Type	Description
`ExecOutput`	Collected stdout, stderr, and exit status

shell_stream()

async def shell_stream(script: str) -> ExecHandle

Shell command with streaming output. Parameters

Name	Type	Description
script	`str`	Shell command string

Returns

Type	Description
`ExecHandle`	Streaming handle

stop()

async def stop() -> None

Gracefully shut down the sandbox (SIGTERM).

stop_and_wait()

async def stop_and_wait() -> tuple[int, bool]

Stop the sandbox and wait for the exit status. Returns

Type	Description
`tuple[int, bool]`	`(exit_code, success)` — `success` is `True` if exit code is `0`

wait()

async def wait() -> tuple[int, bool]

Block until the sandbox exits on its own. Returns

Type	Description
`tuple[int, bool]`	`(exit_code, success)` — `success` is `True` if exit code is `0`

Context manager

async with await Sandbox.create("my-sandbox", image="alpine") as sb:
    output = await sb.shell("echo hello")
    print(output.stdout_text)
# sandbox is automatically killed and removed on exit

Use Sandbox as an async context manager to ensure cleanup. On exit, the sandbox is killed and its persisted state is removed.

Types

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
`__aiter__`	`AsyncIterator[SandboxMetrics]`	Use with `async for`
`recv()`	`SandboxMetrics` `\| None`	Receive next snapshot. Returns `None` when the stream ends.

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

PullSession

Returned by Sandbox.create_with_progress(). Use as an async context manager to track image pull progress.

session = Sandbox.create_with_progress("my-sandbox", image="ubuntu:latest")
async with session:
    async for event in session.progress:
        print(event)
    sb = await session.result()

Property / Method	Type	Description
progress	`AsyncIterator[PullProgress]`	Async iterator of pull progress events
result()	`Awaitable[Sandbox]`	Await to get the final running sandbox

RegistryAuth

Private registry credentials.

Field	Type	Description
username	`str`	Registry username
password	`str`	Registry password

SandboxConfig

The keyword arguments accepted by Sandbox.create() and Sandbox.create_with_progress().

Field	Type	Default	Description
image	`str \| ImageSource`	-	OCI image, local path, or disk image (required)
cpus	`int`	`1`	Virtual CPUs
memory	`int`	`512`	Guest memory in MiB. This is a limit, not a reservation.
workdir	`str`	-	Default working directory for commands
shell	`str`	`"/bin/sh"`	Shell for `shell()` calls
hostname	`str`	-	Guest hostname
user	`str`	-	Default guest user
entrypoint	`list[str]`	-	Override image entrypoint
replace	`bool`	`False`	Replace existing sandbox with same name
max_duration	`float`	-	Maximum sandbox lifetime in seconds
idle_timeout	`float`	-	Idle timeout in seconds
env	`dict[str, str]`	`{}`	Environment variables visible to all commands
scripts	`dict[str, str]`	`{}`	Named scripts mounted at `/.msb/scripts/`
pull_policy	`str \| PullPolicy`	`"if-missing"`	Image pull behavior
log_level	`str \| LogLevel`	-	Override log verbosity
registry_auth	`RegistryAuth`	-	Private registry credentials
volumes	`dict[str, dict]`	`{}`	Volume mounts. See Volumes.
patches	`list[PatchConfig]`	`[]`	Rootfs modifications applied before boot
ports	`dict[int, int]`	`{}`	Port mappings (`host_port: guest_port`)
network	`Network`	`public_only`	Network policy and configuration
secrets	`list[SecretEntry]`	`[]`	Secret injection
detached	`bool`	`False`	If `True`, sandbox survives after your process exits

SandboxHandle

A lightweight handle to an existing sandbox (running or stopped). Obtained via Sandbox.get() or Sandbox.list(). Provides status, configuration, and lifecycle control without an active connection to the guest agent. Call .start() or .connect() to upgrade to a full Sandbox.

Property / Method	Type	Description
name	`str`	Sandbox name
status	`str`	Current status (`"running"`, `"stopped"`, `"crashed"`, `"draining"`, `"paused"`)
config_json	`str`	Raw JSON configuration
created_at	`float \| None`	Creation timestamp (ms since epoch)
updated_at	`float \| None`	Last update timestamp (ms since epoch)
connect()	`Awaitable[Sandbox]`	Connect to a running sandbox
start(*, detached=False)	`Awaitable[Sandbox]`	Start in attached or detached mode
stop()	`Awaitable[None]`	Graceful shutdown
kill()	`Awaitable[None]`	Force terminate
remove()	`Awaitable[None]`	Delete sandbox and state
metrics()	`Awaitable[SandboxMetrics]`	Point-in-time resource metrics

SandboxMetrics

Point-in-time resource usage snapshot.

Field	Type	Description
cpu_percent	`float`	CPU usage as a percentage
disk_read_bytes	`int`	Total bytes read from disk since boot
disk_write_bytes	`int`	Total bytes written to disk since boot
memory_bytes	`int`	Current memory usage in bytes
memory_limit_bytes	`int`	Memory limit in bytes
net_rx_bytes	`int`	Total bytes received over the network since boot
net_tx_bytes	`int`	Total bytes sent over the network since boot
timestamp_ms	`float`	When this measurement was taken (ms since epoch)
uptime_ms	`int`	Time since the sandbox was created (ms)

Getting Started

Rust SDK

TypeScript SDK

Python SDK

​Static methods

​Sandbox.create()

​Sandbox.create_with_progress()

​Sandbox.start()

​Sandbox.get()

​Sandbox.list()

​Sandbox.remove()

​Instance properties

​name

​owns_lifecycle

​fs

​Instance methods

​attach()

​attach_shell()

​detach()

​drain()

​exec()

​exec_stream()

​kill()

​metrics()

​metrics_stream()

​remove_persisted()

​shell()

​shell_stream()

​stop()

​stop_and_wait()

​wait()

​Context manager

​Types

​LogLevel

​MetricsStream

​PullPolicy

​PullSession

​RegistryAuth

​SandboxConfig

​SandboxHandle

​SandboxMetrics

Static methods

Sandbox.create()

Sandbox.create_with_progress()

Sandbox.start()

Sandbox.get()

Sandbox.list()

Sandbox.remove()

Instance properties

name

owns_lifecycle

fs

Instance methods

attach()

attach_shell()

detach()

drain()

exec()

exec_stream()

kill()

metrics()

metrics_stream()

remove_persisted()

shell()

shell_stream()

stop()

stop_and_wait()

wait()

Context manager

Types

LogLevel

MetricsStream

PullPolicy

PullSession

RegistryAuth

SandboxConfig

SandboxHandle

SandboxMetrics