feat(launcher): add rootless Podman container engine support (#63)

.github/workflows/platform-matrix.yml

@@ -57,3 +57,54 @@ jobs:
       - run: npm run check -w run-spaceapp
       - run: npm run pack:dry-run -w run-spaceapp
       - run: node packages/run-spaceapp/bin/spaceapp.mjs --version
+
+  podman-lifecycle:
+    name: Podman Lifecycle / ubuntu-latest
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: "22.23.0"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Set up Podman Compose provider
+        run: |
+          podman --version
+          sudo apt-get update -qq && sudo apt-get install -y -qq podman-compose || true
+
+      - name: Link local run-spaceapp
+        run: npm link -w run-spaceapp
+
+      - name: Install SpaceApp with Podman engine
+        run: |
+          spaceapp install --engine podman --profile small --non-interactive --answers '{"confirm": true}'
+
+      - name: Verify readyz endpoint
+        run: curl --fail --retry 30 --retry-connrefused --retry-delay 2 http://127.0.0.1:4911/readyz
+
+      - name: Verify doctor diagnostics on Podman
+        run: spaceapp doctor
+
+      - name: Test provider install command
+        run: spaceapp provider install opencode
+
+      - name: Test spaceapp backup
+        run: spaceapp backup
+
+      - name: Test spaceapp uninstall with purge-data
+        run: |
+          echo "DELETE" | spaceapp uninstall --purge-data
+
+      - name: Confirm no containers or runtime resources remain
+        run: |
+          test -z "$(podman ps -aq)"
+          VOLUMES="$(podman volume ls -q)"
+          test -z "$VOLUMES"

README.md

@@ -92,20 +92,23 @@ Coordinate multi-step tasks conversationally through the Room Agent or speak nat
 - **Hardware**:
   - Minimum (`small` profile): 4 CPU cores, 8 GB-class RAM (at least 7 GiB reported by the operating system), 6.5 GiB free disk.
   - `large` profile (adds the managed browser): 8 CPU cores, 15 GiB RAM, 11 GiB free disk.
-- **Docker**: If Docker is not installed, the installer automatically installs official Docker Desktop (Windows/macOS) or Docker Engine (Linux).
+- **Container Engine**: Docker Engine / Docker Desktop, or rootless Podman (>= 5 with Compose provider). If Docker is not installed and Podman is absent, the installer automatically installs official Docker Desktop (Windows/macOS) or Docker Engine (Linux).
 
 ### Run the Installation Command
 
 Run the universal command in your terminal:
 
 ```bash
 npx --yes run-spaceapp@latest install
+
+# Or explicitly choose the container engine:
+npx --yes run-spaceapp@latest install --engine podman
 ```
 
 > **Windows 11 Tip**: Use **Command Prompt** (`cmd.exe`) or the Command Prompt profile in Windows Terminal. If PowerShell has a restricted execution policy, run `npx.cmd --yes run-spaceapp@latest install`.
 
 ### What Happens Next (Step-by-Step Onboarding):
-1. **System & Docker Verification**: The launcher verifies CPU, RAM, and disk space, and installs/starts Docker if needed.
+1. **System & Container Engine Verification**: The launcher verifies CPU, RAM, and disk space, and verifies/installs Docker or Podman.
 2. **Container Initialization**: Pulls SpaceApp's images by the digest the npm package pins (from run-spaceapp 1.1.7; earlier packages by exact version tag; published with SBOM and provenance attestations that the release workflow verifies) and the third-party images pinned by digest, then starts the container stack.
 3. **One-Time Setup Token**: The terminal prints a secure 15-minute setup token and automatically opens `http://127.0.0.1:4911`.
 4. **Create Your Operator Account**: Paste the token into the setup screen, enter your email and password, and click Create Owner.
@@ -128,9 +131,9 @@ You can run any command using `npx --yes run-spaceapp@latest <command>` or simpl
 
 | Command | Description | Example |
 | :--- | :--- | :--- |
-| `install` | Full setup: installs Docker if needed, creates secrets, starts stack, and opens browser. | `npx --yes run-spaceapp@latest install --profile auto` |
+| `install` | Full setup: verifies engine (Docker or Podman), creates secrets, starts stack, and opens browser. | `npx --yes run-spaceapp@latest install --engine podman` |
 | `reinstall` | Clean reinstallation of containers while preserving existing data, credentials, and workspaces. | `npx --yes run-spaceapp@latest reinstall --keep-data` |
-| `up` | Starts the Docker application containers in the background. | `npx --yes run-spaceapp@latest up` |
+| `up` | Starts application containers in the background. | `npx --yes run-spaceapp@latest up` |
 | `down` | Stops all SpaceApp containers cleanly without removing data. | `npx --yes run-spaceapp@latest down` |
 | `status` | Checks running container status, health checks, and port bindings. | `npx --yes run-spaceapp@latest status` |
 | `logs` | Shows the most recent container log lines (bounded tail) for troubleshooting. | `npx --yes run-spaceapp@latest logs` |

docs/getting-started.md

@@ -39,6 +39,18 @@ starts the service. Before adding the current user to the `docker` group, it
 explains that the group grants root-level privileges, adds the user
 automatically, and continues in the same command.
 
+## Podman (Rootless)
+
+SpaceApp supports rootless Podman (version 5 or newer with a Compose provider such as `docker-compose-v2` or `podman-compose`) on Linux and macOS:
+
+```bash
+npx --yes run-spaceapp@latest install --engine podman
+```
+
+- **Linux**: Containers run rootless under your user account without requiring root-equivalent `docker` group membership. Workspace bind mounts automatically apply SELinux `z` relabeling. `spaceapp doctor` inspects cgroup v2 controller delegation; if CPU/memory limits cannot be applied, delegate controllers to user sessions via systemd drop-in (`/etc/systemd/system/user@.service.d/delegate.conf` with `[Service]\nDelegate=cpu cpuset io memory pids` followed by `sudo systemctl daemon-reload`). Note that `--access host-root` is not supported on Podman.
+- **macOS**: Podman Machine is supported. The launcher checks machine CPU, memory, and disk against the profile requirements and provides exact `podman machine set` instructions if resizing is needed.
+- **Engine Migration**: Switching engines on an existing installation is refused to prevent data loss (Docker volumes are not visible to Podman). To migrate, run `spaceapp backup`, `spaceapp uninstall --purge-data`, `spaceapp install --engine podman`, and `spaceapp restore`.
+
 ## macOS
 
 Install Node.js 20.11 or newer, then run in Terminal:

packages/run-spaceapp/README.md

@@ -59,9 +59,37 @@ checkpoint and 0.5 GiB headroom. Cached target images require no extra image spa
 Shared layers are excluded when public registry metadata is available; otherwise
 a conservative estimate is shown. Space is checked again after pulling and
 before pausing writers. Existing data is kept in place; the launcher never deletes
-images, backups or volumes to free space. Separate Docker disk capacity is checked
+images, backups or volumes to free space. Separate Docker/Podman disk capacity is checked
 when measurable and its availability is reported.
 
+### Container Engine Selection & Rootless Podman
+
+SpaceApp supports both **Docker Engine / Docker Desktop** and rootless **Podman** (>= 5 with Compose provider, e.g. `docker-compose-v2` or `podman-compose`).
+
+```bash
+# Explicitly choose the container engine
+npx --yes run-spaceapp@latest install --engine podman
+npx --yes run-spaceapp@latest install --engine docker
+```
+
+- **Auto-detection**: If `--engine` is omitted, the installer prefers Docker if working. If Docker is absent and Podman is ready on Linux, Podman is offered interactively (or auto-selected in `--non-interactive`).
+- **SELinux Relabeling**: Workspace bind mounts automatically append `bind: { selinux: "z" }` on Podman to allow container access under SELinux.
+- **cgroup v2 & Resource Limits**: `doctor` inspects cgroup version and controller delegation (`cpu`, `memory`). If resource limits cannot be applied due to missing rootless delegation, `doctor` reports clear guidance to delegate controllers in systemd (`/etc/systemd/system/user@.service.d/delegate.conf` with `Delegate=cpu cpuset io memory pids` and `sudo systemctl daemon-reload`).
+- **macOS Podman Machine**: On macOS, `install --engine podman` checks the active Podman machine's CPU, memory, and disk capacity against the requested profile. If resources are insufficient, it provides the exact resize commands:
+  ```bash
+  podman machine stop
+  podman machine set --cpus <CPUS> --memory <MEMORY_MIB> --disk-size <DISK_GIB>
+  podman machine start
+  ```
+- **Engine Switching & Migration**: To prevent data loss (Docker volumes are not visible to Podman), the launcher refuses switching container engines on an existing installation. To safely migrate engines:
+  ```bash
+  spaceapp backup
+  spaceapp uninstall --purge-data
+  spaceapp install --engine podman
+  spaceapp restore
+  ```
+- **Security Boundaries**: `--access host-root` is supported only on Docker on Linux and is refused on Podman (`Host-root access is not supported on Podman.`).
+
 ### Telemetry
 
 Telemetry is off unless you turn it on. The install wizard lists what is sent