Requirements
Check these before you install. The installer checks them too, before it changes anything, and says in plain words what to do: Docker or its Compose plugin missing (it offers to install them), a port already in use (and by what), less than 4 GB of memory, or less than 10 GB of free disk.
Server
- Operating system: a Linux host, amd64 (x86_64) or arm64.
- Docker: Docker Engine 24 or newer, running, with Docker Compose v2 (the
docker composecommand). Run the installer as root, or as a user who can use Docker. No Docker yet? On Ubuntu, Debian, Red Hat Enterprise Linux, Rocky Linux, AlmaLinux, Oracle Linux and CentOS Stream the installer offers to install it from Docker's official repository (or add--install-dockerto skip the question). - Tested server systems: before each release the installer runs on fresh servers with nothing prepared: Ubuntu 22.04 and 24.04, Debian 12 and 13, RHEL 8 and 9, Rocky Linux 8 and 9, AlmaLinux 8 and 9 and Amazon Linux 2023 on Intel, and Ubuntu 24.04, Debian 12, RHEL 9 and Amazon Linux 2023 on ARM (Graviton). Also tested: a server that already has Ubuntu's
docker.io, one with Podman'sdockerstand-in, one with ufw and one with firewalld turned on, an install stopped part-way and run again, servers hardened to the CIS Level 1 benchmark (RHEL 9 with Red Hat's own CIS profile and SELinux enforcing; Ubuntu with a no-exec/tmpand a 027 umask), a server whose only way to the internet is a proxy, and one behind a proxy that inspects HTTPS with a company certificate authority. Servers that cannot run Gardience (too little memory or disk, a port taken, a Salt master already there) are refused in seconds, before anything on them is changed. Oracle Linux 9 was tested with SELinux enforcing and the firewall on. - Tools:
opensslandcurl. OpenSSL 3 is needed to verify release signatures during an upgrade. - Internet access during a normal install: the installer builds its images, which downloads base images, Python packages and the console's source. With no internet access, use the offline bundle instead.
- A DNS name for the server, if you have one. Agents and browsers use it, and it goes into the TLS certificate.
CPU, memory and disk by fleet size
For a trial, 2 CPUs and 4 GB of memory is plenty.
For production, size the server by how many machines you will manage, and install with the matching --fleet-size value so the Salt master is tuned for that fleet.
| Managed nodes | vCPU | Memory | Disk (data volume) | --fleet-size |
|---|---|---|---|---|
| up to 1,000 | 4 | 8 GB | 40 GB | 1000 |
| 1,000 to 5,000 | 8 | 16 GB | 100 GB | 5000 |
| 5,000 to 10,000 | 16 | 32 GB | 200 GB | 10000 |
| over 10,000 | contact Gardience first |
These rows are estimates. What --fleet-size changes:
| Setting on the Salt master | 1,000 or fewer | 1,001 to 5,000 | over 5,000 |
|---|---|---|---|
worker_threads (about 65 MB of memory each) | 8 | 16 | 24 |
max_open_files | 16384 | 100000 | 100000 |
zmq_backlog | 1000 | 4000 | 4000 |
gather_job_timeout (seconds) | 10 | 15 | 15 |
key_cache: sched (keeps the key list in memory) | off | on | on |
Above 1,000 nodes, agents also get settings that spread their reconnects over about a minute after a Salt master restart (recon_randomize, recon_max, random_reauth_delay).
Disk grows mostly with the audit log and run history. Routine scans and checks add about 2 to 5 MB a day. Changes add about 25 bytes per node they touch, so a patch run on 10,000 nodes adds about 250 KB. Audit log segments are sealed at 50 MB, and there is no automatic retention. Leave room for upgrades as well: an upgrade takes a full backup first, and gardience upgrade --check reports how much free space it needs.
Ports and firewall
Inbound to the Gardience server
| Port | Protocol | From | Purpose | Installer option |
|---|---|---|---|---|
| 443 | TCP | Browsers of people who use the console | The console over HTTPS | --https-port |
| 80 | TCP | Browsers | Redirects to HTTPS only | --http-port |
| 4505 | TCP | Every managed machine | Salt publish port: agents receive jobs | --salt-ports |
| 4506 | TCP | Every managed machine | Salt return port: agents sign in and send results | --salt-ports |
Ports 4505 and 4506 are only used by an all-in-one install. In attach mode, agents connect to your own Salt master, and the Gardience server instead needs:
- inbound HTTPS (443) from your Salt master, for its single sign-on and vault modules, and
- outbound access to your master's salt-api URL (for example port 8000).
A VPN on the Gardience server
If the console opens at https://localhost on the server but not at the server's own address, a VPN app's firewall is blocking local traffic. VPN apps such as Windscribe, NordVPN, Proton VPN and Mullvad drop everything that does not go through the tunnel, including connections to the Gardience containers and from machines on your network. Turn on the app's Allow LAN (or local network access) option, then reconnect. Internet traffic still goes through the VPN. On public Wi-Fi, turn it back off: there it lets other people on the same network reach the server's open ports. The installer checks this at the end and says so when it happens.
Internal ports (never exposed)
These ports exist only on Docker's internal network between the containers. The installer never publishes them on the host, and you do not need firewall rules for them.
| Port | Service |
|---|---|
| 8000 | salt-api, inside the Salt master container |
| 9400 | The Gardience service |
| 9500 | The playbook runner |
Managed machines
Agents only open outbound connections, to ports 4505 and 4506 on the Salt master. No inbound port is needed on a managed machine.
To install the agent, machines download it from the internet: Linux machines fetch the Salt bootstrap script from github.com, and Windows machines fetch the Salt installer from packages.broadcom.com. On networks without internet access, serve those files from an internal mirror.
Example: open the ports with firewalld
sudo firewall-cmd --permanent --add-service=https --add-service=http
sudo firewall-cmd --permanent --add-port=4505-4506/tcp
sudo firewall-cmd --reloadDocker publishes container ports through its own firewall rules, which some host firewalls (such as ufw) do not filter. To limit which addresses reach the agent ports, also use --salt-bind to listen on one host address, and filter at your network firewall.
Primary and standby pairs
If you run a warm standby server, the two servers also need to reach each other's console over HTTPS, and the primary needs SSH access to the standby to copy backups to it. Keep both servers' clocks in sync with NTP or chrony.
Managed machines
- Linux: verified on Ubuntu 24.04 LTS, Ubuntu 22.04 LTS, Ubuntu 20.04 LTS, Debian 12, Debian 11, Red Hat Enterprise Linux 10, Red Hat Enterprise Linux 9, Red Hat Enterprise Linux 8, Oracle Linux 10, Oracle Linux 9, Oracle Linux 8, Rocky Linux 9, Rocky Linux 8, SUSE Linux Enterprise 15 SP6 and Amazon Linux 2023. The agent needs root to install (sudo).
- Windows: verified on Windows Server 2025, Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows 11 and Windows 10 (64-bit). The agent installer is the AMD64 build of Salt. Windows 10 shares its code base with Windows Server 2016 and 2019 and was verified connecting and running jobs; the other platforms passed every check. <!-- platforms:end -->
Every release and Salt agent version tested, with the result of each feature on each one, is on the compatibility matrix.
Gardience installs Salt 3008.3 on new agents and pins that version so OS patching never upgrades it. Agents on Salt 3006.9 are refused by a 3008 master until they are upgraded, because Salt 3008 requires a newer agent sign-in protocol.