Snipara Sandbox Integration

Snipara Sandbox is a Python execution layer that integrates with Snipara for context-aware code generation, explicitly started agents, and multi-step task execution across sandbox, docker, and trusted local backends. Sandbox jobs start only from an explicit user or workflow command; Snipara does not silently launch execution.

Installation

Or install manually:

pip install snipara-sandbox[all]

The current PyPI package is snipara-sandbox. Legacy command aliases remain available for existing installations.

Or install specific features:

Repository validation without LLM API keys

Deterministic repository tests need no LLM API key and no Snipara account. Use a local Docker daemon on macOS or Linux, a prepared dependency image and a reviewed request. Tests run offline by default against an immutable source snapshot, with explicit limits.

pip install 'snipara-sandbox[docker]'

Save the reviewed request as validation-request.json, using your repository path and prepared image:

{
  "workspace": "/absolute/path/to/repository",
  "image": "prepared-tests:project-lock",
  "argv": ["python", "-m", "pytest", "-q"],
  "timeout_seconds": 60,
  "cpus": 1,
  "memory_mb": 512,
  "pids": 64,
  "disk_mb": 128
}

Prepare the dependency image separately, then review and execute this bounded lot:

snipara-sandbox validation gate --request validation-request.json --scope my-reviewed-lot
snipara-sandbox validation run --request validation-request.json
snipara-sandbox validation verify --request validation-request.json --run-id <run-id>

A readiness probe is not a passing test. Verification checks the receipt against the request, image, source snapshot and artifacts; a saved receipt is historical evidence, not a restored live process. If Sandbox is unavailable, choose explicitly between another test environment, configuring Sandbox, or continuing without it. Gate failure does not authorize running tests on the host. Windows and hostile shared multi-tenancy remain unqualified.

Use validation through MCP

Set SNIPARA_SANDBOX_VALIDATION_WORKSPACE to the operator-approved repository root before starting the server. Its deterministic tools are validation_diagnose, validation_run, validation_status, validation_verify, validation_cancel and validation_recover. Companion and Orchestrator can consume the same contract when their installed versions are compatible.

Native approvals and supported versions

Use Sandbox 2.4.1 with Companion 3.9.0, Orchestrator 1.13.0 and plugin 2.2.0 for this workflow. Check the plugin's pinned engine as well as your shell version. Sandbox 2.4.1 includes the restricted Python augmented-assignment fix: x = 1; x += 1; assert x == 2.

Protected MCP tools retain their native approval requirements. A headless neverpolicy cannot ask for consent. Use the client's attended UI or an explicitly connected trusted-host SDK callback; each human answer applies only to the exact pending call. No session or permanent approval is forwarded by that callback. Waiting consumes the existing run budget. Keep refused attempts and never replace missing native proof with a parent-run test.

Orchestrator's ordinary CLI remains headless. See the SDK approval boundary.

TypeScript SDK

npm install @snipara/sandbox
import type { RepositoryValidationRequest, ExecutePythonParams } from "@snipara/sandbox";

Use the published SDK types and protocol helpers with your MCP client. Restricted Python snippets through execute_python and Docker repository validation are separate execution paths. Codex or Claude can call these tools using their native session; Sandbox itself does not need an LLM provider key for those operations.

Optional autonomous agent commands

These explicitly started agent commands use a model provider configured separately. Their provider credentials are distinct from deterministic validation and native MCP calls.

snipara-sandbox init

snipara-sandbox run "Summarize the authentication flow"

snipara-sandbox run --env docker "Parse and analyze logs"

snipara-sandbox agent "Analyze all CSV files and generate a report"

Claude Code / Claude Desktop Setup

Add Snipara Sandbox as an MCP server to get Python execution in Claude. No API keys required for Snipara Sandbox itself.

Step 1: Install with MCP support

pip install snipara-sandbox[mcp]

Step 2: Add to your MCP configuration

Add to ~/.mcp.json (Claude Code) or ~/.claude/claude_desktop_config.json (Claude Desktop):

{

  "mcpServers": {

    "snipara-sandbox": {

      "command": "snipara-sandbox",

      "args": ["mcp-serve"]

    }

  }

}

Step 3: Add Snipara for context (optional but recommended)

Combine Snipara Sandbox with Snipara for context-aware code execution:

{

  "mcpServers": {

    "snipara-sandbox": {

      "command": "snipara-sandbox",

      "args": ["mcp-serve"]

    },

    "snipara": {

      "type": "http",

      "url": "https://api.snipara.com/mcp/YOUR_PROJECT",

      "headers": {

        "X-API-Key": "snp-YOUR-API-KEY"

      }

    }

  }

}

Available MCP Tools

Execution Environments

The standalone Python package can expose other runtime backends such as WebAssembly. The MCP execute_python tool itself selects sandbox, docker, or trusted local execution.

When to Use Snipara Sandbox vs Direct MCP

Use Direct Snipara MCP Tools For:

• Documentation Q&A - "What's the tech stack?"
• Code lookup - "Where is auth handled?"
• Simple retrieval - "List all API endpoints"

Use Snipara Sandbox For:

• Multi-step code tasks - "Implement OAuth integration"
• Complex reasoning - "Refactor auth to use JWT"
• Iterative refinement - "Optimize this function"
• Multi-file changes - "Add validation to all endpoints"

Python API

import asyncio

from snipara_sandbox import SniparaSandbox

async def main():

    sandbox = SniparaSandbox(

        model="openai/YOUR_MODEL",

        environment="docker",

        max_depth=4,

    )

    result = await sandbox.completion("Analyze and fix the auth bug")

    print(result.response)

asyncio.run(main())

Configuration

Create snipara-sandbox.toml in your project:

[snipara_sandbox]

backend = "litellm"

model = "openai/YOUR_MODEL"

environment = "docker"

max_depth = 4

# Snipara integration

snipara_api_key = "snp-..."

snipara_project_slug = "your-project"

# Docker settings

docker_image = "python:3.11-slim"

docker_memory = "512m"

Or use environment variables:

export SNIPARA_SANDBOX_MODEL=openai/YOUR_MODEL

export SNIPARA_SANDBOX_ENVIRONMENT=docker

export SNIPARA_API_KEY=snp-...

export SNIPARA_PROJECT_SLUG=my-project

CLI Commands

Safety Limits

Links

Next Steps