Skip to content

Agent gateway — locking down the web UI

The agent gateway is an optional, separate port that serves only machine endpoints: agent config/heartbeat, collector config/discovery, result ingestion, installer and binary downloads. No login, no frontend, no admin/user API, no updater, no WebSockets — everything else gets a 404 there.

What it's for

If agents/collectors report in from customer networks over the internet, the server has to be publicly reachable. Without a gateway, the entire web UI is necessarily reachable along with it. With the gateway, you expose only the gateway port publicly and restrict the UI port to internal networks/VPN via firewall — customer machines still only need outbound HTTPS.

The gateway is off by default — most installations don't need it.

Activating it

Everything runs through Admin → Instance & maintenance → Agent connection (the same page used for changing the server address):

  1. In the „Agent gateway" section, flip the toggle. Default port is 8443, changeable via „Change port".
  2. The server starts the gateway container and fills in the matching server address automatically. If the start fails (e.g. port already in use), the setting is rolled back automatically and the error shown.

  3. Function test from any machine:

    curl -k https://<server>:8443/health        # → {"status":"ok",...}
curl -k https://<server>:8443/               # → 404 (no frontend)
curl -k https://<server>:8443/api/v1/auth/login   # → 404 (no login)

Deactivating uses the same toggle — reversible, without affecting the running fleet.

Migrating an existing installation — order is mandatory

The UI port keeps serving all endpoints, including agent/collector ones — nothing breaks just from activating the gateway. Only the combination of migration and firewall makes the difference. So, in this order:

  1. Activate the gateway (see above) + run the function test.
  2. Set the server address to the gateway address (e.g. https://server.example.com:8443) — on the same page. From now on all install commands and the pre-filled Windows installer show the gateway address; new machines land correctly from the start.
  3. Migrate the existing fleet: test one device first, then „Migrate all" — see Changing the server URL.
  4. Verification phase: watch until no machine reports in via the old path anymore. Don't proceed early.
  5. Only now: firewall — restrict the UI port to internal/VPN, leave the gateway port public.

Rollback is possible at any time: reopen the firewall or set the address back to the old value — either way, no update, no restart required.

Two separate ports, freely chosen

Both ports can be assigned freely — for example, UI internally on an alternate port, agents on the standard port 443:

HTTPS_PORT=8443           # Web UI
AGENT_GATEWAY_PORT=443    # Agent gateway takes the standard port

Limits (deliberate)

  • Public status pages run on the UI side. Locking down the UI port also makes status pages unreachable — if you need them, open the UI port specifically for the required sources.
  • Installed web app on the phone is the web UI → runs on the UI side (use internal/VPN).
  • Windows installer + install scripts live on the gateway deliberately — that's provisioning customer machines, exactly the port's purpose.

Next