Sandbox

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

Returns

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

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

Returns

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

Returns

Sandbox.list()

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

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

Returns

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

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

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

Returns

attach_shell()

async def attach_shell() -> int

Attach to the sandbox's default shell.

Returns

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

Returns

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

Returns

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

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

Returns

logs()

async def logs(
    tail: int | None = None,
    since_ms: float | None = None,
    until_ms: float | None = None,
    sources: list[str] | 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 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.

import asyncio
import microsandbox

async def main():
    handle = await microsandbox.Sandbox.get("web")

    # Default — all user-program output, regardless of pipe/pty mode
    entries = await handle.logs()

    for e in entries:
        source = {
            "stdout": "OUT",
            "stderr": "ERR",
            "output": "PTY",
            "system": "SYS",
        }[e.source]
        print(
            f"[{e.timestamp_ms / 1000:.3f}] "
            f"{source} {e.session_id}: {e.text().rstrip()}"
        )

    # Filtered: last 50 entries from the past hour, including system lines
    import time
    recent = await handle.logs(
        tail=50,
        since_ms=(time.time() - 3600) * 1000,
        sources=["stdout", "stderr", "output", "system"],
    )

asyncio.run(main())

Timestamps are exposed as float ms since the Unix epoch (UTC) for parity with SandboxMetrics.timestamp_ms. Convert to datetime if needed:

from datetime import datetime, timezone
dt = datetime.fromtimestamp(e.timestamp_ms / 1000, timezone.utc)

Parameters

Returns

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

Returns

shell_stream()

async def shell_stream(script: str) -> ExecHandle

Shell command with streaming output.

Parameters

Returns

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

wait()

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

Block until the sandbox exits on its own.

Returns

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.

LogEntry

A single captured log entry returned by logs().

LogSource

The string values that the source field on a LogEntry can take, also accepted by logs(sources=[...]).

In addition, logs(sources=["all"]) is a shorthand for all four.

MetricsStream

Async stream for receiving periodic metrics snapshots.

PullPolicy

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

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()

RegistryAuth

Private registry credentials.

SandboxConfig

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

InitConfig

Guest init-handoff specification. Pass it (or one of the equivalent shorthand shapes) as the init= kwarg to Sandbox.create() to hand PID 1 inside the guest off to your own init binary after agentd's setup. See Init handoff for image picks, shutdown semantics, and tradeoffs.

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class InitConfig:
    cmd: str
    args: tuple[str, ...] = ()
    env: Mapping[str, str] = {}

The init= kwarg follows the same shape as other Sandbox.create kwargs that carry structured values (image=, network=, etc.): a bare scalar for the simple case, or a dataclass / dict for the rich case.

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"},
    ),
)

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.

SandboxMetrics

Point-in-time resource usage snapshot.