Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/instavm-coderunner/badge.svg)](/listings/instavm-coderunner)

HTML

<a href="/listings/instavm-coderunner"><img src="/api/listings/instavm-coderunner/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. <div align="center">
  2. [![Start](https://img.shields.io/github/stars/instavm/coderunner?color=yellow&style=flat&label=%E2%AD%90%20stars)](https://github.com/instavm/coderunner/stargazers)
  3. [![License](http://img.shields.io/:license-Apache%202.0-green.svg?style=flat)](https://github.com/instavm/coderunner/blob/master/LICENSE)
  4. </div>
  5. # CodeRunner: A local sandbox for your AI agents
  6. CodeRunner helps you sandbox your AI agents and its actions inside a sandbox.
  7. **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.
  8. For cloud managed VMs for agents, we have launched - [InstaVM - Instant computers for AI agents](https://instavm.io)
  9. ## Quick Start
  10. **Prerequisites:** Mac with macOS and Apple Silicon (M1/M2/M3/M4), Python 3.10+
  11. ### Credentials
  12. The installer generates the sandbox token in `~/.coderunner/api-token` (or saves
  13. the `CODERUNNER_API_TOKEN` you exported). Clients send it as
  14. `Authorization: Bearer <token>`; `cat ~/.coderunner/api-token` prints it. Only
  15. `GET /health` is public, and a missing or weak token fails closed. The Claude
  16. Desktop proxy and the examples read the token from that file when the variable
  17. is not set. See [authentication and network boundaries](AUTHENTICATION.md).
  18. ```bash
  19. git clone https://github.com/instavm/coderunner.git
  20. cd coderunner
  21. chmod +x install.sh
  22. ./install.sh
  23. ```
  24. ### Stop and resume
  25. Stop the sandbox when you are done:
  26. ```bash
  27. container stop coderunner
  28. ```
  29. Resume the same sandbox later, preserving its filesystem. Python kernel state is
  30. volatile and does not survive a VM or server restart:
  31. ```bash
  32. container start coderunner
  33. ```
  34. To start over with a clean sandbox, delete the container and run the installer again:
  35. ```bash
  36. container delete coderunner && ./install.sh
  37. ```
  38. ### Resource limits and workspace mounts
  39. CPU and memory limits can be set with installer options or the `CODERUNNER_CPUS` and `CODERUNNER_MEMORY` environment variables:
  40. ```bash
  41. ./install.sh --cpus 4 --memory 8g
  42. ```
  43. 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:
  44. ```bash
  45. ./install.sh \
  46. --mount "$HOME/projects/api:/workspace/api" \
  47. --mount "$HOME/projects/output:/workspace/output:rw"
  48. ```
  49. Extra mounts default to none. Resource and mount settings are fixed when the container is created; delete the container before changing them.
  50. ### Disable outbound network access
  51. By default, code running in the sandbox has unrestricted network access. To run it on a host-only network with no internet access:
  52. ```bash
  53. CODERUNNER_NETWORK=none ./install.sh
  54. ```
  55. 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.
  56. ### With Claude Code
  57. Claude Code runs commands on your machine, as you, with permission prompts as the only boundary. Pointing it at
  58. CodeRunner's tools instead runs the code it writes in the VM: it can only touch the folders you mounted under
  59. `/workspace`, the network you allowed, and the sandbox's own filesystem, whatever it was told to do. Use the
  60. sandbox for code that handles untrusted input or that you would not run by hand, and for several agents that
  61. must not share state (named sessions). It does not protect anything you mount read-write.
  62. ## Run Claude Code inside a Sandbox
  63. `./install.sh` (if not already done)
  64. `container exec -it coderunner /bin/bash`
  65. `root@coderunner:/app# npm install -g @anthropic-ai/claude-code`
  66. <img width="741" height="410" alt="image" src="https://github.com/user-attachments/assets/620490cb-4e85-4c37-bc57-ab2fa1762c78" />
  67. ## Other Integration Options
  68. MCP server will be available at: `http://coderunner.local:8222/mcp`
  69. The installer creates `~/.coderunner/venv` for the Claude Desktop proxy. For the other Python examples, install their dependencies in your own virtualenv:
  70. ```bash
  71. pip install -r examples/requirements.txt
  72. ```
  73. #### 1. Claude Desktop Integration
  74. <details>
  75. <summary>Configure Claude Desktop to use CodeRunner as an MCP server:</summary>
  76. ![demo1](images/demo.png)
  77. ![demo2](images/demo2.png)
  78. ![demo4](images/demo4.png)
  79. 1. **Copy the example configuration:**
  80. ```bash
  81. cd examples
  82. cp claude_desktop/claude_desktop_config.example.json claude_desktop/claude_desktop_config.json
  83. ```
  84. 2. **Edit the configuration file** and replace the placeholder paths:
  85. - Replace `/path/to/your/python` with `$HOME/.coderunner/venv/bin/python` using the full path to your home directory
  86. - Replace `/path/to/coderunner` with the actual path to your cloned repository
  87. Example after editing:
  88. ```json
  89. {
  90. "mcpServers": {
  91. "coderunner": {
  92. "command": "/Users/yourname/.coderunner/venv/bin/python",
  93. "args": ["/Users/yourname/coderunner/examples/claude_desktop/mcpproxy.py"]
  94. }
  95. }
  96. }
  97. ```
  98. 3. **Update Claude Desktop configuration:**
  99. - Open Claude Desktop
  100. - Go to Settings → Developer
  101. - Add the MCP server configuration
  102. - Restart Claude Desktop
  103. 4. **Start using CodeRunner in Claude:**
  104. Code Claude writes now runs in the sandbox.
  105. If the tool shows as "Disabled" in the chat's tool menu although the server is listed as running: quit Claude
  106. Desktop fully (Cmd-Q) and open it again, make sure `command` is the venv python the installer printed (it
  107. has `fastmcp`), and read `~/Library/Logs/Claude/mcp-server-coderunner.log` for the proxy's error. The proxy
  108. needs the sandbox running (`container list`) and the token file `~/.coderunner/api-token`.
  109. </details>
  110. #### 2. Claude Code CLI
  111. <details>
  112. <summary>Use CodeRunner with Claude Code CLI for terminal-based AI assistance:</summary>
  113. **Quick Start:**
  114. ```bash
  115. # 1. Install and start CodeRunner (one-time setup; run as yourself, it asks for sudo when it needs it)
  116. git clone https://github.com/instavm/coderunner.git
  117. cd coderunner
  118. ./install.sh
  119. # 2. Add the sandbox with its token (the installer prints this command)
  120. claude mcp add --transport http coderunner http://coderunner.local:8222/mcp \
  121. --header "Authorization: Bearer $(cat ~/.coderunner/api-token)"
  122. # 3. Reconnect to MCP servers
  123. /mcp
  124. ```
  125. The Claude Code plugin (`claude plugin marketplace add https://github.com/instavm/coderunner-plugin`) predates
  126. the token and gets 401 until it sends the same header; use the command above until the plugin is updated.
  127. **Installation Steps:**
  128. 1. Navigate to Plugin Marketplace:
  129. ![Navigate to Plugin Marketplace](images/gotoplugin.png)
  130. 2. Add the InstaVM repository:
  131. ![Add InstaVM Repository](images/addrepo.png)
  132. 3. Execute Python code with Claude Code:
  133. ![Execute Python Code](images/runcode.png)
  134. That's it! Claude Code now has access to all CodeRunner tools:
  135. - **execute_python_code** - Run Python code in persistent Jupyter kernel
  136. - **start_python_session** - Reserve an isolated kernel for a named session
  137. - **list_python_sessions** - List active named sessions
  138. - **stop_python_session** - Stop a session and discard its kernel state
  139. - **navigate_and_get_all_visible_text** - Web scraping with Playwright
  140. - **list_skills** - List available skills (docx, xlsx, pptx, pdf, image processing, etc.)
  141. - **get_skill_info** - Get documentation for specific skills
  142. - **get_skill_file** - Read skill files and examples
  143. Pass the returned `session_id` to `execute_python_code` to keep state isolated between agents. Up to five named sessions can run concurrently.
  144. **Learn more:** See the [plugin repository](https://github.com/instavm/coderunner-plugin) for detailed documentation.
  145. </details>
  146. #### 3. OpenCode Configuration
  147. <details>
  148. <summary>Configure OpenCode to use CodeRunner as an MCP server:</summary>
  149. ![OpenCode Example](images/opencode-example.png)
  150. Create or edit `~/.config/opencode/opencode.json`:
  151. ```json
  152. {
  153. "$schema": "https://opencode.ai/config.json",
  154. "mcp": {
  155. "coderunner": {
  156. "type": "remote",
  157. "url": "http://coderunner.local:8222/mcp",
  158. "headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" },
  159. "enabled": true
  160. }
  161. }
  162. }
  163. ```
  164. After saving the configuration:
  165. 1. Restart OpenCode
  166. 2. CodeRunner tools will be available automatically
  167. 3. Start executing Python code with full access to the sandboxed environment
  168. </details>
  169. #### 4. Python OpenAI Agents
  170. <details>
  171. <summary>Use CodeRunner with OpenAI's Python agents library:</summary>
  172. ![demo3](images/demo3.png)
  173. 1. **Set your OpenAI API key:**
  174. ```bash
  175. export OPENAI_API_KEY="your-openai-api-key-here"
  176. ```
  177. 2. **Run the client:**
  178. ```bash
  179. python examples/openai_agents/openai_client.py
  180. ```
  181. 3. **Start coding:**
  182. Enter prompts like "write python code to generate 100 prime numbers" and watch it execute safely in the sandbox!
  183. </details>
  184. #### 5. Gemini-CLI
  185. [Gemini CLI](https://github.com/google-gemini/gemini-cli) is recently launched by Google.
  186. <details>
  187. <summary>~/.gemini/settings.json</summary>
  188. ```json
  189. {
  190. "theme": "Default",
  191. "selectedAuthType": "oauth-personal",
  192. "mcpServers": {
  193. "coderunner": {
  194. "httpUrl": "http://coderunner.local:8222/mcp",
  195. "headers": { "Authorization": "Bearer <contents of ~/.coderunner/api-token>" }
  196. }
  197. }
  198. }
  199. ```
  200. ![gemini1](images/gemini1.png)
  201. ![gemini2](images/gemini2.png)
  202. </details>
  203. #### 6. Kiro by Amazon
  204. [Kiro](https://kiro.dev/blog/introducing-kiro/) is recently launched by Amazon.
  205. <details>
  206. <summary>~/.kiro/settings/mcp.json</summary>
  207. ```json
  208. {
  209. "mcpServers": {
  210. "coderunner": {
  211. "command": "/path/to/venv/bin/python",
  212. "args": [
  213. "/path/to/coderunner/examples/claude_desktop/mcpproxy.py"
  214. ],
  215. "disabled": false,
  216. "autoApprove": [
  217. "execute_python_code"
  218. ]
  219. }
  220. }
  221. }
  222. ```
  223. ![kiro](images/kiro.png)
  224. </details>
  225. #### 7. Coderunner-UI (Offline AI Workspace)
  226. [Coderunner-UI](https://github.com/instavm/coderunner-ui) is our own offline AI workspace tool designed for full privacy and local processing.
  227. <details>
  228. <summary>coderunner-ui</summary>
  229. ![coderunner-ui](images/coderunnerui.jpg)
  230. </details>
  231. ## Security
  232. Code runs in an isolated container with VM-level isolation. Your host system and files outside the sandbox remain protected.
  233. From [@apple/container](https://github.com/apple/container/blob/main/docs/technical-overview.md):
  234. >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.
  235. ## Skills System
  236. CodeRunner includes a built-in skills system that provides pre-packaged tools for common tasks. Skills are organized into two categories:
  237. ### Built-in Public Skills
  238. The following skills are included in every CodeRunner installation:
  239. - **pdf-text-replace** - Replace text in fillable PDF forms
  240. - **image-crop-rotate** - Crop and rotate images
  241. ### Using Skills
  242. Skills are accessed through MCP tools:
  243. ```python
  244. # List all available skills
  245. result = await list_skills()
  246. # Get documentation for a specific skill
  247. info = await get_skill_info("pdf-text-replace")
  248. # Execute a skill's script
  249. code = """
  250. import subprocess
  251. subprocess.run([
  252. 'python',
  253. '/app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py',
  254. '/app/uploads/input.pdf',
  255. 'OLD TEXT',
  256. 'NEW TEXT',
  257. '/app/uploads/output.pdf'
  258. ])
  259. """
  260. result = await execute_python_code(code)
  261. ```
  262. ### Adding Custom Skills
  263. Users can add their own skills to the `~/.coderunner/assets/skills/user/` directory:
  264. 1. Create a directory for your skill (e.g., `my-custom-skill/`)
  265. 2. Add a `SKILL.md` file with documentation
  266. 3. Add your scripts in a `scripts/` subdirectory
  267. 4. Skills will be automatically discovered by the `list_skills()` tool
  268. **Skill Structure:**
  269. ```
  270. ~/.coderunner/assets/skills/user/my-custom-skill/
  271. ├── SKILL.md # Documentation with usage examples
  272. └── scripts/ # Your Python/bash scripts
  273. └── process.py
  274. ```
  275. ### Example: Using the PDF Text Replace Skill
  276. ```bash
  277. # Inside the container, execute:
  278. python /app/uploads/skills/public/pdf-text-replace/scripts/replace_text_in_pdf.py \
  279. /app/uploads/tax_form.pdf \
  280. "John Doe" \
  281. "Jane Smith" \
  282. /app/uploads/tax_form_updated.pdf
  283. ```
  284. ## Architecture
  285. CodeRunner consists of:
  286. - **Sandbox Container:** Isolated execution environment with Jupyter kernel
  287. - **MCP Server:** Handles communication between AI models and the sandbox
  288. - **Skills System:** Pre-packaged tools for common tasks (PDF manipulation, image processing, etc.)
  289. ## Examples
  290. The `examples/` directory contains:
  291. - `openai-agents` - Example OpenAI agents integration
  292. - `claude-desktop` - Example Claude Desktop integration
  293. ## Building Container Image Tutorial
  294. https://github.com/apple/container/blob/main/docs/tutorial.md
  295. ## Roadmap
  296. 1. Linux support with Firecracker
  297. 2. Guardrails for external agentic actions
  298. 3. CLI for Coderunner
  299. ## Contributing
  300. We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  301. ## License
  302. 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 in

Free to use. If it’s helped, pass it on.