jailoc
AGENTS.md44 starsChanged 5 days agoMITView on GitHub
jailoc — CLI tool that runs coding agents (OpenCode 1/2, Claude Code, GitHub Copilot CLI, OmO, Antigravity CLI; one per workspace) in sandboxed libkrun micro-VMs. Each workspace gets its own VM with virtio-fs directory shares, a host-side userspace network broker that denies private networks, and SSH-based agent sessions. Module: github.com/seznam/jailoc Language: Go 1.26+ Key deps: stacklok/go-microvm (libkrun), gvisor.dev/gvisor (netbroker stack), docker/docker (image builds, migrate), google/go-containerregistry, golang.org/x/crypto/ssh, BurntSushi/toml, spf13/cobra Hosts: darwin/arm64 (Hypervisor.framework), linux/amd64 and experimental linux/arm64 (KVM). Release builds embed the…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- docs/AGENTS.mdAGENTS.md
- docs/llms.txtllms.txt
- host-validationSkill
- svg-diagramsSkill
- terminal-screenshotsSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
13 rules. About 0 are common, 3 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 51
If the VM is already running, up reloads it instead (internal/cmd/vmreload_unix.go).
- Very specific: line 60
Always wrap: fmt.Errorf("context: %w", err) — never return bare err
- Very specific: line 61
No custom error types — fmt.Errorf wrapping everywhere
- Very specific: line 62
No logging library — fmt.Printf for user output, errors propagate up the stack
- Very specific: line 67
All packages under internal/ — nothing exported
- Very specific: line 68
Prefer Go SDKs over exec.Command shellouts.
- Very specific: line 69
No external dependencies for stdlib-solvable problems (e.g.
- Very specific: line 86
When plugin/opencode1.jsx or plugin/opencode2.jsx changes, rebuild and update the embedded copies:
- Distinctive: line 99
No mocks, fixtures, or testdata directories
- Very specific: line 118
Run go build, go test ./..., and golangci-lint run inside as usual.
- Distinctive: line 135
Run these locally and fix all failures before staging a commit:
- Very specific: line 152
When adding or changing user-facing features, update the corresponding docs in docs/:
- Distinctive: line 158
Keep docs in sync with code changes — a feature without updated docs is incomplete.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md 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
AGENTS.md
Project Overview
jailoc — CLI tool that runs coding agents (OpenCode 1/2, Claude Code, GitHub Copilot CLI, OmO, Antigravity CLI; one per workspace) in sandboxed libkrun micro-VMs. Each workspace gets its own VM with virtio-fs directory shares, a host-side userspace network broker that denies private networks, and SSH-based agent sessions.
Module: github.com/seznam/jailoc
Language: Go 1.26+
Key deps: stacklok/go-microvm (libkrun), gvisor.dev/gvisor (netbroker stack), docker/docker (image builds, migrate), google/go-containerregistry, golang.org/x/crypto/ssh, BurntSushi/toml, spf13/cobra
Hosts: darwin/arm64 (Hypervisor.framework), linux/amd64 and experimental linux/arm64 (KVM). Release builds embed the go-microvm runner + libkrun + libkrunfw runtime (internal/vm/runtime.go, internal/vm/runtimebin/); other builds need [vm] runner / lib_dir. The Nix package builds the VM runtime from source on Linux (x86_64, aarch64) and links its paths into jailoc; on aarch64-darwin it has no runtime.
Architecture
cmd/jailoc/main.go Entry point → cmd.Execute(version, commit, date)
cmd/jailoc-guest/ VM init + SSH server inside the guest (embedded via internal/guestbin)
cmd/jailoc-netbroker/ Host-side network broker process, one per workspace VM
internal/
cmd/ Cobra CLI: root (attach/new/continue sessions) + add, config, down, list, logs, migrate, reload, restart, sessions, status, up
agent/ Built-in coding agent harnesses (opencode1, opencode2, claude, copilot, omo, agy; opencode = alias of opencode2): npm package or GitHub release binary, session flags, env, persisted dirs, default mounts
config/ TOML config parsing, validation (rejects v1 settings), mutation (~/.config/jailoc/config.toml), default config content
workspace/ Workspace name → resolved paths, allowed hosts/networks, CWD matching
docker/ Docker Engine SDK — image resolution/build on the host, v1 volume export for migrate
embed/ go:embed assets (Dockerfile, TUI plugin)
vm/ go-microvm/libkrun VM lifecycle, embedded runtime unpacking, image export into rootfs
guest/ jailoc-guest: init, SSH sessions, secrets, Docker in the VM
guestbin/ go:generate-embedded jailoc-guest binaries
netbroker/ gVisor userspace network stack + IPv4/IPv6 egress policy + filtered DNS
brokerproc/ Starts a jailoc-netbroker process for one workspace
vmnet/, logging/, update/ Supporting packages
vmintegration/ //go:build vmintegration — boots real VMs
docs/ MkDocs documentation (Diátaxis framework, see docs/AGENTS.md)
flake.nix Nix flake: systems, formatter, apps, dev shells; packages come from nix/
nix/
default.nix Dependency map: runtime recipes → jailoc (VM runtime on Linux only)
jailoc.nix jailoc package, vendorHash, runtime paths via -X defaultVMRunner/defaultVMLibDir
runtime/ sources.nix (pins), libkrun-init, libkrunfw, libkrun, go-microvm-runner recipesData flow (jailoc up)
config.Load→ read~/.config/jailoc/config.toml; v1 settings fail validation with a hint to runjailoc migrateworkspace.Resolve→ name → paths, mounts, snapshots, allowed hosts/networks- Validate secret sources, prepare CA bundle and TUI plugin config, compute virtio-fs shares and staged
snapshots vmRuntime→ configured[vm] runner, else the package-provided runtime (for example, the Nix package's), else unpack the embedded runtimebuildWorkspaceImage→ build the image with host Docker (or a builder VM withisolated_build) and convert its layers into EROFS images in the VM image cachestartSupervisor→ boot the workspace VM (jailoc-guest as init) with its netbroker; persistent home under~/.cache/jailoc-vm/workspaces/<ws>/homesecretsPayload(read on the host before boot, incl.from_command) →deliverSecretsover SSH; the guest writes file secrets to/run/secrets(tmpfs) and env secrets to the session environment
If the VM is already running, up reloads it instead (internal/cmd/vmreload_unix.go). Sessions attach over SSH; there is no published agent port or server password.
Network
Guest IPv4 192.168.127.2/24 (gateway .1), IPv6 fd00:127::2/64. All traffic goes through the netbroker: public destinations allowed, private/reserved denied unless listed in allowed_networks or resolved from allowed_hosts. See internal/netbroker/policy.go and policy_ipv6.go.
Conventions
Error handling
- Always wrap:
fmt.Errorf("context: %w", err)— never return bareerr - No custom error types —
fmt.Errorfwrapping everywhere - No logging library —
fmt.Printffor user output, errors propagate up the stack
Code organization
- One file per package concern:
docker.go,workspace.go,config.go - Separate files for distinct concerns within a package (e.g.
fetch.gofor HTTP fetching indocker/) - All packages under
internal/— nothing exported - Prefer Go SDKs over
exec.Commandshellouts; shellouts are limited to the VM runner, broker process, guest-side tools, host CLI tools without a Go SDK (git,gpg,gpgconf), and host/usr/bin/securityon macOS - No external dependencies for stdlib-solvable problems (e.g.
net/httpfor fetching, not a third-party client)
Validation rules
- Workspace names:
^[a-z0-9-]+$ - Forbidden mount prefixes:
/home/agent,/usr,/etc,/var,/bin,/sbin,/lib,/lib64 - CIDR validation via
net.ParseCIDR - URL fields (e.g.
dockerfile): validate scheme (http/https) and non-empty host — reject malformed URLs likehttp:///path - Path expansion:
~→$HOMEon the host, or/home/agentin mount/snapshot guest destinations (skip URL fields — they must not be expanded)
Embedded assets (internal/embed/assets/)
Dockerfile— embedded fallback base image for the VM rootfs (no entrypoint/CMD; jailoc-guest is the init)docker.Dockerfile— Docker layer stages (pinned, checksum-verified Docker CE, buildx, compose); jailoc appends the final stage and builds it on top of the base only forenable_dockerworkspacestui-opencode1.js,tui-opencode2.js— built TUI plugin JS for OpenCode 1 and 2 (fromplugin/opencode1.jsx,plugin/opencode2.jsxvia the Babel-based Solid transform inplugin/build.mjs)tui-plugin.json— minimal package.json for the embedded TUI pluginomo.js— OmO extension,statusline.mjs— Claude Code status line script (workspace indicator, not built)
TUI plugin rebuild
When plugin/opencode1.jsx or plugin/opencode2.jsx changes, rebuild and update the embedded copies:
npm run build
cp dist/tui-opencode1.js dist/tui-opencode2.js internal/embed/assets/npm run build runs the Node-based Babel/Solid pipeline in plugin/build.mjs. The embedded tui-*.js must stay in sync with the plugin sources — go:embed picks it up at compile time.
Testing
- Unit tests:
*_test.gobeside source,t.Parallel(), table-driven witht.Run - Docker integration tests: build tag
//go:build integration(e.g.internal/docker/docker_integration_test.go), need a Docker daemon, not run in CI - VM integration tests:
internal/vmintegration/, build tagvmintegration, need KVM or macOS plus a go-microvm runtime (JAILOC_VM_RUNNER,JAILOC_VM_LIBDIR); run by.github/workflows/vm-integration.yml - Custom
assertContainshelper — no testify - No mocks, fixtures, or testdata directories
t.Setenv()is incompatible witht.Parallel()— tests usingt.Setenvmust NOT be parallelhttptest.NewServerin parallel subtests: uset.Cleanup(ts.Close), NOTdefer ts.Close()(defer runs before parallel subtests start)
Development environment
dev/Dockerfile.jailoc is a workspace overlay for developing jailoc
inside a jailoc workspace. It extends the base image with the Go toolchain, gopls,
and golangci-lint matching CI.
Add to ~/.config/jailoc/config.toml:
[workspaces.jailoc]
paths = ["/path/to/jailoc"]
dockerfile = "https://raw.githubusercontent.com/seznam/jailoc/main/dev/Dockerfile.jailoc"jailoc up jailoc starts a VM with Go, gopls, and golangci-lint on PATH.
Run go build, go test ./..., and golangci-lint run inside as usual.
CI/CD
GitHub Actions workflows:
- CI (
.github/workflows/ci.yml): runs on push/PR to main —go test, golangci-lint v2.15.0, and a TUI plugin sync check (dist/tui-*.jsvs embedded copies) - Security (
.github/workflows/security.yml): push/PR to main and weekly — CodeQL (Go, JS/TS, Actions) and govulncheck, both reporting to GitHub code scanning (govulncheck findings don't fail the job) - VM Integration (
.github/workflows/vm-integration.yml): PRs/pushes to main touching VM code — boots real workspace VMs on an x64 Linux runner with KVM - VM runtime (
.github/workflows/vm-runtime.yml): reusable workflow called by the release, re-release and prerelease workflows, plus PRs touchingscripts/vm-runtime/— builds runtime artifacts for darwin/arm64, linux/amd64, linux/arm64 (libkrun with a musl guest init), the libkrunfw GPL source tarball and runtime license notices (artifacts uploaded only for releases) - Release (
.github/workflows/release-please.yml): runs on push to main — Release Please opens a Release PR; on merge, createsv*tag + GitHub Release, builds the VM runtimes intointernal/vm/runtimebin/and notices/source intobuild/vm-runtime/, then GoReleaser runsgo generate ./internal/guestbin, generatesTHIRD_PARTY_NOTICESand publishes binaries (darwin/arm64, linux/amd64, linux/arm64,CGO_ENABLED=0) plusjailoc_<version>_vm-runtime-source.tarand syft SPDX SBOMs, pushes the Homebrew cask toseznam/homebrew-tap(HOMEBREW_TAP_DEPLOY_KEYdeploy-key secret in thehomebrew-tapenvironment; skipped for pre-releases), and attests build provenance of all checksummed assets - Nix (
.github/workflows/nix.yml): push/PR to main —nix fmtcheck andnix flake check --all-systems, plusnix build .#jailocon x86_64 and aarch64 Linux runners - Nix vendorHash (
.github/workflows/nix-vendor-hash.yml):go.mod/go.sumpushes to main, Dependabot PRs, manual — recomputesvendorHashinnix/jailoc.nixin a cache-free read-only job and commits it from a separate write job - Re-release (
.github/workflows/release.yml): manualworkflow_dispatchfallback — re-runs GoReleaser for an existing tag - Docs (
.github/workflows/release-please.yml): runs as part of the release process — zensical + mkdocs-macros-plugin → GitHub Pages
Before committing
Run these locally and fix all failures before staging a commit:
go build ./...
go test ./...
go vet ./...
golangci-lint runCommits
type(scope): description — types: feat, fix, docs, chore, refactor, test. Imperative mood.
Documentation
Docs follow the Diátaxis framework. See docs/AGENTS.md for conventions.
When adding or changing user-facing features, update the corresponding docs in docs/:
docs/tutorials/— learning-oriented walkthroughs (Getting Started)docs/how-to/— goal-oriented guides (installation, workspace config, custom images, network access, sessions, migration from v1)docs/reference/— exact technical descriptions (CLI, configuration fields, image resolution)docs/explanation/— understanding-oriented context (overview, threat model, architecture, network isolation, secrets)
Keep docs in sync with code changes — a feature without updated docs is incomplete.
docs/llms.txt is an llmstxt.org file listing all doc pages with descriptions. When adding, removing, or renaming a doc page, update llms.txt to match.
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.

