CodeRunner helps you sandbox your AI agents and its actions inside a sandbox.
Key use case: Run AI agent code in a sandbox with explicitly chosen host mounts and network access. Isolation reduces risk; it does not prevent all data loss or exfiltration.
For cloud managed VMs for agents, we have launched - InstaVM - Instant computers for AI agents
Prerequisites: Mac with macOS and Apple Silicon (M1/M2/M3/M4), Python 3.10+
The installer generates the sandbox token in ~/.coderunner/api-token (or saves
the CODERUNNER_API_TOKEN you exported). Clients send it as
Authorization: Bearer <token>; cat ~/.coderunner/api-token prints it. Only
GET /health is public, and a missing or weak token fails closed. The Claude
Desktop proxy and the examples read the token from that file when the variable
is not set. See authentication and network boundaries.
git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
./install.shStop the sandbox when you are done:
container stop coderunnerResume the same sandbox later, preserving its filesystem. Python kernel state is volatile and does not survive a VM or server restart:
container start coderunnerTo start over with a clean sandbox, delete the container and run the installer again:
container delete coderunner && ./install.shCPU and memory limits can be set with installer options or the CODERUNNER_CPUS and CODERUNNER_MEMORY environment variables:
./install.sh --cpus 4 --memory 8gAdditional host directories must be mounted under /workspace. They are read-only by default; add :rw only when the sandbox needs to write to the host:
./install.sh \
--mount "$HOME/projects/api:/workspace/api" \
--mount "$HOME/projects/output:/workspace/output:rw"Extra mounts default to none. Resource and mount settings are fixed when the container is created; delete the container before changing them.
By default, code running in the sandbox has unrestricted network access. To run it on a host-only network with no internet access:
CODERUNNER_NETWORK=none ./install.shIn this mode, the MCP server is available at http://127.0.0.1:8222/mcp. The setting is fixed when the container is created; the installer refuses to resume a container with a different network mode.
Claude Code runs commands on your machine, as you, with permission prompts as the only boundary. Pointing it at
CodeRunner's tools instead runs the code it writes in the VM: it can only touch the folders you mounted under
/workspace, the network you allowed, and the sandbox's own filesystem, whatever it was told to do. Use the
sandbox for code that handles untrusted input or that you would not run by hand, and for several agents that
must not share state (named sessions). It does not protect anything you mount read-write.
./install.sh (if not already done)
container exec -it coderunner /bin/bash
root@coderunner:/app# npm install -g @anthropic-ai/claude-code
MCP server will be available at: http://coderunner.local:8222/mcp
The installer creates ~/.coderunner/venv for the Claude Desktop proxy. For the other Python examples, install their dependencies in your own virtualenv:
pip install -r examples/requirements.txtConfigure Claude Desktop to use CodeRunner as an MCP server:
-
Copy the example configuration:
cd examples cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json -
Edit the configuration file and replace the placeholder paths:
- Replace
/path/to/your/pythonwith$HOME/.coderunner/venv/bin/pythonusing the full path to your home directory - Replace
/path/to/coderunnerwith the actual path to your cloned repository
Example after editing:
{ "mcpServers": { "coderunner": { "command": "/Users/yourname/.coderunner/venv/bin/python", "args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"] } } } - Replace
-
Update Claude Desktop configuration:
- Open Claude Desktop
- Go to Settings → Developer
- Add the MCP server configuration
- Restart Claude Desktop
-
Start using CodeRunner in Claude: Code Claude writes now runs in the sandbox.
If the tool shows as "Disabled" in the chat's tool menu although the server is listed as running: quit Claude Desktop fully (Cmd-Q) and open it again, make sure
commandis the venv python the installer printed (it hasfastmcp), and read~/Library/Logs/Claude/mcp-server-coderunner.logfor the proxy's error. The proxy needs the sandbox running (container list) and the token file~/.coderunner/api-token.
Use CodeRunner with Claude Code CLI for terminal-based AI assistance:
Quick Start:
# 1. Install and start CodeRunner (one-time setup; run as yourself, it asks for sudo when it needs it)
git clone https://github.com/instavm/coderunner.git
cd coderunner
./install.sh
# 2. Add the sandbox with its token (the installer prints this command)
claude mcp add --transport http coderunner http://coderunner.local:8222/mcp \
--header "Authorization: Bearer $(cat ~/.coderunner/api-token)"
# 3. Reconnect to MCP servers
/mcpThe Claude Code plugin (claude plugin marketplace add https://github.com/instavm/coderunner-plugin) predates
the token and gets 401 until it sends the same header; use the command above until the plugin is updated.
Installation Steps:
-
Navigate to Plugin Marketplace:
-
Add the InstaVM repository:
-
Execute Python code with Claude Code:
That's it! Claude Code now has access to all CodeRunner tools:
- execute_python_code - Run Python code in persistent Jupyter kernel
- start_python_session - Reserve an isolated kernel for a named session
- list_python_sessions - List active named sessions
- stop_python_session - Stop a session and discard its kernel state
- navigate_and_get_all_visible_text - Web scraping with Playwright
- list_skills - List available skills (docx, xlsx, pptx, pdf, image processing, etc.)
- get_skill_info - Get documentation for specific skills
- get_skill_file - Read skill files and examples
Pass the returned session_id to execute_python_code to keep state isolated between agents. Up to five named sessions can run concurrently.
Learn more: See the plugin repository for detailed documentation.
Configure OpenCode to use CodeRunner as an MCP server:
Create or edit ~/.config/opencode/opencode.json:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"coderunner": {
"type": "remote",
"url": "http://coderunner.local:8222/mcp",
"headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" },
"enabled": true
}
}
}After saving the configuration:
- Restart OpenCode
- CodeRunner tools will be available automatically
- Start executing Python code with full access to the sandboxed environment
Use CodeRunner with OpenAI's Python agents library:
-
Set your OpenAI API key:
export OPENAI_API_KEY="your-openai-api-key-here"
-
Run the client:
python examples/openai_agents/openai_client.py
-
Start coding: Enter prompts like "write python code to generate 100 prime numbers" and watch it execute safely in the sandbox!
Gemini CLI is recently launched by Google.
~/.gemini/settings.json
{
"theme": "Default",
"selectedAuthType": "oauth-personal",
"mcpServers": {
"coderunner": {
"httpUrl": "http://coderunner.local:8222/mcp",
"headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" }
}
}
}
Kiro is recently launched by Amazon.
~/.kiro/settings/mcp.json
{
"mcpServers": {
"coderunner": {
"command": "/path/to/venv/bin/python",
"args": [
"/path/to/coderunner/examples/claude_desktop/mcpproxy.py"
],
"disabled": false,
"autoApprove": [
"execute_python_code"
]
}
}
}
Coderunner-UI is our own offline AI workspace tool designed for full privacy and local processing.
coderunner-ui
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.
CodeRunner includes a built-in skills system that provides pre-packaged tools for common tasks. Skills are organized into two categories:
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
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)Users can add their own skills to the ~/.coderunner/assets/skills/user/ directory:
- Create a directory for your skill (e.g.,
my-custom-skill/) - Add a
SKILL.mdfile with documentation - Add your scripts in a
scripts/subdirectory - 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
# 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.pdfCodeRunner 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.)
The examples/ directory contains:
openai-agents- Example OpenAI agents integrationclaude-desktop- Example Claude Desktop integration
https://github.com/apple/container/blob/main/docs/tutorial.md
- Linux support with Firecracker
- Guardrails for external agentic actions
- CLI for Coderunner
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
