sandbox_initialize
Start an isolated Docker container running Node.js to create a secure environment for executing scripts and managing dependencies with controlled resource limits.
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 handler function that initializes a new Docker container sandbox for Node.js execution, handling Docker checks, resource limits, labels, volume mounts, and error 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 schema validation using Zod for optional image (Docker image) and port parameters.
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)MCP server tool registration linking the name, description, schema, and handler for sandbox_initialize.
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 );