Built for agents

Agents need a toolchain on demand, deterministic output, and nothing left behind. vroot is a single script that does exactly that — no daemon waiting for you, no build queue, no stdin to negotiate.

--json on stdout meaningful exit codes concurrency-safe forkable snapshots

# Machine-readable entry points

Resource	What it is
`/llms.txt`	compact index and quick start for language models
`/llms-full.txt`	everything in one plain-text file — no HTML, no JavaScript
`/flags.json`	all 42 environments as JSON: flag, aliases, base, description
`/AGENTS.md`	short pointer served verbatim at the site root
docs/AGENTS.md	the canonical contract: rules, JSON shapes, parallelism, forks

# Quick contract

# build (or reuse) an env image and get its path
$ vroot build -python --json
{"env":"/home/u/.local/share/vroot/envs/python-84d0423ed3.sqfs","cached":false}

# run one command; vroot forwards its exit status
$ vroot -python -- python3 -c 'import sys; sys.exit(42)'
$ echo $?
42

# checkpoint a named sandbox into one portable file, then fork it
$ vroot -python work
root@work:~# pip install requests
root@work:~# exit
$ vroot save work out.vroot
$ vroot out.vroot -- python3 -c 'import requests; print(requests.__version__)'

JSON is written to stdout, one value per invocation, newline terminated. Logs and warnings go to stderr. Errors are a single err … line with exit 1.

# JSON shapes

Command	Output
`vroot build FLAGS --json`	`{"env":"…","cached":bool}`
`vroot ls --json`	`[{"name","env","image","bytes","age_minutes"}]`
`vroot envs --json`	`{"images":[{"file","bytes"}],"bases":[{"name","bytes"}]}`
`vroot info NAME --json`	`{"name","env","image","created","bytes","changed_files","path"}`

# Why it suits automation

Deterministic images. Env files are content-addressed: <flags>-<10-hex>.sqfs. The same recipe set always resolves to the same path, so it can be cached by name.
Safe in parallel. Building the same env takes a directory lock; a second process waits for the image instead of racing. Cache unpacking is swapped in atomically.
No ambient state. Unnamed runs are ephemeral and leave nothing behind. Nothing on the host is written outside $VROOT_HOME.
Forkable checkpoints. save produces one immutable file; copy it and boot each copy as an independent sandbox.
No host leakage. The host filesystem is invisible until you bind it with -v; -offline removes the network too.

# Rules of thumb

Call vroot build … --json and parse stdout as JSON.
Use -- CMD for one-shot work and trust the exit status.
Name a sandbox only for state that must survive.
Use save for checkpoints; boot the file to fork.
Run vroot doctor once per host before blaming the build.
Bind host paths explicitly with -v.

Full text: llms-full.txt · source: github.com/gairxx/vroot.