● Community
instavm
⚡ Instant
CodeRunner
by instavm · instavm/coderunner
VM-isolated code execution for agents — Python, Playwright, persistent Jupyter kernel, all sandboxed off your host.
CodeRunner gives Claude (and other agents) a secure, persistent sandbox: run Python with a long-lived Jupyter kernel, scrape with Playwright, manipulate PDFs and images. Container-based VM-level isolation means you can let an agent execute untrusted code without trashing your machine. Exposes itself as MCP so it works in any client.
Why use it
Key features
- VM-level isolation — host filesystem and network protected
- Persistent Jupyter kernel — variables and imports survive across calls
- Playwright bundled for web scraping / browser automation
- Pre-packaged skills: PDF manipulation, image processing
- Available as MCP server at coderunner.local:8222 — wire into any client
Live Demo
What it looks like in practice
ready
Use Cases
Real-world ways to use CodeRunner
When to use: You want Claude to write + run a script you didn't fully review.
Flow
-
Hand it the task
Use coderunner. Write a Python script that downloads my Strava activities CSV from <url>, parses, and computes weekly mileage. Run it in the sandbox.✓ Copied
→ Script executed; output shown; nothing touched my filesystem
-
Iterate
Add a chart of weekly mileage. Re-run.✓ Copied
→ Chart rendered; kernel state preserved (no re-import)
-
Export results
Save CSV + chart to ./out/ on host (this only).✓ Copied
→ Only that one path written; sandbox stays sealed
Outcome: Quick experiments without 'oops, it deleted /Users'.
Pitfalls
- Network access still allowed in sandbox — Disable network if running truly untrusted code; otherwise it can exfiltrate
When to use: You want a 30-minute exploratory data session without losing kernel state.
Flow
-
Load data once
Use coderunner. Load /data/sales.csv into df. Show schema + 5 sample rows.✓ Copied
→ df in kernel; persists for the session
-
Ad-hoc queries
Pivot by region × month, show top 5 anomalies.✓ Copied
→ Pivot + flagged rows
-
Export
Save the anomalies subset to /out/anomalies.csv on host.✓ Copied
→ CSV in /out/
Outcome: Notebook-quality analysis through chat, with actual code running.
Pitfalls
- Kernel state drifts across long sessions; results based on stale variables — Restart the kernel between unrelated tasks; Claude can issue %reset
When to use: Site needs full browser; you don't want a Chrome process running on your host.
Flow
-
Spin up a session
Use coderunner Playwright. Open <url>, wait for the table, extract rows as JSON.✓ Copied
→ JSON returned; browser stayed in sandbox
-
Iterate selectors
Selector missed the price column; adjust to find it.✓ Copied
→ Updated selector; data complete
Outcome: Data extracted; no host browser footprint.
Pitfalls
- Site detects headless and blocks — Switch to chromium with --headed=false-but-stealth options the skill exposes
Combinations
Pair with other MCPs for X10 leverage
Move data in/out of the sandbox via mounted paths only
Mount only /Users/me/data and /Users/me/out; everything else is read-only.✓ Copied
Search → fetch → analyze pipeline
Search via duckduckgo, scrape via coderunner Playwright, analyze in Python.✓ Copied
Cost & Limits
What this costs to run
- API quota
- None — local
- Tokens per call
- Just the code/output tokens
- Monetary
- Free
- Tip
- Persistent kernel saves tokens vs re-importing; reset only when state is wrong
Security
Permissions, secrets, blast radius
Minimum scopes: Mounted filesystem paths only Network on/off via config
Credential storage: Don't put secrets in the sandbox unless you're OK with the agent seeing them
Data egress: If network is on, sandbox can hit any URL — disable for sensitive runs
Never grant: Mount of $HOME or / — sandbox loses its point
- Sandbox reduces blast radius but isn't a panacea — review agent's plan before runs
Troubleshooting
Common errors and fixes
install.sh fails on Linux
Project is macOS Apple Silicon first-class; Linux support varies. Check the issues for distro-specific notes
Playwright stale state
Run kernel_reset; old browser context can persist across calls
Sandbox can't reach the internet
Network disabled in config; flip if you need it. Conversely, isolate when not needed
PDF/image skill missing dependencies
Container image bundles common ones; rebuild image to add custom deps
Alternatives
CodeRunner vs others
| Alternative | When to use it instead | Tradeoff |
|---|
| Anthropic code execution beta | You want server-side execution without local sandbox | Cloud-side; data leaves your machine |
| Docker by hand | You want full control of the container image | Manual setup; no MCP server out of the box |