Metadata-Version: 2.4
Name: mosaic-sandbox
Version: 0.8.1
Summary: Python SDK for Mosaic Sandbox (MAR)
Author: Mosaic
License: Proprietary
Project-URL: Homepage, https://sandbox.mosaicos.com
Project-URL: Documentation, https://sandbox.mosaicos.com/docs/
Project-URL: Support, https://sandbox.mosaicos.com/start/
Project-URL: Changelog, https://sandbox.mosaicos.com/roadmap/
Keywords: sandbox,firecracker,microvm,agent,cli,mcp,ssh
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tomli>=2.0.1; python_version < "3.11"

# Mosaic Sandbox Python SDK

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

Install:

```bash
python -m pip install mosaic-sandbox
```

Authenticate once with the CLI:

```bash
mos auth --token msk_live_...
mos whoami
```

Run the CLI smoke test:

```bash
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:

```bash
mos smoke
```

Python example:

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

```python
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"))
```

```python
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/>
