Node Code Sandbox

Node Code Sandbox

based sandboxes for executing JavaScript snippets with on-the-fly npm dependency installation

136
Stars
26
Forks
0
Releases

Overview

This MCP server implements the Model Context Protocol (MCP) to execute arbitrary JavaScript inside isolated, ephemeral Docker containers, with on-the-fly npm dependency installation. It supports starting and managing Node.js sandbox containers, executing shell commands inside them, and installing per-job npm dependencies before running code. JavaScript snippets can be written as ES modules and their standard output is captured for the response. After execution, containers are torn down cleanly unless detached mode is used to keep them alive for long-running services. The server emphasizes reproducibility and isolation, and offers guidance for ephemeral usage (no persistent host storage). It is intended to be used via MCP clients (e.g., Claude Desktop, VS Code) and can be run locally with Docker or via NPX. The README also outlines example prompts to validate functionality (e.g., printing Hello World, generating files like qrcode.png), and provides configurations for Docker and NPX usage, as well as a VS Code setup. Tools exposed include run_js_ephemeral, sandbox_initialize, sandbox_exec, run_js, sandbox_stop, and search_npm_packages, enabling a full lifecycle of sandbox management, code execution, and package discovery.

Details

Owner
alfonsograziano
Language
TypeScript
License
Updated
2025-12-07

Features

Isolated Node.js sandbox containers

Start and manage isolated Node.js sandbox containers for each job, ensuring environment isolation and reproducibility.

Execute shell commands inside containers

Run arbitrary shell commands within the sandbox to interact with the runtime environment.

Per-job npm dependency installation

Install specified npm dependencies per job before script execution.

ES Module support and stdout capture

Run ES module JavaScript snippets and capture stdout for results.

Tear down containers cleanly

Automatically remove containers after execution (with an option for detached mode to keep them alive).

Detached mode for long-running services

Keep the sandbox container running after script execution to support long-lived servers.

Ephemeral usage (no persistent storage)

Operate with ephemeral containers and no mandatory host storage by default.

Return files and outputs to host

If scripts save files, return stdout and any created files (including images) to the host via the configured files directory.

Audience

DevelopersRun JS in isolated sandboxes with on-the-fly npm installs for experiments.
AI engineersExecute code via MCP clients (Claude, VS Code) in ephemeral containers for experiments.
EducatorsDemonstrate code execution and npm installs in reproducible sandboxes for teaching.

Tags

Node.jssandboxMCPDockerephemeralnpmES modulesCLIVS CodeClaudeserver