Skip to content →
Log in

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.

Add Device workflow with Linux selected and install and login commands visible

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.create permission. 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 .deb and .rpm), Windows (signed installer for x64 and ARM64) and macOS (notarised .pkg for 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#

  1. Open Network → Devices.
  2. Choose Add Device. The same button is on the Overview quick actions.
  3. 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#

  1. Under Install Agent, choose Download for Windows. The file is PulseHA-Agent-Setup.exe, also available from Downloads.
  2. Run the installer.
  3. Open PulseHA from the Start menu or the desktop shortcut. On first run it opens its sign-in window.
  4. Choose Continue in Browser, then approve the device in the Console.

There is no pulsectl command on Windows.

Add Device page with Windows selected showing the installer download and the Continue in Browser note

With Windows selected, Install Agent offers the signed setup download and Authenticate points you to Continue in Browser.

macOS#

  1. Under Install Agent, choose Download for macOS (Apple Silicon) or Download for macOS (Intel).
  2. Open the .pkg and complete the installer.
  3. Open PulseHA from Applications or Spotlight. The window says Sign in to PulseHA.
  4. 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.

Add Device page with macOS selected showing Apple Silicon and Intel downloads

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.

Devices list showing hostnames, owner emails and Connection chips

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#

SymptomWhat to check
Add Device is missingYour role lacks devices.create. Ask an owner or admin.
Linux script stops with This installer must be run as rootRe-run with sudo bash as shown.
Linux script stops with Unsupported package managerThe host has none of dnf, yum or apt. Install from the .deb or .rpm on Downloads instead.
pulsectl login ends with login timed outThe device code expired before approval. Run pulsectl login again.
Browser shows a device-limit messageYou already have 5 devices in this organisation. Ask an admin to revoke one you no longer use.
Row stays PendingThe 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 downThe agent is heartbeating but reports the tunnel disconnected. Run pulsectl up or reconnect from the app.
Device is Online but the app does not loadCheck policy, gateway and posture in that order. Start with Policy simulation.