Mosaic Sandbox Python SDK

mosaic-sandbox is the Python SDK and CLI for Mosaic Sandbox, a Firecracker-based runtime for coding agents.

Install (Python 3.9 or newer):

python3 --version   # 3.9 or newer
python3 -m pip install mosaic-sandbox

Authenticate once with the CLI:

mos auth --token msk_live_...
mos whoami

Run the CLI smoke test:

mos doctor
mos run --template node-20 node -v
mos create --template node-20 --ssh
mos ssh <sandbox-id> --print-command

Or run the one-command first-run check:

mos smoke

Python example:

from mosaic_sandbox import Sandbox

sbx = Sandbox.create(
    template="node-20",
    endpoint="https://sandbox.mosaicos.com",
    api_token="msk_live_...",
    enable_ssh=False,
)

try:
    result = sbx.run_command("node -v")
    print(result.stdout)
    print(result.tti_ms)
finally:
    sbx.destroy()

Functions

A function is a name you keep for a one-shot run: a specification — template, command, secrets, network policy, resources, timeout — that lives in your code. Defining one makes no request and creates nothing to deploy or delete. Each invocation creates one isolated microVM, runs the command, and destroys it, so an idle function costs nothing.

from mosaic_sandbox import Function

thumbnail = Function(
    ["python", "-m", "thumbnail"],
    template="python-3.11",
    secrets=["OBJECT_STORE_TOKEN"],
    network={"allow": ["objects.mosaicos.com:443"]},
    timeout_ms=60_000,
)

result = thumbnail.invoke(env={"OBJECT_KEY": "images/input.jpg"})
print(result.stdout, result.sandbox_destroyed)

What the sandbox is stays fixed for every invocation. Only cwd, env, stdin, timeout_ms and idempotency_key may be passed per call; anything else raises rather than being silently ignored, so one call cannot widen another's secrets or egress. Retrying with the same idempotency_key replays the first invocation instead of running a second one.

Work that must outlive one synchronous call belongs in a process or job, and work that needs a URL belongs behind a preview.

Long-running attempts

Synchronous exec is capped at 900,000 ms (15 minutes). A durable process is owned by the sandbox rather than by the request that starts it, so persist the sandbox and process IDs and reconnect after a client restart. Its lifetime is bounded by its own timeout, when supplied, and by the sandbox TTL.

sbx = Sandbox.create(template="base", ttl_seconds=86_400)
try:
    started = sbx.process.start(["python", "-m", "train"])
    sandbox_id, process_id = sbx.id, started.id

    sbx = Sandbox.connect(sandbox_id)
    handle = next(p for p in sbx.process.list() if p.id == process_id)
    for chunk in handle.iter_logs():
        print(chunk["stdout"], end="")
    result = handle.wait()
finally:
    sbx.destroy()

A running process prevents hibernation; after it finishes, pause/resume works normally. Call handle.kill() to cancel it. The full Python, TypeScript, Go, CLI, and raw-HTTP recovery patterns are in the public documentation.

Image initialization is opt-in: sbx.startup("image") resolves image ENTRYPOINT + CMD, working directory, user and environment in the guest. Use sbx.startup("command", command=["/app/start", "literal argument"]) for literal argv; either mode accepts cwd, user and env overrides. Omitted startup or "none" does nothing. Sandbox.create(startup={"mode": "image"}) also opts in and destroys the sandbox if launch fails. Async methods have the same contract. Repeated calls reattach the durable startup handle rather than rerunning initialization, including on resume/fork. A process launch is not a readiness check; use the handle's status/logs or your application's healthcheck. Guest cwd supports absolute paths such as /app after privilege drop; relative cwd remains workspace-relative, and file API path permissions are unchanged.

LangChain and LlamaIndex tools

Give an agent a sandbox without writing tools for it. Neither framework is a dependency of this SDK; the one you use is imported when you ask for it.

from langchain.agents import create_react_agent
from mosaic_sandbox.integrations.langchain import mosaic_sandbox_tools

agent = create_react_agent(model, mosaic_sandbox_tools(template="python-3.11"))

from llama_index.core.agent import ReActAgent
from mosaic_sandbox.integrations.llamaindex import mosaic_sandbox_tools

agent = ReActAgent.from_tools(mosaic_sandbox_tools(), llm=llm)

The tools — mosaic_run_command, mosaic_run_python, mosaic_run_javascript, mosaic_read_file, mosaic_write_file, mosaic_list_files and mosaic_start_server — share one sandbox, created on the first call rather than when the agent is built. mosaic_start_server returns a public HTTPS preview URL, so "run the dev server and show me" is a single tool call.

Keyword arguments are Sandbox.create's, so snapshot_id= starts the agent in an environment you built earlier. Hold the SandboxToolset yourself if you want to close() it explicitly; close() destroys the sandbox it created but leaves a sandbox you passed in alone, and the toolset is spent either way — a later tool call raises rather than quietly starting a second machine.

Harbor environment provider

Custom-image environments capture CPU and memory at build time. To build an environment with 4 vCPUs and 8192 MB of memory, then restore it:

mos template create --image python:3.12-slim --vcpu 4 --memory-mb 8192 --name my-env-4cpu
mos create --snapshot my-env-4cpu

The same build flags work with --dockerfile. In Python, pass vcpu=4, memory_mb=8192 to Sandbox.create_environment. Supported CPU/memory pairs are listed by mos limits; unsupported pairs are rejected. An existing snapshot cannot be resized with mos create: rebuild under a new name at the required shape, then restore it without shape overrides.

Harbor 0.22 and newer can run its trials in Mosaic Sandbox through the first-party provider. Install the optional dependency on Python 3.12 or newer:

python -m pip install 'mosaic-sandbox[harbor]'

Point Harbor at the provider in the trial environment configuration:

[environment]
import_path = "mosaic_sandbox.integrations.harbor:MosaicEnvironment"

This explicit import path selects the SDK provider. A native provider bundled with Harbor is a separate implementation; record its import path and version when comparing results.

The SDK provider prepares upload/mount directories, then starts the image's ENTRYPOINT plus CMD with the task/trial startup environment, image user, and image working directory. Idle shell commands are skipped. The provider keyword image_command="never" disables startup; an argv list overrides the image command. keepalive=[...] is a literal argv alias for that override, and cannot be combined with a non-default image_command. Both delegate to the shared SDK startup primitive. Downloads similarly use the shared bounded file/archive APIs rather than guest split or whole-file reads. Startup launch errors and observed nonzero exits fail setup. Output and exit state are retained in mosaic-image-startup.jsonl in the trial directory, including successful short-lived initialization. Harbor's configured task healthcheck supplies bounded readiness retries; starting a process alone does not prove service readiness. The general Sandbox SDK still does not automatically execute image entrypoints.

Authenticate first with mos login. The provider builds each Docker image or Dockerfile environment once, keyed by its content hash, and starts one Mosaic snapshot replica builds per requested MOSAIC_HARBOR_REPLICAS (default 1) and starts one Mosaic sandbox per trial. Set that variable to an integer from 1 through 16 to spread named snapshot restores across hosts. The optional MOSAIC_HARBOR_TTL_SECONDS variable controls abandoned-trial cleanup and defaults to 3600. Mosaic supports Linux single-VM tasks, including no-network and public-IPv4/hostname allowlists, and Windows tasks; Docker Compose tasks are out of scope for this provider. A Firecracker guest can run Docker natively, so DinD-style tasks are a plausible follow-up.

A task with [environment].os = "windows" runs in a Windows Server sandbox (guest_os="windows") instead of a Windows container. Its Dockerfile is not built: the sandbox starts from the host's golden image, or from the snapshot named by MOSAIC_HARBOR_WINDOWS_SNAPSHOT (for example one with the task's apps installed). Commands run under cmd.exe as the desktop Administrator; the task workdir is created if missing, LOGS_DIR defaults to C:\logs, and cpus/memory_mb round up to the nearest Windows size (2/4, 2/8, 4/16 or 8/32 GiB). Windows tasks need public networking for now. Without a snapshot, a Windows task's docker_image or Dockerfile FROM must be mcr.microsoft.com/windows/servercore:ltsc2025 or windows/server:ltsc2025 (the golden image is Windows Server 2025); Harbor secrets, volumes, MOSAIC_HARBOR_PERSIST, SSH and image_command/keepalive overrides are refused rather than dropped.

BYOC in-VPC data plane

In an organization whose workload stays in its own VPC (see docs/byoc-data-plane.md), run_command and sandbox.files go straight to the sandbox host's private listener. The SDK mints and refreshes the sandbox-scoped token for you:

sandbox = Sandbox.connect(
    sandbox_id,
    data_plane=True,                      # or MOSAIC_DATA_PLANE=1
    data_plane_ca_bundle="/etc/ssl/private-ca.pem",  # or MOSAIC_DATA_PLANE_CA_BUNDLE
)
sandbox.run_command("make test")
sandbox.files.write("/workspace/out.txt", "...")

data_plane=True isn't required. The gateway marks a BYOC organization's answers, so handles from create, connect and list go to the host from the first call. A bare Sandbox(id) asks POST /v1/introspect once per key before its first exec or file call. No command or file is sent through the gateway either way. MOSAIC_DATA_PLANE=0 skips that question, and the gateway's 409 data_plane_required stays the backstop. Processes, streaming, prompts and fanout raise DataPlaneUnsupportedError for these sandboxes. From the CLI, mos exec <id> -- ... follows the marker as well. Pass --data-plane-ca-bundle PATH for the host's private CA.

Docs: https://sandbox.mosaicos.com/docs/