@b4run/sandbox

Docker and Kubernetes sandbox providers for isolated B4.run workspace execution.

Use this when: You need to isolate workspace filesystem and shell execution from the B4.run host process.

Install

pnpm add @b4run/sandbox

Example

import { dockerSandbox } from "@b4run/sandbox"
import { fakeSandbox } from "@b4run/sandbox/testing"

const provider = dockerSandbox({ scope: "my-app", image: "node:24-slim" })
const testProvider = fakeSandbox()

Runtime and stability

• @b4run/sandbox is a node-only, supported application surface.
• @b4run/sandbox/testing is a node-only, supported testing surface.

A sandbox narrows where workspace operations run; applications still own image hardening, credentials, network policy, and resource limits.

Related

• Sandbox API reference — Docker, Kubernetes, and testing provider contracts.
• Execution Sandbox guide — application setup and security boundaries.
• @b4run/workspace — the filesystem and shell contracts sandbox providers implement.

Maturity and support

B4.run is pre-1.0, and its public surface can change. All publishable B4.run packages release together as a fixed group; review the @b4run/sandbox changelog and upgrading guide before upgrading. For support, use GitHub Discussions; report defects in GitHub Issues.

License

MIT. See the repository license.

Both providers require a stable application/environment scope. Resource names hash scope and the exact thread ID; logical thread IDs remain unchanged. Missing or blank scopes fail immediately. Scope is not authorization or cross-process coordination. Keep it stable across restarts and separate independent deployments.

Breaking change: all resource names change from the former unscoped providers. Existing storage is not automatically reattached, migrated, or deleted. Export required data before upgrading and manage old resources explicitly. Changing scope also selects different storage.