Metadata-Version: 2.4
Name: prootbox
Version: 0.1.0
Summary: Lightweight proot-based Linux sandboxes (Debian/Alpine) with no root required
Author: ssbagpcm
License: MIT
Project-URL: Homepage, https://github.com/ssbagpcm/linux
Project-URL: Issues, https://github.com/ssbagpcm/linux/issues
Keywords: proot,sandbox,container,rootfs,debian,alpine
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Emulators
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
pip install prootbox
```

## CLI

```bash
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

```python
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
