Metadata-Version: 2.4
Name: silicon-sandbox
Version: 0.5.0
Summary: Apple Silicon native AI agent sandbox — three-tier isolated code execution with MCP server
Author: Aaron Montgomery
License: MIT
Project-URL: Homepage, https://github.com/Euda1mon1a/silicon-sandbox
Project-URL: Repository, https://github.com/Euda1mon1a/silicon-sandbox
Project-URL: Issues, https://github.com/Euda1mon1a/silicon-sandbox/issues
Keywords: sandbox,ai-agent,code-execution,apple-silicon,mcp,isolation,seatbelt,microvm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn>=0.30
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: httpx>=0.27
Requires-Dist: sse-starlette>=2.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: all
Requires-Dist: mcp>=1.0; extra == "all"
Dynamic: license-file

# SiliconSandbox

> **Archived — not actively maintained.** This project is published as-is. It works, has 246 tests (94% pass rate), and ran in production for a month. PRs and issues are welcome but may not be addressed.

Apple Silicon native AI agent sandbox and orchestration platform. Runs entirely on macOS using native primitives — no Docker, no cloud dependency.

## What It Does

Provides isolated execution environments for AI agents to run code safely, plus an orchestrator to break complex tasks into parallel subtasks routed across local and cloud LLMs.

Three isolation tiers — pick the right tradeoff between security and speed:

| Tier | Technology | RAM | Boot | Use Case |
|------|-----------|-----|------|----------|
| A (Seatbelt) | macOS `sandbox-exec` + SBPL | ~0 MB | ~50ms | Default for code execution |
| B (MicroVM) | Apple Virtualization.framework + Alpine Linux | ~256 MB | ~260ms | Untrusted binaries, Linux envs, browser automation |
| C (Native) | `subprocess` + rlimit + setpgrp | ~0 MB | ~10ms | Trusted internal tools |

## Architecture

```
Web UI (:8095) ─── Orchestrator (:8094) ─── Sandbox Engine (:8093)
                         │                        │
                    Model Router              Three Tiers:
                    ├─ Local LLM (coder)      ├─ A: Seatbelt (sandbox-exec)
                    ├─ Local LLM (classifier) ├─ B: MicroVM (Virt.framework)
                    └─ Claude API (planner)   └─ C: Native (subprocess + rlimit)
                                                   │
MCP Server (:8100) ──────────────────────────── Engine API
  11 tools for Claude Code                         │
                                              Network Proxy (:8098)
                                              Domain allowlist, deny-all default
```

## Requirements

- macOS 14+ (Sonoma) on Apple Silicon (M1/M2/M3/M4)
- Python 3.12+
- Xcode Command Line Tools (for Swift vm-launcher build)
- Optional: Anthropic API key for the orchestrator's planner

## Quick Start

```bash
# Install dependencies, build vm-launcher, set up LaunchAgents
./scripts/install.sh

# Start all services
./scripts/launch.sh

# Verify
curl -s http://127.0.0.1:8093/health | python3 -m json.tool

# Stop all services
./scripts/stop.sh
```

## Usage

### Direct API

```bash
# Run a command in a Seatbelt sandbox
curl -X POST http://127.0.0.1:8093/sandbox \
  -H 'Content-Type: application/json' \
  -d '{"command": "python3 -c \"print(2+2)\"", "tier": "A", "timeout": 10}'

# Create a persistent session
curl -X POST http://127.0.0.1:8093/session \
  -H 'Content-Type: application/json' \
  -d '{"tier": "A", "ttl_seconds": 3600}'

# Execute in session
curl -X POST http://127.0.0.1:8093/session/{id}/exec \
  -H 'Content-Type: application/json' \
  -d '{"command": "python3 main.py"}'
```

### Python SDK

```python
from silicon_sandbox import Sandbox, Session

# One-shot execution
result = Sandbox.run("echo hello", tier="A")
print(result.stdout)

# Persistent session with file operations
with Session.create() as session:
    session.write_files({"main.py": "print('hello')"})
    result = session.exec("python3 main.py")
    print(result.stdout)
```

### MCP Tools (Claude Code / AI Agents)

Register in your MCP config. Available tools:

- `sandbox_run` — one-shot sandboxed execution
- `sandbox_health` — engine health check
- `session_create` / `session_exec` / `session_destroy` — persistent sessions
- `session_write_files` / `session_read_file` — file operations in sessions
- `session_pause` / `session_resume` — SIGSTOP/SIGCONT process control
- `session_list` — list active sessions

### Desktop Automation (Tier B)

Tier B boots a full Alpine Linux VM with Xvfb, Openbox, and Chromium:

```bash
# Create a desktop session
curl -X POST http://127.0.0.1:8093/session \
  -H 'Content-Type: application/json' \
  -d '{"tier": "B", "image": "desktop"}'

# Take a screenshot
curl http://127.0.0.1:8093/session/{id}/screenshot --output screen.png

# Control the browser via CDP
curl -X POST http://127.0.0.1:8093/session/{id}/browser/control \
  -H 'Content-Type: application/json' \
  -d '{"method": "Page.navigate", "params": {"url": "https://example.com"}}'
```

## Security

- **Deny-default** Seatbelt profiles (SBPL v2): `(deny default)` base with selective allows
- **Blocked paths**: `~/.ssh`, `~/.gnupg`, `~/Library/Keychains`, `~/.config/git/credentials`, `~/.netrc`, `~/.aws`
- **Process isolation**: `os.setpgrp()` + `resource.setrlimit()` per sandbox
- **Network**: deny-all by default, opt-in through domain allowlist proxy on :8098
- **Auth**: optional Bearer token via `SILICONSANDBOX_AUTH_TOKEN` env var

## Configuration

Copy and edit `config/default.yaml`:

```yaml
sandbox:
  seatbelt:
    denied_paths: ["~/.ssh", "~/.gnupg", "~/Library/Keychains"]
    max_cpu_seconds: 120
    max_processes: 50
  microvm:
    default_cpus: 2
    default_memory_gb: 2
  network:
    proxy_port: 8098
    allowed_domains: ["pypi.org", "github.com"]
    deny_all_by_default: true

orchestrator:
  models:
    planner:
      provider: anthropic
      model: claude-sonnet-4-20250514
    coder:
      provider: openai_compatible
      endpoint: "http://127.0.0.1:8080/v1"
      model: "your-local-model"
```

The orchestrator's model router supports any OpenAI-compatible endpoint for local models and Anthropic API for planning/research roles. Set `ANTHROPIC_API_KEY` in your environment for the planner.

## Tests

```bash
.venv/bin/python3 -m pytest tests/ -v
# 246 tests across 8 modules
```

## Project Structure

```
silicon-sandbox/
├── sandbox-engine/          # Core engine (seatbelt, microvm, native, server)
│   ├── sandbox_engine/      # Python package
│   ├── guest-agent/         # MicroVM guest agent (init + shell scripts)
│   └── vm-launcher/         # Swift CLI (Virtualization.framework)
├── orchestrator/            # DAG engine, model router, planner, memory
├── tools/                   # MCP tool servers
│   ├── sandbox-mcp/         # Main MCP server (port 8100)
│   ├── code-interpreter/    # Python/Node/Bash execution
│   ├── file-manager/        # Scoped workspace operations
│   ├── web-research/        # DuckDuckGo + readability
│   └── browser-automation/  # CDP via MicroVM desktop
├── sdk/                     # Python SDK (silicon_sandbox package)
├── ui/                      # Web UI (Alpine.js, single HTML file)
├── config/                  # YAML config, SBPL profiles, VM image scripts
├── scripts/                 # install.sh, launch.sh, stop.sh
├── launchd/                 # LaunchAgent plist templates
└── tests/                   # 246 tests
```

## Acknowledgments

Phase 8 hardening was informed by review of [Alibaba's OpenSandbox](https://github.com/alibaba/OpenSandbox) — specifically the deny-default Seatbelt profile pattern, `preexec_fn` process isolation approach, persistent session concept, and SDK design. No code was copied; the implementation is independent.

## License

MIT — see [LICENSE](LICENSE).
