Checkouts and storage

Separate reusable files from private state#

LayerFS is a first-class Engine Box checkout backend, exposed through the controller, Storage dashboard and MCP. Qualified nodes import an approved repository revision, prepare shared immutable dependencies and create independent writable branches at a stable /project path.

Native agent homes, provider credentials, browser profiles and private memory stay outside reusable checkout bases. Import approval is explicit: tracked source can contain secrets too.

Preview, import, fork#

1. An administrator provisions the pinned LayerFS runtime and registers fixed node configurations and repository aliases.
2. Use storage_preview to inspect the exact source revision and obtain its approval digest.
3. Use storage_import with that revision, digest and an explicit credential-free assertion.
4. Use storage_fork for a private writable workspace.
5. Use storage_action to prepare dependencies, checkpoint, remount, close or reconcile supported interrupted operations.

These operations return durable jobs. Poll completion before using the result. Requests select registered IDs; they do not provide arbitrary host paths or shell commands. See backend configuration and operation reference.

Reuse a prepared dependency generation#

A published package cache is immutable. The qualified pnpm recipe prepares cache metadata before publication, uses an offline frozen install and does not run package lifecycle scripts. Create a new generation to add packages instead of modifying a store that active agents share.

Keep project paths stable so generated shims and native memory resolve consistently. Large Git LFS assets, submodule hydration, incremental builds and game-engine workloads still need separate qualification; a small checkout test does not establish their performance.

Attach a checkout to a VM explicitly#

The node-administrator Incus adapter exports a selected checkout into an owned, stopped VM. The qualified path supports guest writes, script and ELF execution, shared writable mmap, pause/resume and clean detach/reopen. Fleet allocation does not attach it automatically.

Attachment enforces one writer. Storage operations that would change or close the branch are blocked while the VM owns it. Attached VMs cannot currently hibernate, snapshot or fork; file and RAM checkpoints need a coordinated consistency contract.

See the attachment contract before enabling a node.

Checkpoints and recovery have explicit boundaries#

A file checkpoint records a file revision. It does not capture active processes, sockets or guest RAM. Recovery verifies operation receipts and live owned resources; it does not silently replay commands or invent a successful outcome.

The pinned preview has no qualified power-loss durability guarantee. Keep irreplaceable state and authoritative application databases on separately qualified persistent storage. The current recovery and Incus tests do not establish live Wrangler database capture.

See recovery qualification and remaining availability gates.