@summersmile/mastra-opensandbox

OpenSandbox provider for Mastra workspaces.

This package implements a cleaner standalone OpenSandbox integration aimed at Mastra's current workspace provider model:

• OpenSandboxSandbox for workspace command execution and lifecycle management
• OpenSandboxProcessManager for background session-based processes
• openSandboxProvider for Mastra Editor / stored sandbox config hydration
• createCodeInterpreterTools() for OpenSandbox code-interpreter helpers

Status

This package is an initial provider skeleton. It is intentionally opinionated in a few areas:

• It supports automatic reconnect by logical Mastra sandbox ID via metadata.
• It exposes the raw OpenSandbox SDK handle through sandbox.opensandbox.
• It supports OpenSandbox-native volumes passed at sandbox creation time.
• It translates Mastra LocalFilesystem mounts into OpenSandbox host volumes at sandbox creation time.
• It does not support dynamic mount / unmount after the sandbox is already running.
• It does not support interactive stdin for spawned processes because the current OpenSandbox JS SDK does not expose that capability.

Install

npm install @summersmile/mastra-opensandbox @mastra/core

Usage

import { Agent } from "@mastra/core/agent";
import { Workspace } from "@mastra/core/workspace";
import { OpenSandboxSandbox } from "@summersmile/mastra-opensandbox";

const sandbox = new OpenSandboxSandbox({
  id: "my-dev-sandbox",
  domain: "127.0.0.1:8080",
  image: "ubuntu",
  timeoutSeconds: 600
});

const workspace = new Workspace({ sandbox });

const agent = new Agent({
  name: "dev-agent",
  model: "openai/gpt-4.1",
  instructions: "You can execute commands in the sandbox.",
  workspace
});

Local Mounts

import { LocalFilesystem, Workspace } from "@mastra/core/workspace";
import { OpenSandboxSandbox } from "@summersmile/mastra-opensandbox";

const sandbox = new OpenSandboxSandbox({
  domain: "127.0.0.1:8080"
});

const workspace = new Workspace({
  sandbox,
  mounts: {
    "/mnt/project": new LocalFilesystem({
      basePath: "./fixtures/project"
    })
  }
});

OpenSandbox host volumes are immutable after sandbox creation, so add local mounts before the first sandbox start. Your OpenSandbox server must allow the host path prefix through [storage].allowed_host_paths; an empty list means "allow all" and is only suitable for local development.

Editor Provider

import { MastraEditor } from "@mastra/core/editor";
import { openSandboxProvider } from "@summersmile/mastra-opensandbox";

const editor = new MastraEditor({
  sandboxes: {
    [openSandboxProvider.id]: openSandboxProvider
  }
});

Code Interpreter Tools

import { createCodeInterpreterTools } from "@summersmile/mastra-opensandbox";

const tools = createCodeInterpreterTools(sandbox);

Local Smoke Test

1. Start OpenSandbox server with Docker runtime.
2. Build the package with npm run build.
3. Run npm run smoke.

For local development you can use examples/opensandbox-server.dev.toml as a starting point. It leaves allowed_host_paths empty, which is unsafe for production but convenient for verifying host mounts locally.

Integration Tests

Run npm run test:integration.

The integration runner starts its own temporary OpenSandbox server, allocates a random local port, and cleans up test sandboxes automatically. It requires:

• Docker Desktop / Docker Engine
• uvx on PATH

Agent Test

Run npm run test:agent.

This script builds the package first, creates a real Mastra Agent, binds it to a Workspace backed by OpenSandboxSandbox, mounts a LocalFilesystem from scripts/agent-test-workspace to /workspace, forces it to use mastra_workspace_execute_command, and verifies both of these conditions:

• the agent actually invokes the workspace command tool
• the agent writes /workspace/agent-proof.txt with VERIFIED inside the sandbox

By default it uses openai/gpt-4.1-mini; override with MASTRA_TEST_MODEL.

You need the matching model provider key in the environment, for example:

• OPENAI_API_KEY for openai/*
• ANTHROPIC_API_KEY for anthropic/*
• GOOGLE_GENERATIVE_AI_API_KEY for google/*
• OPENROUTER_API_KEY for openrouter/*

For OpenAI-compatible endpoints such as Chutes, provide a model object through environment variables instead of a plain model string:

• MASTRA_TEST_MODEL_URL
• MASTRA_TEST_MODEL_API_KEY
• MASTRA_TEST_PROVIDER_ID
• MASTRA_TEST_MODEL_ID

Chutes also has convenience aliases:

• CHUTES_BASE_URL
• CHUTES_API_KEY
• CHUTES_PROVIDER_ID (optional, defaults to chutes)
• CHUTES_MODEL

If OPEN_SANDBOX_DOMAIN is unset, the script starts a temporary local OpenSandbox server with Docker automatically.

The host-backed proof file remains on disk after the run at scripts/agent-test-workspace/agent-proof.txt.

CI

A minimal GitHub Actions workflow is included at .github/workflows/ci.yml. It runs npm ci, npm run typecheck, npm run build, and npm run test:integration on ubuntu-latest.