Vroot – Instant, daemonless root sandboxes from a single flag

A developer tool called vroot launches instant, daemonless Linux root sandboxes from a single command-line flag, using unprivileged user namespaces and bubblewrap to give agents and developers a real uid 0 shell with no daemon, image registry or sudo. vroot stores each environment as a single compressed image mounted copy-on-write, with typical cold starts in tens of milliseconds, and offers JSON output via commands such as `vroot build -python --json`, `vroot ls --json` and `vroot envs --json`, plus atomic cache extraction so concurrent launches cannot corrupt each other. The project publishes a machine-facing contract in docs/AGENTS.md and lets users checkpoint a sandbox with `vroot save NAME golden.vroot` and fork it into multiple named sandboxes.

Instant, isolated, single-file Linux development environments that boot in milliseconds — built from a flag. vroot gives you a throwaway or persistent root filesystem that starts in milliseconds, is fully isolated from your host, and contains exactly the tools you asked for: vroot banner + quick-start help vroot -base a root shell blank Alpine Linux vroot -python a root shell that has Python vroot -node -python compose flags freely vroot -sqlite -python db a persistent sandbox named "db" vroot -rust -- cargo build run one command instead of opening a shell Nothing from your host is visible inside unless you expose it with -v , and the sandbox disappears when you exit unless you give it a name . It is also the shortest path from an AI agent to a working toolchain: no daemon, no image registry, no sudo, no build queue. See docs/AGENTS.md https://github.com/gairxx/vroot/blob/main/docs/AGENTS.md for the machine-facing contract. Agents do not need a nicer terminal, they need resources on demand and no coordination overhead . vroot is built for that shape of work: - No daemon, no registry, no sudo. A toolchain is one flag away and starts in tens of milliseconds, so an agent can afford to spawn a fresh environment per step instead of reusing a fragile one. - JSON when you ask for it. vroot build -python --json , vroot ls --json , vroot envs --json , vroot info NAME --json — stdout is pure JSON, logs stay on stderr, exit codes are meaningful. - Parallel-safe. N agents asking for the same environment produce one image: the first builds, the rest wait and report "cached": true . Cache extraction is atomic, so concurrent launches cannot corrupt each other. - Checkpoint, then fork. vroot save NAME golden.vroot turns a good state into one file; boot it as many named sandboxes as you like and throw the failed ones away. The image is never modified. - Host stays hidden. Real uid 0 inside, but no host filesystem, no host processes, no host network surprises unless explicitly mounted. - Deterministic surface. Anonymous sandboxes are ephemeral, named ones persist, -offline cuts the network, and vroot doctor is an explicit preflight. bash $ vroot build -python --json {"env":"/home/u/.local/share/vroot/envs/python-84d0423ed3.sqfs","cached":false} $ vroot -python task1 -- pytest -q exit code is pytest's $ vroot save task1 task1.vroot && vroot task1.vroot retry -- pytest -q The full contract output shapes, locking, fork semantics, rules for agents lives in docs/AGENTS.md https://github.com/gairxx/vroot/blob/main/docs/AGENTS.md . vroot is a lightweight sandbox and container alternative for the common case where you just want a clean, disposable Linux shell with some language or tool installed — without images to build, a daemon to run, or a slow boot. - Instant. Environments are stored as single compressed images and mounted copy-on-write. Starting a shell is a mount + exec , not a container boot. Typical cold start is tens of milliseconds. - Isolated. Your real $HOME , files and processes are not visible by default. The sandbox has its own root, PID namespace, hostname and network disable networking with -offline . - Real root, no sudo. Inside you are uid 0 with full capabilities, using unprivileged user namespaces and bubblewrap. No daemon, no setuid helper, no root on the host. - Composable. -php -sqlite -git builds one environment containing all three. Every distinct combination is cached separately and reused. - Single file. Build once, then save a sandbox — including your changes — into one portable .vroot image you can boot anywhere, and register as a real file type on your desktop with vroot filetype install . - Extensible. Every flag is a small text recipe. Add your own language or tool in a few lines — see docs/BUILDING.md https://github.com/gairxx/vroot/blob/main/docs/BUILDING.md . | | vroot | Docker / Podman | chroot | proot | full VM | |---|---|---|---|---|---| | Boot time | ~10–50 ms | ~0.3–2 s | instant | ~0.1–1 s | seconds | | Requires root / daemon | no / no | no / yes or rootless setup | yes | no | no | | Host filesystem hidden | yes | yes | no | partial | yes | | Real uid 0 inside | yes | yes | yes | no faked | yes | | Storage per environment | one file | layered image + container | directory | directory | disk image | | Compose tools by flag | yes | Dockerfile / run args | manual | manual | manual | | Best for | root shells, language sandboxes, reproducible dev shells | services, images, orchestration | legacy sysadmin | emulation, odd arches | full isolation | - Linux with unprivileged user namespaces enabled default on modern distros; check with vroot doctor . - bubblewrap , util-linux unshare , squashfs-tools mksquashfs , unsquashfs . - curl or wget — only for the first build to fetch the base rootfs . - docker — only if you use a flag whose recipe targets the Debian base bun , clojure , groovy , julia , kotlin , scala , swift . sudo apt install bubblewrap util-linux squashfs-tools curl sudo dnf install bubblewrap util-linux squashfs-tools curl sudo pacman -S bubblewrap util-linux squashfs-tools curl Then verify your host: vroot doctor One line, no sudo, no daemon: curl -fsSL https://raw.githubusercontent.com/gairxx/vroot/main/install.sh | sh That installs the launcher to ~/.local/bin/vroot and the recipe catalogue to ~/.local/lib/vroot . Then check the host and start a shell: vroot doctor verify bubblewrap, namespaces, squashfs vroot -python a root shell with Python Prefer clicking? gairxx.github.io/vroot https://gairxx.github.io/vroot/ has copy buttons for every method. | Method | Command | |---|---| | One-line install | curl -fsSL https://raw.githubusercontent.com/gairxx/vroot/main/install.sh \| sh | | Clone and install | git clone https://github.com/gairxx/vroot && cd vroot && sh install.sh | | Source archive | main.tar.gz https://github.com/gairxx/vroot/archive/refs/heads/main.tar.gz → unpack → sh install.sh | | Custom prefix | curl -fsSL ... \| sh -s -- --prefix /opt/vroot | | Pin a ref | curl -fsSL ... \| sh -s -- --version <branch-or-tag | | Uninstall | curl -fsSL ... \| sh -s -- --uninstall | install.sh installs from the working tree when run inside a checkout, and otherwise downloads a tarball — no build step either way. Uninstalling keeps your sandboxes and images in ~/.local/share/vroot . Banner + quick-start help no sandbox vroot A disposable root shell blank Alpine vroot -base A root shell with a language vroot -python vroot -node vroot -rust Compose as many tools as you like vroot -php -sqlite -git Run a single command and exit vroot -node -- node -e 'console.log process.version ' A persistent sandbox you can come back to vroot -python work vroot work -- python3 -c 'print "still here" ' Expose a host directory read-write , keep everything else hidden vroot -go -v ~/src:/src -- sh -c 'cd /src && go test ./...' Fully offline vroot -python -offline Everything is root inside, but your host is untouched: bash $ vroot -python -- sh -c 'id; hostname; ls /home' uid=0 root gid=0 root vroot ls: /home: No such file or directory One flag per tool or language. Combine them to build exactly the environment you need. | -python | -node | -deno | -bun | | -php | -ruby | -perl | -lua | | -r | -julia | -go | -rust | | -zig | -nim | -crystal | -d | | -swift | -haskell | -elixir | -erlang | | -ocaml | -clojure | -groovy | -java | | -kotlin | -scala | -dotnet | -fsharp | | -gcc | -clang | -cmake | -gfortran | | -nasm | -sqlite | -postgres | -mysql | | -git | -openssh | -curl | -vim | | -base | -debian | | | Flags answer to aliases too -python3 , -nodejs , -cargo , -golang , ... . See the full catalog with details in docs/LANGUAGES.md https://github.com/gairxx/vroot/blob/main/docs/LANGUAGES.md or: vroot recipe list vroot FLAGS NAME OPTIONS -- COMMAND | Option | Meaning | |---|---| | -v SRC :DST :ro | expose a host path read-write, or read-only with :ro | | -offline | no network loopback only | | -cwd DIR | working directory default /root | | -env K=V | set an environment variable | | -name NAME | persistent sandbox name | | -hostname H | hostname inside default: the sandbox name | | -clean | start with an empty environment | | -rm | delete the sandbox after this session | | --json | machine-readable output for build , ls , envs , info | | Command | Meaning | |---|---| | vroot ls | list sandboxes | | vroot rm NAME... \| --all | delete sandboxes | | vroot info NAME | sandbox details | | vroot save NAME OUT.vroot | pack a sandbox into one .vroot image file | | vroot OUT.vroot | boot from a saved image file | | vroot filetype install | register the .vroot image file type with the OS | | vroot envs | list built environment images | | vroot prune | clear caches and temporary files | | vroot recipe list\|show\|new\|edit\|path | work with recipes | | vroot doctor | check the host setup | 1. Resolve. Flags are looked up in recipes; matching recipes are merged packages, setup steps, environment, PATH , verification . 2. Build once. A single environment image envs/<flags -<hash .sqfs is built the first time a combination is used: a minimal base rootfs — Alpine, or Debian when a recipe needs glibc — is populated inside a sandbox and packed with mksquashfs . 3. Launch. Each session caches/unpacks the image and starts it through an overlayfs mount plus bubblewrap , giving you a root shell with full capabilities, isolated namespaces and copy-on-write writes. Persistent sandboxes keep their changed files in ~/.local/share/vroot/instances/<name /upper , so save can pack the exact state back into a portable single-file image. ┌──────────── envs/python+sqlite-<hash .sqfs ────────────┐ │ read-only squashfs image built once, cached │ └───────────────────────┬───────────────────────────────┘ │ unsquashfs lowerdir ───────────┤ ▼ host $HOME ── overlayfs COW ──► merged root ── bubblewrap ──► uid 0 shell hidden upperdir your writes namespaces: user, pid, uts, ipc, net, mount Every flag is a small recipe. Adding a language or tool usually takes a few lines: name = mytool provides = mytool base = alpine packages = mytool verify = mytool --version description = My tool vroot recipe new mytool create + edit, then: vroot -mytool See docs/BUILDING.md https://github.com/gairxx/vroot/blob/main/docs/BUILDING.md for worked examples, and docs/RECIPES.md https://github.com/gairxx/vroot/blob/main/docs/RECIPES.md for the field reference. - docs/AGENTS.md https://github.com/gairxx/vroot/blob/main/docs/AGENTS.md — the contract for AI agents and automation - docs/BUILDING.md https://github.com/gairxx/vroot/blob/main/docs/BUILDING.md — add your own language/tool - docs/LANGUAGES.md https://github.com/gairxx/vroot/blob/main/docs/LANGUAGES.md — full flag catalog - docs/RECIPES.md https://github.com/gairxx/vroot/blob/main/docs/RECIPES.md — recipe field reference - examples/ https://github.com/gairxx/vroot/blob/main/examples — example recipes Is this Docker? No. Docker builds and runs OCI images via a daemon and is great for services and orchestration. vroot is a single script that gives you an isolated root shell from a single-file, copy-on-write image — no daemon, no image build, near-instant startup. It is closer to proot or a beefed-up chroot . Do I need root or sudo? No. Everything runs through unprivileged user namespaces and bubblewrap. Is it safe? Do I really get root? Inside the sandbox you are uid 0 with full capabilities, but you are confined by user, PID, mount, UTS and IPC namespaces, and by default the host filesystem is not visible. It is real root in an isolated namespace, not root on your host. Can I access my project files? Yes, explicitly, with -v ~/src:/src . Nothing is shared until you ask. Where are environments stored? Under ~/.local/share/vroot/ envs/ , cache/ , instances/ . Override with $VROOT HOME . Recipes are read from ~/.config/vroot/recipes/ override with $VROOT CONFIG . How do I make a portable environment? vroot save NAME out.vroot writes a single image file; boot it with vroot out.vroot . Images are squashfs under the hood and also work with a .sqfs extension. Can my file manager recognise vroot images? Yes. Run vroot filetype install once. It registers a custom application/x-vroot-image MIME type globs .vroot / .sqfs , plus detection by squashfs magic and a desktop handler, so images show a distinct type and open with vroot . Undo with vroot filetype uninstall ; vroot filetype status shows what is installed. Why Alpine by default? Alpine images are tiny and build in seconds. Recipes that need glibc or apt -only packages opt into a Debian base automatically. Does it work without systemd / in a container / under WSL? It needs unprivileged user namespaces. Run vroot doctor to check. Can an AI agent use it? Yes, that is a first-class use case. Management commands take --json , stdout is pure JSON, exit codes are forwarded from the command you run, builds of the same environment are serialised across parallel processes, and a sandbox can be checkpointed with save and forked by booting the image file under new names. See docs/AGENTS.md https://github.com/gairxx/vroot/blob/main/docs/AGENTS.md . root shell sandbox · unprivileged Linux sandbox · container alternative · lighter than Docker · Docker alternative for shells · proot alternative · chroot alternative · bubblewrap sandbox · user namespace sandbox · rootless sandbox · run as root without sudo · isolated development shell · ephemeral root shell · persistent dev environment · single-file environment · squashfs environment image · overlayfs copy-on-write · instant Linux sandbox · fast sandbox boot · language sandbox · Python sandbox · Node.js sandbox · Rust sandbox · PHP sandbox · Go sandbox · polyglot dev environment · reproducible development environment · disposable shell · dev container alternative · sandbox for AI agents · agent sandbox · LLM tool sandbox · autonomous agent environment · machine-readable sandbox · parallel agent sandboxes · checkpoint and fork sandbox · JSON CLI sandbox · coding agent runtime. MIT https://github.com/gairxx/vroot/blob/main/LICENSE © 2026 gairxx