@tomasko/pdms

Install with npm install -g @tomasko/pdms, then run pdms install once or run a container command directly, such as pdms run --rm alpine echo hello. When run by a regular user, pdms uses rootless containerd. When run by root, it uses rootful containerd and skips UID mapping setup. Each account defaults to its own ~/.local/pdms; root can run pdms install directly in a root login shell.

The npm package contains the complete Linux bootstrap script. On first use, it downloads the latest stable nerdctl-full release and the latest pdms static iptables release, verifies their SHA-256 checksums, and extracts both under ~/.local/pdms. Later commands reuse the installed tools. Set PDMS_HOME=/absolute/path to change the installation, configuration, data, and log directory. There is no project-maintained nerdctl version lock. The bundled iptables includes nft and legacy backends; pdms uses nft by default and does not install a host iptables package.

pdms install downloads tools and starts containerd; it stays running in the background. pdms build starts BuildKit on demand. Run pdms kill with no arguments to stop all containers, remove their containerd tasks (and shims), and stop pdms-managed BuildKit and containerd; container records remain available for a later pdms start. This command does not download tools or start a daemon. pdms kill CONTAINER still sends nerdctl's kill command to that container. Run pdms upgrade after pdms kill to download, verify, and atomically activate the latest nerdctl-full; it refuses to change versions while pdms daemon state or sockets exist. The next regular pdms command starts containerd again. Rootful mode keeps its containerd socket, configuration, data, and logs under the root account's PDMS_HOME. Its home directory must be owned by root. Set PDMS_HOME=/absolute/path to choose another directory.

pdms help lists Docker-style container, image, network, volume, system, and Compose commands without downloading tools. After installation, pdms help run, pdms run --help, and pdms compose up --help show the installed nerdctl command's options without starting containerd. See the nerdctl command reference for supported Docker flags and commands.

Rootless mode requires Linux user namespaces, newuidmap/newgidmap, and subordinate UID/GID ranges. If the mapping helpers are missing, pdms asks for permission, downloads the latest glibc release of uutils/shadow, verifies its SHA-256, and installs its setuid-root helper in PDMS_HOME/privileged using sudo. The helper directory is root-owned. The system's mapping helpers take priority when both are installed. If sudo is unavailable but you can switch to root, run the exact sh .../host-setup.sh command shown by pdms in a root shell, then retry as the regular user. The command includes --uidmap when local mapping helpers are needed and also allocates missing subordinate IDs in /etc/subuid and /etc/subgid; these host files must remain under /etc for UID mapping to work. You can run pdms host-setup USER [PDMS_HOME] [--uidmap] if pdms is on root's PATH.

Linux must expose cgroup v1 or v2 under /sys/fs/cgroup for containers to start. Rootful cgroup v1 also needs the devices controller. pdms install and pdms doctor check this before downloading the container tools. If no cgroup mount exists, rootful pdms mounts cgroup v2 when the kernel supports it, or cgroup v1 on a v1-only kernel. Rootless pdms needs the host administrator to expose cgroups. If a VPS denies the mount even to root, its host administrator or provider must expose cgroups. Rootless cgroup_manager = "none" does not create the kernel mount.

Rootful bridge networking needs host netfilter NAT and the iptables comment match used by the CNI plugins. pdms install, pdms doctor, and commands that may use bridge networking (run, create, build) check these with a temporary, unreferenced NAT chain and remove it immediately. pdms start uses the network mode saved by pdms create, so it does not run an unconditional bridge check; a container created with --net=host can start without the bridge modules. If needed, pdms looks for modprobe in the host's system directories and attempts to load xt_comment and nft_compat. When the host exposes modules for its running kernel but lacks modprobe, rootful pdms installs the host's kmod package. A VPS that does not provide those kernel features or permission to use them cannot run the default bridge network; pdms run --net=host ... explicitly uses the host network instead.

A filesystem mounted nosuid or noexec cannot run a bundled mapping helper from there, and pdms reports this explicitly. Other missing host packages are installed after an interactive approval prompt through sudo on supported apt or dnf systems when running rootless. Bootstrap uses standard host utilities such as curl, tar, sha256sum, and nsenter; the script prompts to install these when missing. Kernel settings that forbid unprivileged user namespaces must be changed by the host administrator.

Supported: Linux x86_64 and arm64. macOS: coming soon.