Platform Support

Which pgcli components and features work on Linux vs macOS

pgcli drives Podman containers on both Linux and macOS. The difference is how containers get networking:

Linux runs Podman natively, so containers share the host network stack (--network host) and reach each other over 127.0.0.1. This is the zero-overhead path and the only one that supports cross-host topologies.
macOS runs Podman inside a podman machine VM. Host networking there binds to the VM’s loopback, which the Mac cannot see, so pgcli instead joins a shared bridge network (pgcli-net) and publishes each port — the Mac reaches it on 127.0.0.1:<port> via gvproxy, and containers reach each other by container name over the bridge. This works for a single host (dev/test); it is not the cross-host HA path.

The table below is the current support matrix. “macOS (single-host)” means fully usable for one machine; features that must advertise a routable address across machines, or that depend on Linux-only container internals, stay Linux only.

Support matrix

Component / feature	Linux	macOS
Instance lifecycle — `pg create` / `start` / `stop` / `restart` / `destroy` / `status`	✅	✅ single-host
`pg psql` / `pg exec`	✅	✅
SQL command reference (`pg exec`, admin queries)	✅	✅
Logs — `pg logs`	✅	✅
Namespace isolation (`pg.yaml` `namespace`)	✅	✅
Data import / export — `pg import` / `pg export`	✅	✅
Clone — `pg clone` (streamed `pg_dump \| pg_restore`)	✅	✅
Extensions — `pg extension install` / `list`	✅	✅
Backup / restore — `pg backup` / `pg restore` (pgBackRest)	✅	✅ single-host
Physical replica — `pg replica`	✅	✅ single-host
Failover — `pg failover` (replica promotion)	✅	✅ single-host
Auto-start on boot — `pg autostart`	✅ systemd user unit	✅ launchd (after login)
Addon — PgBouncer	✅ incl. cross-host pools	✅ single-host dev/test
Addon — PgDog	✅	✅ single-host dev/test
Addon — etcd	✅ incl. cross-host clusters	❌ Linux only
Addon — HAProxy	✅	❌ Linux only
Addon — MinIO	✅ host network	✅ bridge, published ports
Addon — silo	✅ host network	✅ bridge, published ports
Addon — rustfs	✅ host network	⚠️ code-complete bridge path, untested — treated as Linux only
Client — `pg mc` (MinIO client)	✅ host network	✅ bridge (see below)
HA — Patroni (`pg ha`)	✅ incl. cross-host	❌ Linux only

Legend: ✅ supported · ✅ note supported with the stated caveat · ⚠️ present but unverified on that platform · ❌ not supported.

Instance features

Everything built on the managed PostgreSQL instance works on both platforms — lifecycle commands, pg psql / pg exec, logs, namespaces, import/export, clone, extensions, backup/restore (pgBackRest), physical replicas, and failover. The macOS bridge path (published ports + container-name DNS) was proven by the instance and replica/backup paths first; the proxy addons reuse it.

On macOS these are single-host: cross-host replicas and pools that span machines are a Linux --network host + LAN-addresses feature.

Auto-start on boot

Both platforms are supported, via different services:

Linux — a systemd user unit.
macOS — a launchd LaunchAgent. LaunchAgents run at user login, not at system boot, because rootless podman cannot start before someone logs in. Expect containers to come up after you log in, not before. See Auto-start on Boot.

Addons

Addon networking differs per component:

PgBouncer and PgDog — pure proxies, supported on macOS for single-host dev/test. On macOS they join pgcli-net and publish their ports. Client connections are still 127.0.0.1:<port>. See each page’s Platform support section for the backend-address caveat (a remote/backend host must be reachable from the Mac, not 127.0.0.1).
etcd — Linux only. Members run on host networking and advertise their client/peer URLs into the raft membership list as permanent cluster state; retrofitting the macOS bridge + container-name model would rewrite that state. Kept Linux-only until that is designed in.
Patroni (pg ha) — Linux only. Members rely on podman host networking; both root and rootless podman are supported. The podman machine VM’s uid mapping does not align with host networking. The commands fail fast on macOS with a clear message. See Patroni HA.
HAProxy — Linux only. It fronts Patroni members over host networking, which the podman machine VM does not provide to containers; the manager fails fast on macOS.
MinIO — both platforms. Object storage, standalone or as a distributed erasure-coded cluster across hosts. On Linux it serves over host networking; on macOS it joins pgcli-net with its API and console ports published, so the Mac reaches both on 127.0.0.1:<port> (the same path the proxy addons use). The public image is dual-arch (amd64 + arm64).
silo — both platforms. Pigsty’s MinIO fork, so it shares MinIO’s networking story exactly: host networking on Linux, the pgcli-net bridge with published ports on macOS. The public image is dual-arch (amd64 + arm64).
rustfs — Linux only, in practice. pgcli runs a custom wrapper image (ghcr.io/mars-base/pgcli/pgcli-rustfs) whose entrypoint chowns the bind-mounted data/cert directories to rustfs’s fixed uid 10001 from inside the container, before dropping to the unprivileged user. The wrapper image is built dual-arch, and the Go manager has the same macOS bridge path (published ports) as MinIO/silo, so macOS is expected to work — but this addon’s e2e coverage has only run on Linux, so treat it as Linux only until it is exercised on a Mac.
pg mc (MinIO client) — both platforms. It runs the mc binary from a throwaway container, with your ~/.mc/config.json mounted as its own default config path and local file operands (for cp/mirror/diff) mounted at their real paths — on macOS that means under the home directory, the only tree the podman machine shares. On Linux it uses host networking, so a 127.0.0.1 alias reaches a local addon instance; on macOS the container sits on the bridge, where a 127.0.0.1 alias is the container’s own loopback — point aliases at host.containers.internal:<port> for a local Mac addon, or a routable address for a remote store.

Confirming your platform

pg start prints the detected platform in its banner, so you can confirm which path you are on:

=== pg start ===
Platform: linux        # or: macOS