Hub & Fleet Federation

Business tier only. Use a Central Hub plus edge Nodes when you need one dashboard for multiple sites (branch offices, client sites, VLANs on different appliances, or remote locations over Tailscale).

This guide walks through roles, licensing, enrollment, and day-two operations using the same labels you see in Settings → Federation in the app.

What you are building

                    ┌─────────────────────┐
                    │   Central Hub       │
                    │   (Fleet dashboard) │
                    │   No local scanning │
                    └──────────┬──────────┘
                               │  Devices & telemetry sync up
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
        ┌───────────┐    ┌───────────┐    ┌───────────┐
        │ Edge Node │    │ Edge Node │    │ Edge Node │
        │ Site A    │    │ Site B    │    │ Site C    │
        │ (scans    │    │ (scans    │    │ (scans    │
        │  local    │    │  local    │    │  local    │
        │  LAN)     │    │  LAN)     │    │  LAN)     │
        └───────────┘    └───────────┘    └───────────┘

The Hub aggregates inventory, alerts, and fleet status. It does not run subnet discovery itself.
Each Node is a full StacksAtlas appliance on a local network. It scans ARP/mDNS/ping on its site and pushes changes to the Hub.
The Node opens an outbound connection to the Hub. You usually do not need inbound port forwarding on the remote site.

Appliance roles

Role	In the UI	What it does
Standalone	Appliance (Standard Node)	Single-site always-on appliance. Local DB, local users, local scans. Use this role before enrolling into a fleet.
Central Hub	Central Hub (Fleet Master)	Fleet command center. Manages enrolled Nodes and unified device view. Does not scan local subnets.
Federated Node	Appliance (Standard Node)	After enrollment: still scans locally and keeps a local database, but syncs inventory to the Hub. Buffers offline and re-syncs when the link returns.

Single site? Install Business once as Standalone. You do not need a Hub.

Multiple sites? Install Business on the Hub machine, enable Hub mode, then install Business on each remote site and enroll as a Node.

Licensing (Business)

Item	Rule
Hub or standalone	One $40 Business license per Central Hub or standalone appliance
Enrolled Nodes	Each site appliance activates its own Business license
Portable (free)	Cannot run Hub mode or enroll into a fleet
Moving hardware	Deactivate in the Lemon Squeezy customer portal, then activate on the new machine

Each Hub and each enrolled site activates its own Business ($40) license. There is no Hub node-slot pack. Federation is orchestration, not a license pool.

See Getting Started → Licensing for activation steps.

Choose your connection type

Scenario	Enrollment string	Requirements
Same LAN or routable IP	Direct Network (LAN)	Node can reach the Hub's IP or hostname on the network (ports below).
Remote site, home lab, client WAN	Tailscale (Remote)	Hub and Node on the same Tailscale tailnet. Tailscale installed on the host running StacksAtlas.

Enrollment strings look like sa-enroll://… and expire in 15 minutes. Generate a fresh string on the Hub if enrollment fails or times out.

Setup: Central Hub (first)

Complete on the machine that will be your fleet dashboard.

Install Business using the MSI, Mac Install, or Docker appliance (not the free portable build).
Activate your Business license in Settings → LICENSING.
Open Settings → Federation.
Set Appliance Role to Central Hub (Fleet Master).
Click Save & Restart. The service restarts in Hub mode.
After restart, return to Settings → Federation. Use Generate enrollment string:
- Direct Network for LAN/routable setups.
- Tailscale (Remote) after you configure Hub Tailscale identity (next section).
Copy the string. You will paste it on each edge Node.

Hub does not scan your LAN

Install at least one enrolled Node on every subnet or site you want discovered. The Hub only displays what Nodes report.

Setup: Edge Node on the same network (LAN)

On each site that should scan a local subnet:

Install Business on a host connected to that site's LAN.
Activate Business on this Node (each enrolled site needs its own $40 license key; the Hub is not a license pool).
Open Settings → Federation. Leave role as Appliance (Standard Node).
Under Sovereign mTLS enrollment, paste the Hub's Direct Network enrollment string.
Enter a Friendly Site Name (required). Optional: Client, Building, Room for reporting columns.
Click enroll. The appliance restarts as a federated Node.
On the Hub, open Settings → Federation and confirm the site appears in Registered Appliances.

Setup: Edge Node at a remote site (Tailscale)

Use this when the Node cannot route to the Hub's LAN IP (different building, client network, homelab over the internet).

On the Hub

In Settings → Federation → Tailscale, note the Hub's MagicDNS name and 100.x tailnet IP (or configure them after Tailscale is running on the Hub host).
Generate a Tailscale (Remote) enrollment string.

On the Node (remote site)

Install Tailscale on the host running StacksAtlas (not inside an isolated Docker bridge unless you use host networking or mount tailscaled.sock).
Join the same tailnet as the Hub (same Tailscale organization). Use a pre-auth key or sign in via the Tailscale app.
In Settings → Federation on the Node:
- Enable Use Tailscale for Hub Connection.
- Enter the Hub MagicDNS hostname and 100.x IP from the Hub's Federation page.
- Click Save & Restart.
Run Test Hub Reachability via Tailscale. A successful probe on port 5002 means mTLS enrollment can complete.
Paste the Hub's Tailscale (Remote) enrollment string under Sovereign mTLS enrollment and enroll.

Match string type to transport

A Tailscale hostname (.ts.net or 100.x) requires the Tailscale toggle on the Node. A LAN string requires it off. The UI warns if they do not match.

Tailscale ACL (optional)

If devices cannot reach each other on the tailnet, allow federation ports between Hub and Nodes:

5001: Web UI and API
5002: mTLS federation sync

Small homelab tailnets often use a simple member-to-member rule on those ports. Tagged fleet ACLs are available in the in-app Tailscale ACL help panel on the Hub Federation tab.

Ports and firewall

Port	Purpose
5000	HTTP web UI on Windows and Docker (first launch)
5050	HTTP web UI on macOS (first launch)
5001	HTTPS UI and API
5002	Federation mTLS sync

The Node initiates outbound connections to the Hub. Open 5001 and 5002 on the Hub host for traffic from your Nodes (LAN or Tailscale).

Windows Hub firewall: the MSI opens 5000 and 5001 only. For federation you must allow inbound TCP 5002 on the Hub (Windows Firewall or your edge firewall) yourself. Without 5002, enrollment and mTLS sync fail even when the UI on 5001 looks fine.

Fleet updates

Hub fleets update through a local update depot, not by every Node polling the public CDN.

Hub admin: Settings → Infrastructure → Software Updates → Stage the channel.
Hub Dashboard / Federation: Notify update or Update now on an online site (Behind chips show drift).
Node admin confirms under Software Updates (or uses that Node's Scheduled apply window if enabled).

The Hub cannot silently force-upgrade a Node. Full UI map, platform matrix, and Docker host commands: Infrastructure → Software updates · Installation → Docker updates.

After enrollment

On the Hub

Fleet / Registered Appliances: online status, device counts, force sync, open remote setup UI.
Devices: inventory from all sites with site name and reporting metadata.
Alerts & webhooks: fleet-wide (Business).

On the Node

Local dashboard still works if the Hub link drops. Discoveries buffer and sync when the connection returns.
Optional identity governance from the Hub (below).

Fleet device lifecycle

Hub and Node admins can move devices between inventory views without losing audit history.

View	Who sees it	Purpose
Active	Hub and Node	Live inventory from ongoing discovery.
Archive	Hub and Node	Devices set aside without deleting history.
Removed from Fleet	Hub (Admin)	Tombstoned devices suppressed from re-discovery until restored.

Archive: hide from the active grid while keeping the record.
Remove from Fleet (Hub, Admin): tombstone the device so rediscovery does not recreate it until you Restore to Fleet.
Hub → Node relay: lifecycle actions on the Hub are sent to the owning Node when online. Changes made on a Node sync up to the Hub.

CSV exports include governance columns for fleet reporting. See Reporting.

Site reset & recovery

After Reset Site on the Hub, the Node wipes local inventory but keeps enrollment. The Hub shows setup_required until the operator completes abbreviated onboarding on that Node (/onboarding). This is normal: the site is enrolled but not yet scanning.

If a Node loses Hub connectivity for an extended period (e.g. Tailscale sleep), local scanning continues and telemetry buffers until the link returns.

Fleet governance (optional)

Hub administrators can push central control to enrolled Nodes.

Identity (users & SSO)

Setting	Effect on the Node
Sync Core User Registry	Hub user accounts replace local account management. Local user create/delete/password reset is locked.
Sync Global SSO Settings	Hub OIDC/LDAP settings are pushed down. Local SSO edits are locked.

When you first enable user sync, the Node may upload existing local users to the Hub (except the built-in emergency admin account). Plan your admin accounts on the Hub before locking remote sites.

Alerts, SIEM, and scan policy

Setting	Where	Effect on the Node
Hub scan policy push	Settings → SCANNING (Hub)	Per-node or broadcast commit writes scan scopes and engine tuning. Offline Nodes apply on next check-in. See Scan settings.
Sync Alert Settings	Hub Dashboard → node governance	Hub SMTP and webhook configuration replaces local alert settings on the Node.
Delegate Alert Dispatch	Hub Dashboard → node governance	Node sends alert email and webhooks through the Hub instead of directly.
Sync SIEM Settings	Hub Dashboard → node governance	Hub syslog/SIEM export settings are pushed to the Node.
Override alert / SIEM settings	Settings → Federation (Node)	Break-glass: Node keeps local SMTP or syslog when Hub governance is enabled.
Force Sync	Hub Dashboard	Manual full policy push to a Node (users, alerts, scan policy as configured).

Reset site vs remove node

Action	When to use	Hub enrollment	Node local data
Reset Site	Refresh inventory for one site; fix a bad scan state	Kept. Node reconnects automatically.	Wiped and rescanned
Delete Node	Permanently remove a site from the fleet	Removed	Hub copy of devices and logs removed
Decouple	Detach from fleet and run standalone again (on the Node)	Removed from Hub	Kept locally

To re-enroll after Delete Node, generate a new enrollment string on the Hub.

Troubleshooting enrollment

Symptom	Things to check
Enrollment string expired	Strings last 15 minutes. Generate a new one on the Hub.
Already enrolled	On the Hub, delete the stale site row or wait until it shows OFFLINE, then enroll again.
Tailscale probe fails	Same tailnet on Hub and Node? ACL allows 5002? Tailscale on the host, not only in a bridge container?
LAN enroll fails	Can the Node ping the Hub IP? Firewall on Hub for 5001/5002? Correct Direct Network string (not Tailscale)?
Hub at node cap	Not applicable. Each site licenses its own appliance.
No devices on Hub	Hub does not scan. Confirm the Node is online and scanning its local adapter/subnets in Settings → SCANNING.

More: Troubleshooting guide · Scan settings · Discovery pipeline · Reporting (site columns)

Infrastructure: Hub depot, notify, scheduled apply
Getting Started: first run and license activation
Installation: MSI, Mac Install, Docker appliance
Integrations: webhooks and API for fleet automation
Security: RBAC and SSO on the Hub

Network control

Users & roles

Hub & Fleet Federation

What you are building

Appliance roles

Licensing (Business)

Choose your connection type

Setup: Central Hub (first)

Setup: Edge Node on the same network (LAN)

Setup: Edge Node at a remote site (Tailscale)

On the Hub

On the Node (remote site)

Tailscale ACL (optional)

Ports and firewall

Fleet updates

After enrollment

On the Hub

On the Node

Fleet device lifecycle

Site reset & recovery

Fleet governance (optional)

Identity (users & SSO)

Alerts, SIEM, and scan policy

Reset site vs remove node

Troubleshooting enrollment

Related documentation