Adding a Host

Overview

"Adding a host" is a two-sided operation. On the server side, you pre-register the host in the web UI: give it a friendly name, pick its operating system family, optionally place it in host groups, and receive a unique API ID and API key. On the host side, run the one-line install command that downloads and configures the agent using those credentials.

This page walks through the Add Host wizard, the install command, the Waiting for Connection screen, and what to do if the agent never shows up.

The server side is UI-only. You do not need shell access to the PatchMon server. Installing the agent on the target host is a separate job; see Installing the PatchMon Agent for distribution-specific prerequisites.

Permission required: can_manage_hosts. Users with only can_view_hosts see the Hosts list but not the Add Host button.

Before You Start

You will need:

• A PatchMon user account with can_manage_hosts (typically Admin or a custom role).
• Console or SSH access to the host you are adding, with root / sudo (Linux/FreeBSD) or Administrator (Windows).
• Outbound HTTPS from the host to the PatchMon server on port 443. No inbound ports are opened on the host.
• If your PatchMon server uses a self-signed certificate, decide up front whether to install the CA into the host's trust store or to bypass TLS verification in the install command.

Opening the Add Host Wizard

1. In the left navigation, click Hosts. The Hosts page loads with the Total Hosts, Needs Updates, Needs Reboots, and Connection Status summary cards at the top.
2. In the page header, click the blue Add Host button (icon: +). A modal titled Add New Host opens.

The wizard has four steps:

Step indicators at the top highlight where you are. You can go Back at any point before Step 3 is submitted.

Step 1: Choose OS

You pick one of three tiles:

• Linux: Ubuntu, Debian, CentOS, RHEL, Rocky, Alma, Fedora, Alpine, etc.
• FreeBSD: FreeBSD 13 / 14, including pfSense.
• Windows: Windows 10/11 (amd64 or ARM64) and Windows Server 2019 / 2022 / 2025.

The choice controls which install command the wizard generates and which download URL the server uses. You do not pick an architecture (amd64 / arm64 / arm / 386) here. The install script detects it automatically on the target host and downloads the matching binary.

Click Next to continue.

Step 2: Host Details

This form creates the host record on the server. Three groups of fields:

Friendly Name (required)

A human-readable label such as web-01.prod or billing-db. It appears in the Hosts list, dashboards, alerts, and the URL bar (/hosts/<id>). It is editable later from the Host Detail page, so don't worry about getting it perfect.

The placeholder server.example.com is not used as the system hostname. The real hostname is detected when the agent first reports.

Host Groups (optional)

A checkbox list of existing groups with coloured dots next to each name. Tick any group you want the host to belong to; a host can belong to multiple groups. You can change membership later from the Hosts table or the Host Detail page.

If you have no groups yet, this section is empty. Create groups first from Settings → Host Groups, see Managing Host Groups.

Integrations (optional)

Two toggles:

• Docker: enables container, image, volume, and network discovery via the Docker socket. Requires the docker module on your plan.
• Compliance: enables OpenSCAP CIS benchmark scanning. Requires the compliance module on your plan.

These toggles write the initial docker_enabled / compliance_enabled state on the host record. The agent picks them up on its first connection and updates config.yml accordingly. If you're not sure, leave them off; you can switch them on later from the Host Detail → Integrations tab. See Enabling Docker Integration.

Click Next. PatchMon creates the host in Pending state and generates a unique API ID and API key. The key is displayed only once (in the command on the next step). If you close the wizard without copying it, you will need to regenerate credentials from the Host Detail page.

Step 3: Copy the Install Command

The wizard now shows a read-only command tailored to:

• The chosen OS (Linux / FreeBSD / Windows).
• Your server's configured URL.
• The new host's API ID and API key.
• Your global TLS setting (ignore_ssl_self_signed): if it is on, the Linux command uses curl -sk and Windows toggles default to SSL bypass.

Linux / FreeBSD

curl -s "https://patchmon.example.com/api/v1/hosts/install" \
  -H "X-API-ID: patchmon_xxxxxxxx" \
  -H "X-API-KEY: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | sudo sh

On FreeBSD the script drops sudo, because root usually runs the command directly.

Windows

On Windows the command is a PowerShell snippet that downloads the installer via Invoke-WebRequest and executes it. Two checkboxes adjust it:

• Self-signed certificate (SSL bypass): prepends code that forces TLS 1.2 and disables certificate validation for the download. Use only on lab or internal-CA environments.
• Use curl instead of Invoke-WebRequest (if download fails): switches to curl.exe for the download, useful when corporate endpoint-protection tooling breaks Invoke-WebRequest.

The Windows command must be run in an elevated PowerShell (Run as Administrator).

Copy

Click the Copy command button (or the Copy icon). The command is placed in your clipboard and the wizard advances to Step 4. If your browser blocks clipboard access, the wizard falls back to a prompt() dialog with the command pre-selected; copy from there.

Tip: Store the command somewhere safe only if you need it for later re-use. The API key is not shown again from this screen. If you lose it, regenerate credentials from Host Detail → Deploy Agent → API Credentials → Regenerate.

Step 4: Waiting for Connection

After you copy the command, the wizard flips to a progress screen. It polls the server every 2 seconds and walks through four stages:

Run the copied command on the target host. Within a few seconds the status flips to Connected, and shortly after to Done. At Done, the modal closes and the URL changes to /hosts/<hostId>.

If you need to see the command again (for example because you pasted it into the wrong terminal), click View command again to jump back to Step 3. The command and credentials are preserved.

Note: Closing the wizard before the agent connects does not cancel the host. The host remains in Pending state and you can finish enrolment later from the Host Detail page. However, the plaintext API key is cleared from memory once the modal closes. If enrolment is not complete, open the host, click Deploy Agent, and regenerate credentials to get a fresh command.

After Enrolment

Once the agent connects and sends its first report:

• The host moves from Pending to Active.
• The OS type, OS version, architecture, hostname, IP, kernel, and package list populate automatically.
• The Connection column on the Hosts page shows a green WSS badge (or WS if you are running without TLS).
• Packages, repositories, and any enabled integrations (Docker, compliance) start reporting on the configured interval.

Troubleshooting: The Host Doesn't Check In

If the wizard sits on Waiting for connection for more than a minute or two, run through the checks below on the target host.

Check the install command actually ran

On Linux / FreeBSD the install script is verbose. Look for:

• Downloading patchmon-agent-<os>-<arch>...
• Installing to /usr/local/bin/patchmon-agent
• Writing /etc/patchmon/config.yml
• Writing /etc/patchmon/credentials.yml
• Starting patchmon-agent service

If the script aborted early, re-run it. If apt-get fails because of broken packages, open the host again from the Hosts page, click Deploy Agent, tick Force install (bypass broken packages) on the Quick Install tab, and use the regenerated command.

Confirm the service is running

Linux (systemd):

sudo systemctl status patchmon-agent

Alpine (OpenRC):

sudo rc-service patchmon-agent status

Windows:

Get-Service -Name PatchMonAgent

For detailed service management, see Managing the PatchMon Agent.

Test the connection manually

On the host, run the agent's built-in connectivity and credential test:

sudo patchmon-agent ping

A successful response looks like:

API credentials are valid
Connectivity test successful

If this fails, the agent log is the next stop:

sudo tail -n 50 /etc/patchmon/logs/patchmon-agent.log

Common causes:

• HTTP 401: the API key on the host does not match the one stored on the server. Usually this means the wizard was closed and the host was re-created, or credentials were rotated. Regenerate credentials from Host Detail → Deploy Agent.
• TLS / certificate error: the host does not trust the server's TLS certificate. Either install the CA into the host trust store, or set skip_ssl_verify: true in /etc/patchmon/config.yml (lab only).
• Connection refused / timeout: firewall, DNS, or reverse-proxy issue. From the host, curl -I https://patchmon.example.com should return an HTTP response.

See Managing the PatchMon Agent for a full diagnostic walkthrough and the patchmon-agent diagnostics command.

Nothing wrong on the host: still "Waiting"?

Open the host record regardless: from the Hosts page, click the host's friendly name (even while it's in Pending). The page shows a Deploy Agent button near the top right. Click it to reopen the install command and the waiting screen, and try again.

If the host has been Pending for a long time and you want to start over, delete the host from the Hosts page (trash icon or bulk-select → Delete), then add it again from scratch.

Bulk / Automated Enrolment

The Add Host wizard is designed for one host at a time. For automated enrolment:

• Proxmox LXC: PatchMon can auto-enrol all containers on a Proxmox host. See Proxmox LXC Auto-Enrollment Guide.
• Scripted deployments: Use the Integration API to create hosts, then deploy the install command via configuration management (Ansible, Salt, Chef, cloud-init). See Integration API Documentation.

Related Pages

• Managing Host Groups: create groups before (or after) adding hosts.
• Host Detail Page: guided tour of the page you land on after enrolment.
• Installing the PatchMon Agent: full agent-installer documentation.
• Managing the PatchMon Agent: post-install CLI, logs, diagnostics.
• Agent Configuration Reference: every config.yml field explained.