Getting Started

Welcome to StacksAtlas. This guide covers portable (free) and Business (always-on) first runs.

1. Choosing a Tier

Tier	Price	Best for
Free (portable)	$0	Try on Windows, Mac, or Docker. Unlimited discovery per session. No license key, no device cap.
Business	$40 one-time	Persistent always-on appliance. One $40 license per machine. Hub fleet optional.

Two ways to run StacksAtlas. Free means download, scan, and leave when you are done. Business means install it so it keeps watching in the background on a PC, Mac, or NAS.

How you run it	Free	Business
Windows: download and run (no install)
macOS: download and run (no install)
Docker / Linux: try for a session
Windows: install as always-on service
macOS: install as always-on background app
Docker / NAS: always-on appliance

Unlimited device discovery on all tiers. Business adds persistence and fleet. See Site identity & portable. Download links: Installation.

Portable first run (no license)

Download portable for your platform from the home page.
Open http://127.0.0.1:5000 (Windows/Docker) or http://127.0.0.1:5050 (macOS).
Complete onboarding (network scope → scan). No admin account or license key required.
When finished: Close & remove portable data (tray/avatar menu) or docker compose -f docker-compose.portable.yml down -v.

Business first run (license required)

1. Initial Launch

Windows MSI / Mac Install / Docker appliance: browser opens HTTP-first onboarding (http://127.0.0.1:5000 or :5050 on Mac).
Activate your Business license in Settings → Licensing after install if not prompted during onboarding.

2. Create Administrator

On first appliance run:

Email and Password for the primary admin (PBKDF2-hashed locally).
Click Create Account.

3. Activate License

Navigate to Settings → LICENSING.
Paste the license key from your Lemon Squeezy email.
One-time validation locks to this machine's Hardware ID (HWID).

Managing Your License (Self-Service)

One Business license key per appliance: Hub brain, standalone site, or each enrolled Node. To move hardware:

Lemon Squeezy order email → View Order → Licenses → Deactivate.
Activate the same key on the new machine.

Multi-site fleet (Business Hub)

One standalone Business appliance is enough for a single site. For multiple locations (branch offices, client sites, or remote networks over Tailscale):

Designate one install as the Central Hub (fleet dashboard).
Install Business on each site that should scan a local LAN and enroll as an edge Node.
Use Direct Network enrollment strings on routable LANs, or Tailscale (Remote) strings for sites that join via Tailscale.

Full walkthrough: Hub & Fleet Federation →

Map the topology (after first scan)

Discovery fills inventory; it does not know switch ports or Wi-Fi associations by itself. After a sweep:

Open a device → Overview → Network link.
Set Mode (Ethernet / Wi-Fi / Fiber), optional Port / SSID, and Uplink (parent switch or AP).
Check the Dashboard topology map. Devices with an uplink nest under that parent; others stay under the gateway until mapped.

Full field list, bulk tools, and group-by-uplink: Device inventory → Network link.

StacksAtlas + OpenAVC stack (Business, optional)

For room control alongside network monitoring, run OpenAVC on the same site as your StacksAtlas Node. StacksAtlas discovers and inventories devices; OpenAVC runs drivers and macros. Link them from Settings → OPENAVC on the Node (not the Hub), then use the device Controls tab.

Monitor + control pair

Install OpenAVC on the site LAN, enable the integration in StacksAtlas, then follow the step-by-step Control Bridge guide: Integrations → OpenAVC Control Bridge. Requires a permanent Business install (not portable try mode).

Onboarding wizard (`/onboarding`)

First launch opens the onboarding wizard instead of the legacy setup page.

Portable path (no license)

Network scope: confirm adapter and subnet (auto-detected when possible).
Scan: discovery begins immediately.
Optional TLS trust step: enable HTTPS on port 5001 if you want a trusted lock icon in the browser.

No admin account or license key is required for portable.

Business path

License: paste your Lemon Squeezy key (or skip if activating later in Settings).
Plan / role: standalone appliance vs Central Hub (Hub requires Business).
Site metadata: friendly site name and location fields used in fleet reporting.
Network scope: same adapter and subnet flow as portable.
Administrator account: create the local admin user (PBKDF2-hashed locally).

If the Hub database is still initializing, the wizard retries automatically instead of failing with a generic error.

4. Define Network Scope

On its first run, StacksAtlas attempts to automatically detect your local subnet (e.g., 192.168.1.0/24) and begins scanning immediately.

4.1 Select Network Adapter

If you have multiple network interfaces (e.g., Ethernet and Wi-Fi), you must ensure the correct one is selected.

Look at the Global Header at the top of the utility.
Click the Network Toggle (showing your current IP and CIDR).
Select the physical adapter connected to the target network.
The system will reflect the new active range instantly.

4.2 Add Additional Subnets

To monitor VLANs or remote subnets that are not on the local interface:

Navigate to Settings → SCANNING.
Click ADD SCOPE.
CIDR: Enter the range for any additional VLANs you wish to monitor (e.g., 10.0.50.0/24).
Optionally bind a NIC and toggle protocol chips (PING, ARP, mDNS, UPnP).
Click COMMIT ENGINE CHANGES.

See the Scan settings guide for engine tuning and Hub fleet push.

Discovery Limitations (Layer-3 / Routed Subnets)

When monitoring subnets that are NOT directly connected to a local adapter, StacksAtlas operates in Layer-3 mode. Note the following limitations:

No MAC Addresses: ARP resolution only works on the local broadcast domain. Remote devices will not show MAC addresses or OUI-based Vendor info.
No Wake-on-LAN: Magic Packets are generally limited to the local subnet.
Identification: The engine will rely more heavily on Service Fingerprinting and mDNS (if mirrored) for classification.

The Discovery Engine runs continuously in the background (Business appliance). Portable runs scans on demand during your session.

5. Dashboard Overview

Navigate back to the Dashboard. You will see devices populate in real-time. For the full CORE DASHBOARD vs GLOBAL FLEET COMMAND breakdown, see the Dashboard guide.

Key Indicators

Status Ring: The colored ring around the device icon indicates Stability.
- Green: 100% Stable
- Orange: <90% (Warning)
- Red: <50% (Critical)
Vendor Icon: Automatically assigned based on the MAC OUI database.
Names: Populated via mDNS/Bonjour if available.

Device Management

Click any row to open the Device Drawer. See Device inventory for every drawer section.

Custom Name: Override the discovered name (e.g., "Lobby Display").
Location: Assign a physical location.
Responsible Party: Assign a user to manage this device.
Diagnostic Tools: Access Path Diagnostics to map network hops or Deep Scan for security analysis.
Remote Power: Use Wake-on-LAN to boot offline machines directly from the drawer.

Your changes are protected by the Human Property Shield and will never be overwritten by future scans.

Installation

Dashboard