Enroll a gateway
Install and connect a Linux gateway beside private applications.
A gateway is the Linux host that sits next to your private applications and enforces access policy for them. Enrolling one is a single command that the Console generates for you. Use this page for your first gateway and for every one after it.
Prerequisites#
- The owner or admin role, or a custom role with
gateways.create. Without it, Add Gateway shows You don’t have permission to create gateways. Contact your administrator for access. - A Linux host with
sudo, outbound HTTPS to the control plane, and network reachability to the applications it will serve. Gateway enrollment is Linux-only; there is no macOS or Windows gateway. - A shell on that host. The command is designed to be pasted over SSH.
Enrol#
-
Open Network → Gateways → Add Gateway. Add Gateway is also on the Overview quick actions.
-
The page mints a code straight away. Under 1 Install command you see a panel titled Install & enroll (one command) with the note that it is for a Linux host with
sudoand enrolls automatically. The command has this shape:curl -fsSL https://get.pulseha.com/install-gateway.sh | sudo bash -s -- -y --code phgw_...Beneath it the page reads Single-use code with its expiry time.

The Install command panel. Copy takes the whole line, including the code, and Replace code mints a new one.
- Choose Copy and paste the command into a root shell on the host. The
-yflag skips the installer’s confirmation prompt. The installer installs the package, enrolls the gateway, then turns on and starts thepulseha-gatewayservice. It waits for the service to stay up and ends by reporting whether the gateway is running. If something went wrong, the summary says what and prints the commands to run next. - Leave the Console page open. Under 2 Connect, the panel reads Waiting for your gateway to check in and polls the gateway list for you. No manual refresh or extra
systemctlstep is needed. If nothing has enrolled after 10 minutes, the panel suggests checking the installer output on the host.

The Connect panel while it polls the gateway list. It updates on its own once the host reports in.
- Watch the panel change:
- Gateway registered: <name>, with It authenticated successfully. Waiting for the service to report online. The code was redeemed and the gateway record exists.
- Gateway connected: <name>, with the region it checked in from and two links: View gateway and Publish a service.

The connected state names the gateway and offers the two natural next steps.
Installer exit codes#
The installer’s exit status matches its summary, so scripts and provisioning tools can branch on it:
| Code | Meaning |
|---|---|
0 | Installed. With a code, the gateway is enrolled and the service is running. Also 0 when no code was given or --no-start was passed. |
1 | Installation failed. Nothing usable was installed. |
2 | Invalid option. Nothing was attempted. |
3 | Installed, but enrollment failed. The service was left stopped. |
4 | Installed and enrolled, but the pulseha-gateway service did not stay up, or the host has no systemd. |
To enroll without starting the service, add --no-start to the command. Start it when ready:
sudo systemctl enable --now pulseha-gateway
The gateway is named after the host’s hostname unless the installer was given a name. If no name is available it is called Gateway- followed by the first characters of the code.
About the enroll code#
- The Console mints the code with a 24-hour lifetime. The control plane caps any requested lifetime at 168 hours.
- It is single-use. Once a host redeems it, a second redemption fails with code has already been used.
- Replace code revokes the current code and mints a new one. Revoke code cancels it without replacement.
- Leaving the page does not revoke the code. It stays valid until it is used, revoked or expires.
- Minting and revoking are recorded in the audit log as
gateway_enroll_code.createdandgateway_enroll_code.revoked.
If the page shows Couldn’t prepare the install command, choose Try again. The detail line carries the control plane’s error.
Fallback: device-code login#
If you installed the package without a code, run this on the gateway host:
sudo pulseha-gateway login
It prints a code. Approve it on the Console’s Authorize Gateway page (console.pulseha.com/device?type=gateway). Approving a gateway code needs the gateways.create permission as well as devices.create.
Run login with sudo. On gateway 2.20.0 or later, login without sudo on a host installed from the package stops with exit code 5 before using the code.
Re-enroll a gateway#
login on a gateway that is already enrolled changes nothing and exits 3, so running the install command twice is safe. To replace the enrollment, for example after the gateway was removed in the console, mint a new code. On gateway 2.20.0 or later (check with pulseha-gateway version --short), run:
sudo pulseha-gateway login --force --code phgw_...
The gateway backs up its current enrollment first. If the new code is refused, the old enrollment is put back and the service started again.
On an older gateway, remove the enrollment and enroll again. There is no backup: if the new code is refused, the gateway stays unenrolled until you enroll it with another code.
sudo pulseha-gateway logout --force
sudo pulseha-gateway login --code phgw_...
What you should see#
Network → Gateways lists the new gateway with a Status chip:
| Status | Meaning |
|---|---|
| Online | Heartbeat received within the last 90 seconds |
| Degraded | Heartbeating, but the gateway reports a problem |
| Offline | No heartbeat recently; the control plane marks stale gateways offline after about 5 minutes |
| Unknown | No valid last-seen time yet |
The page filters are All, Online, Degraded and Offline. An empty organisation shows No gateways yet. Use Add Gateway above to enroll your first node.

The Gateways list. The Status chip is what to check first after enrolling a host.
Next steps#
- Publish a service and assign it to this gateway under Gateway Assignment.
- Create an access policy that names the service and includes the gateway, either through All tenant gateways or by selecting it.
- Optional: open the gateway’s Edit gateway action. Under Exit Node, turn on Enable Exit Node and choose Save Changes to use the host for internet egress, then add an egress policy. See Exit nodes.
- Optional: add LAN networks behind the gateway (Add Network, with a Name and CIDR such as
10.1.0.0/24) only if you need site-to-site routing.
Troubleshooting#
| Symptom | What to check |
|---|---|
| Installer reports invalid code or invalid code format | The command was edited or truncated when pasting. Copy it again with Copy. |
| Installer reports code has expired | More than 24 hours passed. Choose Replace code and run the new command. |
| Installer reports code has been revoked | Someone chose Revoke code or Replace code. Use the current command on the page. |
| Installer reports code has already been used | Each code enrols one host. Mint a new code for each gateway. |
| Installer reports tenant_suspended | The organisation is suspended. Contact Support. |
| Panel stays on Waiting for your gateway to check in | The install has not finished or the host cannot reach the control plane. Read the installer output on the host and check outbound HTTPS. The panel shows still retrying if its own polling hits an error. |
| Panel stays on Gateway registered | The code was redeemed but the service has not come up. After 3 minutes the panel shows the commands to run on the host: sudo systemctl status pulseha-gateway and sudo journalctl -u pulseha-gateway -n 50. sudo pulseha-gateway doctor checks the host; from version 2.20.0 it prints a fix for each problem. |
| Installer says enrollment failed (exit 3) | The host is not enrolled and the service was left stopped. Choose Replace code and run the new command. Codes are single-use. |
| Installer says the service is not running (exit 4) | The gateway is enrolled, so no new code is needed. Read the journal lines the installer printed, then run sudo systemctl status pulseha-gateway, sudo journalctl -u pulseha-gateway -n 50 and sudo pulseha-gateway doctor. Once the cause is fixed, run sudo systemctl enable --now pulseha-gateway. |
| Gateway shows Offline later | Heartbeats stopped. Check the host is up and has connectivity. |
| Gateway was removed | Remove Gateway cannot be undone. Services that referenced it show a revoked-gateway warning; edit each one and save to clear it. |