{"id":"f002ec5f-de81-4fa2-9462-a32d911da15d","slug":"runboxjs","kind":"skill","name":"runboxjs","summary":"","owner":"runboxjs","repoUrl":"https://github.com/runboxjs/runboxjs","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-31T01:27:33.000Z","addedAt":"2026-10-21T17:52:01.173Z","logoUrl":"https://avatars.githubusercontent.com/u/278894835?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T21:31:39.193Z","sample":false,"url":"https://conduits.dev/tools/runboxjs","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# RunboxJS\n\n[![npm](https://img.shields.io/npm/v/@runboxjs/runboxjs)](https://www.npmjs.com/package/@runboxjs/runboxjs)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)\n[![Rust Edition](https://img.shields.io/badge/Rust-2024-orange)](https://www.rust-lang.org/)\n\n**RunboxJS** is a WebAssembly sandbox runtime that executes project workflows directly in the browser. It provides a complete development environment simulation including a virtual filesystem, multi-runtime command execution (Bun/Node/npm/pnpm/Yarn/Git/Python/pip), terminal I/O streams, hot reload signaling, a DOM inspector bridge, an MCP (Model Context Protocol) server, and AI tool dispatch for assistant orchestration.\n\n- **npm package:** [`@runboxjs/runboxjs`](https://www.npmjs.com/package/@runboxjs/runboxjs)\n- **Rust crate source:** `runbox`\n- **Current version:** `1.2.0`\n\n---\n\n## Table of Contents\n\n- [Why RunboxJS](#why-runboxjs)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Vite Integration](#vite-integration)\n- [Runtime Command Support](#runtime-command-support)\n- [API Overview](#api-overview)\n- [MCP Server](#mcp-server)\n- [AI Integration](#ai-integration)\n- [Agent Journal](#agent-journal)\n- [Local Development](#local-development)\n- [Publishing](#publishing)\n- [Troubleshooting](#troubleshooting)\n- [Documentation Index](#documentation-index)\n- [License](#license)\n\n---\n\n## Why RunboxJS\n\nRunboxJS was designed to bring a full development sandbox experience into the browser, without requiring any server-side infrastructure or host filesystem access:\n\n- **Isolated execution** in browser memory via WebAssembly -- no host filesystem access, no network side effects\n- **Virtual Filesystem (VFS)** with in-memory file/directory tree, change tracking, and hot-reload integration\n- **Multi-runtime command execution** with shell-style routing to Bun, Node.js, npm, pnpm, Yarn, Git, Python, and pip\n- **Package manager simulation** with real `package.json` manipulation and lockfile generation (npm, pnpm, Yarn, Bun)\n- **Git workflow simulation** entirely in memory -- init, add, commit, branch, checkout, merge, push, pull, and more\n- **Python/pip workflow simulation** with native fallback on non-WASM targets and Pyodide bridging in browsers\n- **Hot reload engine** with intelligent strategies: CSS injection, HMR, or full reload based on file type\n- **DOM Inspector bridge** for element inspection with box model, computed styles, and highlight overlays\n- **Terminal streams** compatible with xterm.js for bidirectional I/O\n- **AI tool bridge** (`ai_tools` + `ai_dispatch`) for seamless assistant orchestration with OpenAI, Anthropic, and Gemini\n- **MCP Server** (Model Context Protocol) exposing VFS, shell, and console as tools/resources for Claude Desktop, Cursor, Zed, and Continue\n- **Service Worker bridge** for intercepting network requests and serving files from the VFS\n- **HTTP server simulation** via `globalThis.__runbox_servers` for Express/http-style request handling\n\n---\n\n## Installation\n\n```bash\nnpm install @runboxjs/runboxjs\n```\n\nOr with other package managers:\n\n```bash\npnpm add @runboxjs/runboxjs\nyarn add @runboxjs/runboxjs\nbun add @runboxjs/runboxjs\n```\n\n---\n\n## Quick Start\n\n```ts\nimport init, { RunboxInstance } from '@runboxjs/runboxjs';\n\n// Initialize the WASM module (must be awaited before any API calls)\nawait init();\n\n// Create a sandbox instance\nconst runbox = new RunboxInstance();\n\n// Write a file to the virtual filesystem\nrunbox.write_file('/index.js', new TextEncoder().encode(\"console.log('Hello from RunboxJS!');\"));\n\n// Execute the file\nconst result = JSON.parse(runbox.exec('node /index.js'));\nconsole.log(result.stdout); // \"Hello from RunboxJS!\"\n\n// Install packages\nrunbox.exec('npm init -y');\nrunbox.exec('npm add express');\n\n// Git operations\nrunbox.exec('git init');\nrunbox.exec('git add .');\nrunbox.exec('git commit -m \"initial commit\"');\n```\n\n### Browser-side npm install flow (WASM)\n\nIn WASM, direct HTTP requests are not possible from synchronous Rust code. The install flow uses a two-step bridge:\n\n```js\nasync function npmInstall(runbox) {\n  // 1. Ask RunboxJS which packages are missing\n  const needed = JSON.parse(runbox.npm_packages_needed());\n\n  // 2. Fetch each tarball from the registry and feed it to RunboxJS\n  for (const { name, version } of needed) {\n    const meta = await fetch(`https://registry.npmjs.org/${name}/${version}`).then(r => r.json());\n    const buf = await fetch(meta.dist.tarball).then(r => r.arrayBuffer());\n    runbox.npm_process_tarball(name, version, new Uint8Array(buf));\n  }\n}\n```\n\n---\n\n## Vite Integration\n\n`@runboxjs/runboxjs` is built with `wasm-pack --target web`, so Vite can bundle it directly with zero extra configuration:\n\n```bash\nnpm install @runboxjs/runboxjs\n```\n\n```ts\nimport init, { RunboxInstance } from '@runboxjs/runboxjs';\n```\n\nNo `vite-plugin-wasm` is required for standard client-side Vite apps. See [WASM_SETUP.md](./WASM_SETUP.md) for edge cases and troubleshooting.\n\n---\n\n## Runtime Command Support\n\n`runbox.exec(line)` parses and routes commands by program name to the appropriate runtime:\n\n| Category | Commands | Description |\n|---|---|---|\n| **JS Runtime** | `bun`, `node`, `nodejs`, `tsx`, `ts-node` | JavaScript/TypeScript execution via Bun runtime |\n| **Package Managers** | `npm`, `npx`, `pnpm`, `pnpx`, `yarn` | Package install, add, remove, run, exec, init, list, update, audit |\n| **Git** | `git` | In-memory git operations (init, add, commit, status, log, diff, branch, checkout, merge, reset, clone, fetch, pull, push, remote, config) |\n| **Python** | `python`, `python3`, `pip`, `pip3` | Python execution and pip package management |\n| **Shell Builtins** | `echo`, `ls`, `cat`, `pwd`, `mkdir`, `rm`, `touch` | Basic filesystem operations |\n\nAll commands return a JSON string:\n\n```json\n{\n  \"stdout\": \"...\",\n  \"stderr\": \"...\",\n  \"exit_code\": 0\n}\n```\n\n---\n\n## API Overview\n\nAll methods belong to `RunboxInstance`. For complete details, parameters, return types, and examples, see [docs/API_REFERENCE.md](./docs/API_REFERENCE.md).\n\n| Category | Key Methods |\n|---|---|\n| **Filesystem** | `write_file`, `read_file`, `list_dir`, `file_exists`, `remove_file` |\n| **Command Execution** | `exec` |\n| **npm WASM Install** | `npm_packages_needed`, `npm_process_tarball` |\n| **Git Credentials** | `git_set_user`, `git_set_token` |\n| **Console** | `console_push`, `console_all`, `console_since`, `console_clear` |\n| **Terminal** | `terminal_input`, `terminal_drain`, `terminal_resize`, `terminal_size`, `terminal_clear` |\n| **Hot Reload** | `hot_tick`, `hot_flush` |\n| **Inspector** | `inspector_activate`, `inspector_deactivate`, `inspector_is_active`, `inspector_set_node`, `inspector_selected`, `inspector_overlay`, `inspector_history`, `inspector_request` |\n| **Sandbox Bridge** | `sandbox_command`, `sandbox_event` |\n| **HTTP/SW Bridge** | `http_handle_request`, `sw_handle_request` |\n| **AI Tooling** | `ai_tools`, `ai_dispatch` |\n| **Agent Journal** | `journal_entries`, `journal_since` |\n\n---\n\n## MCP Server\n\nRunboxJS includes a full [Model Context Protocol](https://spec.modelcontextprotocol.io) server that exposes its capabilities to AI assistants. It supports the JSON-RPC 2.0 protocol over stdio, HTTP/SSE, and WebSocket transports.\n\n### Supported MCP Clients\n\n- Claude Desktop\n- Cursor\n- Zed\n- Continue\n- Any MCP-compatible client\n\n### Quick Setup (Claude Desktop)\n\nAdd to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"runbox\": {\n      \"command\": \"runbox\",\n      \"args\": []\n    }\n  }\n}\n```\n\nFor detailed MCP setup, tools, resources, and prompts, see [docs/MCP_GUIDE.md](./docs/MCP_GUIDE.md).\n\n---\n\n## AI Integration\n\nRunboxJS provides a built-in AI tool bridge compatible with OpenAI, Anthropic, and Gemini function calling formats:\n\n```ts\n// Get tool definitions for your AI provider\nconst tools = JSON.parse(runbox.ai_tools('openai')); // or 'anthropic', 'gemini'\n\n// Dispatch a tool call from the AI\nconst result = JSON.parse(runbox.ai_dispatch(JSON.stringify({\n  name: 'exec_command',\n  arguments: { command: 'npm run build' }\n})));\n```\n\nAvailable AI tool names: `read_file`, `write_file`, `list_dir`, `exec_command`, `search_code`, `get_console_logs`, `reload_sandbox`, `install_packages`, `get_file_tree`, `agent_memo`, `get_agent_journal`.\n\nFor assistant integration guidance, see [skills/AGENT_SKILL.md](./skills/AGENT_SKILL.md).\n\n---\n\n## Agent Journal\n\nRunboxJS includes a structured **Agent Journal** — a reasoning log that records *why* a change happened, not just *what* changed. This allows any agent (or developer) to resume work with full decision context.\n\n### How it works\n\nAgents call `agent_memo` before acting to record their intent. The journal is stored in `RunboxInstance` and queryable at any time.\n\n```ts\n// Record intent before making a change\nawait runbox.ai_dispatch(JSON.stringify({\n  name: 'agent_memo',\n  arguments: {\n    tool: 'write_file',\n    reason: 'Extracting auth logic into a hook to avoid duplication across 3 components',\n    files_affected: ['/src/hooks/useAuth.ts'],\n  }\n}));\n\n// Then make the change\nawait runbox.ai_dispatch(JSON.stringify({\n  name: 'write_file',\n  arguments: { path: '/src/hooks/useAuth.ts', content: '...' }\n}));\n\n// A future agent reads the journal to understand context\nconst journal = JSON.parse(runbox.journal_entries());\n// Or incrementally:\nconst recent = JSON.parse(runbox.journal_since(lastSeenId));\n```\n\n### Journal entry shape\n\n```json\n{\n  \"id\": 0,\n  \"timestamp_ms\": 1234,\n  \"tool\": \"write_file\",\n  \"reason\": \"Extracting auth logic into a hook to avoid duplication\",\n  \"result_summary\": \"\",\n  \"files_affected\": [\"/src/hooks/useAuth.ts\"]\n}\n```\n\n### AI tool: `get_agent_journal`\n\n```ts\n// All entries\nrunbox.ai_dispatch(JSON.stringify({ name: 'get_agent_journal', arguments: {} }));\n\n// Since a cursor\nrunbox.ai_dispatch(JSON.stringify({ name: 'get_agent_journal', arguments: { since_id: 4 } }));\n\n// Filter by file\nrunbox.ai_dispatch(JSON.stringify({ name: 'get_agent_journal', arguments: { file: '/src/auth.ts' } }));\n```\n\n---\n\n## Local Development\n\n```bash\n# Rust checks and tests\ncargo check\ncargo test\ncargo bench\n\n# WASM package build (writes pkg/package.json from template)\nnode publisher/build.mjs\n\n# Bump version and build\nnode publisher/build.mjs --bump patch\n```\n\nFor detailed build instructions, project setup, and contribution guidelines, see [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md).\n\n---\n\n## Publishing\n\nUse the scripted flow (recommended):\n\n```bash\nnode publisher/build.mjs --bump patch\nnode publisher/build.mjs --publish\n```\n\nDetailed publishing notes: [NPM_PUBLISH.md](./NPM_PUBLISH.md)\n\n---\n\n## Troubleshooting\n\n### \"crate-type must be cdylib\"\n\n`Cargo.toml` must include:\n\n```toml\n[lib]\ncrate-type = [\"cdylib\", \"rlib\"]\n```\n\n### Vite WASM import errors\n\nRunboxJS no longer requires `vite-plugin-wasm`. If you hit a WASM error, clear caches and ensure your app imports `@runboxjs/runboxjs` from the published package entry.\n\n### Missing module after package install\n\nConfirm both:\n1. The dependency exists in `/package.json`\n2. The corresponding package exists under `/node_modules/<name>/package.json`\n\n### Python message \"python3 not found\"\n\nExpected in environments without native Python. In browser WASM flows, host adapters should provide Pyodide integration.\n\n### MCP Server not responding\n\n1. Ensure the `runbox` binary is in your `PATH`\n2. Check stderr for log output (set `RUNBOX_LOG=debug` for verbose logging)\n3. Verify your MCP client configuration matches the transport type\n\nFor more troubleshooting, see [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md#troubleshooting).\n\n---\n\n## Documentation Index\n\n| Document | Description |\n|---|---|\n| [CHANGELOG.md](./CHANGELOG.md) | Release history and notable changes |\n| [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) | Internal architecture, module structure, data flow, and design decisions |\n| [docs/API_REFERENCE.md](./docs/API_REFERENCE.md) | Complete API reference with all methods, parameters, return types, and examples |\n| [docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md) | Local development setup, building, testing, and contributing |\n| [docs/MCP_GUIDE.md](./docs/MCP_GUIDE.md) | MCP server setup, tools, resources, prompts, and client integration |\n| [TECHNICAL_DOCS.md](./TECHNICAL_DOCS.md) | Legacy technical documentation |\n| [WASM_SETUP.md](./WASM_SETUP.md) | WASM setup guide for Vite integration |\n| [NPM_PUBLISH.md](./NPM_PUBLISH.md) | npm publishing guide |\n| [skills/AGENT_SKILL.md](./skills/AGENT_SKILL.md) | AI assistant integration skill guide |\n\n---\n\n## License\n\nMIT\n"}