Tianyi Cui
9d385cd0d9
Preserve the persistent runtime package description with master's alpha.2 version and locale exports. Refresh the two PTC prompt snapshots for the current plan-tool result type. Validation: full build, 434 focused tests (one skipped), two built-runtime tests, two selected snapshots, package metadata, and all 43 doc-sync checks passed.
description, kind
| description | kind |
|---|---|
| The process-sandbox package group: the confinement seam, per-platform backends, the shared policy resolver, and the Windows write-restriction rung. | package-group |
packages/sandbox
English | 中文
Summary
The sandbox/ group confines subprocess execution to a file-effect policy: commands run read-only, write only under the session workspace (workspace-write), or run unrestricted (danger-full-access). Four packages deliver it: the confinement service (sandbox/), the per-platform backends for Linux, macOS, and Windows (sandbox-local/), the shared policy resolver (sandbox-policy/), and the Windows write-restriction backend (sandbox-windows-acl/). A confined call that a policy denies can retry through a user-approved one-time escalation. Confinement is same-world only: it shares the host kernel and filesystem, while containers, microVMs, and remote executors replace whole capabilities instead of registering here.
Table of Contents
Packages
Four packages play the confinement roles; the subsystem reference owns the exhaustive contracts and the per-call policy semantics.
| Package | Role | ctx key |
|---|---|---|
sandbox/ |
Confinement service contract: modes, enforcement, per-call policy, and the escalation vocabulary | ctx.sandbox |
sandbox-local/ |
Per-platform confinement backends: Linux bwrap then Landlock, macOS Seatbelt, Windows restricted token | registers on ctx.sandbox |
sandbox-policy/ |
Shared policy home: deployment defaults and per-session mode overrides for every enforcing family | ctx.sandboxPolicy |
sandbox-windows-acl/ |
Windows write restriction: confined children may write only in the workspace and a private temp directory | — (mounted by sandbox-local as the win32 backend) |
Related documentation
Start with the subsystem reference for the shared vocabulary, then the confinement decision and its cross-family extension.
- Process sandbox subsystem — modes, per-call policy, wrapped-argv dialects, and fail-closed errors.
- The historical subprocess sandbox decision — the capability boundary, escalation choreography, and deferred phases.
- Cross-family file sandbox reference — the shared policy home and the sandboxed filesystem provider.
- Windows ACL restricted-token sandbox decision — why raw ACL restricted tokens over mxc and AppContainer.
Dev Note
Working context for maintainers — click to expand
None.