jailoc
AGENTS.md44 starsChanged 5 days agoMITView on GitHub
Each page belongs to exactly one quadrant. Do not mix purposes within a page.
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.
- AGENTS.mdAGENTS.md
- docs/llms.txtllms.txt
- host-validationSkill
- svg-diagramsSkill
- terminal-screenshotsSkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 70
No filler sentences ("In this section we will…") — get to the point
- Distinctive: line 71
No temporal language — describe behaviour as timeless fact, not as a change from a previous state.
- Distinctive: line 72
Do not document what is safe or harmless — only document restrictions, warnings, and breaking changes.
- Very specific: line 87
Create the .md file in the correct Diátaxis directory
- Very specific: line 88
Add it to nav: in mkdocs.yml under the matching section
- Very specific: line 89
Add a link from index.md in the appropriate section
- Distinctive: line 93
When a code change affects user-facing behaviour, update all docs that describe it
- Distinctive: line 95
If a how-to references a feature that changed, verify the steps still work
- Very specific: line 96
When adding, removing, or renaming a doc page, update docs/llms.txt — it lists all pages with descriptions following the llmstxt.org spec
≈ “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
docs/AGENTS.md
Documentation Stack
- Framework: Diátaxis — four documentation modes, each with distinct purpose and voice
- Generator: MkDocs with Material theme (
mkdocs.yml) - Plugins:
macros(template variables like{{ version }}) - Extensions:
admonition,pymdownx.details,pymdownx.superfences(with Mermaid custom fence) - Custom CSS:
stylesheets/extra.css— hero image, code block, table, and typography overrides - Build:
zensical+mkdocs-macros-plugin→ GitHub Pages onv*tags
Diátaxis Structure
Each page belongs to exactly one quadrant. Do not mix purposes within a page.
| Directory | Quadrant | Purpose | Voice |
tutorials/ | Learning-oriented | Walk the reader through doing something for the first time | "Follow along with me…" — second person, step-by-step, no unexplained jumps |
how-to/ | Goal-oriented | Solve a specific, already-understood problem | "Do X, then Y" — imperative, assumes context, minimal explanation |
reference/ | Information-oriented | Exact technical descriptions of every field, flag, and behaviour | Dry, complete, consistent structure — tables, no narrative |
explanation/ | Understanding-oriented | Explain why things work the way they do | Discursive prose, assumes the reader wants to understand, not act |
Current pages
docs/
index.md Landing page — hero image, why jailoc, link hub
development.md Contributor guide — build, test, CI, conventions
tutorials/
getting-started.md Install + first workspace walkthrough
how-to/
installation.md Install, host requirements, VM runtime
workspace-configuration.md Workspace selection, paths, env, mounts, snapshots, ports, protect_git, Docker, resources, reload vs restart
custom-images.md URL Dockerfile presets, local Dockerfiles, build context, isolated builds
network-access.md allowed_hosts, allowed_networks, filtered DNS, verifying rules
secrets.md from_env / from_file / from_command secrets, rotation with reload
ssh-git-passthrough.md SSH and GPG agent forwarding, Git config and known_hosts snapshots
sessions.md Start, attach, continue and list agent sessions; logs
coding-agents.md Choose the coding agent (agent, agents.<name>), several agents per project
tui-plugin.md Workspace indicator in the agent UI
migrate-from-v1.md Convert a v1 (Docker) config with jailoc migrate
troubleshooting.md Logs, common errors, VM state files
reference/
cli.md All subcommands with flags and examples
configuration.md Every config.toml field, types, defaults, validation rules
image-resolution.md How the workspace image is chosen, built and exported
default-image.md Tools in the embedded base image
overlay-compatibility.md Rules for workspace Dockerfile overlays
explanation/
overview.md Startup sequence, why a VM
threat-model.md What jailoc protects against and what it does not
security-boundaries.md Trust levels, enforced boundaries, crossing channels, out-of-scope risks
architecture.md Builder/workspace VMs, jailoc-guest, shares, persistent home
network-isolation.md Userspace network broker, IPv4/IPv6 policy, filtered DNS
secrets.md Secret delivery over SSH, tmpfs storage in the guest
resource-use.md Memory reclaim, zram, image cache, disks, broker limits, log rotation
alternatives.md Comparison with other sandboxes and VMMs, why libkrun and a userspace broker
blog/
agent-config.md v2.4 read-only agent config snapshots post (outside Diátaxis; temporal language allowed)
network-rules.md v2.4 network rules & setups post (outside Diátaxis; temporal language allowed)
jailoc-2.md v2 release post (outside Diátaxis; temporal language allowed)Writing Conventions
Language and tone
- English only (project was migrated from Czech)
- Second person for tutorials and how-to ("you"), third person for reference and explanation
- Imperative mood for how-to headings ("Configure network access", not "Configuring network access")
- No filler sentences ("In this section we will…") — get to the point
- No temporal language — describe behaviour as timeless fact, not as a change from a previous state. Avoid "now", "used to", "no longer", "previously", "newly", "has been added", "was replaced". Write as if the reader has no knowledge of prior versions.
- Do not document what is safe or harmless — only document restrictions, warnings, and breaking changes. Assume anything not mentioned is acceptable.
Formatting
#for page title,##for main sections,###for subsections — no deeper than####- Code blocks with language hint:
```bash,```toml,```go - Tables for structured reference data (config fields, CLI flags, port assignments)
- Admonitions for warnings and notes:
!!! warning,!!! note,!!! danger— not blockquotes - Diagrams: hand-written SVG in the section's
img/directory, embedded as(style and steps in thesvg-diagramsskill,.agents/skills/svg-diagrams/) - Internal cross-references use relative paths:
[text](../how-to/network-access.md)
Template variables
{{ version }}expands to$GITHUB_REF_NAMEor"latest"— use it in install commands- Provided by the
macrosplugin viaextra.versioninmkdocs.yml
Adding a new page
- Create the
.mdfile in the correct Diátaxis directory - Add it to
nav:inmkdocs.ymlunder the matching section - Add a link from
index.mdin the appropriate section - Cross-link from related pages where it aids navigation
Updating existing pages
- When a code change affects user-facing behaviour, update all docs that describe it
- Reference pages must stay in sync with code — field names, defaults, validation rules
- If a how-to references a feature that changed, verify the steps still work
- When adding, removing, or renaming a doc page, update
docs/llms.txt— it lists all pages with descriptions following the llmstxt.org spec
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.

