mosaic-sandbox 0.1.0__tar.gz

mosaic_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,67 @@
+Metadata-Version: 2.4
+Name: mosaic-sandbox
+Version: 0.1.0
+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: Repository, https://github.com/nitinrao/Mosaic-Sandbox
+Project-URL: Issues, https://github.com/nitinrao/Mosaic-Sandbox/issues
+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
+
+# 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
+```
+
+Set your endpoint and API token:
+
+```bash
+export MAR_ENDPOINT=https://sandbox.mosaicos.com
+export MAR_API_TOKEN=msk_live_...
+```
+
+Run the CLI smoke test:
+
+```bash
+mar doctor
+mar run --template node-20 node -v
+```
+
+Python example:
+
+```python
+from mosaic_sandbox import Sandbox
+
+sbx = Sandbox.create(
+    template="node-20",
+    endpoint="https://sandbox.mosaicos.com",
+    api_token="msk_live_..."
+)
+
+try:
+    result = sbx.run_command("node -v")
+    print(result.stdout)
+    print(result.tti_ms)
+finally:
+    sbx.destroy()
+```
+
+Docs: <https://sandbox.mosaicos.com/docs/>

mosaic_sandbox-0.1.0/README.md

@@ -0,0 +1,45 @@
+# 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
+```
+
+Set your endpoint and API token:
+
+```bash
+export MAR_ENDPOINT=https://sandbox.mosaicos.com
+export MAR_API_TOKEN=msk_live_...
+```
+
+Run the CLI smoke test:
+
+```bash
+mar doctor
+mar run --template node-20 node -v
+```
+
+Python example:
+
+```python
+from mosaic_sandbox import Sandbox
+
+sbx = Sandbox.create(
+    template="node-20",
+    endpoint="https://sandbox.mosaicos.com",
+    api_token="msk_live_..."
+)
+
+try:
+    result = sbx.run_command("node -v")
+    print(result.stdout)
+    print(result.tti_ms)
+finally:
+    sbx.destroy()
+```
+
+Docs: <https://sandbox.mosaicos.com/docs/>

mosaic_sandbox-0.1.0/mosaic_sandbox/__init__.py

@@ -0,0 +1,6 @@
+"""Low-overhead client for the Mosaic Sandbox daemon."""
+__version__ = "0.1.0"
+
+from .client import AsyncProcessHandle, AsyncSandbox, ExecutionResult, FileInfo, Preview, ProcessHandle, ProcessInfo, Sandbox, Snapshot
+
+__all__ = ["AsyncProcessHandle", "AsyncSandbox", "ExecutionResult", "FileInfo", "Preview", "ProcessHandle", "ProcessInfo", "Sandbox", "Snapshot", "__version__"]

mosaic_sandbox-0.1.0/mosaic_sandbox/cli.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shlex
+import sys
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .client import ProcessHandle, ProcessInfo, Sandbox
+from .migration import PROVIDER_INDEX, assess as assess_migration
+from .migration import list_providers, plan as plan_migration
+
+
+DEFAULT_ENDPOINT = os.environ.get("MAR_ENDPOINT", "http://127.0.0.1:8080")
+
+
+def _request(args: argparse.Namespace, path: str, payload: dict[str, Any] | None = None, method: str = "GET") -> dict[str, Any]:
+    return Sandbox._request(
+        args.endpoint,
+        path,
+        payload or {},
+        method=method,
+        api_token=args.token,
+    )
+
+
+def _emit(value: Any, *, raw: bool = False) -> None:
+    if raw and isinstance(value, str):
+        sys.stdout.write(value)
+        if value and not value.endswith("\n"):
+            sys.stdout.write("\n")
+        return
+    print(json.dumps(value, indent=2, sort_keys=True))
+
+
+def _sandbox(args: argparse.Namespace) -> Sandbox:
+    return Sandbox(args.id, args.endpoint, args.token)
+
+
+def _command(parts: list[str]) -> str:
+    if parts[:1] == ["--"]:
+        parts = parts[1:]
+    if not parts:
+        raise ValueError("a command is required")
+    return shlex.join(parts)
+
+
+def _load_manifest(path: str) -> dict[str, Any]:
+    raw = sys.stdin.read() if path == "-" else Path(path).read_text()
+    value = json.loads(raw)
+    if not isinstance(value, dict):
+        raise ValueError("migration manifest must be a JSON object")
+    return value
+
+
+def _ssh_key(args: argparse.Namespace) -> str | None:
+    path = getattr(args, "ssh_public_key_file", None)
+    return Path(path).expanduser().read_text().strip() if path else None
+
+
+def _sandbox_created(sandbox: Sandbox) -> dict[str, Any]:
+    return {
+        "id": sandbox.id,
+        "state": "running",
+        "tti_ms": sandbox._create_tti_ms,
+        "ssh_connection_string": sandbox.ssh_connection_string,
+        "ssh_host": sandbox.ssh_host,
+        "ssh_port": sandbox.ssh_port,
+        "ssh_private_key_path": sandbox.ssh_private_key_path,
+        "ssh_known_hosts_path": sandbox.ssh_known_hosts_path,
+    }
+
+
+def _agent_config(client: str, endpoint: str) -> str:
+    if client == "codex":
+        return (
+            "[mcp_servers.mosaic_sandbox]\n"
+            'command = "mar"\n'
+            'args = ["mcp"]\n\n'
+            "[mcp_servers.mosaic_sandbox.env]\n"
+            f'MAR_ENDPOINT = "{endpoint}"\n'
+        )
+    config = {
+        "mcpServers": {
+            "mosaic-sandbox": {
+                "command": "mar",
+                "args": ["mcp"],
+                "env": {"MAR_ENDPOINT": endpoint},
+            }
+        }
+    }
+    if client == "cursor":
+        return json.dumps(config, indent=2) + "\n"
+    payload = json.dumps(
+        {
+            "type": "stdio",
+            "command": "mar",
+            "args": ["mcp"],
+            "env": {"MAR_ENDPOINT": endpoint},
+        },
+        separators=(",", ":"),
+    )
+    return (
+        "claude mcp add-json mosaic-sandbox "
+        + shlex.quote(payload)
+        + " --scope project\n"
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="mar",
+        description="Mosaic Sandbox CLI and MCP server for coding agents.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT, help="MAR REST endpoint")
+    parser.add_argument("--token", default=os.environ.get("MAR_API_TOKEN"), help="Bearer token; prefer MAR_API_TOKEN")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    create = sub.add_parser("create", help="Create a sandbox")
+    create.add_argument("--template", default="node-20")
+    create.add_argument("--memory-mb", type=int, default=4096)
+    create.add_argument("--vcpu", type=int, default=2)
+    create.add_argument("--no-ssh", action="store_true", help="Disable the default SSH endpoint")
+    create.add_argument("--ssh-public-key-file", help="Public key to install instead of generating a temporary keypair")
+    create.add_argument("--ssh-private-key", help="Local private key matching --ssh-public-key-file")
+
+    execute = sub.add_parser("exec", help="Execute a command in an existing sandbox")
+    execute.add_argument("--cwd")
+    execute.add_argument("--env", action="append", default=[], metavar="NAME=VALUE")
+    execute.add_argument("--stdin")
+    execute.add_argument("id")
+    execute.add_argument("cmd", nargs=argparse.REMAINDER)
+    execute.add_argument("--timeout-ms", type=int)
+
+    run = sub.add_parser("run", help="Create, execute, and destroy a sandbox")
+    run.add_argument("--template", default="node-20")
+    run.add_argument("--memory-mb", type=int, default=4096)
+    run.add_argument("--vcpu", type=int, default=2)
+    run.add_argument("--timeout-ms", type=int)
+    run.add_argument("--cwd")
+    run.add_argument("--env", action="append", default=[], metavar="NAME=VALUE")
+    run.add_argument("--stdin")
+    run.add_argument("--keep", action="store_true", help="Keep the sandbox after execution")
+    run.add_argument("cmd", nargs=argparse.REMAINDER)
+
+    for name in ("info", "pause", "resume", "destroy"):
+        lifecycle = sub.add_parser(name, help=f"{name.capitalize()} a sandbox")
+        lifecycle.add_argument("id")
+
+    sub.add_parser("health", help="Check daemon health")
+    sub.add_parser("metrics", help="Read runtime metrics")
+    sub.add_parser("mcp", help="Run the MCP stdio server")
+
+    files = sub.add_parser("files", help="Read and modify /workspace")
+    file_sub = files.add_subparsers(dest="file_command", required=True)
+    file_list = file_sub.add_parser("list", help="List a directory")
+    file_list.add_argument("id"); file_list.add_argument("path", nargs="?", default="/workspace")
+    file_read = file_sub.add_parser("read", help="Read a file")
+    file_read.add_argument("id"); file_read.add_argument("path"); file_read.add_argument("--raw", action="store_true")
+    file_write = file_sub.add_parser("write", help="Write a local file or stdin")
+    file_write.add_argument("id"); file_write.add_argument("path"); file_write.add_argument("--from", dest="source", default="-")
+    file_mkdir = file_sub.add_parser("mkdir", help="Create a directory")
+    file_mkdir.add_argument("id"); file_mkdir.add_argument("path"); file_mkdir.add_argument("--no-recursive", action="store_true")
+    file_delete = file_sub.add_parser("delete", help="Delete a file or directory")
+    file_delete.add_argument("id"); file_delete.add_argument("path"); file_delete.add_argument("--recursive", action="store_true")
+    file_move = file_sub.add_parser("move", help="Move a file or directory")
+    file_move.add_argument("id"); file_move.add_argument("source"); file_move.add_argument("destination"); file_move.add_argument("--overwrite", action="store_true")
+
+    process = sub.add_parser("process", help="Manage durable processes")
+    process_sub = process.add_subparsers(dest="process_command", required=True)
+    process_start = process_sub.add_parser("start"); process_start.add_argument("id"); process_start.add_argument("cmd", nargs=argparse.REMAINDER); process_start.add_argument("--cwd")
+    for name in ("status", "logs", "kill"):
+        operation = process_sub.add_parser(name); operation.add_argument("id"); operation.add_argument("process_id")
+    process_input = process_sub.add_parser("input"); process_input.add_argument("id"); process_input.add_argument("process_id"); process_input.add_argument("data")
+
+    snapshot = sub.add_parser("snapshot", help="Manage checkpoints and forks")
+    snapshot_sub = snapshot.add_subparsers(dest="snapshot_command", required=True)
+    snapshot_create = snapshot_sub.add_parser("create"); snapshot_create.add_argument("id"); snapshot_create.add_argument("--name"); snapshot_create.add_argument("--retention-seconds", type=int)
+    snapshot_sub.add_parser("list")
+    for name in ("info", "delete"):
+        operation = snapshot_sub.add_parser(name); operation.add_argument("snapshot_id")
+    snapshot_fork = snapshot_sub.add_parser("fork"); snapshot_fork.add_argument("snapshot_id")
+
+    preview = sub.add_parser("preview", help="Manage expiring preview URLs")
+    preview_sub = preview.add_subparsers(dest="preview_command", required=True)
+    preview_create = preview_sub.add_parser("create"); preview_create.add_argument("id"); preview_create.add_argument("port", type=int); preview_create.add_argument("--expires", type=int, default=3600)
+    preview_revoke = preview_sub.add_parser("revoke"); preview_revoke.add_argument("id"); preview_revoke.add_argument("preview_id")
+    preview_ready = preview_sub.add_parser("ready"); preview_ready.add_argument("id"); preview_ready.add_argument("preview_id")
+
+    config = sub.add_parser("agent-config", help="Print MCP setup for a coding agent")
+    config.add_argument("client", choices=("codex", "claude", "cursor"))
+
+    migrate = sub.add_parser("migrate", help="Assess and plan migrations to Mosaic")
+    migrate_sub = migrate.add_subparsers(dest="migration_command", required=True)
+    migrate_sub.add_parser("providers", help="List supported source providers")
+    for name in ("assess", "plan"):
+        operation = migrate_sub.add_parser(name, help=f"{name.capitalize()} a migration")
+        operation.add_argument("--provider", required=True, choices=tuple(PROVIDER_INDEX))
+        operation.add_argument("--manifest", required=True, help="JSON manifest path, or - for stdin")
+
+    sub.add_parser("doctor", help="Check CLI configuration and daemon connectivity")
+    return parser
+
+
+def _parse_env(values: list[str]) -> dict[str, str]:
+    result = {}
+    for value in values:
+        if "=" not in value or value.startswith("="):
+            raise ValueError(f"invalid environment assignment: {value}")
+        key, item = value.split("=", 1)
+        result[key] = item
+    return result
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "mcp":
+            os.environ["MAR_ENDPOINT"] = args.endpoint
+            if args.token:
+                os.environ["MAR_API_TOKEN"] = args.token
+            from .mcp_server import main as mcp_main
+
+            mcp_main()
+            return 0
+        if args.command == "agent-config":
+            _emit(_agent_config(args.client, args.endpoint), raw=True)
+            return 0
+        if args.command == "migrate":
+            if args.migration_command == "providers":
+                _emit({"providers": list_providers()})
+            else:
+                manifest = _load_manifest(args.manifest)
+                result = (
+                    assess_migration(args.provider, manifest)
+                    if args.migration_command == "assess"
+                    else plan_migration(args.provider, manifest)
+                )
+                _emit(result)
+            return 0
+        if args.command == "files":
+            sandbox = Sandbox(args.id, args.endpoint, args.token)
+            if args.file_command == "list":
+                _emit({"path": args.path, "entries": [asdict(entry) for entry in sandbox.files.list(args.path)]})
+            elif args.file_command == "read":
+                content = sandbox.files.read_bytes(args.path)
+                if args.raw:
+                    sys.stdout.buffer.write(content)
+                else:
+                    _emit({"path": args.path, "content": content.decode("utf-8"), "size": len(content)})
+            elif args.file_command == "write":
+                content = sys.stdin.buffer.read() if args.source == "-" else Path(args.source).read_bytes()
+                _emit({"path": args.path, "size": sandbox.files.write(args.path, content)})
+            elif args.file_command == "mkdir":
+                sandbox.files.mkdir(args.path, recursive=not args.no_recursive); _emit({"path": args.path, "created": True})
+            elif args.file_command == "delete":
+                sandbox.files.remove(args.path, recursive=args.recursive); _emit({"path": args.path, "deleted": True})
+            elif args.file_command == "move":
+                sandbox.files.move(args.source, args.destination, overwrite=args.overwrite); _emit({"source": args.source, "destination": args.destination, "moved": True})
+            return 0
+        if args.command == "process":
+            sandbox = Sandbox(args.id, args.endpoint, args.token)
+            if args.process_command == "start": _emit(asdict(sandbox.process.start(args.cmd[1:] if args.cmd[:1] == ["--"] else args.cmd, cwd=args.cwd).initial))
+            elif args.process_command == "status": _emit(asdict(ProcessHandle(sandbox, ProcessInfo(**sandbox._call("GET", f"/processes/{args.process_id}"))).info()))
+            elif args.process_command == "logs": _emit(sandbox._call("GET", f"/processes/{args.process_id}/logs"))
+            elif args.process_command == "input": sandbox._call("POST", f"/processes/{args.process_id}/input", {"data": args.data}); _emit({"sent": True})
+            elif args.process_command == "kill": sandbox._call("DELETE", f"/processes/{args.process_id}"); _emit({"killed": True})
+            return 0
+        if args.command == "snapshot":
+            if args.snapshot_command == "list": _emit(_request(args, "/v1/snapshots"))
+            elif args.snapshot_command == "info": _emit(_request(args, f"/v1/snapshots/{args.snapshot_id}"))
+            elif args.snapshot_command == "delete": _emit(_request(args, f"/v1/snapshots/{args.snapshot_id}", method="DELETE"))
+            elif args.snapshot_command == "fork":
+                sandbox = Sandbox.create(endpoint=args.endpoint, api_token=args.token, snapshot_id=args.snapshot_id); _emit(_sandbox_created(sandbox))
+            else: _emit(asdict(Sandbox(args.id, args.endpoint, args.token).snapshot(args.name, args.retention_seconds)))
+            return 0
+        if args.command == "preview":
+            sandbox = Sandbox(args.id, args.endpoint, args.token)
+            if args.preview_command == "create": _emit(asdict(sandbox.preview(args.port, args.expires)))
+            elif args.preview_command == "ready": _emit({"preview_id": args.preview_id, "ready": sandbox.preview_ready(args.preview_id)})
+            else: sandbox.revoke_preview(args.preview_id); _emit({"revoked": True})
+            return 0
+        if args.command == "health":
+            _emit(_request(args, "/healthz"))
+            return 0
+        if args.command == "metrics":
+            _emit(_request(args, "/metrics"))
+            return 0
+        if args.command == "doctor":
+            health = _request(args, "/healthz")
+            _emit(
+                {
+                    "cli": "ok",
+                    "endpoint": args.endpoint,
+                    "authentication": "configured" if args.token else "not configured",
+                    "daemon": health,
+                }
+            )
+            return 0
+        if args.command == "create":
+            sandbox = Sandbox.create(
+                template=args.template,
+                memory_mb=args.memory_mb,
+                vcpu=args.vcpu,
+                endpoint=args.endpoint,
+                api_token=args.token,
+                enable_ssh=not args.no_ssh,
+                ssh_public_key=_ssh_key(args),
+                ssh_private_key_path=args.ssh_private_key,
+            )
+            _emit(_sandbox_created(sandbox))
+            return 0
+        if args.command == "exec":
+            if not args.cmd:
+                raise ValueError("exec requires a command after the sandbox ID")
+            result = _sandbox(args).run_command(
+                _command(args.cmd),
+                args.timeout_ms,
+                cwd=args.cwd,
+                env=_parse_env(args.env),
+                stdin=args.stdin,
+            )
+            _emit(asdict(result))
+            return result.exit_code
+        if args.command == "run":
+            if not args.cmd:
+                raise ValueError("run requires a command")
+            sandbox = Sandbox.create(
+                template=args.template,
+                memory_mb=args.memory_mb,
+                vcpu=args.vcpu,
+                endpoint=args.endpoint,
+                api_token=args.token,
+                enable_ssh=False,
+            )
+            try:
+                result = sandbox.run_command(
+                    _command(args.cmd),
+                    args.timeout_ms,
+                    cwd=args.cwd,
+                    env=_parse_env(args.env),
+                    stdin=args.stdin,
+                )
+                _emit({"sandbox_id": sandbox.id, **asdict(result)})
+                return result.exit_code
+            finally:
+                if not args.keep:
+                    sandbox.destroy()
+        if args.command == "info":
+            _emit(_request(args, f"/v1/sandboxes/{args.id}"))
+            return 0
+        sandbox = _sandbox(args)
+        if args.command == "pause":
+            sandbox.pause()
+        elif args.command == "resume":
+            sandbox.resume()
+        elif args.command == "destroy":
+            sandbox.destroy()
+        _emit({"id": args.id, "state": args.command})
+        return 0
+    except (RuntimeError, ValueError) as error:
+        print(f"mar: {error}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())