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 exactly one pvc or ossfs backend and an absolute mount path. PVCs support createIfNotExists, deleteOnSandboxTermination, storageClass, storage, and accessModes. OSSFS supports bucket, endpoint, version, options, accessKeyId, and accessKeySecret.

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

timeoutSeconds defaults to 3600 and must be a positive safe integer. The extension passes it to OpenSandbox without imposing a duration cap; the server's configured maximum still applies. Active sessions renew every half TTL or one hour, whichever is shorter, setting expiration to the renewal time plus timeoutSeconds. Existing sandboxes are also renewed when connected or resumed. Renewal failures are logged and retried at the next interval. Requests never overlap, and shutdown stops renewal and awaits any pending request before pause, kill, or disconnect. Worker crashes stop renewal; this is not durable task recovery.

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

Run the renewal regression tests from this package directory (mock timers and sandbox clients; no live services required):

node --import tsx --test scripts/renewal.test.mjs