CellOS Contract

CellOS is DevCell’s small, immutable guest supervisor image. It boots inside the Firecracker boundary and runs cell-agent; it is not a separately marketed developer distro and it does not replace the repository’s devcontainer.

GuestService

GuestService exposes the guest-side lifecycle that celld calls across the cell transport. The container backend uses a loopback HTTP endpoint. The appliance machine path maps Firecracker vsock port 5000 to a host Unix-domain socket.

• GetGuestVersion returns build metadata for cell-agent.
• GetGuestStatus returns the cell id, CellOS version, guest state, and service list.
• ApplyGuestConfiguration accepts host-provided guest configuration.
• InitializeWorkspace records the intended repository, branch, workspace path, and devcontainer path.
• ListGuestServices reports guest services with endpoint and protocol metadata.
• ListGuestPorts reports discovered workload ports with protocol, endpoint, and visibility.
• PrepareSnapshot and ResumeSnapshot model quiesce/resume hooks.
• NotifyRestore lets the guest refresh status after a restore.
• ShutdownGuest is the guest-side shutdown hook.

Boundary

01hostcelldguest request

02transportvsocktyped channel

03guestcell-agentsupervise · inspect

04runtimeworkspaceservices · ports · snapshots

The container backend runs a real cell-agent, initializes the selected workspace, executes commands, reports ports, and participates in checkpoint quiescing. On Firecracker, the host endpoint and dial path are wired; the staged CellOS rootfs must contain the current cell-agent --listen vsock:5000 build for live guest calls.

Runtime responsibilities

• turn the resolved WorkspacePlan into a runnable project environment;
• select the Dev Container CLI, image, or Dockerfile execution path;
• run workspace commands without giving the client a host shell;
• report services and ports as structured data;
• receive scoped capability and secret grants;
• stop workspace services before a filesystem checkpoint;
• refresh state after restore and shut down cleanly.

Artifact path

Nix builds three CellOS artifacts: a kernel, initrd, and root filesystem. The appliance stages those under its images directory; the Firecracker backend copies a writable rootfs per cell, writes vmconfig.json, and boots the guest with a unique vsock CID. Keeping the guest image reproducible is what makes the machine boundary replaceable rather than hand-configured.