PRoot Distro Next (PDN) - Next Generation Container Platform

PRoot Distro Next (PDN / podnext) is a next-generation container management and service orchestration platform engineered specifically for Termux on Android 16+ and unprivileged rootless Linux environments.

Built entirely in Rust, PDN unifies the PRoot (C) ecosystem, the proot-distro framework, and modern Android runtime compatibility shims into a single high-performance, memory-safe, and leak-proof platform.

---

What's New

v0.2.0 (Cargo.toml reads 0.2.0; podnext version prints podnext 0.2.0). 123 commits since v0.1.8 across 138 files. Every figure below names the command that produced it.

This is a stability, honesty and shape release rather than a feature release: exactly one command was added. Roadmap section 9 is the scope, and it is now 15 met, 1 recorded exception, 0 not met - the exception is stated with its number below rather than rounded up.

• Shape (section 9.2). main.rs 4,679 -> 479, with the whole Clap surface in eight cli/ modules (cli.rs itself 1,450 -> 687); commands/mod.rs 3,719 -> 813; native.rs 1,605 -> 261 behind native/{image,session,meta}.rs (579/623/184). The largest file in crates/podnext/src is commands/mod.rs at 813 - a module root holding re-exports, 13 lines over a ~800 guideline. (find crates/podnext/src -name '*.rs' -exec wc -l {} + | sort -rn | head -3.)
• The help contract is enforced, not remembered. All 123 --help screens stayed byte-identical to the tracked fixture research/cli-help-baseline.txt through both splits, and CI compares it (IDENTICAL: 210617 bytes, sha256 8236a573...).
• run --detach + attach is a real round trip (#57): the same shell pid answers two attaches, a marker written while detached survives, and a supervisor SIGKILL leaves no orphan. The simplifications are declared, not hidden - no SIGWINCH re-forwarding, no replay of output written while detached, and attach needs its stdin open (a closed pipe reconnects and exits 0 with no output).
• Guest bindings and the USER story are measured inside a guest (#66), with a control that goes red when falsified, and the documented examples are executed in CI (#64): 10 blocks run, 41 excluded with a printed reason - and it found two genuinely wrong examples.
• podnext doctor reports host checks and, with --container <name>, the guest side including the proot argv.
• Gates that can fail. The issue ledger (129 checks; an untriaged issue fails the build - CI reports 129 PASS / 0 FAIL / 0 SKIPPED), the warning ratchet keyed by toolchain (266 warnings measured cold on this device, and the same 266 on the runner - whose recorded ceiling is still 290 and therefore loose, tracked in #73 rather than hand-edited into a generated file), the tracked help fixture, scripts/local_gate.sh, and scripts/preflight_release.sh, which smoke-tests the release artifact before the tag exists because the tag publishes a release marked latest immediately.
• One criterion is a recorded exception, not a claim. Daemon metadata routing produces identical output with constant round trips, but latency independence is unmet: in-process p50 5.20 ms against 1.48 ms at ten containers, because freshness revalidates each metadata.json over IPC. An O(1) freshness key would serve in-place rewrites stale, a regression against the cached index (p50 1.3-2.2 ms), so the criterion is left unmet on purpose with the measurement beside it.
• Deferred to v0.3.0 (roadmap section 10): the mobility polygon - alias-deriving installs, install from a local tarball / OCI layout / URL with checksum, multi-arch through the emulator, the wider login polygon, portable export/import, and registry push/pull (blocked until the image store retains layer blobs, #37/#39).

---

1. Feature Comparison: PodNext vs PRoot-Distro

Feature / Metric	proot-distro (Termux Default)	podnext (PRoot Distro Next)	PDN Advantage
Language & Execution	Multi-layer Bash / Python script	Native compiled Rust binary	Zero scripting overhead, memory safety
Login Cold-Start Latency	~0.603 s	~0.097 s	~5× faster execution
Container Listing Latency	~0.160 s	~0.008 s	~20× faster execution
Environment Isolation	Leaks 24 to 163 host env vars (PATH, ANDROID_ROOT, etc.)	Strictly sanitized (6 essential clean vars)	Pure container isolation, no host pollution
Guest Root Identity	Basic permissive emulation	Native --change-id=0:0 emulation	Flawless apt, dpkg, and Linux package manager operations
Shared Memory (/dev/shm)	Overwrites host or unmanaged	Isolated standalone POSIX shared memory (1777)	Chromium headless & Playwright DOM dump run out of the box
Exit Code Propagation	Prone to truncation or collapsing to 1	Accurate child process exit code forwarding (ChildExit)	CI/CD pipelines & automation scripts receive real exit codes
File Transfer Security	Standard tar pipe	Strict path traversal enforcement (rejects ..)	Rejects directory traversal exploits into host rootfs
Filesystem Synchronization	No built-in hash-based sync	sync with SHA-256 content hashes & --delete	I/O-efficient delta-only directory transfers
Service Supervision	None (processes die when shell exits)	Process supervisor, restart policies, watchdog	Long-running background daemon services
Resource Governance	None	cgroups v2 memory & CPU quota controllers	Prevents mobile device OOM freezes
Android Integration	Manual	Termux:Boot autostart, WakeLock engine	Services survive device sleep states
IPC & Automation	None	Standalone D-Bus broker & declarative GitOps manifests	Production-grade automation on Android
Kernel Docker Support	Blocked (seccomp SIGSYS on mount(2))	Polymorphic RuntimeBackend architecture (UML bridge)	Direct path to full Docker via User-Mode Linux VM

---

2. Usage Tiers: From Core Distro to Advanced Orchestration

The command hierarchy in podnext is partitioned into three distinct tiers:

┌────────────────────────────────────────────────────────────────────────┐
│  TIER 1: SIMPLE & CORE DISTRO (Everyday proot-distro drop-in)          │
│  install · login · run · list · copy · sync · rename · reset · remove  │
├────────────────────────────────────────────────────────────────────────┤
│  TIER 2: INTERMEDIATE (Multi-Container, OCI Images, Volumes & Backups) │
│  image · volume · network · backup · ps · sessions · attach · kill    │
├────────────────────────────────────────────────────────────────────────┤
│  TIER 3: ADVANCED (Service Supervisor, Watchdog, Quota, D-Bus, GitOps) │
│  service · daemon · watchdog · quota · log · dbus · gitops · boot      │
└────────────────────────────────────────────────────────────────────────┘

---

Tier 1: Core Distro Usage (Drop-in Replacement)

For everyday development environments, commands are intuitive and straightforward:

1. Search and Install Distributions

# View curated official distributions
podnext search

# Search Docker Hub / OCI registries
podnext search debian --limit 5

# Install Debian 13 (Trixie)
podnext install debian:13

# Install Ubuntu with a custom container name
podnext install ubuntu:22.04 --name my-ubuntu

2. Interactive Shell & Ad-hoc Execution

# Enter interactive root shell
podnext login debian

# Run commands directly from the host without spawning an interactive shell
podnext run debian -- apt update && apt install -y curl git

3. Inspect Container Status & OS Version

# Display installed containers with genuine detected distro names and versions
podnext list

4. Fast & Secure File Exchange (Copy & Sync)

# Copy files from container to host (traversal-safe)
podnext copy debian:/etc/hosts ./hosts.bak

# Recursively copy directory from host into container
podnext copy ./my-project debian:/root/my-project -R

# Sync directory using SHA-256 delta hashes with deletion propagation
podnext sync ./my-project debian:/root/my-project --delete

5. Rename, Reset, or Remove Containers

# Rename an installed container
podnext rename debian deb-prod

# Reset container back to its original clean OCI state
podnext reset deb-prod

# Remove container and permanently clean up storage
podnext remove deb-prod --force

---

Tier 2: Intermediate Storage & Backup (Multi-Container)

For advanced storage management, backup snapshots, and multi-container environments:

1. Local OCI Image Cache Management

# List locally cached OCI images
podnext image ls

# Pull an image (experimental/stub: use 'podnext install' for runnable containers)
podnext image pull alpine:latest

2. Persistent Storage Volumes

# Create a named persistent volume
podnext volume create postgres-data

# List existing volumes
podnext volume ls

# Prune unused dangling volumes
podnext volume prune

3. Isolated Bridge Networks

# Create an isolated bridge network
podnext network create internal-net

# List active container networks
podnext network ls

4. Backup Snapshots & Restoration

# Create a full compressed snapshot archive of a container
podnext backup create deb-prod

# View available snapshot archives
podnext backup list

# Restore a snapshot to a new container
podnext backup restore <backup-id> --target deb-restored

---

Tier 3: Advanced Systems (Supervision, Daemons & IPC)

For production services, mobile boot persistence, resource limits, and GitOps workflows:

1. Background Supervisor Daemon

# Start background supervisor daemon
podnext daemon start

# Check supervisor daemon status
podnext daemon status

2. Managed Services & Lifecycle

# Start a supervised background service with automatic restart policy
podnext service start web-server

# Inspect service state and process PID
podnext service status web-server

# View live service logs (use log query; service logs is an experimental stub)
podnext log query --service web-server

3. Resource Quotas (cgroups v2)

# Limit maximum memory usage to 512MB
podnext quota set web-server memory 512M

# Restrict CPU utilization (2 cores = 200%)
podnext quota set web-server cpu 200

# Monitor real-time CPU and RAM utilization
podnext quota usage web-server

4. Watchdog & Circuit Breakers

# Configure automatic restart policy: up to 3 restarts within a 60 second window
podnext watchdog setpolicy web-server on-failure 3 60

# Inspect circuit breaker status
podnext watchdog status

5. D-Bus IPC Broker & Declarative GitOps

# Run standalone D-Bus broker on a UNIX domain socket
podnext dbus serve --socket $TMPDIR/pdn-dbus.sock

# Call service methods over D-Bus
podnext dbus call org.pnnext.Service /org/pnnext/Service org.pnnext.Service.List --socket $TMPDIR/pdn-dbus.sock

# Synchronize declarative container & volume manifests via GitOps
podnext gitops sync

# Detect configuration drift
podnext gitops drift

6. Android Keep-Alive & WakeLock

# Acquire Android Partial WakeLock to prevent container suspension during screen-off
podnext wakelock acquire web-server partial

# Enable boot autostart via Termux:Boot
podnext boot enable web-server

---

3. Browser & Automation Compatibility: Playwright on Android

PDN has been verified to execute modern headless web browsers inside unprivileged rootless containers due to standalone /dev/shm provisioning (POSIX shared memory mode 1777):

# Inside a PDN Debian container:
apt update && apt install -y chromium chromium-sandbox
chromium --headless=new --no-sandbox --disable-gpu --dump-dom "https://example.com"

Result: Clean HTML DOM extraction without shared memory denial errors (EACCES / ENOSPC).

---

4. Verification Status & CI/CD Pipeline

The GitHub Actions automated verification matrix is 100% Passing (Green):

Workflow	Scope & Test Matrix	Status
PDN CI/CD	Host Build, Issue ledger (93 PASS / 0 FAIL / 0 SKIPPED at 892549a), Cross-Compile aarch64, Fuzzing, Docs mdBook, Security Audit	SUCCESS
Android Cross-Compile	Matrix: aarch64-linux-android & x86_64-linux-android with NDK r27c & r30	SUCCESS
Benchmark Suite	Performance & latency regression benchmarks	SUCCESS

---

5. Crates Architecture

PDN is organized into 6 modular Rust crates:

Crate	Responsibility
proot-core	Core PRoot engine: ptrace syscall tracing, VFS routing, path resolution, seccomp BPF filters.
proot-distro-core	Container lifecycle, SELinux-safe layer unpacking, OCI digest verification, /dev/shm management, OCI manifest handling.
proot-compat	Android compatibility layer: platform personality shims, mount helpers, cgroup v2 shims, sysfs stubs.
pn-gateway	Fail-safe supervisor, container guardrails, health monitors, Prometheus metrics.
pn-next	Advanced runtime orchestration: scheduler, bridge networking, volume drivers, D-Bus broker, supervisor service, GitOps engine.
podnext	Unified CLI frontend and supervisor daemon binaries (podnext, podnext-daemon).

---

6. References & Further Reading

• Migration Guide from proot-distro
• Complete CLI Reference
• Architectural Analysis & Roadmap
• Internal Capabilities & Testing Suite
• Docker Runtime Integration Blueprint via UML

---

License

SPDX-License-Identifier: GPL-2.0-or-later. The full text is in LICENSE.

Copyright (C) 2026 PDN Contributors. This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.