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.