A root shell in a sandbox,
built from a flag.

Instant, isolated, single-file Linux development environments that boot in milliseconds — no daemon, no sudo, no host access by default.

For humans at a terminal, and for AI agents that need a toolchain on demand without a build queue.

µs boot real uid 0 · no sudo one portable .vroot image bubblewrap + overlayfs 42 built-in recipes MIT · open source

$ curl -fsSL https://raw.githubusercontent.com/gairxx/vroot/main/install.sh | sh

One line, no sudo — installs to ~/.local/bin/vroot.

Try the demo ↓ Install options Read the docs ★ GitHub

# Live demo

This terminal is a realistic simulation that runs entirely in your browser. Type commands or click the chips below — you are root inside a disposable sandbox, and your host stays hidden.

you@laptop — vroot terminal in-browser · simulated

Click to run

Suggestions

# Built for agents

Agents do not need a nicer terminal — they need resources on demand and no coordination overhead. No daemon, no registry, no sudo, tens of milliseconds to a root shell.

Machine-readable

$ vroot build -python --json
{"env":"…/python-84d0423ed3.sqfs","cached":false}

$ vroot ls --json
[{"name":"job7","env":"python-84d0423ed3",
  "bytes":20598,"age_minutes":3}]

stdout is pure JSON, logs stay on stderr, exit codes are forwarded from the command you run.

Parallel-safe

$ vroot build -python &
$ vroot build -python &
{"env":"…","cached":false}
{"env":"…","cached":true}

One image per flag set: the first agent builds, the rest wait on a lock and reuse it. Cache extraction is atomic, so concurrent launches cannot corrupt each other.

Checkpoint and fork

$ vroot save golden golden.vroot
$ vroot golden.vroot try1 -- pytest -q
$ vroot golden.vroot try2 -- pytest -q
$ vroot try1 -- git diff

The image is read-only; every fork writes to its own overlay, so a failed attempt costs a name, never the good state.

Host stays hidden

Real uid 0 inside, but no host filesystem, no host processes and no host network surprises unless you mount or allow them. -offline cuts the network, anonymous sandboxes vanish on exit, named ones persist until vroot rm.

Agent contract → llms.txt flags.json

# Quick start

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

$ vroot -python -- sh -c 'id; hostname; ls /home'
uid=0(root) gid=0(root)
vroot
ls: /home: No such file or directory   ← the host is not visible

# How it works

Resolve flags

Each flag maps to a small recipe. -php -sqlite -git merges into one environment definition.

Build once to a file

A minimal Alpine (or Debian) rootfs is populated in a sandbox and packed into a single squashfs image.

Launch copy-on-write

The image is mounted with overlayfs and started via bubblewrap: real root, isolated namespaces, your host hidden.

Want to understand it fully or add your own tool? Recipe reference · Full docs

# Install

$ curl -fsSL https://raw.githubusercontent.com/gairxx/vroot/main/install.sh | sh

Then check the host and start a shell:

vroot doctor      # verify bubblewrap, namespaces, squashfs
vroot -python     # a root shell with Python

Method	Command
Clone and install	`git clone https://github.com/gairxx/vroot.git && cd vroot && sh install.sh`
Source archive	main.tar.gz → unpack → `sh install.sh`
Custom prefix	`curl -fsSL …/install.sh \| sh -s -- --prefix /opt/vroot`
Pin a ref	`curl -fsSL …/install.sh \| sh -s -- --version <branch-or-tag>`
Uninstall	`curl -fsSL …/install.sh \| sh -s -- --uninstall`

Requires Linux with user namespaces, plus bubblewrap, util-linux and squashfs-tools. docker is only needed for flags that build on a Debian base. The installer needs no build step and keeps sandboxes/images when uninstalling.

# How it compares

	vroot	Docker / Podman	chroot	proot
Boot time	~10–50 ms	~0.3–2 s	instant	~0.1–1 s
Needs root / daemon	no / no	no / yes	yes	no
Host filesystem hidden	yes	yes	no	partial
Real uid 0 inside	yes	yes	yes	no (faked)
Storage per env	one file	layers + container	directory	directory
Compose tools by flag	yes	Dockerfile	manual	manual