coderunner

CodeRunner is an MCP server that enables AI models to generate and run code locally in a sandboxed environment on macOS. It keeps your actual files on your machine, preventing upload to the cloud, while allowing LLMs to generate, inspect, and execute Python code within a controlled container. The server exposes tools that your AI agent can call, including executing Python code in a persistent kernel, navigating web content, and applying preset “skills” like PDF text replacement or image processing. Typical workflows include asking an AI to write Python code for data processing or file transformation, then having that code execute safely inside the sandbox and return the results or generated files to you. The tools available are designed to be used through the MCP interface, so you can list skills, fetch documentation for a skill, and run a skill script against your local data. CodeRunner also integrates with popular desktop tooling like Claude Desktop, Claude Code CLI, OpenCode, and other agent ecosystems, enabling a local-first AI development loop without uploading sensitive data.

To use CodeRunner, install and run the MCP server, then connect your client tooling (Claude Code CLI, Claude Desktop, OpenCode, or Gemini/Kiro integrations) to http://coderunner.local:8222/mcp. Once connected, you can issue prompts that translate into Python code execution requests, skill invocations, or file processing steps. Common commands exposed via the MCP tooling layer include execute_python_code (to run Python in a persistent kernel), navigate_and_get_all_visible_text (for web content extraction via Playwright), list_skills (to discover available capabilities), get_skill_info (docs for a specific skill), and get_skill_file (read skill scripts and examples). The skills system ships with built-in capabilities such as pdf-text-replace and image-crop-rotate, among others, enabling ready-to-use data transformations and processing tasks.

Prerequisites:

• macOS with Apple Silicon (M1/M2/M3/M4) or compatible hardware
• Python 3.10 or newer
• Command-line access to install dependencies

Step-by-step installation:

1. Clone the repository git clone https://github.com/instavm/coderunner.git cd coderunner

2. Prepare the environment and install dependencies

   • If you’re using a virtual environment (recommended): python3 -m venv venv source venv/bin/activate
   • Install required Python packages (examples/requirements.txt contains necessary deps): pip install -r examples/requirements.txt

3. Install CodeRunner itself (one-time setup)

   • Make the install script executable and run it: chmod +x install.sh sudo ./install.sh

4. Run the MCP server (if not started by the installer)

   • The server runs an entrypoint module for the MCP proxy; ensure it’s accessible at: http://coderunner.local:8222/mcp

5. Verify installation

   • Open the MCP URL in a browser or use a client tool to ensure the server responds at the /mcp endpoint.

Optional validation steps for CLI tooling:

• If you use Claude Code CLI or other integrations, follow their specific setup steps to connect to http://coderunner.local:8222/mcp.
• You may need to install extra plugins or configure paths as shown in the integration docs within the repository.

Tips and common issues:

• Ensure your macOS firewall or network settings allow connections to http://coderunner.local:8222/mcp.
• The sandboxed environment relies on container isolation; ensure your Python path and entry script (mcpproxy) are accessible and valid in your setup.
• When configuring external clients (Claude Desktop, Claude Code CLI, OpenCode, Gemini, Kiro), point them to the endpoint /mcp and supply any necessary authentication or plugin-specific configuration.
• If you change the repository location, update client configurations to reflect the new path to the MCP server.
• Built-in skills like pdf-text-replace and image-crop-rotate are pre-configured; you can extend or add new skills under the skills system and reference them via list_skills and get_skill_info.
• If you encounter performance or sandbox issues, ensure you are running the latest installer and dependencies from examples/requirements.txt, and verify you are on a supported macOS version with Apple Silicon.