forkcell 0.1.0a0__tar.gz

forkcell-0.1.0a0/LICENSE

@@ -0,0 +1,51 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work shall be under the terms and conditions of this License.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+8. Limitation of Liability. In no event and under no legal theory shall any Contributor be liable to You for damages arising as a result of this License or out of the use or inability to use the Work.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer support, warranty, indemnity, or other liability obligations on Your own behalf only.

forkcell-0.1.0a0/NOTICE

@@ -0,0 +1,12 @@
+ForkCell
+Copyright 2026 BeforeWire.
+
+ForkCell is distributed under the Apache License, Version 2.0.
+
+ForkCell depends on OpenShell as its governed runtime. The preview branch pins a runtime fork at:
+
+  https://github.com/beforewire/openshell
+
+That runtime fork is derived from NVIDIA OpenShell and retains the upstream OpenShell copyright, license, and notices in the submodule repository.
+
+The OpenShell workspace-substrate patch used by ForkCell is applied in the pinned runtime fork. A patch artifact is retained under `patches/` for review and upstreaming provenance.

forkcell-0.1.0a0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: forkcell
+Version: 0.1.0a0
+Summary: Governed execution cells for AI agents, with rollback and receipts
+Author: BeforeWire
+License: Apache-2.0
+Keywords: ai-agents,sandbox,checkpoint,openshell,policy,receipts
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# ForkCell
+
+[中文](README.zh-CN.md) | English
+
+ForkCell is a governed execution-cell layer for AI agents: it adds fast workspace rollback, policy-bound runs, and reviewable receipts to local agent execution.
+
+> Checkpoint -> governed run -> receipt -> accept, restore, or fork.
+
+ForkCell is currently the `v0.1.0-preview` source preview (`0.1.0a0` Python package version). The public-preview branch is intentionally small: it contains the ForkCell control plane, a pinned governed-runtime submodule, a review patch artifact, and the minimum scripts/docs needed to understand and run the preview.
+
+## Why ForkCell Exists
+
+AI agents increasingly edit repositories, install packages, call APIs, and touch credentials. A plain sandbox can isolate a process, and a plain snapshot can roll files back, but teams also need to answer:
+
+- What checkpoint did the agent start from?
+- What runtime policy governed the run?
+- Which egress or L7 policy events occurred?
+- Was the failed run restored, accepted, or forked?
+- Can a reviewer inspect a durable receipt instead of raw logs?
+
+ForkCell turns a risky agent command into an auditable transaction.
+
+## What ForkCell Does
+
+ForkCell owns the transaction/control plane:
+
+- creates filesystem checkpoints for a cell workspace;
+- runs commands through a governed runtime integration;
+- binds policy revision, checkpoint identity, workspace config, and command result into receipts;
+- records accept/restore decisions as first-class artifacts;
+- restores quickly through metadata generation switching on the native overlay backend;
+- keeps fallback/degraded backend decisions explicit.
+
+Runtime enforcement is handled by the configured governed runtime; see
+`Runtime Integration` for the current preview substrate.
+
+ForkCell does **not** implement business-semantic policy such as refund limits or claim eligibility in core. Business policy should live in an external application/PDP/tool gateway. ForkCell focuses on runtime capability policy and transaction receipts.
+
+## Repository Layout
+
+```text
+forkcell/
+  forkcell/                  # Python CLI/API and checkpoint providers
+  scripts/                   # preview build, gateway, and smoke scripts
+  patches/                   # runtime patch review/provenance artifacts
+  docs/                      # architecture and preview docs
+  upstream/openshell         # submodule: current pinned runtime fork
+```
+
+The OpenShell patch is already applied in the pinned `beforewire/openshell` submodule. The patch file under `patches/` is kept as a review/upstreaming artifact, not as a normal build-time step.
+
+## Runtime Integration
+
+ForkCell's preview runtime integration uses a pinned OpenShell fork:
+
+```text
+repo:    https://github.com/beforewire/openshell
+branch:  forkcell-workspace-substrate
+tag:     forkcell-runtime-v0.1.3-preview
+commit:  393c25a86d9128ff5e38ecf537809efe58470266
+```
+
+The runtime fork carries a narrow workspace-substrate change:
+
+- Docker driver accepts a typed `docker.workspace` / `forkcell_overlay` contract;
+- the workspace backing volume is mounted at a private path;
+- the supervisor prepares/chowns overlay runtime directories before privilege drop and hardening;
+- runtime policy, egress, credential, and OCSF paths stay unchanged.
+
+In this preview, OpenShell provides the runtime enforcement layer:
+
+- sandbox lifecycle;
+- process and filesystem policy;
+- egress/L7 policy;
+- credential/provider path;
+- OCSF/log events.
+
+See `patches/openshell.lock` and `docs/openshell-native-fast-substrate.md`.
+
+## Quickstart
+
+Prerequisites:
+
+- macOS or Linux host with Docker available;
+- Python 3.11+;
+- Rust/Cargo for building OpenShell CLI/gateway;
+- access to the `beforewire/openshell` submodule.
+
+Clone with submodules:
+
+```bash
+git clone --recurse-submodules https://github.com/beforewire/forkcell.git
+cd forkcell
+```
+
+Or initialize submodules after cloning:
+
+```bash
+git submodule update --init --recursive
+```
+
+Install ForkCell locally:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Run the lightweight preview smoke:
+
+```bash
+./scripts/validate_public_smoke.sh
+```
+
+Build the pinned governed runtime:
+
+```bash
+./scripts/build_patched_openshell_runtime.sh
+python3 -m forkcell.cli runtime install --from upstream/openshell
+```
+
+Start the local patched runtime gateway:
+
+```bash
+./scripts/start_patched_openshell_gateway.sh
+export FORKCELL_OPENSHELL_BIN="$PWD/.forkcell/runtime/native-overlay/bin/openshell"
+export OPENSHELL_GATEWAY_ENDPOINT="http://127.0.0.1:17671"
+```
+
+Create a native cell and run a restore-on-fail command:
+
+```bash
+mkdir -p /tmp/forkcell-demo
+printf 'hello\n' >/tmp/forkcell-demo/hello.txt
+
+python3 -m forkcell.cli native init demo --from /tmp/forkcell-demo
+python3 -m forkcell.cli native run --checkpoint-before --restore-on-fail demo -- \
+  sh -lc 'echo changed > hello.txt; exit 7'
+python3 -m forkcell.cli receipt show --cell demo --latest --format md
+cat /tmp/forkcell-demo/hello.txt
+```
+
+The command intentionally exits with status `7` inside the sandbox. Success means
+ForkCell records `Decision: restored` in the receipt and the final `cat` prints
+`hello`.
+
+Stop the gateway when done:
+
+```bash
+./scripts/stop_patched_openshell_gateway.sh
+```
+
+## Current Preview Metrics
+
+Latest validation for this preview line:
+
+- native overlay `restore_sync_ms`: `0ms` on small, medium, and pruned workspaces, meaning the synchronous generation switch is sub-ms/rounded to zero;
+- native overlay correctness matrix: `7/7` cases passed;
+- native policy smoke: deny host, allow GET, and L7 deny passed;
+- runtime packaging and CI-style gate passed;
+- runtime sandbox lifecycle is still roughly hundreds of milliseconds, so only the synchronous restore substrate should be described as sub-ms/`0ms`.
+
+Fresh README-path validation on macOS + Docker also produced a tiny-workspace receipt with `checkpoint duration: 0ms`, `restore duration: 0ms`, `restore_sync_ms: 0ms`, and `total_restore_path_ms: 726ms`. The latter includes runtime sandbox delete/lifecycle and log collection, not just ForkCell's restore substrate.
+
+A sanitized evidence summary is in `docs/evidence-summary.md`.
+
+## Backends
+
+- `native-overlay`: production fast path when the patched governed runtime is configured.
+- `layer-clone`: compatible fallback; restore is metadata-only but run-layer preparation copies the checkpoint tree.
+- `volume-delta`: governed Docker volume workspace with CAS/delta restore.
+- `local-overlay`: local degraded-policy filesystem fallback for development.
+
+In this preview, `native-overlay`, `layer-clone`, and `volume-delta` are backed by OpenShell. The backend names describe ForkCell restore strategies; the runtime integration describes the sandbox/policy engine underneath.
+
+## Non-goals For This Preview
+
+- no memory/process checkpoint;
+- no VM/MicroVM/KVM isolation layer;
+- no business-semantic policy evaluator in ForkCell core;
+- no replacement for OpenShell policy/egress enforcement;
+- no claim of pure macOS/Windows native isolation;
+- no claim that full sandbox lifecycle is `0ms`.
+
+## Documentation
+
+- `docs/architecture.md` - product boundary and control-plane architecture.
+- `docs/openshell-native-fast-substrate.md` - OpenShell workspace substrate design.
+- `docs/testing-plan.md` - preview smoke and integration validation plan.
+- `docs/evidence-summary.md` - sanitized validation summary.
+
+## About BeforeWire
+
+ForkCell is part of BeforeWire's agent-trust infrastructure work: make agent execution reviewable, reversible, and policy-bound without pretending that local development needs a full cloud MicroVM product on day one.
+
+## Status
+
+`v0.1.0-preview` / `0.1.0a0` is experimental. The preview is intended to show the product boundary and the working checkpoint/restore/receipt path before the project is promoted to a broader public release.

forkcell-0.1.0a0/README.md

@@ -0,0 +1,199 @@
+# ForkCell
+
+[中文](README.zh-CN.md) | English
+
+ForkCell is a governed execution-cell layer for AI agents: it adds fast workspace rollback, policy-bound runs, and reviewable receipts to local agent execution.
+
+> Checkpoint -> governed run -> receipt -> accept, restore, or fork.
+
+ForkCell is currently the `v0.1.0-preview` source preview (`0.1.0a0` Python package version). The public-preview branch is intentionally small: it contains the ForkCell control plane, a pinned governed-runtime submodule, a review patch artifact, and the minimum scripts/docs needed to understand and run the preview.
+
+## Why ForkCell Exists
+
+AI agents increasingly edit repositories, install packages, call APIs, and touch credentials. A plain sandbox can isolate a process, and a plain snapshot can roll files back, but teams also need to answer:
+
+- What checkpoint did the agent start from?
+- What runtime policy governed the run?
+- Which egress or L7 policy events occurred?
+- Was the failed run restored, accepted, or forked?
+- Can a reviewer inspect a durable receipt instead of raw logs?
+
+ForkCell turns a risky agent command into an auditable transaction.
+
+## What ForkCell Does
+
+ForkCell owns the transaction/control plane:
+
+- creates filesystem checkpoints for a cell workspace;
+- runs commands through a governed runtime integration;
+- binds policy revision, checkpoint identity, workspace config, and command result into receipts;
+- records accept/restore decisions as first-class artifacts;
+- restores quickly through metadata generation switching on the native overlay backend;
+- keeps fallback/degraded backend decisions explicit.
+
+Runtime enforcement is handled by the configured governed runtime; see
+`Runtime Integration` for the current preview substrate.
+
+ForkCell does **not** implement business-semantic policy such as refund limits or claim eligibility in core. Business policy should live in an external application/PDP/tool gateway. ForkCell focuses on runtime capability policy and transaction receipts.
+
+## Repository Layout
+
+```text
+forkcell/
+  forkcell/                  # Python CLI/API and checkpoint providers
+  scripts/                   # preview build, gateway, and smoke scripts
+  patches/                   # runtime patch review/provenance artifacts
+  docs/                      # architecture and preview docs
+  upstream/openshell         # submodule: current pinned runtime fork
+```
+
+The OpenShell patch is already applied in the pinned `beforewire/openshell` submodule. The patch file under `patches/` is kept as a review/upstreaming artifact, not as a normal build-time step.
+
+## Runtime Integration
+
+ForkCell's preview runtime integration uses a pinned OpenShell fork:
+
+```text
+repo:    https://github.com/beforewire/openshell
+branch:  forkcell-workspace-substrate
+tag:     forkcell-runtime-v0.1.3-preview
+commit:  393c25a86d9128ff5e38ecf537809efe58470266
+```
+
+The runtime fork carries a narrow workspace-substrate change:
+
+- Docker driver accepts a typed `docker.workspace` / `forkcell_overlay` contract;
+- the workspace backing volume is mounted at a private path;
+- the supervisor prepares/chowns overlay runtime directories before privilege drop and hardening;
+- runtime policy, egress, credential, and OCSF paths stay unchanged.
+
+In this preview, OpenShell provides the runtime enforcement layer:
+
+- sandbox lifecycle;
+- process and filesystem policy;
+- egress/L7 policy;
+- credential/provider path;
+- OCSF/log events.
+
+See `patches/openshell.lock` and `docs/openshell-native-fast-substrate.md`.
+
+## Quickstart
+
+Prerequisites:
+
+- macOS or Linux host with Docker available;
+- Python 3.11+;
+- Rust/Cargo for building OpenShell CLI/gateway;
+- access to the `beforewire/openshell` submodule.
+
+Clone with submodules:
+
+```bash
+git clone --recurse-submodules https://github.com/beforewire/forkcell.git
+cd forkcell
+```
+
+Or initialize submodules after cloning:
+
+```bash
+git submodule update --init --recursive
+```
+
+Install ForkCell locally:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+Run the lightweight preview smoke:
+
+```bash
+./scripts/validate_public_smoke.sh
+```
+
+Build the pinned governed runtime:
+
+```bash
+./scripts/build_patched_openshell_runtime.sh
+python3 -m forkcell.cli runtime install --from upstream/openshell
+```
+
+Start the local patched runtime gateway:
+
+```bash
+./scripts/start_patched_openshell_gateway.sh
+export FORKCELL_OPENSHELL_BIN="$PWD/.forkcell/runtime/native-overlay/bin/openshell"
+export OPENSHELL_GATEWAY_ENDPOINT="http://127.0.0.1:17671"
+```
+
+Create a native cell and run a restore-on-fail command:
+
+```bash
+mkdir -p /tmp/forkcell-demo
+printf 'hello\n' >/tmp/forkcell-demo/hello.txt
+
+python3 -m forkcell.cli native init demo --from /tmp/forkcell-demo
+python3 -m forkcell.cli native run --checkpoint-before --restore-on-fail demo -- \
+  sh -lc 'echo changed > hello.txt; exit 7'
+python3 -m forkcell.cli receipt show --cell demo --latest --format md
+cat /tmp/forkcell-demo/hello.txt
+```
+
+The command intentionally exits with status `7` inside the sandbox. Success means
+ForkCell records `Decision: restored` in the receipt and the final `cat` prints
+`hello`.
+
+Stop the gateway when done:
+
+```bash
+./scripts/stop_patched_openshell_gateway.sh
+```
+
+## Current Preview Metrics
+
+Latest validation for this preview line:
+
+- native overlay `restore_sync_ms`: `0ms` on small, medium, and pruned workspaces, meaning the synchronous generation switch is sub-ms/rounded to zero;
+- native overlay correctness matrix: `7/7` cases passed;
+- native policy smoke: deny host, allow GET, and L7 deny passed;
+- runtime packaging and CI-style gate passed;
+- runtime sandbox lifecycle is still roughly hundreds of milliseconds, so only the synchronous restore substrate should be described as sub-ms/`0ms`.
+
+Fresh README-path validation on macOS + Docker also produced a tiny-workspace receipt with `checkpoint duration: 0ms`, `restore duration: 0ms`, `restore_sync_ms: 0ms`, and `total_restore_path_ms: 726ms`. The latter includes runtime sandbox delete/lifecycle and log collection, not just ForkCell's restore substrate.
+
+A sanitized evidence summary is in `docs/evidence-summary.md`.
+
+## Backends
+
+- `native-overlay`: production fast path when the patched governed runtime is configured.
+- `layer-clone`: compatible fallback; restore is metadata-only but run-layer preparation copies the checkpoint tree.
+- `volume-delta`: governed Docker volume workspace with CAS/delta restore.
+- `local-overlay`: local degraded-policy filesystem fallback for development.
+
+In this preview, `native-overlay`, `layer-clone`, and `volume-delta` are backed by OpenShell. The backend names describe ForkCell restore strategies; the runtime integration describes the sandbox/policy engine underneath.
+
+## Non-goals For This Preview
+
+- no memory/process checkpoint;
+- no VM/MicroVM/KVM isolation layer;
+- no business-semantic policy evaluator in ForkCell core;
+- no replacement for OpenShell policy/egress enforcement;
+- no claim of pure macOS/Windows native isolation;
+- no claim that full sandbox lifecycle is `0ms`.
+
+## Documentation
+
+- `docs/architecture.md` - product boundary and control-plane architecture.
+- `docs/openshell-native-fast-substrate.md` - OpenShell workspace substrate design.
+- `docs/testing-plan.md` - preview smoke and integration validation plan.
+- `docs/evidence-summary.md` - sanitized validation summary.
+
+## About BeforeWire
+
+ForkCell is part of BeforeWire's agent-trust infrastructure work: make agent execution reviewable, reversible, and policy-bound without pretending that local development needs a full cloud MicroVM product on day one.
+
+## Status
+
+`v0.1.0-preview` / `0.1.0a0` is experimental. The preview is intended to show the product boundary and the working checkpoint/restore/receipt path before the project is promoted to a broader public release.

forkcell-0.1.0a0/forkcell/__init__.py

@@ -0,0 +1,7 @@
+"""ForkCell MVP package."""
+
+__version__ = "0.1.0a0"
+
+from forkcell.api import ForkCellClient, ForkCellCommandError, ForkCellSandbox
+
+__all__ = ["ForkCellClient", "ForkCellCommandError", "ForkCellSandbox", "__version__"]

forkcell-0.1.0a0/forkcell/api.py

@@ -0,0 +1,191 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+
+class ForkCellCommandError(RuntimeError):
+    def __init__(self, args: list[str], returncode: int, stdout: str, stderr: str) -> None:
+        self.args_list = args
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        super().__init__(
+            f"forkcell command failed ({returncode}): {' '.join(args)}\nstdout:\n{stdout}\nstderr:\n{stderr}"
+        )
+
+
+@dataclass(frozen=True)
+class CommandResult:
+    args: list[str]
+    returncode: int
+    stdout: str
+    stderr: str
+    json: dict[str, Any]
+
+
+def _extract_json_object(text: str) -> dict[str, Any]:
+    decoder = json.JSONDecoder()
+    for index, char in enumerate(text):
+        if char != "{":
+            continue
+        try:
+            value, end = decoder.raw_decode(text[index:])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict) and not text[index + end :].strip():
+            return value
+    raise ValueError("missing JSON object in command output")
+
+
+def _normalize_command(command: str | Iterable[str]) -> list[str]:
+    if isinstance(command, str):
+        return ["sh", "-lc", command]
+    return [str(part) for part in command]
+
+
+LEGACY_BACKEND_ALIASES = {
+    "openshell-native-overlay": "native-overlay",
+    "openshell-layer-clone": "layer-clone",
+    "openshell-volume": "volume-delta",
+}
+
+
+def _normalize_backend(backend: str) -> str:
+    return LEGACY_BACKEND_ALIASES.get(backend, backend)
+
+
+class ForkCellClient:
+    """Small Python facade for agent-style ForkCell workflows.
+
+    The facade intentionally shells out to `python -m forkcell.cli` so the API
+    and CLI share the same state, receipts, and review artifacts during the
+    current governed-runtime integration.
+    """
+
+    def __init__(
+        self,
+        *,
+        root: str | Path | None = None,
+        python: str | None = None,
+        env: Mapping[str, str] | None = None,
+    ) -> None:
+        self.root = Path(root or Path.cwd()).resolve()
+        self.python = python or sys.executable
+        self.env = dict(os.environ)
+        if env:
+            self.env.update(env)
+
+    def cli(self, args: list[str], *, check: bool = True) -> CommandResult:
+        full_args = [self.python, "-m", "forkcell.cli", *args]
+        proc = subprocess.run(full_args, cwd=self.root, env=self.env, text=True, capture_output=True)
+        parsed: dict[str, Any] = {}
+        output = proc.stdout.strip()
+        if output:
+            try:
+                parsed = _extract_json_object(output)
+            except ValueError:
+                parsed = {}
+        if check and proc.returncode != 0:
+            raise ForkCellCommandError(full_args, proc.returncode, proc.stdout, proc.stderr)
+        return CommandResult(
+            args=full_args,
+            returncode=proc.returncode,
+            stdout=proc.stdout,
+            stderr=proc.stderr,
+            json=parsed,
+        )
+
+    def create_native_cell(
+        self,
+        *,
+        source: str | Path,
+        name: str | None = None,
+        backend: str = "native-overlay",
+    ) -> "ForkCellSandbox":
+        cell = name or f"fc-api-{uuid.uuid4().hex[:8]}"
+        self.cli(["native", "init", cell, "--from", str(Path(source).resolve())])
+        return ForkCellSandbox(client=self, name=cell, backend=_normalize_backend(backend))
+
+    def native_cell(self, name: str, *, backend: str = "native-overlay") -> "ForkCellSandbox":
+        return ForkCellSandbox(client=self, name=name, backend=_normalize_backend(backend))
+
+    def review_status(self) -> dict[str, Any]:
+        return self.cli(["review", "status", "--format", "json"]).json
+
+
+@dataclass
+class ForkCellSandbox:
+    client: ForkCellClient
+    name: str
+    backend: str = "native-overlay"
+    auto_delete: bool = True
+
+    def __post_init__(self) -> None:
+        self.backend = _normalize_backend(self.backend)
+
+    def __enter__(self) -> "ForkCellSandbox":
+        return self
+
+    def __exit__(self, exc_type: object, exc: object, tb: object) -> None:
+        if self.auto_delete:
+            self.delete(check=False)
+
+    def status(self) -> dict[str, Any]:
+        return self.client.cli(["native", "status", self.name]).json
+
+    def checkpoint(self, *, name: str | None = None) -> dict[str, Any]:
+        args = ["native", "checkpoint", self.name]
+        if name:
+            args.extend(["--name", name])
+        return self.client.cli(args).json
+
+    def restore(self, checkpoint: str | None = None) -> dict[str, Any]:
+        args = ["native", "restore", self.name]
+        if checkpoint:
+            args.append(checkpoint)
+        return self.client.cli(args).json
+
+    def run(
+        self,
+        command: str | Iterable[str],
+        *,
+        checkpoint_before: bool = False,
+        checkpoint_name: str | None = None,
+        restore_on_fail: bool = False,
+        policy: str | Path | None = None,
+        logs_since: str = "5m",
+    ) -> dict[str, Any]:
+        if self.backend == "native-overlay":
+            args = ["native", "run"]
+        elif self.backend == "layer-clone":
+            args = ["native", "run-layer"]
+        else:
+            args = ["run", self.name, "--backend", self.backend]
+        if checkpoint_before:
+            args.append("--checkpoint-before")
+        if checkpoint_name:
+            args.extend(["--checkpoint-name", checkpoint_name])
+        if restore_on_fail:
+            args.append("--restore-on-fail")
+        if policy:
+            args.extend(["--policy", str(policy)])
+        if logs_since:
+            args.extend(["--logs-since", logs_since])
+        if self.backend in {"native-overlay", "layer-clone"}:
+            args.append(self.name)
+        args.extend(["--", *_normalize_command(command)])
+        run = self.client.cli(args).json
+        receipt = Path(run.get("receipt", ""))
+        if receipt.exists():
+            return json.loads(receipt.read_text())
+        return run
+
+    def delete(self, *, check: bool = True) -> dict[str, Any]:
+        return self.client.cli(["native", "delete", self.name], check=check).json