Release
How Sandswap releases are cut, what the release package contains, and how to consume it. The pipeline produces a fully OFFLINE tarball: extract on any x86_64 Linux host with KVM and deploy — no Go/Rust toolchain required.
Related: Storage Requirements (the storage contract the package satisfies).
1. Cutting a release
# 1. Ensure main is green and the working tree is clean.
# 2. Tag and push — the pipeline does the rest:
git tag <version> && git push origin <version>
# 3. Watch the "release" workflow on GitHub Actions (30–40 min:
# the custom kernel build dominates).
# 4. Verify the release assets: tarball + SHA256SUMS.
# 5. Spot-check: sha256sum -c SHA256SUMS on the downloaded tarball.
The pipeline (.github/workflows/release.yml, ubuntu-24.04):
- installs build + deploy dependencies (
build/install-deps.shplus the custom-kernel compile deps: flex bison bc libelf-dev libssl-dev); - builds the guest kernel (
kernel/build.sh custom; the packaged kernel is always the IPv6 variant — routed-ipv6 networking and the egress enabler depend on it); - builds all artifacts with the version stamped into every Go binary (
GO_LDFLAGS_EXTRApassing-X …Version/Commit/BuildTime); - builds the Ubuntu rootfs template (chroot: root; ownership handed back);
- packages via
build/package-release.sh— this gates on the packaged kernel (an IPv6 probe plus atcp_diag_destroyprobe: the warden’s cross-tenant TIME_WAIT sweep must have its kernel side compiled in) and vendors etcd; - creates the GitHub Release with the tarball and
SHA256SUMS.
2. Dry run without a tag
Run the workflow manually (workflow_dispatch) with a version label (e.g. <version>-rc1): it produces a draft release with the full asset set. Inspect, then publish from the release page, or delete and re-cut.
3. Local fallback (no CI)
On a machine with the full toolchain:
bash build/build.sh all # incl. kernel/custom if you need IPv6
bash build/build-ubuntu-rootfs.sh # chroot: needs root
bash build/package-release.sh <version>
# → dist/sandswap-<version>-linux-amd64.tar.gz + SHA256SUMS + RELEASE_NOTES.md
# then, with the GitHub CLI authenticated:
gh release create <version> dist/sandswap-<version>-linux-amd64.tar.gz \
dist/SHA256SUMS --title "sandswap <version>" --notes-file dist/RELEASE_NOTES.md
package-release.sh first asserts artifact completeness (every binary, kernel, initramfs, and template present), build.sh check, the syscall census, and the kernel gates above. The gates run unconditionally (there is no bypass flag); the vendored etcd (v3.6.13) is downloaded on first use into output/etcd/ and re-verified against its pinned checksum.
4. Package contents
sandswap-<ver>-linux-amd64/
├── deploy/
│ ├── baremetal/ bare-metal deploys (single-node, cluster,
│ │ one-machine-etcd) + single-host simulations,
│ │ ops tooling (sandswap-ops.sh,
│ │ rotate-volume-seed.sh), gen-baremetal-certs,
│ │ setup-host, cleanup/uninstall, systemd units,
│ │ cluster sample yamls, and the deployed-stack
│ │ drills verify-eino / verify-etcd-fence /
│ │ verify-negative-path / verify-cert-rotation
│ ├── setup-network.sh host bridge + NAT
│ ├── gen-certs.sh mTLS material generator (the e2e benchmark
│ │ harness in the package shells out to it)
│ └── udev/ vsock device lockdown rule (sandlot group)
├── common/sh/ runtime.sh + stack.sh — the shared runtime the
│ deploy tree sources (logging, path defaults,
│ ss_* identity helpers)
├── e2e/ the latency benchmark scripts + their shared
│ harness (common.sh, pin.sh,
│ latency-benchmark-aiagent,
│ latency-benchmark-unmount,
│ latency-benchmark-load,
│ latency-benchmark-alloc-sweep): the package lets
│ non-developers reproduce docs/benchmark
│ against the prebuilt output/
├── security/ vsockguard attach/attest/detach/verify, host checks
├── docs/ the documentation tree
├── output/ PREBUILT artifacts + .release-stamp:
│ static binaries (gateway, sandlot, sandvmm, sandns,
│ boxout, sandctl, bindregdump, warden-probe,
│ template-tool, vsockguardctl, vsockguard.bpf.o),
│ vmlinux.bin (CONFIG_IPV6=y), initramfs.cpio.gz,
│ rootfs-template/, rootfs-ubuntu/,
│ eino/openai/keepalive example agents,
│ loadgen (the benchmark client),
│ etcd/{etcd,etcdctl} (vendored v3.6.13)
├── META version / commit / built / arch / kernel gates
└── LICENSE LICENSE-FAQ.md NOTICE README.md VERSION
The .release-stamp (VERSION’s content, inside output/) is what flips bm_build_artifacts — and every freshness gate that reads it — into “prebuilt package, bypass builds”: a consumer deploy runs with NO toolchain.
Deliberately excluded: build/, kernel/ and all other sources (prebuilt binaries ship), the rest of e2e/ (dev-side suites), deploy/k8s/ (container-image deployments use their own pipeline), and the dev-only private-topology drills verify-failover.sh / verify-binpack.sh.
5. Consumer quick start
Unpack under a directory the service identities can traverse and deploy with the bare-metal script below (no toolchain). The deployer writes /etc/sandswap/sandctl.env (public URLs + CA), so the sandctl client commands work without extra flags. See Quick Start → Using a release package for the full walkthrough.
tar xzf sandswap-<ver>-linux-amd64.tar.gz && cd sandswap-<ver>-linux-amd64
# 1. Deploy (systemd, leave-running; no LLM key needed):
sudo bash deploy/baremetal/deploy-single-node.sh --skip-build
# 2. Verify with a live multi-agent interaction — 4 AI agents working their
# sandboxes through the deployed gateway, all interaction printed:
sudo env DEEPSEEK_API_KEY=sk-... \
bash deploy/baremetal/verify-eino.sh --agent-count 4
verify-eino.sh creates the agents and SandFS instances itself, runs every LLM↔tool interaction, and prints a PASS/FAIL summary; its full transcript lands in /tmp/sandswap-logs/eino-test.log.
6. Uninstall
One command removes everything the deployment installed:
sudo bash deploy/baremetal/uninstall.sh
It stops and disables the systemd units, kills any leftover processes, detaches the vsockguard BPF program, tears down the host bridge/TAPs and nftables rules, unmounts overlay mounts, and removes: /etc/sandswap (configs + certs), installed binaries, the systemd units, the udev rule and sysctl file, runtime/log state, and etcd data dirs.
Data warning — /var/lib/sandswap (including agent volumes) is deleted by default. To keep agent data:
sudo bash deploy/baremetal/uninstall.sh --keep-data
The service identities (sandlot, sandserv, sandprov) are intentionally kept — their pinned uid/gid must stay stable across reinstalls (see Storage Requirements). To also remove them: sudo userdel sandlot sandserv sandprov && sudo groupdel sandlot sandserv sandprov (re-run any deploy to recreate them).
deploy/baremetal/cleanup.sh is the lighter tool for a different job: resetting the host BETWEEN deploys (processes, mounts, network — data and configs stay). Use cleanup.sh to redeploy cleanly, uninstall.sh to remove Sandswap from the machine.
7. Requirements and caveats
- x86_64 Linux, KVM (
/dev/kvm), root for the deploy scripts, curl/python3 (standard). Binaries are static — no distribution glibc constraint. Services run as dedicated non-root identities (sandlot985:985,sandserv986:986,sandprov983:983 — auto-created by the deploy). - Shared-storage deployments: all nodes sharing volumes/templates MUST use identical uid/gid numbers for the service identities (pinned by default; overrides via
SS_UID_*/SS_GID_*must match fleet-wide). Full contract and the NFS export recipe: Storage Requirements. vsockguard.bpf.ois compiled against the build kernel’s BTF; attaching is best-effort and degrades to a warning on incompatible kernels.- Cluster deploys (
deploy-cluster-*.sh) are local-only: the control host prepares a self-contained stage bundle and prints per-node install commands — shipping it to the target hosts and running each host’s role install is the operator’s job (Ansible, rsync, or by hand). - The eino verification paths (
e2e/single-node-multi-agent.sh,deploy/baremetal/verify-eino.sh) need an LLM API key; the deploys themselves do not.