When you install the Ployz daemon, you choose how it manages its sidecars and where its control-plane services bind. These choices are captured in two flags:Documentation Index
Fetch the complete documentation index at: https://mintlify.com/getployz/ployz/llms.txt
Use this file to discover all available pages before exploring further.
--runtime and --service-mode. Together they determine which processes run where, how they are supervised, and how the daemon survives a restart.
Runtime target
The runtime target controls how the WireGuard mesh, NATS store, gateway, and DNS sidecars are run.| Value | Description |
|---|---|
docker | Sidecars run as Docker containers sharing a ployz-networking network namespace |
host | Sidecars run directly on the host as processes or system units |
Service mode
The service mode controls how sidecars are supervised and where the control-plane binds.| Value | Description |
|---|---|
user | Child-process or container supervision; control-plane binds on loopback (Docker) or overlay (host) |
system | systemd manages the sidecar units; control-plane binds on the overlay address |
Runtime matrix
The two axes combine into three supported configurations:| Runtime target | Service mode | Meaning |
|---|---|---|
docker | user | Docker-backed mesh/store/sidecars with loopback control-plane binding |
host | user | Host-backed mesh/store, child-process sidecars, overlay control-plane binding |
host | system | Host-backed mesh/store, system-managed sidecars, overlay control-plane binding |
Docker runtime only supports
--service-mode user. Passing --service-mode system with --runtime docker is an error.System mode requires systemd and is only supported on Linux. On macOS,
--service-mode system is not available.Platform defaults
The installer chooses defaults based on your platform and available tooling:- macOS
- Linux
Default runtime:
Default service mode:
dockerDefault service mode:
userOn macOS, the daemon runs on the host and everything else runs inside the Docker Desktop Linux VM. OrbStack or Docker Desktop must be installed and running before you install Ployz.Docker runtime (docker / user)
In the Docker runtime, the daemon starts aployz-networking container that owns the WireGuard interface (wg0). NATS, gateway, DNS, and all workload containers join that container’s network namespace so they share the overlay interface without needing host networking.
The daemon itself runs on the host and bridges into the container network using OverlayBridge (a userspace WireGuard and smoltcp bridge). The control plane binds on loopback addresses on the host side.
When to use:
- macOS (required — there is no host WireGuard on macOS without additional tooling)
- Linux environments where host networking modification is restricted
- Development and CI where Docker is already available
- Docker (or OrbStack on macOS) installed and running
- The daemon must be able to start and manage containers
Host runtime, user mode (host / user)
In host user mode, the daemon spawns sidecars as child processes bound to the host network. WireGuard is configured directly on the host using the kernel module. The control-plane services bind on the node’s overlay address. Child processes are supervised by the daemon. If the daemon exits, sidecars may be restarted on the next daemon start depending on whether they are adopted or recreated. The daemon always inspects what is already running before touching anything. When to use:- Linux nodes where you do not need systemd unit management
- Environments where you want simpler process supervision without system service registration
- Linux with WireGuard kernel module available
- Root or appropriate capabilities for network interface configuration (or sudo)
Host runtime, system mode (host / system)
In host system mode, sidecars are registered as systemd units. The daemon installs and enables units for NATS, gateway, and DNS duringdaemon install. On subsequent starts, the daemon adopts running units whose identity matches and recreates any that have drifted.
System mode provides the strongest data-plane durability: sidecars keep running even if ployzd is not, and they are restarted by systemd if they crash.
When to use:
- Production Linux nodes managed by systemd
- Environments where you need the data plane (WireGuard, NATS, gateway, DNS) to survive daemon restarts or upgrades cleanly
- Linux with systemd
- Root or
sudo— system service registration requires elevated privileges
Daemon restart behavior
The daemon is designed to be disposable. Restarting or upgradingployzd does not disrupt the data plane:
| Component | On daemon restart |
|---|---|
| Workload containers | Never touched |
| Gateway | Adopted if running and config matches; recreated on drift |
| DNS | Adopted if running and config matches; recreated on drift |
| NATS | Adopted if running and parent netns unchanged; recreated on drift |
| WireGuard | Adopted if healthy |
| CLI RPC listeners | Ephemeral — restarted with the daemon |
Choosing a runtime
I am on macOS
I am on macOS
Use
--runtime docker --service-mode user. This is the default and the only supported configuration for macOS. Install and start OrbStack or Docker Desktop before running the installer.I am on Linux with systemd and sudo
I am on Linux with systemd and sudo
Use
--runtime host --service-mode system. This is the default the installer selects automatically when systemd and sudo are available. Sidecars will be managed as systemd units.I am on Linux without systemd or without sudo
I am on Linux without systemd or without sudo
Use
--runtime host --service-mode user. The installer selects this automatically when system mode is not available. Sidecars run as child processes of the daemon.I want to use Docker on Linux
I want to use Docker on Linux
Use
--runtime docker --service-mode user. This is valid on Linux and works the same way as macOS, with sidecars running inside Docker containers. Note that --service-mode system is not supported with the Docker runtime.