mastra-opensandbox

OpenSandbox integration for the Mastra agent framework.

Provides a WorkspaceSandbox implementation, background process management, Code Interpreter tools, and network policy controls for running AI agent workloads in isolated Docker containers.

Features

• OpenSandboxSandbox — Full WorkspaceSandbox implementation with lifecycle management (start, stop, destroy, reconnect)
• OpenSandboxProcessManager — Background process spawning and management via sandbox sessions
• Code Interpreter Tools — runCode, writeFile, readFile Mastra tools for multi-language code execution (Python, JavaScript, TypeScript, Java, Go, Bash)
• Network Policy — Egress controls at sandbox creation time and runtime patching

Prerequisites

• Node.js >= 22.13.0
• Docker (for running OpenSandbox server)
• OpenSandbox server running (self-hosted or cloud)

Installation

npm install mastra-opensandbox @mastra/core zod

Quick Start

1. Start the OpenSandbox server

# Using docker-compose (included in this repo)
docker-compose up -d

# Pre-pull the code interpreter image
docker pull opensandbox/code-interpreter:latest

2. Create an agent with a sandbox workspace

import { Agent } from '@mastra/core/agent';
import { Workspace } from '@mastra/core/workspace';
import { OpenSandboxSandbox, createCodeInterpreterTools } from 'mastra-opensandbox';

const sandbox = new OpenSandboxSandbox({
  domain: 'localhost:8080',
  image: 'opensandbox/code-interpreter:latest',
  timeoutSeconds: 600,
});

const tools = createCodeInterpreterTools(sandbox);

const agent = new Agent({
  name: 'dev-agent',
  model: { provider: 'ANTHROPIC', name: 'claude-sonnet-4-6' },
  instructions: 'You are a coding assistant. Use the sandbox to run code.',
  workspace: new Workspace({ sandbox }),
  tools,
});

const response = await agent.generate('Run Python: print(2 + 2)');

API Reference

OpenSandboxSandbox

Main sandbox class implementing Mastra's WorkspaceSandbox interface.

const sandbox = new OpenSandboxSandbox(config?: OpenSandboxConfig);

OpenSandboxConfig

| Option | Type | Default | Description | |--------|------|---------|-------------| | domain | string | process.env.OPENSANDBOX_DOMAIN ?? 'localhost:8080' | Server host:port | | apiKey | string | process.env.OPENSANDBOX_API_KEY | API key | | protocol | 'http' \| 'https' | 'http' | Connection protocol | | requestTimeoutSeconds | number | 30 | HTTP timeout | | image | string | 'opensandbox/code-interpreter:latest' | Docker image | | entrypoint | string[] | — | Custom entrypoint | | env | Record<string, string> | — | Environment variables | | timeoutSeconds | number \| null | 600 | Sandbox TTL (null = no expiry) | | metadata | Record<string, string> | — | Metadata labels | | networkPolicy | NetworkPolicy | — | Egress policy | | sandboxId | string | — | Reconnect to existing sandbox | | workingDirectory | string | '/home/user' | Default working directory |

Methods

| Method | Description | |--------|-------------| | start() | Create or connect to sandbox | | stop() | Pause the sandbox | | destroy() | Kill and clean up | | executeCommand(cmd, args?, opts?) | Run a shell command | | getInfo() | Get sandbox status | | getInstructions() | System prompt instructions | | getEgressPolicy() | Get current network policy | | patchEgressRules(rules) | Update egress rules at runtime |

Properties

| Property | Type | Description | |----------|------|-------------| | instance | Sandbox | Raw OpenSandbox SDK handle (throws if not started) | | connectionConfig | ConnectionConfig | Current connection config | | processes | OpenSandboxProcessManager | Background process manager |

createCodeInterpreterTools(sandbox)

Creates three Mastra tools for code execution:

• runCode — Execute code in Python, JS, TS, Java, Go, or Bash with session state
• writeFile — Write a file inside the sandbox
• readFile — Read a file from the sandbox

const tools = createCodeInterpreterTools(sandbox);
// tools.runCode, tools.writeFile, tools.readFile

OpenSandboxProcessManager

Background process management (accessible via sandbox.processes):

const handle = await sandbox.processes.spawn('node server.js');
const list = await sandbox.processes.list();
await sandbox.processes.kill(handle.pid);

Network Policy

Control outbound network access:

// At creation time
const sandbox = new OpenSandboxSandbox({
  networkPolicy: {
    defaultAction: 'deny',
    egress: [
      { action: 'allow', target: 'pypi.org' },
      { action: 'allow', target: 'npmjs.org' },
    ],
  },
});

// At runtime
await sandbox.patchEgressRules([
  { action: 'allow', target: 'github.com' },
]);

Deployment Modes

| Mode | Configuration | |------|---------------| | Local Docker | domain: 'localhost:8080' | | Self-hosted (same network) | domain: 'opensandbox.internal:8080' | | Self-hosted (TLS) | domain: 'sandbox.mycompany.com', protocol: 'https', apiKey: '...' | | Kubernetes | domain: 'opensandbox-server.sandbox-ns.svc:8080' |

Development

# Install dependencies
npm install

# Build
npm run build

# Type check
npm run typecheck

# Run unit tests
npm run test

# Run integration tests (requires Docker + OpenSandbox server)
docker-compose up -d
npm run test:integration

# Lint
npm run lint

# Format
npm run format

License

The project is published under the BSD 3-Clause license. For details see the LICENSE file.