{"id":"31623936-2579-4419-85f6-bfd853431fd2","slug":"snipara-sandbox","kind":"mcp","name":"snipara-sandbox","summary":"","owner":"Snipara","repoUrl":"https://github.com/Snipara/snipara-sandbox","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-01-22T21:16:38.000Z","addedAt":"2026-10-21T16:42:01.662Z","logoUrl":"https://avatars.githubusercontent.com/u/258092479?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["utilities"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T21:51:42.226Z","sample":false,"url":"https://conduits.dev/tools/snipara-sandbox","language":"Python","transports":["stdio"],"install":{"pypi":"snipara-sandbox"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Snipara Sandbox\n\n## Stateful execution runtime for persistent AI workflows\n\nModern AI agents can reason, write code, call tools, and solve complex tasks.\n\nBut most agent workflows are still transient. They lose execution state, restart\nfrom partial context, repeat failed work, and struggle to resume reliably across\nsessions, tools, users, and model changes.\n\nSnipara Sandbox is a state-aware execution runtime for persistent AI workflows. It\nadds a durable execution layer around AI agents so they can execute code safely,\npreserve trajectories, validate intermediate results, and resume long-running\nworkflows with continuity.\n\n```text\nContext\n  -> Planning\n  -> Execution\n  -> Validation\n  -> Persistent State\n  -> Resume Later\n```\n\nSnipara Sandbox is part of the broader Snipara ecosystem. Snipara provides persistent\nproject memory and shared context. Snipara Sandbox adds persistent execution,\nresumable workflows, and sandboxed task continuity.\n\n## The Problem\n\nLarge context windows are useful, but they do not solve execution continuity.\n\nAI systems also need infrastructure for:\n\n- persistent execution state\n- resumable workflows\n- sandboxed code execution\n- validation-aware task loops\n- trajectory persistence\n- recoverable orchestration\n\nWithout that layer, even strong agents often rediscover prior results, lose\nintermediate state, and restart work instead of continuing it.\n\nSnipara Sandbox exists to make execution durable.\n\n## Core Concepts\n\n### Persistent execution state\n\nSnipara Sandbox gives workflows a stateful execution environment instead of treating\nevery task as a one-shot prompt. Agents can store intermediate results, inspect\nprior execution, and continue from known state.\n\n### Sandboxed execution\n\nAgents can execute Python in controlled environments:\n\n- local RestrictedPython execution for fast trusted development\n- Docker isolation for stronger process and filesystem boundaries\n- optional WebAssembly support for portable sandboxing\n\n### Trajectory persistence\n\nExecutions can be logged as structured trajectories. This makes workflows easier\nto inspect, debug, audit, replay, and improve.\n\n### Validation-aware orchestration\n\nSnipara Sandbox is designed for workflows that do not just generate outputs, but also\ncheck them. Code execution, tool calls, and validation steps become part of the\nsame recoverable workflow.\n\n## Features\n\n- Persistent workflow state\n- Sandboxed Python execution\n- Docker isolation with resource limits\n- Resumable task orchestration\n- Trajectory logging\n- Validation-aware execution loops\n- Multi-step execution continuity\n- MCP-compatible runtime tools\n- Optional Snipara context and memory integration\n- LiteLLM backend support for OpenAI, Anthropic, and 100+ providers\n\n## Relationship With Snipara\n\nSnipara Sandbox is designed to work naturally with Snipara.\n\n```text\nLLM / Agent\n  -> Snipara Context and Memory\n  -> Snipara Sandbox\n  -> Sandboxed Execution\n```\n\nIn this architecture:\n\n- Snipara provides persistent shared context, project memory, and retrieval.\n- Snipara Sandbox provides persistent execution continuity and sandboxed runtime state.\n- The LLM handles reasoning, generation, and tool selection.\n\nThe runtime is optional. Snipara can function independently as a shared memory\nand context layer for AI systems.\n\nSnipara Sandbox extends the stack when a workflow needs:\n\n- long-running task execution\n- state continuity across sessions\n- validation through real code\n- auditable execution traces\n- recoverable orchestration\n\nIn short: Snipara keeps the context alive. Snipara Sandbox keeps the execution alive.\n\n## Installation\n\n```bash\n# Basic install\npip install snipara-sandbox\n\n# With Docker sandbox support\npip install snipara-sandbox[docker]\n\n# With MCP server support\npip install snipara-sandbox[mcp]\n\n# With Snipara integration\npip install snipara-sandbox[snipara]\n\n# Full install\npip install snipara-sandbox[all]\n```\n\nPackage version in this repo: `2.4.1`.\n\nFor deterministic repository tests without an LLM API key or Snipara account,\nuse the [repository validation workflow](docs/repository-validation.md).\n\nSee [CHANGELOG.md](CHANGELOG.md) for release history.\n\n## Quick Start\n\n### CLI\n\n```bash\nsnipara-sandbox init\n\nsnipara-sandbox run \"Analyze this dataset and validate the result with Python\"\n\nsnipara-sandbox run --env docker \"Process this untrusted input in an isolated runtime\"\n\nsnipara-sandbox logs\n```\n\nInspect the effective configuration:\n\n```bash\nsnipara-sandbox config show\nsnipara-sandbox config show --json\n```\n\nThe legacy `rlm` command remains available for existing users.\n\n### Python API\n\n```python\nimport asyncio\n\nfrom snipara_sandbox import SniparaSandbox\n\n\nasync def main():\n    runtime = SniparaSandbox(\n        model=\"gpt-4o-mini\",\n        environment=\"docker\",\n        max_depth=4,\n        token_budget=8000,\n    )\n\n    result = await runtime.completion(\n        \"Find the data quality issues in ./data and validate the findings.\"\n    )\n\n    print(result.response)\n    print(result.trajectory_id)\n\n\nasyncio.run(main())\n```\n\n## MCP Runtime Tools\n\nSnipara Sandbox includes an MCP server that gives AI coding agents a sandboxed Python\nruntime without requiring separate LLM API keys for the runtime itself.\n\n```bash\npip install snipara-sandbox[mcp]\nsnipara-sandbox mcp-serve\n```\n\nExample MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"SniparaSandbox\": {\n      \"command\": \"snipara-sandbox\",\n      \"args\": [\"mcp-serve\"]\n    }\n  }\n}\n```\n\nCore MCP tools:\n\n| Tool | Purpose |\n|------|---------|\n| `execute_python` | Execute Python in `sandbox`, `docker`, or `local` sessions |\n| `get_repl_context` | Read persistent session variables |\n| `set_repl_context` | Store persistent session variables |\n| `clear_repl_context` | Reset session state |\n| `list_sessions` | Inspect active runtime sessions |\n| `destroy_session` | Destroy a runtime session |\n| `snipara_agent_run` | Start an autonomous agent task |\n| `snipara_agent_status` | Check an agent run |\n| `snipara_agent_cancel` | Cancel an agent run |\n\n`execute_python` accepts an optional `environment` parameter (`sandbox`,\n`docker`, `local`). Each `session_id` stays bound to its first environment, and\nthe tool returns a structured MCP receipt with backend, timeout, session, and\nresource metrics.\n\n## Using Snipara Sandbox With Snipara\n\nSnipara credentials are detected automatically when available. The native HTTP\nclient is preferred, with `snipara-mcp` kept as a compatibility fallback.\n\nOAuth:\n\n```bash\nsnipara-mcp-login\nsnipara-mcp-status\n```\n\nAPI key:\n\n```bash\nexport SNIPARA_API_KEY=snp-...\nexport SNIPARA_PROJECT_SLUG=my-project\n```\n\nPython:\n\n```python\nfrom snipara_sandbox import SniparaSandbox\n\nruntime = SniparaSandbox(\n    model=\"gpt-4o-mini\",\n    environment=\"docker\",\n    snipara_api_key=\"snp-...\",\n    snipara_project_slug=\"my-project\",\n)\n\nresult = await runtime.completion(\n    \"Use project context to explain the authentication flow and validate examples.\"\n)\n```\n\nWhen configured, Snipara tools provide semantic context retrieval, shared project\ncontext, and optional durable memory. Snipara Sandbox uses that context during\nexecution while preserving the workflow trajectory.\n\n## Configuration\n\nCreate `snipara-sandbox.toml` in your project:\n\n```toml\n[snipara_sandbox]\nbackend = \"litellm\"\nmodel = \"gpt-4o-mini\"\nenvironment = \"docker\"\nmax_depth = 4\nmax_subcalls = 12\ntoken_budget = 8000\nverbose = false\n\ndocker_image = \"python:3.11-slim\"\ndocker_cpus = 1.0\ndocker_memory = \"512m\"\ndocker_network_disabled = true\ndocker_mount_workspace = true\n# docker_workspace_path = \".\"\ndocker_workspace_setup = \"none\"  # use \"tests-only\" or \"dev\" for repo-backed test runs\n# docker_workspace_install_command = \"python -m pip install -e \\\".[dev]\\\"\"\n\nsnipara_project_slug = \"your-project\"\n```\n\nEnvironment variables are also supported:\n\n```bash\nexport SNIPARA_SANDBOX_MODEL=gpt-4o-mini\nexport SNIPARA_SANDBOX_ENVIRONMENT=docker\nexport SNIPARA_PROJECT_SLUG=my-project\n```\n\n## Runtime Environments\n\n| Environment | Use case | Isolation |\n|-------------|----------|-----------|\n| `local` | Fast trusted development | RestrictedPython in process |\n| `docker` | Production and untrusted inputs | Container isolation |\n| `wasm` | Portable sandboxing | WebAssembly runtime |\n\nDocker mode is recommended for production and untrusted execution.\nBy default it mounts the current workspace read-only at `/workspace`, so the\nruntime can inspect and test the repo while keeping process isolation and\nnetwork disabled.\n\nFor actual repo-backed test runs, enable workspace setup:\n\n```toml\n[snipara_sandbox]\nenvironment = \"docker\"\ndocker_mount_workspace = true\ndocker_workspace_setup = \"tests-only\"\n```\n\nThat prepares a cached local Docker image from the current workspace and\ninstalls its dependencies at image-build time. Runtime execution still uses a\nread-only mount and no network. `tests-only` installs `pytest` and\n`pytest-asyncio` while exposing the mounted repo via `PYTHONPATH=/workspace`;\n`dev` performs a full editable dev install instead. The workspace-image build\nuses a sandbox-owned context instead of the project's `.dockerignore`, so test\nfiles and packaging metadata remain available, and build failures now include\nrecent Docker log lines for faster debugging. If your project does not use\n`.[dev]`, set `docker_workspace_install_command` explicitly.\n\n```bash\nsnipara-sandbox run --env docker \"Validate this user-submitted transformation\"\n```\n\n## Trajectory Logging\n\nSnipara Sandbox records execution trajectories as structured JSONL logs.\n\n```bash\nsnipara-sandbox logs\nsnipara-sandbox logs <trajectory-id>\n```\n\nTrajectory events include:\n\n- prompts and responses\n- tool calls and tool results\n- parent and child call relationships\n- token usage\n- duration and execution metadata\n\nFor visual inspection:\n\n```bash\npip install snipara-sandbox[visualizer]\nsnipara-sandbox visualize\n```\n\n## Development\n\n```bash\ngit clone https://github.com/Snipara/snipara-sandbox\ncd snipara-sandbox\n\npip install -e \".[dev]\"\n\npytest\nruff check src/\nmypy src/\npython -m build\n```\n\n## Documentation\n\n- [Quickstart Guide](docs/quickstart.md)\n- [Architecture Guide](docs/architecture.md)\n- [MCP Integration](docs/mcp-integration.md)\n- [Configuration](docs/configuration.md)\n- [Tool Development](docs/tools.md)\n- [Snipara Integration](docs/snipara.md)\n\n## Repositories\n\n- [Snipara Server](https://github.com/Snipara/snipara-server)\n- [Snipara MCP](https://github.com/alopez3006/snipara-mcp)\n- [Snipara Memory](https://github.com/Snipara/snipara-memory)\n- [Snipara Sandbox](https://github.com/Snipara/snipara-sandbox)\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n"}