fix(install): drop podman as hard dependency for RPM installation

[pimlock]

Summary

Make package installation runtime-neutral so installing OpenShell does not require Podman, Docker, or another optional compute runtime. The RPM no longer depends on Podman, package-managed gateways retain automatic driver selection, and the installer reports package installation and gateway health as separate outcomes.

This version keeps runtime detection inside the gateway. install.sh uses the read-only detection CLI for immediate guidance, while every gateway start logs the selected driver, all detected alternatives, multi-runtime pinning guidance, and the rootless Podman bind command when applicable.

Related Issue

Closes #2007

Installation Invariants

• Select the supported native installation method deterministically for the host.
• Install matching openshell and openshell-gateway artifacts in the package manager's standard executable path.
• Install and enable the gateway as a supervised user service.
• Preserve existing gateway configuration and state across installs and upgrades.
• Keep the listener on loopback with TLS unless the operator explicitly changes it.
• Do not install, remove, start, or configure optional Docker and Podman runtimes.
• Leave compute-driver selection automatic unless the operator explicitly pins a driver.
• Treat package installation and gateway health as separate outcomes: activation failure leaves OpenShell installed, returns nonzero, and prints recovery instructions.
• Keep the installer safe to rerun after the operator fixes a runtime or service prerequisite.

Changes

• Remove Podman dependencies and podman.socket ordering from the RPM spec.
• Leave the RPM compute driver unset and default its listener to 127.0.0.1:17670.
• Add openshell-gateway config detect-driver with stable kubernetes, podman, docker, or none output.
• Detect all available runtimes at gateway startup while retaining Kubernetes → Podman → Docker selection priority.
• Log the auto-selected driver and detected alternatives on every gateway start.
• Warn when multiple runtimes are available and show how to pin the intended driver.
• Warn when Podman is auto-selected on loopback and show the explicit rootless Podman bind command.
• Keep install.sh advisory: it never changes driver selection or listener configuration.
• Add openshell-gateway config set for typed, validated, comment-preserving, atomic TOML updates.
• Report package installation succeeded separately from gateway service is healthy.
• Leave installed packages and the supervised service in place after activation failure, with actionable recovery guidance.
• Verify Linux and Homebrew service definitions retain automatic restart supervision.
• Keep published docs focused on stable prerequisites and configuration; context-dependent recovery guidance remains owned by install.sh and gateway diagnostics.

Runtime Scenarios

Environment	Result
No Docker or Podman	Package installation succeeds, gateway health fails, and install.sh returns nonzero with diagnostics. The service keeps retrying and can recover after a runtime is installed. Rootless Podman still requires the explicit bind change before sandboxes can call back.
Podman available	Podman is auto-selected. The installer and gateway show the rootless bind command without applying it. Installing Docker later does not override Podman because Podman has higher priority.
Docker available	Docker is auto-selected. If Podman is installed later, the running process remains on Docker, but the next restart selects Podman unless Docker is explicitly pinned.
Multiple runtimes	The gateway logs every detected runtime, the selected driver, and openshell-gateway config set --compute-driver <driver> guidance.
VM	VM remains opt-in and is never auto-detected. The driver must be installed where needed and selected explicitly.

Why This Option

This design follows the invariants above: package installation stays independent of optional runtimes, configuration remains operator-owned and visible in TOML, loopback is never widened implicitly, and runtime changes after installation remain observable. Keeping the warning in the gateway is important because an installer-only warning cannot cover Docker or Podman installed later.

Automatic selection remains the zero-configuration recovery path. Explicit config set commands are the stability mechanism when an operator wants a fixed driver.

Alternatives Explored

• Keep Podman as an RPM dependency. Rejected because it prevents Docker-only hosts from installing OpenShell.
• Install Docker or Podman from install.sh. Rejected because repository setup, rootless configuration, daemon lifecycle, licensing, and enterprise policy vary across supported systems.
• Add install.sh --compute-driver / OPENSHELL_INSTALL_COMPUTE_DRIVER. Implemented during exploration, then removed because it duplicated gateway configuration policy and made installation persist a driver choice.
• Persist the auto-detected driver automatically. Rejected because observational detection should not silently become operator configuration or prevent future fallback.
• Set OPENSHELL_DRIVERS in service definitions. Rejected because environment values outrank TOML and make later config edits appear ineffective.
• Rewrite TOML from shell. Rejected because preserving comments, schema validity, and atomicity in shell would be fragile.
• Automatically bind 0.0.0.0 when Podman is detected. Rejected because runtime probing must not silently expose the gateway on host interfaces.
• Warn only from install.sh. Insufficient because runtimes can be installed or removed after installation.
• Warn only in gateway service logs. Insufficient for initial discoverability, so the installer also uses detect-driver for immediate Podman guidance.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• mise run test passes (included by mise run pre-commit)
• mise run ci passes (mise run pre-commit is the ci alias)
• E2E tests added/updated (not applicable; no E2E files changed)

Focused coverage:

• Driver detection ordering and first-driver compatibility
• Multi-runtime pinning guidance
• Rootless Podman loopback guidance
• Installer package-success/service-health outcome messages
• Linux and Homebrew service restart supervision
• RPM metadata and Podman-absent installation behavior

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture and published docs updated

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2137.docs.buildwithfern.com/openshell

[pimlock]

Addressed the documentation feedback in 095565e9:

• Removed the package runtime/service matrix from the installation page and replaced the VM exception in the install prerequisite with a link to the compute-driver reference.
• Removed the duplicated auto-detection and VM packaging explanation from the gateway configuration reference.
• Reverted the installation page's RPM bind-address wording; the 0.0.0.0 follow-up remains separate.
• Kept VM packaging details in the compute-driver reference, clarified where Debian and Homebrew install the binary and that the gateway finds those locations after explicit VM selection, and simplified the enablement section.

mise run pre-commit passes.

[pimlock]

🏗️ build-from-issue-agent

Implemented proposal: runtime-neutral installation with gateway-owned detection

The final implementation treats package installation and gateway health as separate outcomes while keeping optional compute runtimes outside OpenShell's ownership.

Contract

• Install matching CLI and gateway artifacts through the host's native package mechanism.
• Install and enable a supervised user service.
• Never install or configure Docker or Podman.
• Preserve user config and keep a fresh listener on loopback with TLS.
• Leave driver selection automatic unless the operator explicitly pins it.
• If activation fails, leave the package installed, return nonzero, and print recovery instructions.

Detection and guidance

openshell-gateway config detect-driver exposes the first automatic result as kubernetes, podman, docker, or none without reading or modifying configuration. install.sh runs it as the target user and prints the rootless Podman bind command when Podman is selected.

Gateway startup now detects all available runtimes in Kubernetes → Podman → Docker priority order. On every automatic start it:

1. Logs the selected driver and every detected alternative.
2. Warns when multiple runtimes exist and shows openshell-gateway config set --compute-driver <driver> so the operator can pin the intended choice.
3. Warns when Podman is selected on loopback and shows openshell-gateway config set --bind-address 0.0.0.0:17670 for rootless Podman.

This gateway-level warning is necessary because the environment can change after installation. For example, adding Podman to a Docker-only host leaves the running gateway unchanged, but the next restart selects Podman unless Docker is pinned.

Why this option

The approach preserves the installation invariants: packages remain runtime-neutral, detection remains observational, user configuration remains explicit, and the gateway is never exposed beyond loopback without an operator action. The installer provides immediate discoverability, while gateway startup provides durable guidance for later environment changes.

Alternatives explored

• Keeping the RPM pinned to Podman or retaining a hard Podman dependency.
• Installing and managing Docker or Podman from install.sh.
• Adding install.sh --compute-driver and an environment equivalent.
• Persisting the detected driver automatically.
• Setting a higher-precedence OPENSHELL_DRIVERS value in service definitions.
• Mutating TOML directly from shell.
• Automatically widening the listener when Podman is detected.
• Providing guidance only in the installer or only in service logs.

The final implementation combines the useful parts of the last two options: immediate installer guidance plus authoritative startup diagnostics, without automatic configuration changes.

[pimlock]

@maxamillion @drew this is now implemented as a runtime-neutral installation contract.

Problem: a Docker-only RHEL host could not install OpenShell because the RPM required Podman.

Implemented outcome:

• The RPM no longer requires Podman.
• install.sh installs the CLI and gateway service but never installs or configures Docker or Podman.
• Package installation and gateway health are reported separately. If no runtime exists, OpenShell remains installed, the script returns nonzero with instructions, and the supervised service retries.
• Driver selection stays automatic and is evaluated at each gateway start.
• The gateway logs the selected driver and all detected alternatives.
• Multiple runtimes produce an explicit pinning command.
• Auto-selected Podman on loopback produces the rootless Podman bind command.
• No detection path silently changes config or binds the gateway to 0.0.0.0.

The main installation invariants are: native package installation, CLI and gateway availability, a supervised user service, preserved user configuration, loopback/TLS defaults, no management of optional runtimes, explicit operator-owned driver pinning, and a clear split between package success and service health.

We explored:

1. Keeping Podman as a dependency or installing runtimes ourselves.
2. Adding install.sh --compute-driver and persisting the chosen driver.
3. Setting OPENSHELL_DRIVERS in the service environment.
4. Using gateway detection only in the installer.
5. Warning only from gateway service logs.
6. Automatically widening the listener for Podman.

The selected design combines installer detection for immediate discoverability with gateway startup warnings for long-term correctness. This covers runtimes installed after OpenShell while keeping detection observational and all configuration changes explicit.

[pimlock]

Not sure if exposing the detected driver just for this is worth it. Arguably it provides a slightly better UX, guiding the user, rather than requiring after-the-fact troubleshooting.