Palmshed Sandbox (palmshed/sandbox)

General-purpose, language-agnostic sandbox specification and multi-language SDK suite.

palmshed/sandbox provides a canonical runtime specification (spec/) and SDKs for secure process execution, filesystem isolation, resource limits, network policies, and stdout/stderr streaming across pluggable execution backends.

---

Current Status & Stability Expectations

• SDK Release Version: v1.3.0 (Phase 2 complete plus the optional RFC 0006 OS filesystem isolation extension, the optional RFC 0007 CPU hard quota extension, best-effort peakMemoryBytes, bounded retained output with truncated, and macOS Seatbelt confinement)
• Runtime Specification: 1.3.0 (the 1.0.0 contract stays frozen; 1.1.0, 1.2.0, and 1.3.0 add only optional extensions and one documented retention behavior; see spec/version.md)
• Stability: Stable. The runtime contract is frozen at v1.0.0 with 1.1.0, 1.2.0, and 1.3.0 adding only optional extensions plus the documented retention behavior. API contracts follow Semantic Versioning rules outlined in spec/compatibility.md and changes are gated by the 6-month deprecation policy (spec/deprecations.md).
• Network isolation note: On macOS, networkIsolation is true (5/5 adversarial leak tests pass). On Linux, it is dynamically probed at init(): true when unprivileged user namespaces are available, false on CI runners where they are restricted (falls back to proxy env vars). On Windows it is false (no native unprivileged network isolation; see RFC 0004). The Docker backend maps disabled/allow/proxy policies since backend-parity work item #4.
• v1.0 security guarantee: Native v1.0 provides soft process isolation with a hardened virtual filesystem boundary. OS-level filesystem isolation for executed workloads ships in v1.1.0 as an optional, capability-reported extension (osFilesystemIsolation; RFC 0006). Platform status:
  • OS-level filesystem isolation (RFC 0006): implemented for Linux (Landlock + unshare --user, runtime-allowlist confinement) and macOS (Seatbelt profile via sandbox-exec, allow-default with targeted denies); reported supported only after a real confined self-test. Windows is unsupported
  • Windows network isolation: unsupported (no native unprivileged mechanism; RFC 0004)
  • Docker resource/network enforcement: enforced since backend-parity work item #4 (cpuLimits, memoryLimits, networkIsolation all true with integration coverage)
  • cpuQuota: hard rate cap that throttles instead of killing, shipped in v1.2.0 (RFC 0007); enforced on Linux, Windows, and Docker where each platform's probe passes, macOS reports false (cpuTimeLimit time budgets are enforced everywhere cpuLimits is true)
• Firecracker design status: the six-track backend design is complete and recorded (RFC 0012), but no real VM has booted and no capability has been verified. Implementation awaits a real KVM-capable host and guest-agent READY; until then the backend remains unvalidated with all capability claims unpromoted.

---

Architectural Hierarchy

1. Runtime Specification (spec/): JSON Schemas & versioning (spec/version.md).
2. Compliance Suite (compliance/): Cross-language conformance test suite.
3. SDKs (sdk/): Reference TypeScript SDK (sdk/typescript, published to npm as 1.3.0); Rust SDK released as v0.1.0 (sdk/rust); Go SDK released as go-v0.1.0 (sdk/go, -race verified); Python SDK released as py-v0.1.0 (sdk/python, async-first). Each non-npm SDK carries its own tag namespace (v0.x, go-v0.x, py-v0.x) so version lines stay independent.
4. Backends (backends/): Native process driver, Docker container driver; Firecracker design complete per RFC 0012 (six-track sequence decided) with implementation blocked on a real KVM-capable host; WASI remains planned.

---

Installation

npm install @palmshed/sandbox

---

Quickstart (TypeScript Reference SDK)

import { Sandbox } from '@palmshed/sandbox';

const sandbox = await Sandbox.create({
  cpu: 2,
  memory: "512MB",
  timeout: 30000,
  network: "disabled",
  backend: "native"
});

const execution = await sandbox.exec("node -v");
await execution.wait();

console.log("Node version:", execution.stdout());

await sandbox.destroy();

See AGENTS.md for full architectural guidelines and specification rules.

---

Development & Verification

The repository uses a shared preflight and verification pipeline (scripts/), the same scripts CI runs:

• npm run preflight:quick - fast developer feedback (git state, prose punctuation, required READMEs, SDK typecheck).
• npm run preflight - full deterministic gate: SDK build/typecheck/tests, compliance/TCK, repro laboratory, examples, consumer test, JSON-schema validation, docs, workflows, package tarball, and git state.
• npm run preflight:release - preflight plus the release-readiness gate (SDK version == spec version == git tag, CHANGELOG entry).
• npm run production:validate - builds, packs, and installs the release artifact, then runs the production scenario suite and a soak smoke against the packed package (never the workspace build). This is the release confidence gate CI runs on the Ubuntu/macOS/Windows matrix.

Run the production suite alone with node production/run.mjs (--list, --only <ids>, --verbose); see production/README.md.

---

Debug Logging (SANDBOX_LOG=debug)

Set SANDBOX_LOG=debug to emit lifecycle and resource-enforcement events to stderr (off by default):

SANDBOX_LOG=debug node your-app.mjs

Emitted events (consistent across the native and Docker backends):

Event	Meaning
backend.init	Backend initialized (capability flags + configured limits)
exec.start	Execution started (backend, pid where available, limits)
exec.end	Execution finished (exit code, duration, timeout flag, CPU ms)
resource.enforced	A resource limit was enforced (cpu / memory / disk)
backend.destroy	Backend torn down

Log lines contain identifiers and resource configuration only: never secrets, environment values, command contents, or filesystem contents. See docs/errors.md for the error-code reference.