@mayflower/mayflower-sandboxjs

Browser-native DeepAgents sandbox backend built on top of BusyBox WASM and Pyodide.

License

This package is distributed under GPL-2.0-only.

The reason is straightforward: the published build bundles BusyBox WebAssembly assets under dist/assets/busybox/. Because BusyBox is GPLv2 and is redistributed as part of this package, the safe package-level license is GPL-2.0-only.

Corresponding BusyBox source and build materials are copied into dist/third_party/busybox-wasm/ during pnpm run build. See THIRD_PARTY_NOTICES.md for the shipped third-party compliance details.

Status

This repository currently ships:

• BrowserWasmSandbox extends BaseSandbox
• In-memory and persistent workspace adapters (memory, auto, persistent)
• BusyBox-backed shell execution
• Pyodide-backed Python execution
• Mixed command orchestration for top-level python stages
• Build-time asset packaging under dist/assets

Install

pnpm install
pnpm run build

Usage

import { BrowserWasmSandbox } from "@mayflower/mayflower-sandboxjs";

const sandbox = await BrowserWasmSandbox.create({
  persistence: "memory",
  allowNetwork: false,
  statefulPython: true,
});

await sandbox.uploadFiles([
  ["/tmp/demo.py", new TextEncoder().encode("print('hello from pyodide')")],
]);

const result = await sandbox.execute("python /tmp/demo.py");
console.log(result.output, result.exitCode);

const downloaded = await sandbox.downloadFiles(["/tmp/demo.py"]);
console.log(downloaded[0]);

await sandbox.close();

Asset Modes

Bundled mode:

• Build the package with pnpm run build.
• Consume the package normally and let the bundler rewrite the new URL(..., import.meta.url) asset references.

Self-hosted mode:

• Serve dist/assets/ from your app.
• Pass assetBaseUrl to BrowserWasmSandbox.create({ assetBaseUrl }).

Build output also contains dist/third_party/busybox-wasm/, which is the BusyBox-related source and build material shipped with the package for GPL compliance.

Example

The repo contains a Vite demo in examples/vite-demo.

pnpm run example:dev

Notes

• Network access is disabled by default.
• The canonical workspace lives outside the runtime filesystems and is committed atomically after successful execution.
• V1 does not provide streaming logs or shell session persistence across calls.
• If you replace BusyBox with a differently licensed shell runtime in the future, the package-level licensing constraints may change.