Distribution & reachability¶

Under Admin → Engine & Collection → Distribution you configure two things:

Where agents and collectors fetch their binaries and updates from (the three distribution modes).
Which URLs your machines use to reach the server (the server URLs — including the base for the optional agent gateway).

The three distribution modes¶

integrated (default)¶

The Vesana server itself serves the binaries — at https://<your-server>/agent/install.sh, /collector/install.sh and so on. The installer and auto-update fetch everything straight from the server.

Distribution URL: not needed — it is your own server URL.
"Test distribution server": checks that the binaries are present locally on the server. It does not test vesana.org — that is the vendor website, not a distribution source.
The right choice for the vast majority of self-hosted installations.

external¶

The Vesana server is reachable internally only (e.g. via VPN), but customer VMs still need to install and update. Binaries then come from a separate, reachable distribution server.

Distribution URL: required — the publicly reachable URL of the distribution server (layout /{dist}/vX.Y.Z/…).
"Test distribution server": probes that URL over HTTP.

offline_only¶

No reachable server at all. Binaries are distributed as a tar.gz/zip bundle (USB, file share) and unpacked locally. Auto-updates are off; updating means shipping a new bundle.

Create a bundle: the Offline bundle tab when adding an agent/collector.
"Test distribution server": not applicable (there is no server to test).

The server URLs¶

The same page has two URL fields that are easy to confuse:

Field	Who uses it?	When to set it?
Agent server URL (public)	Agents, collectors, install scripts, the pre-filled Windows installer	When machines reach the server at a different address than your browser — especially with the agent gateway enabled (then including the port, e.g. `https://server.example.com:8443`). Empty = Vesana derives the URL from your browser address.
Internal server URL	Install snippets in the `external`/`offline_only` modes	When customer VMs reach the (internal) server via VPN/site-to-site under an internal address.

The agent server URL ends up everywhere a machine gets provisioned: in the Linux/Windows install commands, in the downloaded setup.exe (the URL is patched into the binary server-side) and in offline bundles.

Test reachability (from the server)

Next to the field there is a test button: the server calls its own agent server URL (GET /health). This exposes typos, wrong ports and firewall issues immediately — before you migrate a single agent. TLS verification is deliberately disabled so the test also works with a self-signed certificate.

Agent gateway: locking down the web UI¶

Since v1.9.93. When agents and collectors report in from customer networks over the internet, your server must be publicly reachable. Without further measures that also exposes the entire web UI: login page, management API, everything.

The agent gateway solves this: a separate port that serves machine endpoints only — agent configuration, heartbeats, result ingestion, installers and binary downloads. No login page, no frontend, no management or admin API. In your firewall you only open the gateway port and restrict the UI port to internal networks or VPN. Customer machines still need outbound HTTPS only — nothing changes there.

Enabling it — right in the UI (since v1.9.95)¶

On the same page (Admin → Engine & Collection → Distribution) you will find the "Agent gateway" card: enter a port (default 8443) → "Enable gateway" — done. Vesana persists the setting (it survives updates and restarts) and starts the gateway container. If the start fails — e.g. because the port is already taken on the host — the setting is rolled back automatically and the error is shown right in the card. Disabling works via the same button. No manual server access required.

Alternative: manually via .env (headless/automation, v1.9.93–94 or without the updater)

Add two lines to your installation's .env and restart the stack:

COMPOSE_PROFILES=agent-gateway     # combine profiles: "ai,agent-gateway"
AGENT_GATEWAY_PORT=8443            # host port, freely choosable (default 8443)

docker compose -f docker-compose.prod.yml up -d

The gateway container uses the same image and the same TLS certificates as the main web server. Smoke test:

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

Both ports are freely choosable¶

Only one public IP, and agents should use standard port 443? Just swap:

HTTPS_PORT=8443           # web UI moves to 8443 (internal only)
AGENT_GATEWAY_PORT=443    # agents use the standard port

Migrating an existing installation — order matters!¶

The UI port keeps serving everything (including the agent endpoints). Your agents only break if you migrate them and then close the firewall. So strictly in this order:

Enable the gateway (see above) and verify with the three curl probes.
Set the agent server URL (see server URLs) to the gateway URL, e.g. https://server.example.com:8443 — and click the reachability test. From now on new agents automatically get the right URL.
Migrate the existing fleet: Admin → Instance & Maintenance → Server URLs — switch agents and collectors to the gateway URL. Every machine picks up the new URL on its next heartbeat and rewrites its own configuration.
Control phase: watch the diagnostics log (category "Connection") until all machines come in via the new path. Do not proceed earlier.
Only now: firewall — UI port (HTTPS_PORT) internal/VPN only, gateway port public.

Don't lock yourself out

If you close the firewall before the fleet is migrated, all agents lose their connection (status "No data"). This is always reversible — reopening the firewall is enough — but it costs monitoring gaps. Stick to the order.

Rollback¶

At any time, without an update or restart: reopen the firewall, or switch the server URL back via the same migration page.

What deliberately does NOT go through the gateway¶

Area	Why	Consequence
Public status pages	human endpoint, needs the frontend	With a locked-down UI port they are not publicly reachable — if needed, open the UI port selectively for the required sources
Mobile app	talks to the regular user API	Technicians use the app via VPN / the internal URL
APK download (`/downloads/`)	human artifact	download via the web UI

The Windows installer (setup.exe) and the install scripts, however, are deliberately available on the gateway — that is provisioning of customer machines, which is exactly what the port is for. You can hand the download link directly to a customer.

Troubleshooting¶

Symptom	Cause / fix
`curl https://server:8443/health` → timeout	Firewall/NAT: gateway port not open, or container not running (`docker compose ps`)
Reachability test in the admin UI fails, `curl` from the customer network works	The server itself cannot reach its own public URL (hairpin NAT). The test is a strong indicator, but the customer site is the ground truth
Agent stays on "No data" after migration	Check agent.log on the machine (`C:\ProgramData\Vesana\Agent\agent.log` or `journalctl -u vesana-agent`): does it show the new URL? Timeout → firewall; 401 → token; TLS error → certificate/`insecure_skip_verify`
Login page visible on the gateway port	Must never happen — check the role: the container needs `VESANA_NGINX_ROLE=gateway` (set automatically with the standard compose)

Self-signed certificate?¶

If your server does not (yet) have a public certificate, enable the option "Server uses a self-signed certificate" when adding an agent/collector — the installer then skips TLS verification. For publicly reachable servers, better set up a real certificate (e.g. Let's Encrypt). The gateway automatically uses the same certificates as the web UI.