sandbox_initialize
Initialize an isolated Docker container with Node.js to create a secure execution environment for running JavaScript code and NPM packages.
Instructions
Start a new isolated Docker container running Node.js. Used to set up a sandbox session for multiple commands and scripts.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | ||
| port | No | If set, maps this container port to the host |
Implementation Reference
- src/tools/initialize.ts:31-92 (handler)The main handler function `initializeSandbox` that executes the tool logic: checks Docker, creates a labeled Docker container with volume mount, registers it, and returns the container ID or handles errors with cleanup.export default async function initializeSandbox({ image = DEFAULT_NODE_IMAGE, port, }: { image?: string; port?: number; }): Promise<McpResponse> { if (!isDockerRunning()) { return { content: [textContent(DOCKER_NOT_RUNNING_ERROR)], }; } const containerId = `js-sbx-${randomUUID()}`; const creationTimestamp = Date.now(); const portOption = port ? `-p ${port}:${port}` : `--network host`; // prefer --network host if no explicit port mapping // Construct labels const labels = [ `mcp-sandbox=true`, `mcp-server-run-id=${serverRunId}`, `mcp-creation-timestamp=${creationTimestamp}`, ]; const labelArgs = labels.map((label) => `--label "${label}"`).join(' '); const { memFlag, cpuFlag } = computeResourceLimits(image); try { execSync( `docker run -d ${portOption} ${memFlag} ${cpuFlag} ` + `--workdir /workspace -v ${getFilesDir()}:/workspace/files ` + `${labelArgs} ` + // Add labels here `--name ${containerId} ${image} tail -f /dev/null` ); // Register the container only after successful creation activeSandboxContainers.set(containerId, creationTimestamp); logger.info(`Registered container ${containerId}`); return { content: [textContent(containerId)], }; } catch (error) { logger.error(`Failed to initialize container ${containerId}`, error); // Ensure partial cleanup if execSync fails after container might be created but before registration try { execSync(`docker rm -f ${containerId}`); } catch (cleanupError: unknown) { // Ignore cleanup errors - log it just in case logger.warning( `Ignoring error during cleanup attempt for ${containerId}: ${String(cleanupError)}` ); } return { content: [ textContent( `Failed to initialize sandbox container: ${error instanceof Error ? error.message : String(error)}` ), ], }; } }
- src/tools/initialize.ts:23-29 (schema)Input argument schema using Zod: optional `image` (Docker image) and `port` (host port mapping).export const argSchema = { image: z.string().optional(), port: z .number() .optional() .describe('If set, maps this container port to the host'), };
- src/server.ts:51-56 (registration)Registration of the 'sandbox_initialize' tool on the MCP server instance, specifying name, description, input schema, and handler function.server.tool( 'sandbox_initialize', 'Start a new isolated Docker container running Node.js. Used to set up a sandbox session for multiple commands and scripts.', initializeSchema, initializeSandbox );