Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -97,5 +97,11 @@ RUN npm install [email protected] -g
RUN npx [email protected] install


# Create a non-root user
RUN useradd -ms /bin/bash coderunner

Comment on lines +101 to +102

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

critical

The newly created coderunner user needs write permissions for directories within /app, such as /app/jupyter_runtime, which are currently owned by root. Without this, the Jupyter server may fail at runtime. Please change the ownership of the /app directory after creating the user.

RUN useradd -ms /bin/bash coderunner
RUN chown -R coderunner:coderunner /app

# Switch to the non-root user
USER coderunner

# Use the entrypoint script
ENTRYPOINT ["/entrypoint.sh"]
21 changes: 14 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

# CodeRunner: Run AI Generated Code Locally

CodeRunner is an MCP (Model Context Protocol) server that executes AI-generated code in a sandboxed environment on your Mac using Apple's native [containers](https://github.com/apple/container).
CodeRunner is a cross-platform MCP (Model Context Protocol) server that executes AI-generated code in a secure, sandboxed environment. It supports macOS via Apple's native [containers](https://github.com/apple/container) and Linux/Windows via Docker.

**Key use case:** Process your local files (videos, images, documents, data) with remote LLMs like Claude or ChatGPT without uploading your files to the cloud. The LLM generates code that runs locally on your machine to analyze, transform, or process your files.

Expand All @@ -24,18 +24,23 @@ CodeRunner is an MCP (Model Context Protocol) server that executes AI-generated

## Quick Start

**Prerequisites:** Mac with macOS and Apple Silicon (M1/M2/M3/M4), Python 3.10+
**Prerequisites:**
* **For macOS:** Apple Silicon (M1/M2/M3/M4) and the [Apple Container](https://github.com/apple/container/releases) tool installed.
* **For Linux/Windows:** [Docker](https://docs.docker.com/get-docker/) installed and running.

```bash
git clone https://github.com/instavm/coderunner.git
cd coderunner
chmod +x install.sh
sudo ./install.sh
./install.sh
```

MCP server will be available at: http://coderunner.local:8222/mcp
The script will detect your operating system and set up CodeRunner accordingly.

**Install required packages** (use virtualenv and note the python path):
* **On macOS:** The MCP server will be available at `http://coderunner.local:8222/mcp`
* **On Linux/Windows:** The MCP server will be available at `http://localhost:8222/mcp`

**Install required packages for examples:**
```bash
pip install -r examples/requirements.txt
```
Expand Down Expand Up @@ -169,11 +174,13 @@ Code runs in an isolated container with VM-level isolation. Your host system and
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.

On Linux and Windows, CodeRunner uses Docker for similar containerization and security benefits.

## Architecture

CodeRunner consists of:
- **Sandbox Container:** Isolated execution environment with Jupyter kernel
- **MCP Server:** Handles communication between AI models and the sandbox
- **Sandbox Container:** Isolated execution environment (Apple Container or Docker) with a Jupyter kernel.
- **MCP Server:** Handles communication between AI models and the sandbox.

## Examples

Expand Down
116 changes: 64 additions & 52 deletions install.sh
Original file line number Diff line number Diff line change
@@ -1,77 +1,89 @@
#!/bin/bash

# --- Helper Functions ---

# Function to check if a command exists
command_exists() {
command -v "$1" &> /dev/null
}

# Function to get current macOS version
get_macos_version() {
sw_vers -productVersion | awk -F. '{print $1 "." $2}'
}

# Check the system type
if [[ "$OSTYPE" != "darwin"* ]]; then
echo "❌ This script is intended for macOS systems only. Exiting."
exit 1
fi
# --- Main Installation Logic ---

# Check macOS version
macos_version=$(get_macos_version)
if (( $(echo "$macos_version < 26.0" | bc -l) )); then
echo "Warning: Your macOS version is $macos_version. Version 26.0 or later is recommended. Some features of 'container' might not work properly."
else
echo "Starting CodeRunner Setup..."

# --- macOS Specific Setup ---
if [[ "$OSTYPE" == "darwin"* ]]; then
echo "✅ macOS system detected."
fi

download_url="https://github.com/apple/container/releases/download/0.3.0/container-0.3.0-installer-signed.pkg"
# Check macOS version
macos_version=$(get_macos_version)
if (( $(echo "$macos_version < 26.0" | bc -l) )); then
echo "⚠️ Warning: Your macOS version is $macos_version. Version 26.0 or later is recommended for Apple Container."
fi

# Check if container is installed and display its version
if command -v container &> /dev/null
then
echo "Apple 'container' tool detected. Current version:"
# Check for Apple Container tool
if command_exists container; then
echo "✅ Apple 'container' tool detected."
container --version
current_version=$(container --version | awk '{print $4}')
echo $current_version
target_version=$(echo $download_url | awk -F'/' '{print $8}')
else
echo "❌ Apple 'container' tool not found."
echo "Please install it from: https://github.com/apple/container/releases"
exit 1
fi

echo "Starting Apple Container services..."
container system start
sudo container system dns create local
container system dns default set local

if [ "$current_version" != "$target_version" ]; then
echo "Consider updating to version $target_version. Download it here: $download_url"
fi
echo "Pulling the latest image for Apple Container..."
container image pull instavm/coderunner

echo "Stopping any running Apple 'container' processes..."
else
echo "Apple 'container' tool not detected. Proceeding with installation..."

# Download and install the Apple 'container' tool
echo "Downloading Apple 'container' tool..."
curl -Lo container-installer.pkg "$download_url"

echo "Installing Apple 'container' tool..."
sudo installer -pkg container-installer.pkg -target /
fi
echo "→ Ensuring coderunner assets directory exists..."
ASSETS_SRC="$HOME/.coderunner/assets"
mkdir -p "$ASSETS_SRC"

echo "Starting the Sandbox Container..."
container system start
echo "🚀 Starting CodeRunner container..."
container run --volume "$ASSETS_SRC:/app/uploads" --name coderunner --detach --rm --cpus 8 --memory 4g instavm/coderunner

echo "Setting up local network domain..."
echo "✅ Setup complete! MCP server is available at http://coderunner.local:8222/mcp"

# Run the commands for setting up the local network
echo "Running: sudo container system dns create local"
sudo container system dns create local
# --- Docker-based Setup for Linux/Other ---
else
echo "✅ Non-macOS system detected. Setting up with Docker."

echo "Running: container system dns default set local"
container system dns default set local
# Check for Docker
if ! command_exists docker; then
echo "❌ Docker is not installed. Please install Docker to continue."
echo "Visit: https://docs.docker.com/get-docker/"
exit 1
fi

echo "Starting the Sandbox Container..."
container system start
echo "✅ Docker is installed."

# Check if Docker daemon is running
if ! docker info &> /dev/null; then
echo "❌ Docker daemon is not running. Please start Docker and re-run this script."
exit 1
fi

echo "Pulling the latest image: instavm/coderunner"
container image pull instavm/coderunner
echo "Pulling the latest image from Docker Hub..."
docker pull instavm/coderunner

echo "→ Ensuring coderunner assets directory"
ASSETS_SRC="$HOME/.coderunner/assets"
mkdir -p "$ASSETS_SRC"
echo "→ Ensuring coderunner assets directory exists..."
ASSETS_SRC="$HOME/.coderunner/assets"
mkdir -p "$ASSETS_SRC"

# Run the command to start the sandbox container
echo "Running: container run --name coderunner --detach --rm --cpus 8 --memory 4g instavm/coderunner"
container run --volume "$ASSETS_SRC:/app/uploads" --name coderunner --detach --rm --cpus 8 --memory 4g instavm/coderunner
echo "🚀 Starting CodeRunner container using Docker..."
docker run -d --rm --name coderunner \
-p 8222:8222 \
-v "$ASSETS_SRC:/app/uploads" \
instavm/coderunner
Comment on lines +83 to +86

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

critical

There's a critical permission issue with the mounted volume. The /app/uploads directory inside the container will be owned by the host user's UID/GID, but the processes inside the container run as the coderunner user, which likely has a different UID. This will prevent the application and Jupyter from writing files to the shared directory, causing runtime failures.

A common solution is to handle this at container startup. For example, the entrypoint script could be run as root to chown the mounted directory, and then switch to the coderunner user before executing the main application.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should revert this commit. Or maybe I will handle it in a new PR soon.


echo "✅ Setup complete. MCP server is available at http://coderunner.local:8222/mcp"
echo "✅ Setup complete! MCP server is available at http://localhost:8222/mcp"
fi
Loading