@pleach/sandbox
Vendor-neutral SandboxProvider contract — the seam @pleach/coding-agent reads, with adapter packages slotting under it for Docker, Firecracker, E2B, Modal, or your own runner.
@pleach/sandbox is the contract layer between @pleach/core
runtimes and whatever process isolation a host chooses to ship —
a Docker container, a Firecracker microVM, an E2B or Modal
sandbox, an in-process fixture. It ships the SandboxProvider
interface plus an in-memory fixture; vendor adapters publish
under their own names (@pleach/sandbox-<vendor>) and slot in
against the same contract. @pleach/coding-agent is the
canonical consumer — its file-read, file-write, and shell tools
all dispatch through the provider this package defines.
What it provides
- The
SandboxProvidercontract a host implements once and reuses across every sandboxed tool — read, write, list, exec — per the four-tool sketch incoding-agent.mdx. - An in-memory fixture suitable for tests and replay runs where the host hasn't wired a real backing process.
- The canonical name (
SandboxProvider) plus the legacySandboxAdapterretained as a@deprecatedalias, per the status row inpackages.mdx. - The peer-dep anchor
@pleach/coding-agentdeclares at^0.1.0(see Coding agent for the locked decisions).
Where it fits
@pleach/sandbox is the seam between the runtime and the
sandboxed tool surface — the low-level SandboxProvider contract
(execute, readFile, writeFile, listFiles, plus
acquire / release / capabilities). There is no ctx.sandbox:
core's ToolContext is sandbox-agnostic and carries only
toolCallId + signal?. Instead the host closes over a sandbox
handle when it constructs the tools; @pleach/coding-agent ships a
thin SandboxClient facade (exec, readFile, writeFile) built
over the low-level provider, and the tool handlers call that — see
Coding agent. The
direction lock keeps @pleach/core itself sandbox-agnostic:
consumers reach for @pleach/sandbox directly, and the coding-agent
SKU composes on top of both.
Install
npm install @pleach/sandboxAPI surface
The constructor signature, the full SandboxProvider method
set, the option shapes for the in-memory fixture, and the
@deprecated alias surface all live on the package's npm page:
@pleach/sandbox.
This page is placement orientation — what the SKU is for and
where it slots into the substrate. The npm README is the source
of truth for the contract itself; if a claim here disagrees with
the published README, the README wins.
Where to go next
@pleach/base-tools
Domain-agnostic tool primitives — math, datetime, scratchpad, unit_convert, text_search, and opt-in url_fetch with a citation extractor.
@pleach/replay
The `@pleach/replay` package — ReplayClient + ReplayHandle walk the canonical event log via runtime.events.iterate/fold, with tenantId required and a typed cache-miss policy.