coderunner
A local sandbox for your AI agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/instavm/coderunner with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/instavm/coderunner'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/instavm-coderunner)HTML
<a href="/listings/instavm-coderunner"><img src="/api/listings/instavm-coderunner/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
**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
Stop and resume
Stop the sandbox when you are done:
container stop coderunner
Resume the same sandbox later, preserving uploads, kernels, and installed packages:
container start coderunner
To start over with a clean sandbox, delete the container and run the installer again:
container delete coderunner && ./install.sh
Disable outbound network access
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.sh
In 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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 433 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <div align="center">
- [](https://github.com/instavm/coderunner/stargazers)
- [](https://github.com/instavm/coderunner/blob/master/LICENSE)
- </div>
- # CodeRunner: A local sandbox for your AI agents
- 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](https://instavm.io)
- ## Quick Start
- **Prerequisites:** Mac with macOS and Apple Silicon (M1/M2/M3/M4), Python 3.10+
- ### Credentials
- 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](AUTHENTICATION.md).
- ```bash
- git clone https://github.com/instavm/coderunner.git
- cd coderunner
- chmod +x install.sh
- ./install.sh
- ```
- ### Stop and resume
- Stop the sandbox when you are done:
- ```bash
- container stop coderunner
- ```
- Resume the same sandbox later, preserving its filesystem. Python kernel state is
- volatile and does not survive a VM or server restart:
- ```bash
- container start coderunner
- ```
- To start over with a clean sandbox, delete the container and run the installer again:
- ```bash
- container delete coderunner && ./install.sh
- ```
- ### Resource limits and workspace mounts
- CPU and memory limits can be set with installer options or the `CODERUNNER_CPUS` and `CODERUNNER_MEMORY` environment variables:
- ```bash
- ./install.sh --cpus 4 --memory 8g
- ```
- Additional 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:
- ```bash
- ./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.
- ### Disable outbound network access
- By default, code running in the sandbox has unrestricted network access. To run it on a host-only network with no internet access:
- ```bash
- CODERUNNER_NETWORK=none ./install.sh
- ```
- In 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.
- ### With Claude Code
- 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.
- ## 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`
- <img width="741" height="410" alt="image" src="https://github.com/user-attachments/assets/620490cb-4e85-4c37-bc57-ab2fa1762c78" />
- ## Other Integration Options
- 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:
- ```bash
- pip install -r examples/requirements.txt
- ```
- #### 1. Claude Desktop Integration
- <details>
- <summary>Configure Claude Desktop to use CodeRunner as an MCP server:</summary>
- 
- 
- 
- 1. **Copy the example configuration:**
- ```bash
- cd examples
- cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
- ```
- 2. **Edit the configuration file** and replace the placeholder paths:
- - Replace `/path/to/your/python` with `$HOME/.coderunner/venv/bin/python` using the full path to your home directory
- - Replace `/path/to/coderunner` with the actual path to your cloned repository
- Example after editing:
- ```json
- {
- "mcpServers": {
- "coderunner": {
- "command": "/Users/yourname/.coderunner/venv/bin/python",
- "args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
- }
- }
- }
- ```
- 3. **Update Claude Desktop configuration:**
- - Open Claude Desktop
- - Go to Settings → Developer
- - Add the MCP server configuration
- - Restart Claude Desktop
- 4. **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 `command` is the venv python the installer printed (it
- has `fastmcp`), and read `~/Library/Logs/Claude/mcp-server-coderunner.log` for the proxy's error. The proxy
- needs the sandbox running (`container list`) and the token file `~/.coderunner/api-token`.
- </details>
- #### 2. Claude Code CLI
- <details>
- <summary>Use CodeRunner with Claude Code CLI for terminal-based AI assistance:</summary>
- **Quick Start:**
- ```bash
- # 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
- /mcp
- ```
- The 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:**
- 1. Navigate to Plugin Marketplace:
- 
- 2. Add the InstaVM repository:
- 
- 3. 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](https://github.com/instavm/coderunner-plugin) for detailed documentation.
- </details>
- #### 3. OpenCode Configuration
- <details>
- <summary>Configure OpenCode to use CodeRunner as an MCP server:</summary>
- 
- Create or edit `~/.config/opencode/opencode.json`:
- ```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:
- 1. Restart OpenCode
- 2. CodeRunner tools will be available automatically
- 3. Start executing Python code with full access to the sandboxed environment
- </details>
- #### 4. Python OpenAI Agents
- <details>
- <summary>Use CodeRunner with OpenAI's Python agents library:</summary>
- 
- 1. **Set your OpenAI API key:**
- ```bash
- export OPENAI_API_KEY="your-openai-api-key-here"
- ```
- 2. **Run the client:**
- ```bash
- python examples/openai_agents/openai_client.py
- ```
- 3. **Start coding:**
- Enter prompts like "write python code to generate 100 prime numbers" and watch it execute safely in the sandbox!
- </details>
- #### 5. Gemini-CLI
- [Gemini CLI](https://github.com/google-gemini/gemini-cli) is recently launched by Google.
- <details>
- <summary>~/.gemini/settings.json</summary>
- ```json
- {
- "theme": "Default",
- "selectedAuthType": "oauth-personal",
- "mcpServers": {
- "coderunner": {
- "httpUrl": "http://coderunner.local:8222/mcp",
- "headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" }
- }
- }
- }
- ```
- 
- 
- </details>
- #### 6. Kiro by Amazon
- [Kiro](https://kiro.dev/blog/introducing-kiro/) is recently launched by Amazon.
- <details>
- <summary>~/.kiro/settings/mcp.json</summary>
- ```json
- {
- "mcpServers": {
- "coderunner": {
- "command": "/path/to/venv/bin/python",
- "args": [
- "/path/to/coderunner/examples/claude_desktop/mcpproxy.py"
- ],
- "disabled": false,
- "autoApprove": [
- "execute_python_code"
- ]
- }
- }
- }
- ```
- 
- </details>
- #### 7. Coderunner-UI (Offline AI Workspace)
- [Coderunner-UI](https://github.com/instavm/coderunner-ui) is our own offline AI workspace tool designed for full privacy and local processing.
- <details>
- <summary>coderunner-ui</summary>
- 
- </details>
- ## Security
- Code runs in an isolated container with VM-level isolation. Your host system and files outside the sandbox remain protected.
- From [@apple/container](https://github.com/apple/container/blob/main/docs/technical-overview.md):
- >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:
- ```python
- # 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
- ```bash
- # 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](CONTRIBUTING.md) for guidelines.
- ## License
- This project is licensed under the Apache 2.0 License - see the [LICENSE](LICENSE) file for details.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.