Kernel and filesystem compatibility¶

This page lists what AWC needs from a Linux host.

The host admission probe gates every entry below. A host that fails an assessed probe is unschedulable for writable mounts.

Supported host profile¶

The certified host profile.

Requirement	Value
Kernel	6.1 or newer
Cgroup hierarchy	cgroup v2
FUSE	enabled
OverlayFS	enabled
Local filesystem for cache and upper	ext4 or XFS
xattrs	usable
Privileges	root or equivalent host capabilities for mount management
Local storage	local SSD or NVMe strongly recommended
Network	outbound access to the control plane and object store
Operating system	Linux only (no Windows or macOS mounts)

The daemon reads the kernel release from /proc/sys/kernel/osrelease and parses the leading major.minor. A release below 6.1 fails the probe.

Kernel facilities AWC depends on¶

Facility	What AWC uses it for
OverlayFS	Composes the read-only base snapshot (lower) with a private writable delta (upper).
FUSE	Serves the shared read-only base filesystem.
cgroup v2	Freezes the execution cgroup for a quiesced checkpoint.
ext4 or XFS	Backs the cache and the per-session `upper` and `work` directories.
xattrs	Carries OverlayFS whiteout and opacity markers.
Mount namespaces	Publishes the merged view to the host, then bind-mounts it into a sandbox. Not a probe category; enforced by the mount helper.

OverlayFS mount contract¶

The workspace overlay is mounted as overlay over three directories:

lowerdir=/var/lib/awc/basefs/tenants/<tenant-id>/snapshots/<root-digest>
upperdir=/var/lib/awc/workspaces/<workspace-id>/<generation>/upper
workdir=/var/lib/awc/workspaces/<workspace-id>/<generation>/work

The mounter shells out to mount -t overlay overlay -o <options> <merged>.

Required mount options¶

AWC disables every OverlayFS behavior that makes checkpoint delta interpretation ambiguous. Each of the following MUST be explicitly off before a workspace is exposed.

Option	Required value	Reason
`redirect_dir`	`off`	Directory redirects would defeat delta interpretation.
`metacopy`	`off`	Metadata-only copy-up splits content from metadata.
`index`	`off`	Hard-link index adds state AWC does not interpret.
`xino`	`off`	Inode remapping is not needed and complicates stable inodes.

AWC rejects any option set where one of these four is absent or set to a value other than off. The mount path checks the policy before it exposes the workspace. Unsupported combinations fail mount creation.

OverlayFS delta interpretation¶

The checkpoint builder scans the upper directory and interprets the kernel's overlay representation. The recognized markers and their xattr namespaces are:

Marker	xattr	Meaning
Whiteout	character device `0/0` entry in upper	The matching lower entry is deleted.
Opaque directory	`trusted.overlay.opaque=y` or `user.overlay.opaque=y`	Lower children of this directory are hidden.

AWC tries user.overlay.opaque first, then trusted.overlay.opaque. An unsupported redirect or metacopy marker causes a safe checkpoint failure, never an incorrect snapshot.

Lowerdir path component¶

OverlayFS reserves : as the lowerdir list separator. The lower path component therefore uses a colon-free form: the digest's first colon is replaced with a dash, for example sha256-<hex> instead of sha256:<hex>. The digest keeps its canonical sha256:<hex> form everywhere else.

FUSE read-only basefs¶

One shared read-only FUSE filesystem is mounted at the configured basefs path.

Property	Value
Mount point	`/var/lib/awc/basefs` (required field, no default)
Snapshot path	`/var/lib/awc/basefs/tenants/<tenant-id>/snapshots/<root-digest>/`
Exposed operations	`lookup`, `getattr`, `readdir`, `open`, `read`, `readlink`, `statfs`
Write operations	Return `EROFS`
Mount options	`RO`, `FSName=awc-basefs`, `AutoUnmount`, `AllowRoot`

There is one multiplexed FUSE daemon per host, not one per workspace.

AllowRoot and the overlay-over-FUSE mount¶

The OverlayFS lowerdir points into the FUSE basefs that awcd itself serves. The kernel resolves the lowerdir with root-class credentials. Without AllowRoot, the FUSE mount denies that resolution with EACCES and the overlay mount fails. AllowRoot grants access to root and to the mount owner, which is awcd. This behavior is recorded in the awcd.service capability note.

Privileges and capabilities¶

awcd runs as the unprivileged awc user but holds a fixed, minimal capability set so it can perform privileged mount operations and access /dev/fuse.

Capability	Reason
`CAP_SYS_ADMIN`	Mount, OverlayFS, bind, cgroup freeze, and `setns`.
`CAP_DAC_OVERRIDE`	Required for the workspace OverlayFS mount whose `lowerdir` lives in the read-only FUSE basefs. Without it, the kernel's lowerdir resolution fails with `EACCES`.
`CAP_DAC_READ_SEARCH`	Checkpoint upper-directory bookkeeping.
`CAP_CHOWN`	Per-session upper-directory ownership.
`CAP_FOWNER`	Upper-directory file operations.

See systemd units for the full unit. Device access is scoped with DeviceAllow=/dev/fuse rw; PrivateDevices is not set because awcd needs /dev/fuse.

Mount namespace visibility¶

awcd creates the internal merged mount in the host mount namespace, then bind-mounts the path into an authorized sandbox namespace or a configured host target.

The awcd.service unit deliberately omits the systemd directives that create a private mount namespace with disconnected propagation: ProtectSystem, ProtectHome, PrivateTmp, ProtectKernelModules, ProtectKernelLogs, ProtectClock, ProtectProc, and ReadWritePaths. Those directives would confine awcd mounts to a namespace that clients, the worker, and acceptance checks cannot see. Other hardening axes are retained. See systemd units.

Namespace target handles¶

A bind target into a sandbox namespace MUST be identified by a stable, integration-provided handle, never by a raw PID supplied by an untrusted process.

A raw PID is rejected as a namespace handle.
When a PID is used internally, awcd retains a pidfd-modeled token and re-checks the reuse generation before it enters a namespace or binds.

Bind mount hardening¶

Option	Default
`nodev`	Always on
`nosuid`	Always on
`noexec`	Off by default; policy-selected by the sandbox

The inverse options dev and suid are rejected. noexec is off by default because agents may need to run built binaries; the sandbox owns that decision, not the storage layer. The bind target MUST be under an allow-listed root.

cgroup v2 quiesce¶

A quiesced checkpoint freezes the execution cgroup, synchronizes the filesystem, scans a stable delta, publishes, and resumes. The freezer writes and reads the cgroup v2 freeze file.

Operation	Action
Freeze	Write `1` to `<cgroup>/cgroup.freeze`.
Thaw	Write `0` to `<cgroup>/cgroup.freeze`.
Confirm frozen	Read `<cgroup>/cgroup.freeze` and poll until `1`.

The freeze timeout is bounded by checkpoint.freeze_timeout_seconds (default 10 seconds). The cgroup MUST be below an allow-listed agent subtree, awcd MUST never freeze itself, and a quiesced checkpoint MUST be rejected if the execution group cannot be safely controlled.

Host admission probe¶

Before admitting a host for writable mounts, awcd MUST run or verify a compatibility probe. Admission is fail-closed.

Registration-time checklist¶

The full checklist a host MUST pass at registration. Each item names one required FUSE or overlay behavior.

Check name	Behavior verified
`fuse_lower_directory`	FUSE lower-directory support.
`file_create_modify_delete_rename_chmod`	File create, modify, delete, rename, and chmod.
`symlink_behavior`	Symlink creation and read.
`directory_opacity_whiteouts`	Directory opacity and whiteouts.
`copy_up_behavior`	Copy-up from lower to upper.
`supported_mount_options`	The AWC option set is accepted.
`checkpoint_interpretation`	Delta interpretation matches the live merged view.
`unmount_cleanup`	The overlay unmounts cleanly.

A host with every check passing is ACTIVE. Any failure leaves the host UNSCHEDULABLE for writable mounts.

Live readiness probe¶

The /readyz endpoint runs four privilege-free probes on every scrape. They read /proc or /sys and need no capabilities.

The four probes are Kernel, CgroupV2, Fuse, and OverlayFs.

Readiness fails closed on kernel compatibility: an unverified host reports Unknown and /readyz denies new mounts.

Probe states and admission decision¶

A probe result is one of Pass, Fail, or NotAssessed. NotAssessed is distinct from Fail: the host is not known-bad, it is unverified.

Report	Admission decision	Readiness component
Every assessed probe passes	`Schedulable`	`Ok`
One or more critical probes could not be assessed	`Unverified`	`Unknown`
One or more assessed probes failed	`Unschedulable`	`Down`

The functional probes (rename, chmod, symlink, copy-up, whiteout, opacity, checkpoint interpretation, unmount cleanup) require an overlay mount and therefore CAP_SYS_ADMIN. On an unprivileged host they report NotAssessed rather than Fail, so the host is Unverified, not Unschedulable.

Certified tool suite¶

The tool compatibility suite materializes a snapshot to a real directory and runs one documented operation of each certified tool against it.

Tool	Documented operation
Git	`init`, `add`, `commit`, `log`.
ripgrep	Recursive content search.
GNU coreutils	`ls`, executable script run, `readlink`, `chmod`.
Python and pytest	A stdlib-only test run.
Node.js and a package manager	Offline package script run.
Rust and Cargo	Offline `cargo build` of a std-only crate.
A compiler and linker	`cc` compile and link.
Archive tools	`tar` create and extract.
A language server	Crate indexing.

A tool absent from the environment is skipped, not failed. Network-bound operations are out of scope, so the suite runs offline. The suite proves the materialized tree is byte-, mode-, and symlink-faithful. OverlayFS-specific behavior (whiteouts, copy-up) is verified separately from this suite; a live privileged FUSE mount is out of scope for this suite.

Kernel version matrix¶

A tested kernel matrix is meant to be published with each release. The current repository does not publish that matrix; the only version fact is the minimum floor.

Range	Status	Reason
6.1 and newer	Minimum supported	Minimum floor enforced at admission.
Below 6.1	Unsupported	Fails the admission probe.
Specific certified versions	Per release	Not present in this repository.

A host between the floor and a future certified-version matrix reports Schedulable from the static probes only if it also passes the functional probe. See Current scope.

Current scope¶

What the current build does not yet do:

No published kernel matrix. A tested kernel matrix is required per release. The repository ships the minimum floor (6.1) and a probe harness, but no certified-version table.
The functional admission probe is privilege-gated. The registration-time checklist is aggregated by the daemon, but the live functional checks that require an overlay mount run only where the daemon has CAP_SYS_ADMIN. On an unprivileged host the functional categories report NotAssessed and the host is Unverified, not Schedulable.
No language server is certified in this environment. The language-server slot in the tool suite skips when no functioning server is installed.
File watchers are not in the tool suite. Common file watchers are conditional on design-partner need. No watcher test is shipped.
The live readiness probe covers four categories. /readyz assesses only Kernel, CgroupV2, Fuse, and OverlayFs. The remaining static probes (UpperFilesystem, Xattrs, MountOptions) and all functional probes are part of the registration-time report, not the per-scrape readiness aggregate. See observability.