@kothar-hq/host-container-capabilities 0.9.1 → 0.10.0

package/README.md

@@ -5,7 +5,7 @@ An [agent skill](https://agentskills.io) that finds out which container engines
 Coding agents run on Windows hosts (some with WSL), on Linux and macOS, inside WSL, and in cloud sandboxes. An agent that assumes `docker` reaches a Linux engine gets it wrong on a Windows host in Windows-container mode, and one that "fixes" that by switching Docker Desktop stops every container on the host. This skill gives the agent a probed report instead:
 
 - **Windows engine:** whether one answers, and the isolation (`process` or `hyperv`) that ltsc2019, ltsc2022 and ltsc2025 images need on this host build.
-- **Linux engine:** the default WSL distro's own Docker, then other WSL 2 distros, then the default docker context, then an existing Docker Desktop Linux pipe. On Linux and macOS, the docker CLI's current context.
+- **Linux engine:** the default WSL distro's own Docker, then other WSL 2 distros, then the default docker context, then an existing Docker Desktop Linux pipe, then Podman. On Linux and macOS, the docker CLI's current context, then Podman. The report says whether the engine is rootless and whether SELinux is enforced.
 - **Routing:** run locally when the engine exists, otherwise offer the project's CI workflow.
 - **Shared-host safety:** everything the agent creates is named and labelled, and only that is cleaned up. Docker Desktop is never switched, and no daemon is started or installed without asking.
 
@@ -54,7 +54,7 @@ sh .claude/skills/host-container-capabilities/scripts/host-capabilities.sh
 
 - Windows: PowerShell 7. Linux, macOS and WSL: a POSIX `sh`.
 - The installer needs Node.js 20 or later. The skill itself doesn't need Node.
-- Docker is the only container runtime probed today. Podman and others are tracked in the [issues](https://github.com/kothar-hq/host-container-capabilities/issues).
+- Docker and Podman are probed today. Other runtimes are tracked in the [issues](https://github.com/kothar-hq/host-container-capabilities/issues).
 
 ## Versions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kothar-hq/host-container-capabilities",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "An agent skill that finds out which container engines a host has (Windows, Linux, WSL) and routes container work to a local engine or to CI.",
   "keywords": [
     "agent-skill",

package/skills/host-container-capabilities/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: host-container-capabilities
-description: Find out which container engines this host has (a Windows engine for Windows containers, a Linux engine such as a WSL distro's own Docker, both, or neither) and route container work to a local engine or to CI. Use before any docker command, before building or testing an image, before running Linux tools such as shellcheck or actionlint in a container, or when asked whether this machine can run Linux or Windows containers.
+description: Find out which container engines this host has (a Windows engine for Windows containers, a Linux engine such as Docker, Podman or a WSL distro's own Docker, both, or neither) and route container work to a local engine or to CI. Use before any docker or podman command, before building or testing an image, before running Linux tools such as shellcheck or actionlint in a container, or when asked whether this machine can run Linux or Windows containers.
 license: MIT
 metadata:
-  version: "0.9.1"
+  version: "0.10.0"
   repository: https://github.com/kothar-hq/host-container-capabilities
 ---
 
@@ -31,10 +31,12 @@ The fields that decide things:
 | `platform` | `windows`, `wsl` (the agent is running inside WSL), `linux` or `macos` |
 | `windowsEngine.available`, `.invoke` | Whether a Windows engine answers, and the command that reaches it (`docker`, or `docker.exe` from inside WSL) |
 | `windowsEngine.ltsc.<2019\|2022\|2025>.isolation` | `process`, `hyperv`, or `null` when that Windows version's images can't run here. Only filled in on Windows. |
-| `linuxEngine.available`, `.invoke` | Whether a Linux engine answers, and the command that reaches it, for example `["wsl.exe","--distribution","Ubuntu","--exec","docker"]` |
+| `linuxEngine.available`, `.invoke` | Whether a Linux engine answers, and the command that reaches it, for example `["wsl.exe","--distribution","Ubuntu","--exec","docker"]` or `["podman"]` |
+| `linuxEngine.kind` | `docker`, `wsl` (Docker inside a WSL distro), `docker-desktop-linux` or `podman`. It decides the flags in section 3. |
+| `linuxEngine.rootless`, `.selinux` | Whether the engine runs rootless, and whether SELinux is enforced on its host. They decide the user and mount flags in section 3. |
 | `linuxEngine.repoPath` | The project's path as the Linux engine's host sees it, for bind mounts |
 | `linuxEngine.containers` minus `.claudeContainers` | Containers that belong to someone else (the user's devcontainers, CI runners). Leave them alone. |
-| `linuxEngine.reason`, `.tried` | Why there's no Linux engine, and what was tried |
+| `linuxEngine.reason`, `.tried` | Why there's no Linux engine (for example `socket permission denied`), and what was tried |
 | `policy.sharedHost` | `true` unless the user overrode it. Shared means strict cleanup (section 4). |
 | `policy.createdByLabel`, `.sessionLabelKey` | The labels to put on everything you create (section 4) |
 | `github.authenticated` | Whether `gh` can dispatch workflows |
@@ -65,6 +67,17 @@ $linux = $report.linuxEngine
     --volume "$($linux.repoPath):/src:ro" --workdir /src rhysd/actionlint:1.7.12 -color
 ```
 
+- **Podman takes the same arguments** as docker for everything this skill does (`run`, `build`, `ps`, `images`, `rm`, `rmi`, `--label`, `--filter label=`). Give images their full name (`docker.io/rhysd/actionlint:1.7.12`): Podman may not search Docker Hub for a short name.
+- **Files written to a bind mount should belong to the user.** Which flag does that depends on the engine:
+
+  | `kind` | `rootless` | Flag |
+  | --- | --- | --- |
+  | `podman` | `true` | `--userns=keep-id` |
+  | `podman` | `false` | `--user "$(id -u):$(id -g)"` |
+  | any Docker kind | `false` | `--user "$(id -u):$(id -g)"` |
+  | any Docker kind | `true` | none: root in the container is already the user on the host. `--user` would map to a different host user. |
+
+- **SELinux:** when `linuxEngine.selinux` is `true`, add `:Z` to a bind mount (`--volume "$PWD:/src:Z"`, or `:ro,Z`), or the container can't read it. `:Z` relabels the directory, so only use it on the project, never on a home directory or a system path.
 - **Prefer PowerShell on Windows.** Git Bash rewrites arguments that look like paths (`/src` becomes `C:/Program Files/Git/src`), so in Bash prefix the command with `MSYS_NO_PATHCONV=1`.
 - **`--exec` runs docker without a shell** inside the distro. Don't pass `bash -lc '...'` through `wsl.exe`: the quoting breaks and `$variables` are expanded in the wrong place.
 - **`/mnt/c` is slow.** That's fine for linters and for reading the project. For a real build, copy the sources into the container or a Linux directory instead of building on the bind mount.
@@ -80,7 +93,7 @@ On a shared host (`policy.sharedHost`, the default), everything you create carri
 
 Prefer images that are already present (`docker images`). If you pull one, note that it wasn't there before, and remove exactly that reference when you're done.
 
-Clean up only what carries your session's label, on the engine you created it on:
+Clean up only what carries your session's label, on the engine you created it on. Put the engine's `invoke` in place of `docker`. The same commands work with Podman:
 
 ```sh
 docker ps -aq --filter label=<policy.sessionLabelKey>=<tag> | xargs -r docker rm -f
@@ -91,9 +104,12 @@ Never `docker system prune`, `docker image prune` or `docker builder prune` on a
 
 ## 5. When an engine is missing
 
+- **`linuxEngine.reason` is `socket permission denied`:** Docker is installed and running, but this user can't use its socket. Offer, after asking, to add the user to the `docker` group (`sudo usermod -aG docker "$USER"`, then a new login; this makes the user root-equivalent on the host, so say so), or to set up rootless Docker or Podman instead. Don't work around it with `sudo docker`.
+- **`linuxEngine.reason` is `no docker or podman CLI is installed`** (a cloud sandbox, a fresh machine): offer the CI workflow, or report what's missing.
 - **No Linux engine, but WSL is installed** (`linuxEngine.tried` names the distros): offer to install Docker Engine in the distro, or to start its daemon if `tried` says it isn't reachable. Both are host changes, so ask first. Otherwise, offer the CI workflow.
 - **No Linux engine and no WSL** (Windows without WSL, or a Linux or macOS host without Docker): offer the CI workflow, or report what's missing.
-- **No Windows engine** (Linux, macOS, or a cloud sandbox): Windows container images can only be built in CI, on a Windows runner. Don't try workarounds.
+- **No Windows engine** (Linux, macOS, or a cloud sandbox): Windows container images can only be built in CI, on a Windows runner. Don't try workarounds. Podman can't run Windows containers, so it never fills in `windowsEngine`.
+- **A remote Windows engine:** when the docker CLI's current context (or `DOCKER_HOST`) reaches a Windows engine from Linux or macOS, `windowsEngine.invoke` is `["docker"]`. Bind mounts of this host don't work there, and `ltsc` is `null`.
 
 ## 6. Never
 
@@ -117,7 +133,7 @@ Per host, in `.claude/host-container-capabilities.overrides.local.json` in the p
 }
 ```
 
-- `linuxEngine`: `auto` (the default), `none`, `wsl:<distro>` (Windows only), `docker` (the default docker context, if it's a Linux engine), or `docker-desktop-linux` (Windows only: Docker Desktop's Linux engine pipe, if it already exists; it's never switched to)
+- `linuxEngine`: `auto` (the default: Docker first, then Podman), `none`, `wsl:<distro>` (Windows only: Docker, then Podman, in that distro), `docker` (the default docker context, if it's a Linux engine), `podman` (the podman CLI; where `docker` is the podman-docker shim, the report says `podman`), or `docker-desktop-linux` (Windows only: Docker Desktop's Linux engine pipe, if it already exists; it's never switched to)
 - `sharedHost`: set `false` only on a host that nothing else uses
 - `maxAgeHours`: how long a report is reused
 - `createdByLabel`, `sessionLabelKey`: the labels from section 4, for a project that already has a labelling convention

package/skills/host-container-capabilities/scripts/Get-HostCapabilities.ps1

@@ -11,8 +11,10 @@ On Windows it checks:
 - the Windows engine behind the default docker context: its version, default isolation, and the isolation each of
   ltsc2019, ltsc2022 and ltsc2025 needs on this host build
 - a Linux engine, in this order: the default WSL distro's own Docker, any other WSL 2 distro's Docker (the
-  docker-desktop distros are skipped), the default docker context if it is a Linux engine, and Docker Desktop's
-  Linux engine pipe if it already exists. It stops at the first that answers. Probing a stopped WSL distro boots it.
+  docker-desktop distros are skipped), the default docker context if it is a Linux engine, Docker Desktop's
+  Linux engine pipe if it already exists, then Podman in each WSL 2 distro (which includes Podman Desktop's
+  podman-machine distros) and the native podman CLI. It stops at the first that answers. Probing a stopped WSL
+  distro boots it.
 - gh, and whether it is logged in (the exit code only; nothing it prints is kept)
 
 It never switches Docker Desktop between Windows and Linux containers, never starts a daemon, and installs nothing.
@@ -23,8 +25,8 @@ current directory, otherwise the current directory.
 The report is cached in <root>/.claude/host-container-capabilities.windows.local.json, which should be gitignored.
 A cached report is reused until it is older than maxAgeHours, the overrides file is newer than it, or -Refresh is
 given. Overrides are read from <root>/.claude/host-container-capabilities.overrides.local.json, a flat JSON object:
-  linuxEngine             'auto' (default), 'none', 'wsl:<distro>', 'docker' (the default docker context) or
-                          'docker-desktop-linux'
+  linuxEngine             'auto' (default), 'none', 'wsl:<distro>' (Docker, then Podman, in that distro), 'docker'
+                          (the default docker context), 'docker-desktop-linux' or 'podman' (the native podman CLI)
   sharedHost              true (default). Set false only on a host that nothing else uses.
   maxAgeHours             24 (default)
   createdByLabel          the key=value label the agent puts on everything it creates
@@ -97,8 +99,8 @@ if (Test-Path $overridesPath) {
     foreach ($key in @($userOverrides.Keys)) {
         if ($overrides.Contains($key)) { $overrides[$key] = $userOverrides[$key] } else { Write-Warning "Ignoring unknown override '$key'" }
     }
-    if ($overrides.linuxEngine -notmatch '^(auto|none|docker|docker-desktop-linux|wsl:.+)$') {
-        throw "Override linuxEngine '$($overrides.linuxEngine)' must be auto, none, docker, docker-desktop-linux or wsl:<distro>"
+    if ($overrides.linuxEngine -notmatch '^(auto|none|docker|docker-desktop-linux|podman|wsl:.+)$') {
+        throw "Override linuxEngine '$($overrides.linuxEngine)' must be auto, none, docker, docker-desktop-linux, podman or wsl:<distro>"
     }
     if ($overrides.createdByLabel -notmatch '^[^=\s]+=\S+$') {
         throw "Override createdByLabel '$($overrides.createdByLabel)' must be key=value, without spaces"
@@ -136,6 +138,11 @@ function Invoke-Native {
 # and sets $script:probeError when the engine doesn't answer.
 function Get-EngineFact {
     param([Parameter(Mandatory)][string[]]$Docker)
+    $cli = Invoke-Native ($Docker + @('--version'))
+    if ($cli.ExitCode -eq 0 -and $cli.Output -match 'podman') {
+        $script:probeError = 'docker is the podman-docker shim'
+        return $null
+    }
     $version = Invoke-Native ($Docker + @('version', '--format', '{{.Server.Os}}|{{.Server.Version}}'))
     if ($version.ExitCode -ne 0 -or $version.Output -notmatch '^(\w+)\|(\S+)$') {
         $script:probeError = ($version.Output -split "`n" | Where-Object { $_ } | Select-Object -First 1) ?? 'no output'
@@ -144,6 +151,7 @@ function Get-EngineFact {
     $os, $serverVersion = $Matches[1], $Matches[2]
     $info = Invoke-Native ($Docker + @('info', '--format', '{{.OperatingSystem}}|{{.Isolation}}'))
     $operatingSystem, $isolation = if ($info.ExitCode -eq 0) { $info.Output -split '\|', 2 } else { $null, $null }
+    $security = Invoke-Native ($Docker + @('info', '--format', '{{.SecurityOptions}}'))
     $endpoint = Invoke-Native ($Docker + @('context', 'inspect', '--format', '{{.Endpoints.docker.Host}}'))
     $names = Invoke-Native ($Docker + @('ps', '-a', '--format', '{{.Names}}'))
     $mine = Invoke-Native ($Docker + @('ps', '-aq', '--filter', "label=$($overrides.createdByLabel)"))
@@ -152,12 +160,42 @@ function Get-EngineFact {
         ServerVersion   = $serverVersion
         OperatingSystem = $operatingSystem
         Isolation       = if ($isolation) { $isolation } else { $null }
+        Rootless        = if ($security.ExitCode -eq 0) { $security.Output -match 'rootless' } else { $null }
+        Selinux         = if ($security.ExitCode -eq 0) { $security.Output -match 'selinux' } else { $null }
         Endpoint        = if ($endpoint.ExitCode -eq 0) { $endpoint.Output } else { $null }
         Names           = @($names.Output -split "`n" | Where-Object { $_ })
         ClaudeCount     = @($mine.Output -split "`n" | Where-Object { $_ }).Count
     }
 }
 
+# Asks a Podman CLI (an array such as 'wsl.exe','-d','Fedora','--exec','podman') about its engine, with Podman's
+# own field names. Returns $null and sets $script:probeError when the engine doesn't answer.
+function Get-PodmanFact {
+    param([Parameter(Mandatory)][string[]]$Podman)
+    $format = '{{.Host.OS}}|{{.Version.Version}}|{{.Host.Distribution.Distribution}} {{.Host.Distribution.Version}}|' +
+        '{{.Host.Security.Rootless}}|{{.Host.Security.SELinuxEnabled}}|{{.Host.RemoteSocket.Path}}'
+    $info = Invoke-Native ($Podman + @('info', '--format', $format))
+    $line = $info.Output -split "`n" | Where-Object { $_ -match '^\w+\|' } | Select-Object -First 1
+    if ($info.ExitCode -ne 0 -or -not $line) {
+        $script:probeError = ($info.Output -split "`n" | Where-Object { $_ } | Select-Object -First 1) ?? 'no output'
+        return $null
+    }
+    $os, $serverVersion, $operatingSystem, $rootless, $selinux, $endpoint = $line.Trim() -split '\|', 6
+    $names = Invoke-Native ($Podman + @('ps', '-a', '--format', '{{.Names}}'))
+    $mine = Invoke-Native ($Podman + @('ps', '-aq', '--filter', "label=$($overrides.createdByLabel)"))
+    [pscustomobject]@{
+        Os              = $os
+        ServerVersion   = $serverVersion
+        OperatingSystem = $operatingSystem
+        Isolation       = $null
+        Rootless        = if ($rootless -in 'true', 'false') { $rootless -eq 'true' } else { $null }
+        Selinux         = if ($selinux -in 'true', 'false') { $selinux -eq 'true' } else { $null }
+        Endpoint        = if ($endpoint) { $endpoint } else { $null }
+        Names           = @($names.Output -split "`n" | Where-Object { $_ })
+        ClaudeCount     = @($mine.Output -split "`n" | Where-Object { $_ }).Count
+    }
+}
+
 # Host
 $os = Get-CimInstance Win32_OperatingSystem
 $hostBuild = [Environment]::OSVersion.Version.Build
@@ -221,34 +259,49 @@ try {
     $candidates = @()
     $wslCandidates = @($distros | Where-Object { $_.version -eq 2 -and $_.name -notlike 'docker-desktop*' } |
         Sort-Object { -not $_.default })
+    # Kind 'wsl' is Docker inside a WSL distro. Kind 'podman' is Podman, inside a WSL distro (Distro is set, which
+    # covers Podman Desktop's podman-machine distros) or through the native podman CLI (Distro is $null).
+    $nativePodman = [pscustomobject]@{ Kind = 'podman'; Distro = $null }
     switch -Regex ($overrides.linuxEngine) {
         '^auto$' {
             $candidates += $wslCandidates | ForEach-Object { [pscustomobject]@{ Kind = 'wsl'; Distro = $_.name } }
             $candidates += [pscustomobject]@{ Kind = 'docker'; Distro = $null }
             if ($dockerDesktopLinuxPipe) { $candidates += [pscustomobject]@{ Kind = 'docker-desktop-linux'; Distro = $null } }
+            $candidates += $wslCandidates | ForEach-Object { [pscustomobject]@{ Kind = 'podman'; Distro = $_.name } }
+            if (Get-Command podman -ErrorAction SilentlyContinue) { $candidates += $nativePodman }
+        }
+        '^wsl:(.+)$' {
+            $candidates += [pscustomobject]@{ Kind = 'wsl'; Distro = $Matches[1] }
+            $candidates += [pscustomobject]@{ Kind = 'podman'; Distro = $Matches[1] }
         }
-        '^wsl:(.+)$' { $candidates += [pscustomobject]@{ Kind = 'wsl'; Distro = $Matches[1] } }
+        '^podman$' { $candidates += $nativePodman }
         '^(docker|docker-desktop-linux)$' { $candidates += [pscustomobject]@{ Kind = $Matches[1]; Distro = $null } }
     }
 
     $linuxEngine = [ordered]@{
         available = $false; kind = $null; distro = $null; invoke = $null; endpoint = $null; serverVersion = $null
-        operatingSystem = $null; containers = $null; claudeContainers = $null; repoPath = $null; reason = $null; tried = @()
+        operatingSystem = $null; rootless = $null; selinux = $null; containers = $null; claudeContainers = $null
+        repoPath = $null; reason = $null; tried = @()
     }
     foreach ($candidate in $candidates) {
         $docker = switch ($candidate.Kind) {
             'wsl' { @('wsl.exe', '--distribution', $candidate.Distro, '--exec', 'docker') }
             'docker' { @('docker') }
             'docker-desktop-linux' { @('docker', '--host', 'npipe:////./pipe/dockerDesktopLinuxEngine') }
+            'podman' {
+                if ($candidate.Distro) { @('wsl.exe', '--distribution', $candidate.Distro, '--exec', 'podman') } else { @('podman') }
+            }
         }
-        $fact = if ($candidate.Kind -eq 'docker') { $defaultEngine } else { Get-EngineFact $docker }
+        $fact = if ($candidate.Kind -eq 'docker') { $defaultEngine }
+            elseif ($candidate.Kind -eq 'podman') { Get-PodmanFact $docker }
+            else { Get-EngineFact $docker }
         $failure = if (-not $fact) { if ($candidate.Kind -eq 'docker') { $defaultError } else { $script:probeError } }
             elseif ($fact.Os -ne 'linux') { "it is a $($fact.Os) engine" }
         if ($failure) {
             $linuxEngine.tried += [ordered]@{ kind = $candidate.Kind; distro = $candidate.Distro; error = $failure }
             continue
         }
-        $repoPath = if ($candidate.Kind -eq 'wsl') {
+        $repoPath = if ($candidate.Distro) {
             (Invoke-Native @('wsl.exe', '--distribution', $candidate.Distro, '--exec', 'wslpath', '-a', $projectRoot)).Output
         } else { $null }
         $linuxEngine.available = $true
@@ -258,6 +311,8 @@ try {
         $linuxEngine.endpoint = $fact.Endpoint
         $linuxEngine.serverVersion = $fact.ServerVersion
         $linuxEngine.operatingSystem = $fact.OperatingSystem
+        $linuxEngine.rootless = $fact.Rootless
+        $linuxEngine.selinux = $fact.Selinux
         $linuxEngine.containers = $fact.Names.Count
         $linuxEngine.claudeContainers = $fact.ClaudeCount
         $linuxEngine.repoPath = $repoPath
@@ -265,6 +320,7 @@ try {
     }
     if (-not $linuxEngine.available) {
         $linuxEngine.reason = if ($overrides.linuxEngine -eq 'none') { 'disabled by the linuxEngine override' }
+            elseif ($linuxEngine.tried | Where-Object { $_.error -match 'permission denied' }) { 'socket permission denied' }
             elseif (-not $wsl.installed) { 'WSL is not installed and no other Linux engine answered' }
             else { 'no candidate answered; see tried' }
     }

package/skills/host-container-capabilities/scripts/host-capabilities.sh

@@ -9,7 +9,7 @@
 # The project root is $HOST_CONTAINER_CAPABILITIES_ROOT, else the git work tree around the current directory,
 # else the current directory. The report is cached in <root>/.claude/host-container-capabilities.<platform>.local.json.
 # Overrides are read from <root>/.claude/host-container-capabilities.overrides.local.json, a flat JSON object with
-# linuxEngine (auto, none or docker), sharedHost (true), maxAgeHours (24), createdByLabel, sessionLabelKey and
+# linuxEngine (auto, none, docker or podman), sharedHost (true), maxAgeHours (24), createdByLabel, sessionLabelKey and
 # runnerContainerPattern. It never starts a daemon and installs nothing.
 set -eu
 
@@ -66,8 +66,8 @@ ov_session=$(json_value "$overrides" sessionLabelKey)
 ov_runners=$(json_value "$overrides" runnerContainerPattern)
 : "${ov_engine:=auto}" "${ov_shared:=true}" "${ov_age:=24}"
 : "${ov_label:=io.github.kothar-hq.created-by=agent}" "${ov_session:=io.github.kothar-hq.session}"
-case "$ov_engine" in auto | none | docker) ;; *)
-    echo "host-capabilities.sh: override linuxEngine '$ov_engine' must be auto, none or docker here" >&2; exit 2 ;;
+case "$ov_engine" in auto | none | docker | podman) ;; *)
+    echo "host-capabilities.sh: override linuxEngine '$ov_engine' must be auto, none, docker or podman here" >&2; exit 2 ;;
 esac
 case "$ov_shared" in true | false) ;; *) echo "host-capabilities.sh: override sharedHost must be true or false" >&2; exit 2 ;; esac
 case "$ov_age" in '' | *[!0-9]*) echo "host-capabilities.sh: override maxAgeHours must be a whole number" >&2; exit 2 ;; esac
@@ -84,46 +84,119 @@ if [ "$refresh" = 0 ] && [ -f "$cache" ] && [ -z "$(find "$overrides" -newer "$c
     fi
 fi
 
-# probe <docker command...>: asks a docker CLI about its engine. Sets p_os, p_version, p_osname, p_isolation,
-# p_endpoint, p_total and p_mine, or p_error when the engine doesn't answer.
-probe() {
-    p_os='' p_version='' p_osname='' p_isolation='' p_endpoint='' p_total='' p_mine='' p_error=''
-    if ! out=$("$@" version --format '{{.Server.Os}}|{{.Server.Version}}' 2>&1) || [ "${out#*|}" = "$out" ]; then
-        p_error=$(printf '%s\n' "$out" | sed -n '/./{p;q;}')
-        : "${p_error:=no output}"
+# The probes set p_os, p_version, p_osname, p_isolation, p_endpoint, p_rootless, p_selinux, p_total and p_mine,
+# or p_error when the engine doesn't answer.
+reset_probe() {
+    p_os='' p_version='' p_osname='' p_isolation='' p_endpoint='' p_rootless='' p_selinux='' p_total='' p_mine='' p_error=''
+}
+# first_error <command...>: the first non-empty line the command prints on stderr
+first_error() {
+    p_error=$("$@" 2>&1 >/dev/null | sed -n '/./{p;q;}' || true)
+    : "${p_error:=no output}"
+}
+count_containers() {
+    p_total=$("$@" ps -aq 2>/dev/null | wc -l | tr -d ' ')
+    p_mine=$("$@" ps -aq --filter "label=$ov_label" 2>/dev/null | wc -l | tr -d ' ')
+}
+# is_podman <cli>: true when the CLI is Podman, which includes the podman-docker shim named docker
+is_podman() { "$1" --version 2>/dev/null | grep -qi podman; }
+
+# probe_docker <docker command...>: asks a docker CLI about its engine
+probe_docker() {
+    reset_probe
+    if ! out=$("$@" version --format '{{.Server.Os}}|{{.Server.Version}}' 2>/dev/null) || [ "${out#*|}" = "$out" ]; then
+        first_error "$@" version --format '{{.Server.Os}}|{{.Server.Version}}'
         return 1
     fi
     p_os=${out%%|*} p_version=${out#*|}
     info=$("$@" info --format '{{.OperatingSystem}}|{{.Isolation}}' 2>/dev/null || true)
     p_osname=${info%%|*} p_isolation=${info#*|}
+    security=$("$@" info --format '{{.SecurityOptions}}' 2>/dev/null || true)
+    case "$security" in *rootless*) p_rootless=true ;; *) p_rootless=false ;; esac
+    case "$security" in *selinux*) p_selinux=true ;; *) p_selinux=false ;; esac
     p_endpoint=$("$@" context inspect --format '{{.Endpoints.docker.Host}}' 2>/dev/null || true)
-    p_total=$("$@" ps -aq 2>/dev/null | wc -l | tr -d ' ')
-    p_mine=$("$@" ps -aq --filter "label=$ov_label" 2>/dev/null | wc -l | tr -d ' ')
+    count_containers "$@"
 }
 
-# Linux engine: the docker CLI's current context (DOCKER_HOST, Docker Desktop, colima, a distro's own Docker)
-l_available=false l_kind='' l_invoke=null l_version='' l_osname='' l_endpoint='' l_total='' l_mine='' l_reason='' l_tried=''
-if [ "$ov_engine" = none ]; then
-    l_reason='disabled by the linuxEngine override'
-elif ! command -v docker >/dev/null 2>&1; then
-    l_reason='docker CLI not installed'
-    l_tried="{\"kind\": \"docker\", \"distro\": null, \"error\": $(js "$l_reason")}"
-elif probe docker && [ "$p_os" = linux ]; then
-    l_available=true l_kind=docker l_invoke='["docker"]' l_version=$p_version l_osname=$p_osname
-    l_endpoint=$p_endpoint l_total=$p_total l_mine=$p_mine
-else
-    if [ -n "$p_os" ]; then p_error="it is a $p_os engine"; fi
-    l_reason='no candidate answered; see tried'
-    l_tried="{\"kind\": \"docker\", \"distro\": null, \"error\": $(js "$p_error")}"
+# probe_podman <podman command...>: asks a Podman CLI about its engine, with Podman's own field names
+probe_podman() {
+    reset_probe
+    format='{{.Host.OS}}|{{.Version.Version}}|{{.Host.Distribution.Distribution}} {{.Host.Distribution.Version}}|{{.Host.Security.Rootless}}|{{.Host.Security.SELinuxEnabled}}|{{.Host.RemoteSocket.Path}}'
+    if ! out=$("$@" info --format "$format" 2>/dev/null) || [ "${out#*|}" = "$out" ]; then
+        first_error "$@" info --format "$format"
+        return 1
+    fi
+    IFS='|' read -r p_os p_version p_osname p_rootless p_selinux p_endpoint <<EOF
+$out
+EOF
+    case "$p_rootless" in true | false) ;; *) p_rootless='' ;; esac
+    case "$p_selinux" in true | false) ;; *) p_selinux='' ;; esac
+    case "$p_endpoint" in /*) p_endpoint="unix://$p_endpoint" ;; esac
+    count_containers "$@"
+}
+
+# Linux engine: Docker first (the docker CLI's current context: DOCKER_HOST, Docker Desktop, colima, a distro's own
+# Docker), then Podman.
+l_available=false l_kind='' l_invoke=null l_version='' l_osname='' l_endpoint='' l_rootless='' l_selinux=''
+l_total='' l_mine='' l_reason='' l_tried='' l_denied=0
+# A Windows engine behind the docker CLI's current context (DOCKER_HOST or a remote context)
+remote_windows=0 rw_version='' rw_endpoint='' rw_isolation=''
+
+add_tried() {
+    entry="{\"kind\": \"$1\", \"distro\": null, \"error\": $(js "$2")}"
+    if [ -n "$l_tried" ]; then l_tried="$l_tried, $entry"; else l_tried=$entry; fi
+    case "$2" in *[Pp]ermission\ denied*) l_denied=1 ;; esac
+}
+found_linux() {
+    l_available=true l_kind=$1 l_invoke="[\"$2\"]" l_version=$p_version l_osname=$p_osname l_endpoint=$p_endpoint
+    l_rootless=$p_rootless l_selinux=$p_selinux l_total=$p_total l_mine=$p_mine
+}
+try_docker() {
+    if ! command -v docker >/dev/null 2>&1; then add_tried docker 'docker CLI not installed'; return 1; fi
+    if is_podman docker; then add_tried docker 'docker is the podman-docker shim'; return 1; fi
+    if ! probe_docker docker; then add_tried docker "$p_error"; return 1; fi
+    if [ "$p_os" = linux ]; then found_linux docker docker; return 0; fi
+    if [ "$p_os" = windows ]; then
+        remote_windows=1 rw_version=$p_version rw_endpoint=$p_endpoint rw_isolation=$p_isolation
+    fi
+    add_tried docker "it is a $p_os engine"
+    return 1
+}
+try_podman() {
+    cli=podman
+    if ! command -v podman >/dev/null 2>&1; then
+        if command -v docker >/dev/null 2>&1 && is_podman docker; then
+            cli=docker
+        else
+            add_tried podman 'podman CLI not installed'
+            return 1
+        fi
+    fi
+    if ! probe_podman "$cli"; then add_tried podman "$p_error"; return 1; fi
+    if [ "$p_os" = linux ]; then found_linux podman "$cli"; return 0; fi
+    add_tried podman "it is a $p_os engine"
+    return 1
+}
+case "$ov_engine" in
+    none) l_reason='disabled by the linuxEngine override' ;;
+    docker) try_docker || true ;;
+    podman) try_podman || true ;;
+    auto) try_docker || try_podman || true ;;
+esac
+if [ "$l_available" = false ] && [ -z "$l_reason" ]; then
+    if [ "$l_denied" = 1 ]; then
+        l_reason='socket permission denied'
+    elif ! command -v docker >/dev/null 2>&1 && ! command -v podman >/dev/null 2>&1; then
+        l_reason='no docker or podman CLI is installed'
+    else
+        l_reason='no candidate answered; see tried'
+    fi
 fi
 
-# Windows engine: only reachable from WSL, through Windows' docker.exe
+# Windows engine: from WSL, through Windows' docker.exe. From anywhere, a remote one behind the docker CLI's
+# current context. Podman can't run Windows containers.
 w_available=false w_invoke=null w_endpoint='' w_version='' w_isolation='' w_runners='' w_reason=''
-if [ "$platform" != wsl ]; then
-    w_reason="a $platform host has no Windows engine"
-elif ! command -v docker.exe >/dev/null 2>&1; then
-    w_reason='docker.exe is not on the PATH (WSL interop off, or no Windows Docker)'
-elif probe docker.exe && [ "$p_os" = windows ]; then
+if [ "$platform" = wsl ] && command -v docker.exe >/dev/null 2>&1 && probe_docker docker.exe && [ "$p_os" = windows ]; then
     w_available=true w_invoke='["docker.exe"]' w_endpoint=$p_endpoint w_version=$p_version w_isolation=$p_isolation
     if [ -n "$ov_runners" ]; then
         w_runners=0
@@ -133,6 +206,13 @@ elif probe docker.exe && [ "$p_os" = windows ]; then
         done
     fi
     w_reason='per-LTSC isolation is only worked out on Windows: run Get-HostCapabilities.ps1 with pwsh.exe'
+elif [ "$remote_windows" = 1 ]; then
+    w_available=true w_invoke='["docker"]' w_endpoint=$rw_endpoint w_version=$rw_version w_isolation=$rw_isolation
+    w_reason='a remote engine behind the docker context: per-LTSC isolation is not worked out, and bind mounts of this host do not work'
+elif [ "$platform" != wsl ]; then
+    w_reason="a $platform host has no Windows engine, and the docker context does not reach one"
+elif ! command -v docker.exe >/dev/null 2>&1; then
+    w_reason='docker.exe is not on the PATH (WSL interop off, or no Windows Docker)'
 else
     if [ -n "$p_os" ]; then p_error="docker.exe reaches a $p_os engine"; fi
     w_reason="docker.exe: $p_error"
@@ -192,6 +272,8 @@ cat >"$cache" <<EOF
     "endpoint": $(js "$l_endpoint"),
     "serverVersion": $(js "$l_version"),
     "operatingSystem": $(js "$l_osname"),
+    "rootless": $(jn "$l_rootless"),
+    "selinux": $(jn "$l_selinux"),
     "containers": $(jn "$l_total"),
     "claudeContainers": $(jn "$l_mine"),
     "repoPath": $(js "$root"),