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

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

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"

Authenticate first with mos login. The provider builds each Docker image or Dockerfile environment once, keyed by its content hash, and starts one Mosaic sandbox per trial. Mosaic currently supports Linux single-VM tasks, including no-network and public-IPv4/hostname allowlists; Docker Compose and Windows tasks are out of scope for this provider. A Firecracker guest can run Docker natively, so DinD-style tasks are a plausible follow-up.

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

Release files for mosaic-sandbox 0.12.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mosaic-sandbox 0.12.1
File	Size	Uploaded
mosaic_sandbox-0.12.1.tar.gz	194.1 kB	Aug 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for mosaic-sandbox 0.12.1
File	Interpreter	ABI	Platform	Reset
mosaic_sandbox-0.12.1-py3-none-any.whl 138.4 kB Aug 25, 2026	Python 3	none	any	Details

Total release size: 332.6 kB

Release files / mosaic_sandbox-0.12.1.tar.gz

Download URL	mosaic_sandbox-0.12.1.tar.gz
Size	194.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`b23959e1bd1c5e5342edc50689d01241958f5e6f9b9d2c0b397022c6b5b0b3f2`
BLAKE2b-256 checksum How to use checksums	`d8a1d6048b394611ab383644bd13d35a592ea45db1d64899d3f664adac114772`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.8`

Release files / mosaic_sandbox-0.12.1-py3-none-any.whl

Download URL	mosaic_sandbox-0.12.1-py3-none-any.whl
Size	138.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`be52177366a093f94e3b69cff797c9b89878ce6197887bc0b09b639bf006bf94`
BLAKE2b-256 checksum How to use checksums	`d54d52696a156146be2b3ab918d55c686ee1ca2d3bc34c4857c513b9463a81c5`
Upload date	Aug 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.8`