Metadata-Version: 2.4
Name: mcpaisuite-sandboxmcp
Version: 1.0.3
Summary: Secure, polyglot code execution engine for AI agents with MCP support
Project-URL: Homepage, https://github.com/gashel01/sandboxmcp
Project-URL: Repository, https://github.com/gashel01/sandboxmcp
Author-email: gashel01 <gaeldev@gmail.com>
License: AGPL-3.0-or-later
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog>=24.0
Provides-Extra: all
Requires-Dist: cryptography>=42.0; extra == 'all'
Requires-Dist: docker>=7.0; extra == 'all'
Requires-Dist: fastapi>=0.100; extra == 'all'
Requires-Dist: mcpaisuite-planningmcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-websearchmcp>=1.0; extra == 'all'
Requires-Dist: mcpaisuite-workspacemcp>=1.0; extra == 'all'
Requires-Dist: uvicorn>=0.23; extra == 'all'
Provides-Extra: api
Requires-Dist: fastapi>=0.100; extra == 'api'
Requires-Dist: uvicorn>=0.23; extra == 'api'
Provides-Extra: browser
Requires-Dist: mcpaisuite-websearchmcp>=1.0; extra == 'browser'
Provides-Extra: crypto
Requires-Dist: cryptography>=42.0; extra == 'crypto'
Provides-Extra: dev
Requires-Dist: cryptography>=42.0; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: docker
Requires-Dist: docker>=7.0; extra == 'docker'
Provides-Extra: planningmcp
Requires-Dist: mcpaisuite-planningmcp>=1.0; extra == 'planningmcp'
Provides-Extra: workspacemcp
Requires-Dist: mcpaisuite-workspacemcp>=1.0; extra == 'workspacemcp'
Description-Content-Type: text/markdown

# sandboxmcp

> Secure, polyglot code execution engine for AI agents with MCP support

Part of the [MCP AI Suite](https://mcpaisuite.dev).

## Features

- **Polyglot execution** -- run Python, JavaScript (Node), and shell in isolated environments
- **Process backend** for zero-dependency local execution with resource limits
- **Docker hardened mode** -- fully isolated containers with memory limits, CPU quotas, and network control
- **Code validation** with auto-fix for common issues and dangerous-pattern rejection
- **Secret vault** -- in-memory or environment-based credential injection without exposing secrets to agent output
- **Network egress control** -- global allowlist of permitted domains, default deny-all
- **Host access guard** -- optional controlled access to host commands with allow/block lists and auto-approve mode
- **Web tools** -- web search, page fetching, and browser rendering (lazily delegated to websearchmcp; requires the optional `browser` extra)
- **Full audit logging** via SQLite -- every execution, approval, and security event recorded

## Installation

```bash
pip install mcpaisuite-sandboxmcp
# Optional extras:
pip install "mcpaisuite-sandboxmcp[docker]"        # Docker backend support
pip install "mcpaisuite-sandboxmcp[browser]"       # Web tools (web_search / fetch_webpage / browser_fetch via websearchmcp)
pip install "mcpaisuite-sandboxmcp[workspacemcp]"  # workspacemcp suite integration
pip install "mcpaisuite-sandboxmcp[planningmcp]"   # planningmcp suite integration
pip install "mcpaisuite-sandboxmcp[dev]"           # Development tools
pip install "mcpaisuite-sandboxmcp[all]"           # Docker + browser + suite integrations
```

The web tools (`web_search`, `fetch_webpage`, `browser_fetch`) are lazily imported from
[websearchmcp](https://github.com/gashel01/websearchmcp) at call time and require the `browser` extra
(or `all`). Without it, those tools raise an import error while the rest of sandboxmcp works normally.

## Quick Start

```python
from sandboxmcp import SandboxFactory, ExecutionRequest, Language

sandbox = SandboxFactory.default()
result = await sandbox.execute(ExecutionRequest(
    code='print("Hello from sandbox!")',
    language=Language.python,
))
print(result.stdout)  # "Hello from sandbox!"
```

## MCP Server

```bash
sandboxmcp serve
```

## Configuration

| Variable | Default | Description |
|---|---|---|
| `SANDBOXMCP_BACKEND` | `process` | Execution backend: `process` or `docker` |
| `SANDBOXMCP_MAX_CONCURRENT` | `4` | Max concurrent executions |
| `SANDBOXMCP_NETWORK` | `false` | Enable network access |
| `SANDBOXMCP_HOST_ACCESS` | `false` | Enable host command execution |
| `SANDBOXMCP_HOST_AUTO_APPROVE` | `false` | Auto-approve host commands |
| `SANDBOXMCP_VAULT` | `memory` | Vault backend: `memory` or `env` |
| `SANDBOXMCP_AUDIT` | `sqlite` | Audit backend: `memory` or `sqlite` |
| `SANDBOXMCP_MAX_RAM_MB` | `512` | Max RAM per execution (MB) |
| `SANDBOXMCP_TIMEOUT` | `60` | Execution timeout (seconds) |

### Docker Hardened Mode

For maximum isolation, use the Docker backend:

```python
sandbox = SandboxFactory.create(
    default_backend="docker",
    image="python:3.12-slim",
    memory_limit="256m",
    network_mode="none",
)
```

This runs each execution in a disposable container with enforced memory limits, CPU quotas, and no network access.

## API Reference

### SandboxPipeline

The central orchestrator for code execution with full security pipeline.

```python
await sandbox.execute(request: ExecutionRequest) -> SandboxResult
await sandbox.create_session(language, namespace) -> Session
await sandbox.execute_in_session(session_id, code) -> SandboxResult
await sandbox.list_sessions() -> list[Session]
```

### SandboxFactory

```python
SandboxFactory.default()                 # Process backend, in-memory vault, no network
SandboxFactory.from_env()                # Build from environment variables
SandboxFactory.from_yaml("config.yaml")  # Build from YAML config
SandboxFactory.create(default_backend="docker", enable_network=True, ...)
```

## Architecture

SandboxPipeline orchestrates a security pipeline: incoming code passes through CodeValidator (syntax check, dangerous-pattern scan, auto-fix), then to the execution backend (Process or Docker), with NetworkGuard controlling egress and InMemoryVault injecting secrets. An AsyncJobQueue manages concurrency, and all events are recorded by the audit logger.

## Testing

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

## License

AGPL-3.0 — see [LICENSE](LICENSE).

Open source for individuals and open-source projects. For commercial use in closed-source products, a commercial license is available — contact [gaeldev@gmail.com](mailto:gaeldev@gmail.com).
