proot.js

Serious proot container builder and runner for rootfs workflows with a full CLI and reusable Node.js API.

Creator: SoyMaycol

Features

• Create containers from local rootfs folders, tarballs, zip archives, or remote URLs
• Full CLI with init, create, run, exec, shell/enter, list, info, validate, pack, unpack, delete, doctor
• Advanced configuration for binds, environment, root-id, custom proot binary, profiles, and extra proot args
• RAM and ETF sizing hints for tooling pipelines
• Config stored per-container in .proot.js/containers/<name>/container.json

Install

npm install -g proot.js

Or add as a dependency:

npm install proot.js

Quick start

proot.js init --name demo --rootfs ./rootfs
proot.js create demo --rootfs ./rootfs --rootfs-copy
proot.js run demo

Create from an archive

--rootfs accepts a directory or a common archive format (tar, tar.gz, tar.xz, tar.zst, tar.bz2, zip).

proot.js create alpine --rootfs ./alpine-rootfs.tar
proot.js run alpine /bin/sh

Create from a URL

proot.js create ubuntu --rootfs-url https://example.com/ubuntu-rootfs.tar

CLI commands

proot.js init
proot.js create <name>
proot.js list
proot.js run <name> [command...]
proot.js exec <name> [command...]
proot.js shell <name>
proot.js enter <name>
proot.js inspect <rootfs>
proot.js info <name>
proot.js validate <name>
proot.js pack <name> --output ./rootfs.tar
proot.js unpack <name> ./rootfs.tar
proot.js delete <name>
proot.js doctor

Config file

proot.config.json created with proot.js init is a template. Containers store their config in .proot.js/containers/<name>/container.json.

Only the rootfs path is required to start a container. All other fields are optional and can be omitted.

Example:

{
  "name": "demo",
  "creator": "SoyMaycol",
  "rootfs": {
    "path": "/abs/path/to/rootfs",
    "distro": "alpine",
    "arch": "x86_64",
    "source": "local"
  },
  "runtime": {
    "entry": "/bin/sh",
    "args": ["-l"],
    "workdir": "/",
    "rootId": true,
    "proot": "proot",
    "prootArgs": ["-v"],
    "profile": "auto",
    "verbose": false
  },
  "limits": {
    "ramMiB": 512,
    "etfMiB": 128
  },
  "mounts": {
    "binds": [
      { "host": "/home/me/data", "guest": "/data", "mode": "rw" }
    ],
    "tmpfs": [],
    "system": [
      { "host": "/dev", "guest": "/dev", "mode": "rw" },
      { "host": "/proc", "guest": "/proc", "mode": "rw" },
      { "host": "/sys", "guest": "/sys", "mode": "rw" },
      { "host": "/etc/resolv.conf", "guest": "/etc/resolv.conf", "mode": "ro" },
      { "host": "/etc/hosts", "guest": "/etc/hosts", "mode": "ro" }
    ]
  },
  "env": {
    "LANG": "C.UTF-8",
    "TERM": "xterm-256color"
  }
}

RAM and ETF

limits.ramMiB and limits.etfMiB are sizing hints for container workflows and tooling. They do not hard-enforce memory limits in proot. Use them to keep scripts, CI, or external wrappers aligned with your desired resources.

Advanced usage

Bind mounts and environment overrides at runtime:

proot.js run demo --bind /host/cache:/cache:rw --env TZ=UTC --env APP_ENV=prod

Pass custom proot arguments:

proot.js run demo --proot-arg -v --proot-arg --sysvipc

If your command includes flags, use -- to separate CLI options:

proot.js exec demo -- /bin/sh -c "echo hello"

Select a specific proot binary:

proot.js run demo --proot /usr/local/bin/proot

Select a platform profile:

proot.js run demo --profile android

Disable default system binds if your host is minimal:

proot.js run demo --no-system-binds

Node.js API

const { createContainer, runContainer } = require("proot.js");

await createContainer("demo", { rootfs: "./rootfs", rootfsCopy: true });
runContainer("demo");

Requirements

• proot installed on the host
• tar for packing/unpacking rootfs
• unzip for zip rootfs

When installing from npm, a postinstall check will report missing system tools and suggest install commands.

Testing

npm test

Environment compatibility

proot.js adapts to the host environment and allows selecting a compatible proot binary. On Android/Termux it automatically disables LD_PRELOAD, applies Termux symlinks, and sets a safe workdir. Use proot.js doctor and proot.js inspect <rootfs> to inspect compatibility.

Beginner-friendly Termux example:

proot.js create termux --rootfs-url https://github.com/termux/termux-packages/releases/download/bootstrap-2026.03.01-r1%2Bapt.android-7/bootstrap-aarch64.zip --profile android
proot.js run termux pwd

License

MIT

Architecture selection

proot.js create debian --arch x86_64 --rootfs ./debian-rootfs.tar

Startup command

proot.js init --entry /bin/bash --entry-arg -l
proot.js create demo --config ./proot.config.json