Install the agent
Install and authenticate a supported PulseHA endpoint.
The PulseHA agent runs on each laptop, desktop or server that needs to reach private services. This page covers the Add Device flow in the Console, which gives you the right installer and the login step for each platform.

Select a supported platform, install the agent, then complete its authentication step.
Before you start#
- You need the owner, admin or user role, or a custom role with the
devices.createpermission. Without it, Network → Devices hides Add Device and the page redirects back to the device list. - The device needs outbound HTTPS to the control plane and a browser you can sign in with.
- Supported platforms today: Linux (x86-64
.deband.rpm), Windows (signed installer for x64 and ARM64) and macOS (notarised.pkgfor Apple Silicon and Intel). The Mobile tile is marked Soon and cannot be selected. - Each user can authorise up to 5 devices in an organisation. Re-authorising a device you already own does not count against this.
Open the Add Device page#
- Open Network → Devices.
- Choose Add Device. The same button is on the Overview quick actions.
- Under 1 Select Platform, pick Linux, Windows or macOS. The Install Agent and Authenticate sections update to match.
The right-hand Setup Steps panel lists the three stages: Select Platform, Install the Agent, Authenticate.
Linux#
Under Install Agent, the Installation Command is:
curl -fsSL https://get.pulseha.com/install-agent.sh | sudo bash
The script reads /etc/os-release, picks dnf, yum or apt, adds the signed PulseHA repository and installs the pulseha-agent package. It asks for confirmation before changing anything; pass -y to skip the prompt. The package installs the agentd daemon as pulseha-agent.service and the CLI at /usr/bin/pulsectl. Updates then arrive through apt upgrade or dnf upgrade.
Under Authenticate, the Login Command is:
pulsectl login
On a terminal it asks How would you like to sign in? with two options: Browser (device code) and Enrollment token. Pick the browser option. The CLI prints a card titled Sign in to PulseHA with a URL and Your code, then shows waiting for approval until you finish in the browser. Details are in Linux agent.
Windows#
- Under Install Agent, choose Download for Windows. The file is
PulseHA-Agent-Setup.exe, also available from Downloads. - Run the installer.
- Open PulseHA from the Start menu or the desktop shortcut. On first run it opens its sign-in window.
- Choose Continue in Browser, then approve the device in the Console.
There is no pulsectl command on Windows.

With Windows selected, Install Agent offers the signed setup download and Authenticate points you to Continue in Browser.
macOS#
- Under Install Agent, choose Download for macOS (Apple Silicon) or Download for macOS (Intel).
- Open the
.pkgand complete the installer. - Open PulseHA from Applications or Spotlight. The window says Sign in to PulseHA.
- Choose Continue in Browser, then approve the device in the Console.
There is no pulsectl command on macOS. The full walkthrough is in macOS agent.

With macOS selected there are separate downloads for Apple Silicon and Intel Macs.
Approve the device in the browser#
Every platform ends on the Console’s Authorize Device page. If the browser was opened by the agent, the code is already in the URL and the page approves it as soon as you are signed in. Otherwise paste the code into Device Code and choose Authorize Device. The page then shows Device authorized. Return to your client to finish. See Authorize a device for the error cases.
What you should see#
Back in Network → Devices, the new row shows the hostname, your email beneath it, and a Connection chip. It starts as Pending and changes to Online when the agent registers and sends its first heartbeat. The list refreshes itself every 30 seconds.

The Devices list after enrolment. Each row shows the hostname, the owner beneath it and a Connection chip.
An Online device has no access by itself. It receives only the services that an Allow policy grants it. See Your first access policy.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Add Device is missing | Your role lacks devices.create. Ask an owner or admin. |
| Linux script stops with This installer must be run as root | Re-run with sudo bash as shown. |
| Linux script stops with Unsupported package manager | The host has none of dnf, yum or apt. Install from the .deb or .rpm on Downloads instead. |
pulsectl login ends with login timed out | The device code expired before approval. Run pulsectl login again. |
| Browser shows a device-limit message | You already have 5 devices in this organisation. Ask an admin to revoke one you no longer use. |
| Row stays Pending | The code was approved but the agent has not registered. On Linux check systemctl status pulseha-agent and pulsectl status. On Windows or macOS reopen the app. |
| Row shows Tunnel down | The agent is heartbeating but reports the tunnel disconnected. Run pulsectl up or reconnect from the app. |
| Device is Online but the app does not load | Check policy, gateway and posture in that order. Start with Policy simulation. |