Mosaic Sandbox Python SDK

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

Install:

python -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.

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

Release files for mosaic-sandbox 0.10.0

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.10.0
File	Size	Uploaded
mosaic_sandbox-0.10.0.tar.gz	163.9 kB	Aug 22, 2026	Details

Built distribution (wheel)

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

Total release size: 284.8 kB

Release files / mosaic_sandbox-0.10.0.tar.gz

Download URL	mosaic_sandbox-0.10.0.tar.gz
Size	163.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`cba98bacd6e282be425f92573581b89e3d4d7b57714fcf5bbac7dc7e4bc5295d`
BLAKE2b-256 checksum How to use checksums	`92aebf5816674f9f52fc476bf161910fb45c66b40e5a10413e8bcc6e6efe5e4a`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

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

Download URL	mosaic_sandbox-0.10.0-py3-none-any.whl
Size	120.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`667bbcc0fa5cacc613213df659f6dd3fec64d4375e825d3f4fca3f5e4feace64`
BLAKE2b-256 checksum How to use checksums	`63b2ace772a2c2ca1e63092aa36ba5cc28ce0b28340e3887133e3b856aea8915`
Upload date	Aug 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`