--- title: Sandbox description: Python 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.create()configure and boot a sandbox Sandbox.create_with_progress()boot with pull progress Sandbox.start()restart a stopped one Sandbox.get()handle to an existing one Sandbox.list()all sandboxes Sandbox.list_with()filter by labels Sandbox.remove()delete a stopped one

Properties3

sb.name()sandbox name (async method) sb.owns_lifecycleattached vs detached (async) sb.fsread / write files

Instance18

sb.exec()run a command sb.exec_stream()run, stream events sb.shell()run through a shell sb.shell_stream()shell, stream events sb.ssh()SSH client / server sb.attach()interactive PTY session sb.attach_shell()attach to the shell sb.metrics()resource snapshot sb.metrics_stream()stream metrics sb.logs()captured output sb.log_stream()stream / follow logs sb.stop()graceful shutdown sb.request_stop()request stop, don't wait sb.kill()force terminate sb.request_kill()signal kill, don't wait sb.request_drain()graceful drain sb.wait_until_stopped()block until it exits sb.detach()release, keep running

Patch factory · Patch7

Patch.text() Patch.append() Patch.mkdir() Patch.remove() Patch.copy_file() Patch.copy_dir() Patch.symlink()

Types

SandboxConfig InitConfig SecurityProfile SandboxHandle SandboxStopResult SandboxStatus SandboxMetrics MetricsStream LogEntry LogStream LogSource LogLevel PullPolicy RegistryAuth PatchConfig PullSession PullEvent

Typical flow

```python from microsandbox import Sandbox # 1. configure + 2. boot the microVM async with await Sandbox.create("api", image="python", memory=1024) as sb: # 3. run out = await sb.exec("python", ["-V"]) print(out.stdout_text) # 4. on exit the sandbox is killed and its state removed ``` ## Static methods --- #### Sandbox.create()
staticasync
```python @staticmethod async def create(name: str, **kwargs) -> Sandbox ``` Create and boot a sandbox. Keyword arguments provide individual config fields; see [`SandboxConfig`](#sandboxconfig) for the full set. Pulls the image if needed, boots the VM, starts the guest agent, and waits until it is ready to accept commands. Sandbox names must be non-empty and no longer than 128 UTF-8 bytes. The returned `Sandbox` is an async context manager. Use `async with` to guarantee cleanup; on exit the sandbox is killed and its persisted state removed.

Parameters

namestr
Sandbox name, up to 128 UTF-8 bytes.
**kwargsSandboxConfig
Configuration fields: image, cpus, memory, volumes, ports, network, secrets, detached, and more.

Returns

Sandbox
Running sandbox, usable as an async context manager.
```python 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 ``` --- #### Sandbox.create_with_progress()
static
```python @staticmethod def create_with_progress(name: str, **kwargs) -> PullSession ``` Same parameters as [`create()`](#sandbox-create) but returns a [`PullSession`](#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

namestr
Sandbox name, up to 128 UTF-8 bytes.
**kwargsSandboxConfig
Same configuration fields as create().

Returns

PullSession
Session for tracking pull progress and obtaining the final sandbox.
```python session = Sandbox.create_with_progress("my-sandbox", image="ubuntu:latest") async with session: async for event in session.progress: print(event.event_type) sb = await session.result() ``` --- #### Sandbox.start()
staticasync
```python @staticmethod async def start(name: str, *, detached: bool = False) -> Sandbox ``` Restart a previously stopped sandbox. The VM reboots using the persisted configuration.

Parameters

namestr
Name of a stopped sandbox, up to 128 UTF-8 bytes.
detachedbool
When True, the sandbox survives after your process exits. Default False.

Returns

Sandbox
Running sandbox.
```python sb = await Sandbox.start("api") ``` --- #### Sandbox.get()
staticasync
```python @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 without requiring a full connection to the guest agent.

Parameters

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

Returns

SandboxHandle
Handle with status and lifecycle control.
```python handle = await Sandbox.get("api") print(handle.status) ``` --- #### Sandbox.list()
staticasync
```python @staticmethod async def list() -> list[SandboxHandle] ``` List all sandboxes (running, stopped, and crashed).

Returns

list[SandboxHandle]
All sandbox handles.
```python for h in await Sandbox.list(): print(h.name, h.status) ``` --- #### Sandbox.list_with()
staticasync
```python @staticmethod async def list_with(*, labels: Mapping[str, str] | None = None) -> list[SandboxHandle] ``` List sandboxes filtered by label. Only sandboxes whose labels match every supplied key/value pair are returned.

Parameters

labelsMapping[str, str] | None
Label key/value pairs to match. None returns every sandbox, like list().

Returns

list[SandboxHandle]
Matching sandbox handles.
```python workers = await Sandbox.list_with(labels={"role": "worker"}) ``` --- #### Sandbox.remove()
staticasync
```python @staticmethod async def remove(name: str) -> None ``` 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

namestr
Sandbox name, up to 128 UTF-8 bytes.
```python await Sandbox.remove("api") ``` --- ## Instance properties --- #### sb.name
instanceasync
```python async def name(self) -> str ``` The sandbox name. This is an async method; call `await sb.name()`.

Returns

str
Sandbox name, up to 128 UTF-8 bytes.
```python print(await sb.name()) ``` --- #### sb.owns_lifecycle
propertyasync
```python @property async def owns_lifecycle(self) -> bool ``` Whether this handle owns the sandbox lifecycle. A sandbox returned directly by [`create()`](#sandbox-create) or [`start()`](#sandbox-start) owns lifecycle, including when created with `detached=True`, until you call [`detach()`](#sb-detach). Handles upgraded via [`SandboxHandle.connect()`](#sandboxhandle) do not own lifecycle. This is an async property; use `await sb.owns_lifecycle`.

Returns

bool
True if this handle owns the lifecycle.
--- #### sb.fs
property
```python @property def fs(self) -> SandboxFsOps ``` 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](/sdk/python/filesystem) for API details.

Returns

SandboxFsOps
Filesystem handle.
```python await sb.fs.write("/tmp/hello.txt", b"hi") ``` --- ## Instance methods Command execution (`exec`, `exec_stream`, `shell`, `shell_stream`) is documented on the [Execution](/sdk/python/execution) page; SSH (`ssh`) on the [SSH](/sdk/python/ssh) page. The lifecycle, attach, metrics, and logs methods follow. --- #### sb.attach()
instanceasync
```python async def attach( self, cmd: str, args: list[str] | None = None, *, cwd: str | None = None, user: str | None = None, env: Mapping[str, str] | None = None, detach_keys: str | None = None, ) -> int ``` Bridge your terminal directly to a process inside the sandbox for a fully interactive PTY session. Returns the process exit code once the session ends.

Parameters

cmdstr
Command to run.
argslist[str] | None
Command arguments.
cwdstr | None
Working directory.
userstr | None
Guest user.
envMapping[str, str] | None
Environment variables.
detach_keysstr | None
Custom detach key sequence.

Returns

int
Exit code of the process.
```python code = await sb.attach("python", ["-i"]) ``` --- #### sb.attach_shell()
instanceasync
```python async def attach_shell(self) -> int ``` Attach your terminal to the sandbox's default shell for an interactive session.

Returns

int
Exit code.
```python await sb.attach_shell() ``` --- #### sb.metrics()
instanceasync
```python async def metrics(self) -> SandboxMetrics ``` 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

SandboxMetrics
Resource metrics.
```python m = await sb.metrics() print(f"cpu {m.cpu_percent:.1f}% · mem {m.memory_bytes // 1_048_576} MiB") ``` --- #### sb.metrics_stream()
instanceasync
```python async def metrics_stream(self, interval: float = 1.0) -> MetricsStream ``` Stream resource metrics at a regular interval. The returned [`MetricsStream`](#metricsstream) supports both `recv()` and `async for`.

Parameters

intervalfloat
Seconds between metric snapshots. Default 1.0.

Returns

MetricsStream
Async stream yielding a snapshot each interval.
```python stream = await sb.metrics_stream(1.0) async for snapshot in stream: print(f"{snapshot.cpu_percent:.1f}%") ``` --- #### sb.logs()
instanceasync
```python async def logs( self, tail: int | None = None, since_ms: float | None = None, until_ms: float | None = None, sources: list[LogReadSource] | None = None, ) -> list[LogEntry] ``` 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"` as shorthand for all four. Timestamps are exposed as `float` ms since the Unix epoch (UTC) for parity with [`SandboxMetrics.timestamp_ms`](#sandboxmetrics).

Parameters

tailint | None
Show only the last N entries after other filters apply.
since_msfloat | None
Inclusive lower bound on entry timestamp (ms since epoch).
until_msfloat | None
Exclusive upper bound on entry timestamp (ms since epoch).
sourceslist[LogReadSource] | None
Sources to include. None = ["stdout", "stderr", "output"]. Add "system" to merge runtime/kernel diagnostics, or use "all" for all four.

Returns

list[LogEntry]
Matching entries in chronological order.
```python import time from microsandbox import Sandbox handle = await Sandbox.get("web") # Default — all user-program output, regardless of pipe/pty mode entries = await handle.logs() for e in entries: label = {"stdout": "OUT", "stderr": "ERR", "output": "PTY", "system": "SYS"}[e.source] print(f"[{e.timestamp_ms / 1000:.3f}] {label} {e.session_id}: {e.text().rstrip()}") # Filtered: last 50 entries from the past hour, including system lines recent = await handle.logs( tail=50, since_ms=(time.time() - 3600) * 1000, sources=["stdout", "stderr", "output", "system"], ) ``` --- #### sb.log_stream()
instanceasync
```python async def log_stream( self, sources: list[LogReadSource] | None = None, since_ms: float | None = None, from_cursor: str | None = None, until_ms: float | None = None, follow: bool = False, ) -> LogStream ``` Stream captured log entries as a [`LogStream`](#logstream). With `follow=True` the stream stays open and yields new entries as they are written, like `tail -f`. Resume an earlier stream by passing the [`cursor`](#logentry) of the last entry you saw as `from_cursor`. Also available on [`SandboxHandle`](#sandboxhandle).

Parameters

sourceslist[LogReadSource] | None
Sources to include. Same semantics as logs().
since_msfloat | None
Inclusive lower bound on entry timestamp (ms since epoch).
from_cursorstr | None
Resume after this opaque cursor (from a prior LogEntry.cursor).
until_msfloat | None
Exclusive upper bound on entry timestamp (ms since epoch).
followbool
When True, keep the stream open and yield new entries as they arrive. Default False.

Returns

LogStream
Async stream of log entries.
```python stream = await sb.log_stream(follow=True) async for entry in stream: print(entry.text().rstrip()) ``` --- #### sb.stop()
instanceasync
```python async def stop(self, timeout: float | None = None) -> None ``` 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 ten seconds by default; pass `timeout` to override the graceful shutdown window before force-kill escalation.

Parameters

timeoutfloat | None
Seconds to wait for graceful exit before force-kill. None uses the ten-second default.
```python await sb.stop() ``` --- #### sb.request_stop()
instanceasync
```python async def request_stop(self) -> None ``` Request graceful shutdown and return once the request is sent, without waiting for stopped state. Pair with [`wait_until_stopped()`](#sb-wait_until_stopped) when the caller needs to observe the terminal state. ```python await sb.request_stop() ``` --- #### sb.kill()
instanceasync
```python async def kill(self, timeout: float | None = None) -> None ``` 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()`](#sb-stop) for graceful shutdown that gives the workload a chance to flush.

Parameters

timeoutfloat | None
Seconds to wait for the stopped state to be observed.
```python await sb.kill() # SIGKILL, no graceful shutdown ``` --- #### sb.request_kill()
instanceasync
```python async def request_kill(self) -> None ``` Request force termination and return once the signal is sent, without waiting for stopped state. ```python await sb.request_kill() ``` --- #### sb.request_drain()
instanceasync
```python async def request_drain(self) -> None ``` 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. Useful for zero-downtime rotation of worker sandboxes. Use [`wait_until_stopped()`](#sb-wait_until_stopped) when the caller needs stopped-state observation. ```python await sb.request_drain() ``` --- #### sb.wait_until_stopped()
instanceasync
```python async def wait_until_stopped(self) -> SandboxStopResult ``` Block until the sandbox is observed in a terminal non-running state, without triggering a stop or kill request.

Returns

SandboxStopResult
Terminal status and optional observed exit code.
```python result = await sb.wait_until_stopped() print(result.status, result.exit_code) ``` --- #### sb.detach()
instanceasync
```python async def detach(self) -> None ``` Release the handle without stopping the sandbox. The sandbox continues running as a background process. Reconnect later with [`Sandbox.get()`](#sandbox-get). ```python sb = await Sandbox.create("worker", image="python", detached=True) await sb.detach() # keeps running in the background ``` --- ## Patch Factory class for rootfs patches passed to `Sandbox.create(..., patches=[...])`. Each static method returns a [`PatchConfig`](#patchconfig). By default a patch 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. --- #### Patch.text()
factorystatic
```python @staticmethod def text(path: str, content: str, *, mode: int | None = None, replace: bool = False) -> PatchConfig ``` Write UTF-8 text content at `path`.

Parameters

pathstr
Absolute path inside the guest.
contentstr
Text content.
modeint | None
File mode, e.g. 0o644.
replacebool
When True, overwrite an existing path.
```python from microsandbox import Patch, Sandbox sb = await Sandbox.create( "api", image="python", patches=[Patch.text("/etc/app.conf", "debug=1\n", mode=0o644)], ) ``` --- #### Patch.append()
factorystatic
```python @staticmethod def append(path: str, content: str) -> PatchConfig ``` Append `content` to an existing file at `path`. If the file lives in a lower image layer, it's copied up first.

Parameters

pathstr
Absolute path inside the guest.
contentstr
Text to append.
--- #### Patch.mkdir()
factorystatic
```python @staticmethod def mkdir(path: str, *, mode: int | None = None) -> PatchConfig ``` Create a directory at `path`. Idempotent: a no-op if the directory already exists.

Parameters

pathstr
Absolute path inside the guest.
modeint | None
Directory mode, e.g. 0o755.
--- #### Patch.remove()
factorystatic
```python @staticmethod def remove(path: str) -> PatchConfig ``` Delete a file or directory at `path`. Idempotent: a no-op if the path doesn't exist.

Parameters

pathstr
Absolute path inside the guest.
--- #### Patch.copy_file()
factorystatic
```python @staticmethod def copy_file(src: str, dst: str, *, mode: int | None = None, replace: bool = False) -> PatchConfig ``` Copy a single host file at `src` into the guest rootfs at `dst`.

Parameters

srcstr
Host source file.
dststr
Absolute destination path inside the guest.
modeint | None
File mode, e.g. 0o644. None keeps the source mode.
replacebool
When True, overwrite an existing path at dst.
--- #### Patch.copy_dir()
factorystatic
```python @staticmethod def copy_dir(src: str, dst: str, *, replace: bool = False) -> PatchConfig ``` Recursively copy a host directory at `src` into the guest rootfs at `dst`.

Parameters

srcstr
Host source directory.
dststr
Absolute destination path inside the guest.
replacebool
When True, overwrite an existing path at dst.
--- #### Patch.symlink()
factorystatic
```python @staticmethod def symlink(target: str, link: str, *, replace: bool = False) -> PatchConfig ``` Create a symlink at `link` pointing to `target`.

Parameters

targetstr
What the symlink points to (literal symlink target text).
linkstr
Absolute path of the symlink itself.
replacebool
When True, overwrite an existing path at link.
--- ## Types ### SandboxConfig
kwargs

Used by create() · create_with_progress()

The keyword arguments accepted by [`create()`](#sandbox-create) and [`create_with_progress()`](#sandbox-create_with_progress). There is no `SandboxConfig` object you construct directly; these are passed as `**kwargs`. | Field | Type | Default | Description | |-------|------|---------|-------------| | image | `str \| `[`ImageSource`](/sdk/python/snapshots) | - | OCI image, local path, or disk image. Required unless `snapshot=` is passed. Use `Image.oci("python:3.12", upper_size_mib=8192)` to set an OCI upper size | | snapshot | `str \| os.PathLike` | - | Snapshot artifact to boot from instead of `image=`. Mutually exclusive with `image=` | | cpus | `int` | `1` | Virtual CPUs. This is a limit, not a reservation | | 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 | | security | [`SecurityProfile`](#securityprofile) `\| str` | `"default"` | In-guest security profile. `"restricted"` sets `no_new_privs`, drops mount-admin capability from user commands, and forces `nosuid,nodev` on user mounts | | hostname | `str` | - | Guest hostname | | user | `str` | - | Default guest user | | entrypoint | `list[str]` | - | Override the image's stored ENTRYPOINT. Consulted by `msb exec` / `msb run` (CLI command resolution), **not** by `sb.exec` / `sb.shell` which pass `cmd` literally | | init | `str \| dict \| `[`InitConfig`](#initconfig) | - | Hand off PID 1 to a guest init binary. See [Custom init system](/sandboxes/customize#custom-init-system) and [`InitConfig`](#initconfig) for accepted shapes | | replace | `bool` | `False` | Replace an existing sandbox with the same name (10s SIGTERM grace, then SIGKILL) | | replace_with_timeout | `float` | `10` | Seconds to wait after `SIGTERM` before escalating to `SIGKILL` (`0` skips `SIGTERM`). Implies `replace=True` | | 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/` and added to `PATH` | | pull_policy | `str \| `[`PullPolicy`](#pullpolicy) | `"if-missing"` | Image pull behavior | | log_level | `str \| `[`LogLevel`](#loglevel) | - | Override log verbosity | | registry_auth | [`RegistryAuth`](#registryauth) | - | Private registry credentials | | volumes | `dict[str, `[`MountConfig`](/sdk/python/volumes)`]` | `{}` | Volume mounts. See [Volumes](/sdk/python/volumes) | | patches | `list[`[`PatchConfig`](#patchconfig)`]` | `[]` | Rootfs modifications applied before boot | | ports | `dict[int, int] \| Sequence[`[`PortBinding`](/sdk/python/networking#portbinding)`]` | `{}` | Port mappings. Dict form is TCP and binds to `127.0.0.1`; use `PortBinding` for explicit bind addresses or UDP | | network | [`Network`](/sdk/python/networking#network) | `public_only` | Network policy and configuration | | secrets | `list[`[`SecretEntry`](/sdk/python/secrets#secretentry)`]` | `[]` | Secret injection | | detached | `bool` | `False` | If `True`, spawn the sandbox in detached mode; call [`detach()`](#sb-detach) before dropping the returned handle when it should keep running | ### InitConfig
dataclass

Used by create(init=...)

Custom init specification. Pass it (or one of the equivalent shorthand shapes) as the `init=` kwarg to [`create()`](#sandbox-create) to hand PID 1 inside the guest off to your own init binary after agentd's setup. Frozen dataclass. See [Custom init system](/sandboxes/customize#custom-init-system) for image picks, shutdown semantics, and tradeoffs. | Field | Type | Default | Description | |-------|------|---------|-------------| | cmd | `str` | - | Absolute path or `"auto"` to the init binary. Auto honors a known image ENTRYPOINT init before probing `/sbin/init`, `/lib/systemd/systemd`, and `/usr/lib/systemd/systemd`, and preserves attached init-entrypoint commands | | args | `tuple[str, ...]` | `()` | Supplemental argv (`argv[0]` is implicitly `cmd`) | | env | `Mapping[str, str]` | `{}` | Extra env vars merged on top of the inherited env | The `init=` kwarg follows the same shape as other structured `create` kwargs: a bare scalar for the simple case, or a dataclass / dict for the rich case. | Form | Equivalent to | |------|---------------| | `init="auto"` or `init="/sbin/init"` | `InitConfig(cmd=...)` | | `init={"cmd": ..., "args": [...], "env": {...}}` | dict equivalent of `InitConfig` | | `init=InitConfig(cmd="/sbin/init", args=("--foo",))` | itself | ```python from microsandbox import InitConfig, Sandbox # Common case: bare string. sb = await Sandbox.create("worker", image="jrei/systemd-debian:12", init="auto") # Argv / env: dataclass. sb = await Sandbox.create( "worker", image="jrei/systemd-debian:12", init=InitConfig( cmd="/lib/systemd/systemd", args=("--unit=multi-user.target",), env={"container": "microsandbox"}, ), ) ``` ### SecurityProfile
enum

Used by create(security=...)

Sandbox-wide in-guest security profile. A `StrEnum`, so the string values are accepted directly. | Value | Description | |-------|-------------| | `"default"` | Standard profile | | `"restricted"` | Sets `no_new_privs`, drops mount-admin capability from user commands, and forces `nosuid,nodev` on user mounts | ### SandboxHandle
class

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

A lightweight handle to an existing sandbox (running or stopped). Provides status, configuration, and lifecycle control **without** an active connection to the guest agent. You cannot `exec` or `fs` on a handle; call `.start()` or `.connect()` to upgrade to a full [`Sandbox`](#instance-methods). | Property / Method | Type | Description | |-------------------|------|-------------| | name | `str` | Sandbox name, up to 128 UTF-8 bytes | | status | `str` | Current status. See [`SandboxStatus`](#sandboxstatus) | | 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) | | config() | `dict[str, Any]` | Parsed configuration | | refresh() | `Awaitable[`[`SandboxHandle`](#sandboxhandle)`]` | Re-fetch status and metadata, returning a fresh handle | | connect(timeout=None) | `Awaitable[`[`Sandbox`](#instance-methods)`]` | Connect to a running sandbox, optionally with an explicit timeout in seconds | | start(*, detached=False) | `Awaitable[`[`Sandbox`](#instance-methods)`]` | Start in attached or detached mode | | stop(timeout=None) | `Awaitable[None]` | Gracefully shut down and wait until stopped state is observed | | request_stop() | `Awaitable[None]` | Request graceful shutdown without waiting | | kill(timeout=None) | `Awaitable[None]` | Force terminate and wait until stopped state is observed | | request_kill() | `Awaitable[None]` | Request force termination without waiting | | request_drain() | `Awaitable[None]` | Request graceful drain without waiting | | wait_until_stopped() | `Awaitable[`[`SandboxStopResult`](#sandboxstopresult)`]` | Block until the sandbox reaches terminal state | | remove() | `Awaitable[None]` | Delete sandbox and state | | metrics() | `Awaitable[`[`SandboxMetrics`](#sandboxmetrics)`]` | Point-in-time resource metrics | | logs(...) | `Awaitable[list[`[`LogEntry`](#logentry)`]]` | Read captured `exec.log` (works without starting) | | log_stream(...) | `Awaitable[`[`LogStream`](#logstream)`]` | Stream captured log entries (works without starting) | | snapshot(name) | `Awaitable[Snapshot]` | Create a named [snapshot](/sdk/python/snapshots) of the sandbox | | snapshot_to(path) | `Awaitable[Snapshot]` | Create a [snapshot](/sdk/python/snapshots) at a path | ### SandboxStopResult
class

Returned by wait_until_stopped()

Observed terminal sandbox state returned by [`wait_until_stopped()`](#sb-wait_until_stopped). | Property | Type | Description | |----------|------|-------------| | name | `str` | Sandbox name | | status | `str` | Terminal status that was observed. See [`SandboxStatus`](#sandboxstatus) | | exit_code | `int \| None` | Process exit code when it is available | | signal | `int \| None` | Terminating signal number when the sandbox was killed by a signal | | observed_at | `float` | When the terminal state was observed (ms since epoch) | | source | `str \| None` | Where the terminal observation came from | ### SandboxStatus
enum

Used by SandboxHandle.status · SandboxStopResult.status

The string status values a sandbox can report. A `StrEnum`, exposed as plain strings on `status` fields. | 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 | | `"paused"` | VM paused | ### SandboxMetrics
class

Returned by metrics() · metrics_stream()

Point-in-time resource usage snapshot. | Field | Type | Description | |-------|------|-------------| | cpu_percent | `float` | CPU usage as a percentage | | vcpu_time_ns | `int` | Cumulative vCPU time consumed since boot, in nanoseconds | | memory_bytes | `int` | Current memory usage in bytes | | memory_available_bytes | `int \| None` | Guest-reported available memory in bytes when known | | memory_host_resident_bytes | `int \| None` | Host-resident memory backing the guest in bytes when known | | memory_limit_bytes | `int` | Memory limit in bytes | | disk_read_bytes | `int` | Total bytes read from disk since boot | | disk_write_bytes | `int` | Total bytes written to disk since boot | | net_rx_bytes | `int` | Total bytes received over the network since boot | | net_tx_bytes | `int` | Total bytes sent over the network since boot | | upper_used_bytes | `int \| None` | Guest-visible OCI upper filesystem used bytes when the protected reporter is available and fresh | | upper_free_bytes | `int \| None` | Guest-visible OCI upper filesystem free bytes when the protected reporter is available and fresh | | upper_host_allocated_bytes | `int \| None` | Host-allocated bytes for the writable OCI upper image when available | | uptime_ms | `int` | Time since the sandbox was created (ms) | | timestamp_ms | `float` | When this measurement was taken (ms since epoch) | ### MetricsStream
class

Returned by metrics_stream()

Async stream for receiving periodic metrics snapshots. | Method | Returns | Description | |--------|---------|-------------| | `__aiter__` / `__anext__` | [`SandboxMetrics`](#sandboxmetrics) | Use with `async for` | ### LogEntry
class

Returned by logs() · iterated from LogStream

A single captured log entry returned by [`logs()`](#sb-logs) or iterated from a [`LogStream`](#logstream). | Property / Method | Type | Description | |-------------------|------|-------------| | timestamp_ms | `float` | Wall-clock capture time (ms since Unix epoch, UTC) | | source | [`LogSource`](#logsource) | Where the chunk came from | | session_id | `int \| None` | Relay-monotonic session id; `None` for `"system"` entries | | cursor | `str` | Opaque resume token; pass back via `log_stream(from_cursor=...)` | | data | `bytes` | The chunk's raw bytes | | text() | `str` | Convenience: UTF-8 decode of `data` (lossy; invalid bytes are replaced) | ### LogStream
class

Returned by log_stream()

Async stream of [`LogEntry`](#logentry) values, returned by [`log_stream()`](#sb-log_stream). | Method | Returns | Description | |--------|---------|-------------| | `__aiter__` / `__anext__` | [`LogEntry`](#logentry) | Use with `async for` | ### LogSource
literal

Used by LogEntry.source · logs(sources=...)

The string values the `source` field on a [`LogEntry`](#logentry) can take, also accepted by `logs(sources=[...])` and `log_stream(sources=[...])`. The read form additionally accepts `"all"`. | 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 | | `"all"` | Read shorthand for all four sources (accepted by `sources=`, never returned on an entry) | ### LogLevel
enum

Used by create(log_level=...)

Sandbox process log verbosity. A `StrEnum`, so the string values are accepted directly. | Value | Description | |-------|-------------| | `"trace"` | Most verbose, all diagnostic output | | `"debug"` | Debug and higher | | `"info"` | Info and higher | | `"warn"` | Warnings and errors only | | `"error"` | Errors only | ### PullPolicy
enum

Used by create(pull_policy=...)

Controls when the SDK fetches an OCI image from the registry. A `StrEnum`, so the string values are accepted directly. | 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 | ### RegistryAuth
dataclass

Used by create(registry_auth=...)

Credentials for authenticating to a private container registry. Frozen dataclass; construct directly or via `RegistryAuth.basic(username, password)`. | Field | Type | Description | |-------|------|-------------| | username | `str` | Registry username | | password | `str` | Registry password | ### PatchConfig
dataclass

Returned by Patch.* factory methods · used by create(patches=...)

A single rootfs patch. Produced by the [`Patch`](#patch) factory; you'd normally not construct one directly. Frozen dataclass. | Field | Type | Description | |-------|------|-------------| | kind | `str` | One of `"text"`, `"file"`, `"copy_file"`, `"copy_dir"`, `"symlink"`, `"mkdir"`, `"remove"`, `"append"` | | path | `str \| None` | Absolute guest path (text / mkdir / remove / append) | | content | `str \| None` | Text content (text / append) | | src | `str \| None` | Host source path (copy_file / copy_dir) | | dst | `str \| None` | Guest destination path (copy_file / copy_dir) | | target | `str \| None` | Symlink target | | link | `str \| None` | Symlink path | | mode | `int \| None` | File / directory mode (e.g. `0o644`) | | replace | `bool` | When `True`, overwrite an existing path at the destination. Defaults to `False` | ### PullSession
class

Returned by create_with_progress()

Returned by [`create_with_progress()`](#sandbox-create_with_progress). The factory itself is synchronous; use the returned session as an async context manager to track image pull progress. | Property / Method | Type | Description | |-------------------|------|-------------| | progress | `AsyncIterator[`[`PullEvent`](#pullevent)`]` | Async iterator of pull progress events | | result() | `Awaitable[`[`Sandbox`](#instance-methods)`]` | Await once to get the final running sandbox. A second call raises `RuntimeError` | ```python 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() ``` ### PullEvent
class

Iterated from PullSession.progress

Native event object emitted by [`PullSession.progress`](#pullsession). Inspect `event_type` and the fields relevant to that event; fields that do not apply to a particular event are `None`. | Field | Type | Description | |-------|------|-------------| | event_type | `str` | Event tag, e.g. `"resolving"`, `"resolved"`, `"layer_download_progress"`, `"complete"` | | reference | `str \| None` | Image reference being pulled | | manifest_digest | `str \| None` | Resolved manifest digest | | layer_count | `int \| None` | Number of layers | | total_download_bytes | `int \| None` | Total bytes to download across layers | | layer_index | `int \| None` | Index of the layer this event concerns | | digest | `str \| None` | Layer blob digest | | diff_id | `str \| None` | Layer diff id | | downloaded_bytes | `int \| None` | Bytes downloaded so far for the layer | | total_bytes | `int \| None` | Total bytes for the layer | | bytes_read | `int \| None` | Bytes read during materialization | ```python session = Sandbox.create_with_progress("my-sandbox", image="ubuntu:latest") async with session: async for event in session.progress: if event.event_type == "resolved": print(f"{event.layer_count} layers, {event.total_download_bytes} bytes") elif event.event_type == "layer_download_progress": print(f"layer {event.layer_index}: {event.downloaded_bytes}/{event.total_bytes}") sb = await session.result() ```