Skip to content →
Log in

Linux agent

Install, sign in, and verify a PulseHA Linux endpoint.

The Linux agent is a systemd service plus the pulsectl command-line tool. Use this page to install it on a workstation or server, sign in, and confirm it is healthy.

Before you start#

  • A Debian/Ubuntu or RHEL/Rocky/Fedora host. The installer needs dnf, yum or apt. Packages are published for x86-64.
  • Root access (sudo) and outbound HTTPS.
  • A Console account with the owner, admin or user role, so you can approve the device.
  • The install command is shown under Network → Devices → Add Device with Linux selected. It is also on Downloads.

Install#

curl -fsSL https://get.pulseha.com/install-agent.sh | sudo bash

What the script does:

  1. Reads /etc/os-release and prints Detected: <distribution> (deb|rpm/amd64).
  2. Prints This will add the PulseHA repository and install pulseha-agent. and waits for confirmation. Pass -y (or --yes) to skip the prompt, which is useful over SSH.
  3. Adds the signed PulseHA repository and installs pulseha-agent with your package manager.
  4. The package’s post-install step enables and starts pulseha-agent.service, and adds the invoking user to the pulseha group so the desktop app can talk to the daemon. Log out and back in for that group change to apply.
  5. Prints PulseHA Agent Installation Complete! followed by the next step, pulsectl login.

Installed paths: the daemon runs as pulseha-agent.service and the CLI is /usr/bin/pulsectl. Updates arrive through apt upgrade or dnf upgrade.

Install Agent and Authenticate sections of Add Device with Linux selected

The Linux panel on Add Device: the installation command above, the login command below.

For unattended installs the script accepts --token <enrollment-token> and --tenant <tenant-id>. It then runs pulsectl login --token for you and prints Agent enrolled, or Enrollment failed. Retry with: pulsectl login.

Sign in#

pulsectl login

On a terminal the CLI asks How would you like to sign in? and offers Browser (device code) or Enrollment token. For a normal user device choose the browser option.

The CLI prints a card:

  • Sign in to PulseHA
  • Open this URL in your browser: followed by a console.pulseha.com/device link that already carries your code
  • Your code: followed by the code

Open the link. Sign in to the Console if asked. Because the code is in the URL, the Authorize Device page approves it as soon as you are signed in and shows Device authorized. Return to your client to finish. Meanwhile the terminal shows waiting for approval and ends with Signed in as <your email>.

The code is valid for 15 minutes. If it lapses, the CLI prints login timed out and you run pulsectl login again.

Non-interactive options, for scripts and servers:

pulsectl login --token <enrollment-token>
pulsectl login --oidc-token <token> --tenant <tenant-id>

Verify operation#

Run:

pulsectl status

The status card shows these rows:

RowMeaning
AccountThe signed-in email and organisation, or not logged in with a hint to run pulsectl login
TunnelThe device’s tunnel IP and traffic counters
PostureThe last posture check result, when posture is configured
ExitExit-node region and state, when exit routing is in use
SessionHow long the current session has been up
Policysynced and how long ago the last policy sync happened

Then open Network → Devices in the Console. The row for this hostname should show Online under Connection. Other chips mean:

ChipMeaning
PendingApproved, but the agent has not registered yet
OnlineHeartbeat received within the last 4 minutes
Tunnel downHeartbeating, but the agent reports the tunnel disconnected
Recently seenLast heartbeat between 4 and 10 minutes ago
OfflineNo recent heartbeat
Blocked, Archived, RevokedLifecycle states set by an operator; see Devices

Device drawer for a Linux laptop showing Connection, Platform, Version and Tunnel IP

The device drawer for a Linux laptop. Check Connection, Version and Tunnel IP here after pulsectl status.

Finally test a service that an Allow policy grants to you. An Online agent does not imply access. The service must exist, the policy must include your user, group or device, the policy’s gateway scope must include the serving gateway, and an enforcing posture policy must not have stripped your routes.

Useful commands#

CommandPurpose
pulsectl up / pulsectl downConnect or disconnect the tunnel
pulsectl refreshForce a policy re-sync after an admin changes access
pulsectl gatewaysList gateways and peers the agent knows about
pulsectl logs --tail 200Show recent agent logs; add --follow to stream
pulsectl diagnosticsExport a support bundle (alias pulsectl diag)
pulsectl accounts listShow enrolled accounts; switch and remove take an id
pulsectl logoutSign out the active account
pulsectl helpList every command

Troubleshooting#

  • pulsectl cannot reach the daemon. Check the service: systemctl status pulseha-agent. Start it with sudo systemctl start pulseha-agent.
  • No URL and code appear. Make sure the host can reach the control plane over HTTPS, then run pulsectl login again.
  • Browser says the code is invalid or expired. Codes are single-use and expire after 15 minutes. Start again from the terminal.
  • Browser reports the device limit. You already have 5 devices in this organisation. Ask an admin to revoke one, or re-enrol an existing device of yours, which reuses its record.
  • Console shows Pending for a long time. Check pulsectl status for Account. If it says not logged in, the approval did not complete; run pulsectl login again.
  • Online but the application fails. Run Policy simulation for your user and the service, then check Audit for the denial.

To remove the agent, run sudo apt remove pulseha-agent or sudo dnf remove pulseha-agent. The pre-remove step stops and disables the service.