Skip to content →
Log in

Deployment

Place gateways and agents for resilient private access.

PulseHA has two things you install: the agent on endpoints and the gateway beside applications. Everything else (control plane, console, Orbit) is hosted. This page covers the deployment patterns those two pieces support, which platforms ship, and what each host needs.

What ships#

ComponentPlatformsInstall
AgentLinux (amd64, .deb and .rpm), Windows (installer), macOS (Apple Silicon and Intel .pkg)Downloads or curl -fsSL https://get.pulseha.com/install-agent.sh | sudo bash on Linux
GatewayLinux only (x86-64 packages)One command generated by Network → Gateways → Add Gateway
iOS and AndroidComing soonnot yet available

The Linux agent authenticates with pulsectl login. Windows and macOS authenticate from the PulseHA app, which opens a browser.

Pattern 1: agents on endpoints, gateway beside private apps#

This is the baseline. Put one gateway in each network that hosts applications you want to publish. The gateway needs:

  • a Linux host with wg, nft and ip installed (the package pulls them in) and net.ipv4.ip_forward=1;
  • outbound HTTPS to gw-api.pulseha.com and api.pulseha.com;
  • inbound UDP 51820 from wherever devices connect, or at least a NAT that hole punching can open;
  • a route to every application it will serve.

The gateway forwards device traffic to applications with source NAT from its LAN interface. Applications see connections from the gateway’s LAN address, so firewall rules on the application side need only allow the gateway. Only traffic matching a compiled access rule is forwarded; the forward chain drops everything else.

Each device talks to control over HTTPS and to gateways over WireGuard. It does not need inbound ports.

Pattern 2: more than one gateway per service#

Assign a service to two or more gateways that can all reach it. Control sends each device a ranked list, and the agent routes the service through one gateway at a time, moving when the active one degrades. The ranking prefers gateways whose health probe for that service passes, then administrative priority, then load, then latency. Configure a health probe on the service so the ranking has real data.

Gateways do not share state with each other for this pattern. Each one independently holds the full peer list and ruleset for the tenant.

Pattern 3: site-to-site#

Site-to-site connects a LAN behind one gateway to a LAN behind another. Add each LAN CIDR on the gateway’s Networks tab, then create a policy under Network → Access → Site-to-Site with a source gateway and network, a destination gateway and network, and an effect. Control adds the destination gateway as a WireGuard peer of the source gateway with the destination CIDRs as allowed IPs, and the destination always adds the source as a peer. Bidirectional policies add the reverse rules.

Current site-to-site policies apply to all protocols and ports. A Masquerade flag on the LAN network NATs remote traffic to the gateway’s LAN address, which avoids adding return routes on the remote LAN. Site-to-site grants nothing to devices; endpoint access still comes from access policies.

Pattern 4: exit node on your own gateway#

Edit a gateway and switch on Enable Exit Node. Then add an egress policy under Network → Access → Egress Policies. The policy’s routing mode is Required, Optional or Disallowed; the selection strategy is Auto or Pinned to specific gateways or regions. With a Required policy and no eligible gateway available, the agent fails closed unless the policy allows fail-open.

On the device, exit mode adds 0.0.0.0/0 (and ::/0) to the chosen gateway’s allowed IPs, installs split default routes, and adds bypass routes for the gateway endpoint and control plane. The gateway forwards with source NAT. The gateway’s resolver becomes the device’s DNS server, and Secure Web filtering applies to that traffic.

Pattern 5: Orbit public egress#

Orbit gives devices an exit outside your network. Enable it under Network → Orbit → Settings, pick the allowed regions, then set the egress policy’s public path to prefer or require Orbit. The agent brings up a separate tunnel (pulseorbit) to a point of presence using credentials control issues for 7 days, verifies egress works, and only then moves the default route. Region selection follows Orbit routing rules and the device’s location; the agent re-checks its desired region every 5 minutes. Orbit is for internet traffic only; private applications still need a gateway and an access policy.

Sizing and placement notes#

  • Put the gateway on the same network as the application, or on one with a direct route. Every hop between gateway and application is unencrypted by PulseHA.
  • A gateway marks a device peer stale after 5 minutes without a handshake and removes it until the next handshake. This bounds the peer list on a busy gateway to devices that are actually connected.
  • Control publishes configuration to gateways as a complete, versioned snapshot. A gateway that cannot reach control keeps enforcing its last good ruleset.
  • The gateway exposes health on 127.0.0.1:8080/healthz and Prometheus metrics on 127.0.0.1:9090/metrics. Scrape them from the host.

Verify a deployment#

  1. Network → Gateways shows the gateway Online without an Upgrade required chip.
  2. Network → Devices shows each device Online with a current posture state.
  3. Network → Services shows a HEALTHY chip on each probed service.
  4. Network → Access → Access Policies has an Enabled Allow policy covering the device and the service.
  5. On a device, pulsectl gateways shows a recent handshake and the service CIDR under one gateway.
  6. Security → Audit records the resulting access decisions.