CodeRunner: A local sandbox for your AI agents

CodeRunner helps you sandbox your AI agents and its actions inside a sandbox.

Key use case: You can run multiple Claude Code or AI agents in our sandbox without any fear of data loss and exfilteration.

Quick Start

Prerequisites: Mac with macOS and Apple Silicon (M1/M2/M3/M4), Python 3.10+

git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.sh

Run Claude Code inside a Sandbox

./install.sh (if not already done)

container exec -it coderunner /bin/bash

root@coderunner:/app# npm install -g @anthropic-ai/claude-code

Other Integration Options

MCP server will be available at: http://coderunner.local:8222/mcp

Install required packages (use virtualenv and note the python path):

pip install -r examples/requirements.txt

1. Claude Desktop Integration

2. Claude Code CLI

# 1. Install and start CodeRunner (one-time setup)
git clone https://github.com/instavm/coderunner.git
cd coderunner
sudo ./install.sh

# 2. Install the Claude Code plugin
claude plugin marketplace add https://github.com/instavm/coderunner-plugin
claude plugin install instavm-coderunner

# 3. Reconnect to MCP servers
/mcp

3. OpenCode Configuration

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "coderunner": {
      "type": "remote",
      "url": "http://coderunner.local:8222/mcp",
      "enabled": true
    }
  }
}

4. Python OpenAI Agents

5. Gemini-CLI

Gemini CLI is recently launched by Google.

{
  "theme": "Default",
  "selectedAuthType": "oauth-personal",
  "mcpServers": {
    "coderunner": {
      "httpUrl": "http://coderunner.local:8222/mcp"
    }
  }
}

6. Kiro by Amazon

Kiro is recently launched by Amazon.

{
  "mcpServers": {
    "coderunner": {
      "command": "/path/to/venv/bin/python",
      "args": [
        "/path/to/coderunner/examples/claude_desktop/mcpproxy.py"
      ],
      "disabled": false,
      "autoApprove": [
        "execute_python_code"
      ]
    }
  }
}

7. Coderunner-UI (Offline AI Workspace)

Coderunner-UI is our own offline AI workspace tool designed for full privacy and local processing.

Security

Code runs in an isolated container with VM-level isolation. Your host system and files outside the sandbox remain protected.

From @apple/container:

Each container has the isolation properties of a full VM, using a minimal set of core utilities and dynamic libraries to reduce resource utilization and attack surface.

Skills System

CodeRunner includes a built-in skills system that provides pre-packaged tools for common tasks. Skills are organized into two categories:

Built-in Public Skills

The following skills are included in every CodeRunner installation:

• pdf-text-replace - Replace text in fillable PDF forms
• image-crop-rotate - Crop and rotate images

Using Skills

Skills are accessed through MCP tools:

# List all available skills
result = await list_skills()

# Get documentation for a specific skill
info = await get_skill_info("pdf-text-replace")

# Execute a skill's script
code = """
import subprocess
subprocess.run([
    'python',
    '/app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py',
    '/app/uploads/input.pdf',
    'OLD TEXT',
    'NEW TEXT',
    '/app/uploads/output.pdf'
])
"""
result = await execute_python_code(code)

Adding Custom Skills

Users can add their own skills to the ~/.coderunner/assets/skills/user/ directory:

1. Create a directory for your skill (e.g., my-custom-skill/)
2. Add a SKILL.md file with documentation
3. Add your scripts in a scripts/ subdirectory
4. Skills will be automatically discovered by the list_skills() tool

Skill Structure:

~/.coderunner/assets/skills/user/my-custom-skill/
├── SKILL.md              # Documentation with usage examples
└── scripts/              # Your Python/bash scripts
    └── process.py

Example: Using the PDF Text Replace Skill

# Inside the container, execute:
python /app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py \
    /app/uploads/tax_form.pdf \
    "John Doe" \
    "Jane Smith" \
    /app/uploads/tax_form_updated.pdf

Architecture

CodeRunner consists of:

• Sandbox Container: Isolated execution environment with Jupyter kernel
• MCP Server: Handles communication between AI models and the sandbox
• Skills System: Pre-packaged tools for common tasks (PDF manipulation, image processing, etc.)

Examples

The examples/ directory contains:

• openai-agents - Example OpenAI agents integration
• claude-desktop - Example Claude Desktop integration

Building Container Image Tutorial

https://github.com/apple/container/blob/main/docs/tutorial.md

Roadmap

1. Linux support with Firecracker
2. Guardrails for external agentic actions
3. CLI for Coderunner

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.