Secure JavaScript code execution sandbox using Deno for MCPC agents. This package provides a safe environment to execute user-provided JavaScript code with MCP tool access via JSON-RPC IPC.
- 🔒 Secure Sandboxing: Uses Deno's permission system for isolated code execution with JSON-RPC IPC for tool calls between sandbox and host (handle-sandbox)
- 🚀 Easy Integration: Plugin-based integration with MCPC
- 📦 Zero Config: Automatically locates Deno binary from npm package
- 🛡️ Resource Limits: Configurable timeouts and memory limits
# npm
npm install @mcpc-tech/plugin-code-execution
pnpm add @mcpc-tech/plugin-code-execution
# jsr
npx jsr add @mcpc/plugin-code-execution
pnpm add jsr:@mcpc/plugin-code-executionimport { mcpc } from "@mcpc/core";
import { createCodeExecutionPlugin } from "@mcpc/plugin-code-execution/plugin";
const server = await mcpc(
[{ name: "my-agent", version: "1.0.0" }, {
capabilities: { tools: {} },
}],
[{
name: "my-agent",
description: `
An agent that can execute JavaScript code securely.
<tool name="filesystem.read_file"/>
<tool name="filesystem.write_file"/>
`,
deps: {
mcpServers: {
"filesystem": {
command: "npx",
args: ["-y", "@wonderwhy-er/desktop-commander@latest"],
transportType: "stdio",
},
},
},
plugins: [
createCodeExecutionPlugin({
sandbox: {
timeout: 30000, // 30 seconds
memoryLimit: 512, // 512 MB
permissions: [], // No extra permissions
},
}),
],
options: {
mode: "code_execution",
},
}],
);The plugin exposes a Unix-style interface with tool and args:
// Execute code
await callTool("my-agent", {
tool: "exec",
args: { code: "2 + 2" },
});
// Get tool documentation (like Unix man command)
await callTool("my-agent", {
tool: "man",
args: { tools: ["filesystem.read_file"] }, // optional: specific tools
});The plugin uses bidirectional JSON-RPC communication:
- Host spawns Deno sandbox subprocess
- Host sends
executeCoderequest with user's JavaScript code - Sandbox runs the code
- When code calls
callMCPTool(toolName, params):- Sandbox sends
callToolrequest to host - Host executes the actual MCP tool
- Host sends response back to sandbox
- Sandbox receives result and continues code execution
- Sandbox sends
- Sandbox returns final execution result to host
The Deno sandbox runs with minimal permissions by default. You control access by passing Deno permission flags directly:
// No permissions - can only call MCP tools
createCodeExecutionPlugin();
// Allow network access to specific domains
createCodeExecutionPlugin({
sandbox: {
permissions: ["--allow-net=github.com,api.example.com"],
},
});
// Allow reading specific directories
createCodeExecutionPlugin({
sandbox: {
permissions: ["--allow-read=/tmp,/var/log"],
},
});interface SandboxConfig {
timeout?: number; // Execution timeout in ms (default: 30000)
memoryLimit?: number; // Memory limit in MB (default: unlimited)
permissions?: string[]; // Deno flags, e.g., ["--allow-net", "--allow-read=/tmp"]
}Example with custom permissions:
createCodeExecutionPlugin({
sandbox: {
timeout: 60000,
permissions: [
"--allow-net=api.example.com",
"--allow-read=/tmp",
"--allow-env=HOME,USER",
],
},
});sequenceDiagram
participant Host as Host (Node)
participant Sandbox as Sandbox (Deno)
Host->>Sandbox: executeCode("fetch('https://google.com')")
activate Sandbox
Note over Sandbox: deno run --no-prompt
Sandbox--xHost: PermissionDenied: --allow-net needed
deactivate Sandbox
Host->>Sandbox: executeCode("callMCPTool('http.fetch', ...)")
activate Sandbox
Sandbox->>Host: callTool('http.fetch', {url: 'https://google.com'})
activate Host
Note over Host: Execute MCP tool
Host-->>Sandbox: {status: 200, body: "..."}
deactivate Host
Sandbox-->>Host: execution result
deactivate Sandbox
Permission Model
// Sandbox runs WITHOUT permissions by default
// ❌ These operations will fail:
const code = `
await Deno.readTextFile('/file.txt'); // PermissionDenied: --allow-read needed
await fetch('https://api.com'); // PermissionDenied: --allow-net needed
Deno.env.get('SECRET'); // PermissionDenied: --allow-env needed
`;
// ✅ All operations must go through MCP tools:
const code = `
await callMCPTool('desktop-commander.read_file', { path: '/file.txt' });
await callMCPTool('http-client.fetch', { url: 'https://api.com' });
`;
// Or grant specific permissions if needed:
createCodeExecutionPlugin({
sandbox: {
permissions: ["--allow-net=api.example.com", "--allow-read=/tmp"],
},
});See examples/ directory for complete examples:
basic-usage.ts- Simple code execution with plugin integration
# Run tests
deno test --allow-all tests/
# Run example
deno run --allow-all examples/basic-usage.tsMIT