@pi-harness/plugin-docker-sandbox

Docker Sandbox — Run descriptor-safe argv commands with local-only Docker images, no container network, a read-only workspace by default, fixed CPU, memory, and PID limits, sanitized output, strict panel reporting, and cancellation cleanup.

Returned sanitized output is limited to 12,000 UTF-8 bytes. When it exceeds that budget, the tool and panel include an explicit tail-only truncation notice within the same budget. Unicode characters are not split. The panel may shorten this returned preview further and separately indicates that display truncation.

Install

npm install --save-exact @pi-harness/plugin-docker-sandbox

Enable

Add the entry to the Cordis profile the harness starts from:

- id: docker-sandbox
  name: "@pi-harness/plugin-docker-sandbox"
  config: {}

The Pi Harness plugin marketplace installs and enables this package for you; the steps above are the manual equivalent.

Native workspace

sandbox_exec binds both the workspace mount and the Docker client working directory to the native session that initiated the call. Before a native session is available, it uses the harness launch directory. Session replacement, session ID changes, or workspace changes clear the prior panel result. The scope is checked after image inspection, immediately before container startup, and before returning a result.

A session change prevents a pending container from starting and discards results from an older scope. It does not immediately interrupt an already-started container; existing run timeouts and caller/disposal cancellation cleanup still apply, and completed writes cannot be rolled back. Writable mounts continue to require both write=true and confirmWrite=true.

If Docker auto-removal races explicit cleanup, the plugin waits up to 10 additional seconds for Docker to confirm the container is absent. Permission errors, other inspection failures, and removal timeouts remain cleanup errors.

The 120-second run timeout force-terminates the local Docker client before forcibly removing its owned container. A container process ignoring SIGTERM cannot extend the run until its normal completion. Cleanup time is additional to the run deadline; a failed cleanup is reported rather than hidden.

Image inspection distinguishes a missing local image from daemon connection, permission, or other Docker failures. Other inspection failures retain Docker's bounded, sanitized diagnostic instead of advising that the image is missing. Inspection never pulls an image or starts a container.