prootbox

Lightweight proot-based Linux sandboxes (Debian/Alpine) with no root required.

• No root / no setuid: pure proot, unprivileged.
• Persistent machines you can create, attach to, and delete.
• Ephemeral sandboxes that vanish on exit.
• Detached sessions that keep a machine alive in the background.
• Per-sandbox hostname (via unprivileged UTS namespace when available).
• Zero runtime dependencies — pure stdlib, Python 3.6+.

All state lives in the current working directory at the time each call runs (proot-<arch>, base-<distro>/, machines/, sessions/), so different project folders stay isolated.

Install

pip install prootbox

CLI

prootbox                                  # show help
prootbox run                              # ephemeral debian
prootbox run --distro alpine

prootbox create mybox --distro alpine     # create persistent
prootbox attach mybox                     # open shell
prootbox list
prootbox delete mybox

prootbox session start sess1 mybox        # detached session on mybox
prootbox session attach sess1
prootbox session list
prootbox session stop sess1

python3 -m prootbox run                   # works as a module too

Python API

import prootbox as pb

# Ergonomic builder form
pb.create(pb.alpine("my-box"))
pb.create(pb.debian("dev"))
pb.attach("dev")
pb.delete(pb.alpine("my-box"))

pb.run(pb.ephemeral("alpine"))
pb.run()                                  # ephemeral debian

# Or direct form
pb.create("my-box", distro="alpine")
pb.run_ephemeral(distro="debian")

for m in pb.list_machines():
    print(m["name"], m["distro"])

# Sessions
pb.session_start("sess1", machine="dev")
pb.session_attach("sess1")
pb.session_stop("sess1")

Requirements

• Linux (x86_64 or arm64)
• unshare and cp in $PATH (standard on any distro)
• Internet access on first run (downloads proot + rootfs tarballs)

How it works

On first use in a working directory, prootbox downloads a static proot binary and the requested distro's rootfs tarball, extracts it to base-<distro>/, and patches it (DNS, sudo, apt sandboxing). Machines are created with cp -alT (hardlinks) so they take almost no extra disk until written to.

License

MIT