InstaVM CodeRunner Plugin for Claude Code

This plugin enables Claude Code to execute Python code in a local sandboxed Apple container using InstaVM CodeRunner via the Model Context Protocol (MCP).

Quick Start

# 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 instavm/coderunner-plugin

claude plugin install instavm-coderunner

That's it! Claude Code now has access to all CodeRunner tools.

Installation

Prerequisites

IMPORTANT: You must have CodeRunner installed and running before installing this plugin.

Install CodeRunner

git clone https://github.com/instavm/coderunner.git
cd coderunner
sudo ./install.sh

This will:

• Install Apple's container runtime (version 0.8.0+)
• Pull the instavm/coderunner container image
• Start the CodeRunner MCP service at http://coderunner.local:8222/mcp

Verify CodeRunner is running:

curl http://coderunner.local:8222/execute -X POST -H "Content-Type: application/json" -d '{"code":"print(\"test\")"}'

Install via GitHub URL (Recommended)

# Add the InstaVM marketplace from GitHub
claude plugin marketplace add instavm/coderunner-plugin

# Install the plugin
claude plugin install instavm-coderunner

Install via Claude CLI

$ claude

1. /plugin --> Marketplaces

   

2. Add the InstaVM marketplace repository:

   

3. Install the instavm-coderunner plugin and reconnect with /mcp

Usage

Once installed, Claude Code can execute Python code in the sandboxed CodeRunner container. Simply ask Claude to run Python code, and it will automatically use the CodeRunner environment.

Example: Running Python Code

The plugin provides several capabilities:

• Execute arbitrary Python code with persistent state
• Access popular Python libraries (pandas, numpy, matplotlib, requests, etc.)
• Fetch and process web content with Playwright
• Work with files in a sandboxed environment
• List and use specialized skills for tasks like PDF manipulation, image processing, and more

Features

• Sandboxed Execution: All code runs in an isolated Apple container
• Persistent Kernel: Jupyter kernel maintains state across executions
• Rich Libraries: Pre-installed data science and web scraping libraries
• Web Scraping: Built-in Playwright support for browser automation
• Specialized Skills: Access to pre-built skills for common tasks
• Secure: Network-isolated environment for safe code execution

Available Tools

The plugin exposes these MCP tools to Claude Code:

• execute_python_code: Run Python code in a persistent Jupyter kernel
• navigate_and_get_all_visible_text: Fetch and extract text from webpages
• list_skills: View available specialized skills
• get_skill_info: Get documentation for specific skills
• get_skill_file: Access additional skill documentation files

Troubleshooting

Plugin Not Working

1. Verify CodeRunner is running:

   curl http://coderunner.local:8222/execute -X POST -H "Content-Type: application/json" -d '{"code":"print(\"test\")"}'

2. Reconnect MCP servers in Claude Code:

   /mcp
   

3. Check plugin installation:

   claude plugin list

CodeRunner Not Starting

If CodeRunner fails to start:

cd coderunner
sudo ./install.sh

Ensure you have:

• macOS with Apple Silicon or Intel
• Administrator privileges for installation
• Apple container runtime (installed automatically by install.sh)

Uninstalling

# Uninstall the plugin
claude plugin uninstall instavm-coderunner

# Remove the marketplace
claude plugin marketplace remove instavm/coderunner-plugin

# Stop CodeRunner (optional)
container stop coderunner

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests to the GitHub repository.

License

This plugin is released under the MIT License.

Related Projects

• InstaVM CodeRunner - The sandboxed Python execution environment
• Claude Code - Anthropic's official CLI for Claude