forkcell 0.1.0a0

Governed execution cells for AI agents, with rollback and receipts

ForkCell

中文 | 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

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:

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:

git clone --recurse-submodules https://github.com/beforewire/forkcell.git
cd forkcell

Or initialize submodules after cloning:

git submodule update --init --recursive

Install ForkCell locally:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Run the lightweight preview smoke:

./scripts/validate_public_smoke.sh

Build the pinned governed runtime:

./scripts/build_patched_openshell_runtime.sh
python3 -m forkcell.cli runtime install --from upstream/openshell

Start the local patched runtime gateway:

./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:

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:

./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.