host-validation
Skill44 starsChanged 5 days agoMITView on GitHub
Validate jailoc features end to end by booting real workspace VMs on a local or remote (SSH) macOS or Linux/KVM host, isolated from the user's own workspaces. Use when a change needs proof beyond unit tests (VM boot, shares, protect_git, network policy, DNS filtering, reload, secrets, migrate, Landlock), or when asked to test a branch or PR on a host.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- docs/AGENTS.mdAGENTS.md
- docs/llms.txtllms.txt
- svg-diagramsSkill
- terminal-screenshotsSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 38
Isolate: Write $S/env.sh and source it in every shell/SSH script:
- Very specific: line 71
Diagnose failures before reporting: Read $XDG_CACHE_HOME/jailoc-vm/workspaces/<ws>/ (supervisor.log, microvm/console.log, microvm/vm.log, …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Host validation
Unit tests run anywhere; this skill proves behaviour inside real VMs. Every
run is isolated: its own HOME, config and cache under a scratch directory,
so the user's workspaces, VMs and caches stay untouched. Results go into a local
report, one row per check.
Steps
- Pick the host and commit. Local, or
ssh -o BatchMode=yes <host>. Record OS, kernel (uname -r), arch, Docker version, and on Linux/dev/kvmaccess and Landlock (cat /sys/kernel/security/lsm). List running VMs of the user (jailoc list,pgrep -af jailoc-) so you can leave them alone. Done when the report header names host, OS/kernel, commit SHA and the user's running VMs. Build at the commit in a clone outside the user's checkout (remote: clone or
git fetch origin <sha> && git checkout --detach FETCH_HEAD):go generate ./internal/guestbin # embeds jailoc-guest; without it the VM cannot boot go build -o $S/jailoc ./cmd/jailocDone when
$S/jailoc --helpruns andgit rev-parse HEADin the clone is the target SHA (a plaingo buildleaves--versionwithout the commit).Isolate. Write
$S/env.shand source it in every shell/SSH script:export S=/path/to/scratch HOME=$S/home XDG_CONFIG_HOME=$S/home/.config XDG_CACHE_HOME=$S/home/.cache export PATH=/usr/local/go/bin:$PATH J=$S/jailoc # call $J by absolute path; ~ now points into $SDone when
$J listshows no workspaces.Provide the VM runtime. Release builds embed it. A dev build needs
[vm] runnerandlib_dirin$XDG_CONFIG_HOME/jailoc/config.toml; reuse a runtime a release jailoc already unpacked:[vm] runner = "<real home>/.cache/jailoc-vm/runtime/<hash>/runtime/jailoc-vm-runner" lib_dir = "<real home>/.cache/jailoc-vm/runtime/<hash>/runtime:<real home>/.cache/jailoc-vm/runtime/<hash>/firmware"Otherwise build one (
docs/development.md, "Building and testing"). A runner must match the go-microvm revision ingo.modwhen the change touches go-microvm options (task build-runnerin a go-microvm checkout at that revision; keep the unpacked runtime's patched libkrun inlib_dir). Done when a minimal workspace (paths = ["$S/proj"]) reachesrunningin$J upand$J exec -w <ws> -- id </dev/nullprintsuid=1000(agent).- Run the checks from checks.md that the change touches, plus
the boot smoke test. Each check states its setup, commands and expected
result. Long jobs (test suites,
vmintegration) run in the background with a log ending in anEXIT <code>line; poll the log. Done when every selected check has PASS or FAIL with the command and the output that decided it. - Diagnose failures before reporting. Read
$XDG_CACHE_HOME/jailoc-vm/workspaces/<ws>/(supervisor.log,microvm/console.log,microvm/vm.log,broker.jsonl) and re-run the step onmainto tell a regression from an existing problem. Done when each FAIL names its cause or says "reproduces on main". - Clean up:
$J down --purge <ws>for every scratch workspace, remove scratch Docker volumes, thenchmod -R u+w $S && rm -r $S(the Go module cache is read-only). Done whenpgrep -af jailoc-lists only the user's own VMs from step 1.
Gotchas
jailoc execreads stdin: insidessh host 'bash -s' <<'EOF'scripts give every$J execa</dev/null, or it swallows the rest of the script.jailoc exec -w <ws> -- cmd,jailoc sessions -w <ws>;shell,traffic,strace,logs,up,down,reloadtake the workspace as an argument.- Guest
sudois disabled withprotect_git = true; use a second workspace without it for root-in-guest checks. internal/vmintegrationhard-codesdns_upstream = "1.1.1.1". Where the host network blocks it, the DNS-dependent subtests fail; point it at the host's resolver in an uncommitted local edit, rerun, then revert. Run it withJAILOC_VM_RUNNER/JAILOC_VM_LIBDIRset to the runtime from step 4 and-timeout 45m.- Containers and small hosts have a tiny
/tmp: setTMPDIRandGOTMPDIRto a roomy directory. On macOS keepTMPDIRshort (/tmp): Unix socket paths are limited to 104 bytes. - The guest's process limit stops bash fork loops early; open many connections from one Python process instead.
TestConfinedRunnerAccessskips without Landlock (containers): Landlock results only count from a real Linux host.- The runner appears in
psasjailoc-<workspace>; its second argument is the VM config JSON.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

