# @pleach/sandbox (/docs/sandbox)



`@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 [#what-it-provides]

* The `SandboxProvider` contract a host implements once and
  reuses across every sandboxed tool — read, write, list, exec —
  per the four-tool sketch in `coding-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 legacy
  `SandboxAdapter` retained as a `@deprecated` alias, per the
  status row in `packages.mdx`.
* The peer-dep anchor `@pleach/coding-agent` declares at
  `^0.1.0` (see [Coding agent](/docs/coding-agent#locked-decisions) for the locked
  decisions).

## Where it fits [#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](/docs/coding-agent#sandbox-tool-surface). 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 [#install]

```bash
npm install @pleach/sandbox
```

## API surface [#api-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`](https://www.npmjs.com/package/@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 [#where-to-go-next]

<Cards>
  <Card title="Coding agent" href="/docs/coding-agent" description="The canonical consumer — sandboxed tools, per-edit checkpoints, replay-as-debugger." />

  <Card title="Packages" href="/docs/packages" description="The full @pleach/* SKU matrix and the contract status for @pleach/sandbox." />

  <Card title="Architecture" href="/docs/architecture" description="The substrate map — where sandboxed tool dispatch sits relative to seams, the audit ledger, and the event log." />
</Cards>