How It Works
How Sandswap works, from the outside in. Read in order for a full picture; each page also stands alone.
- Concepts & Terms — the vocabulary everything else builds on.
- Architecture — the components and their communication paths.
- Design Principles — the invariants every change must preserve.
- Topologies — the deployment shapes: single-node to distributed, embedded vs boxout.
- SandFS — the core abstraction: a persistent per-agent volume and its two modes (flat writable rootfs vs read-only overlay + writable workspace).
- Templates — where rootfs templates live (local store + OCI registry) and how each mode consumes them.
- microVM Lifecycle — microVM states, verified creation, recycle, re-adopt, crash teardown, and the warden countdown.
- Isolation and Swap — time-sharing one microVM across SandFS: the swap machinery and the strong-isolation guarantees behind it.
- Guest Kernel Hardening — the guest kernel as a trust root: the minimized build and its configuration, the capability/seccomp fence on agent code, the blast radius of a compromise, and the reuse limits that bound it.
- Ownership & DNS — exclusive ownership, placement, and owner-aware routing.
- Resilience — failure detection, takeover, tolerance-first recovery.
- Threat Model — the adversaries outside the microVM boundary: local user, network, compromised gateway or VMM, and the trust roots.
- Vsockguard — the BPF LSM that pins the host-side vsock transport.
- Egress Enabler Contract — how egress security is constructed: the unforgeable per-attachment identity, its two carriers, the binding-region format, and the host-side isolation baseline (integration side: Egress Integration).
- Namespaces — the control-plane tenancy dimension: the IdP-issued
sandswap_nsclaim, the two enforcement rules, and why the exec plane is untouched.
Then the components, one page each — responsibilities, interfaces, workflow, and state: