Pi OpenSandbox Extension

pi-extension-opensandbox is a server-side Pi extension factory. It routes Pi's bash, read, write, edit, ls, find, and grep tools to one task-scoped OpenSandbox instance. It has no CLI flags and does not read environment variables.

Embed

Create a factory from validated task input and supply it as an inline extension:

import { createOpenSandboxExtension } from "pi-extension-opensandbox";

const extensionFactories = [{
  name: "opensandbox",
  factory: createOpenSandboxExtension({ config: taskSandbox }),
}];

Pass extensionFactories to createAgentSessionServices. Bind extensions before prompting and dispose the enclosing AgentSessionRuntime in a finally block. Disposal emits session_shutdown; a sandbox created by the task is killed, while a connected sandbox is only disconnected.

Configuration

The factory config requires domain. protocol defaults to http; apiKey is optional and should be supplied by the embedding service, not an untrusted caller.

Creation requires exactly one source:

{
  "domain": "sandbox.internal:8080",
  "image": "opensandbox/code-interpreter:v1.1.0",
  "workspace": "/workspace",
  "volumes": [{
    "name": "task-workspace",
    "pvc": { "claimName": "piworker-cwd-pvc" },
    "mountPath": "/workspace"
  }]
}

Use snapshotId instead of image to create from a snapshot. A volume has one PVC backend and an absolute mount path. PVCs support createIfNotExists, deleteOnSandboxTermination, storageClass, storage, and accessModes.

To operate an existing sandbox, provide only sandboxId with connection settings:

{
  "domain": "sandbox.internal:8080",
  "sandboxId": "sbx_123",
  "workspace": "/workspace"
}

Sandbox.connect() cannot add an image, snapshot, or mounts. The factory rejects those create-only fields for a connected sandbox. A paused sandbox is resumed before the agent begins.

Safety

Remote-tool startup failures are fail-closed: no tool or interactive shell command falls back to the worker host. Metadata keys under opensandbox.io/ are rejected. Network egress is default-deny; networkAllowlist becomes explicit allow rules.

Development Checks

pnpm --dir packages/pi-extension-opensandbox check