boltarr

Using Boltarr

A practical guide to operating Boltarr day-to-day. For installation, see the README.

All addresses below (192.168.1.x, ntfy.example.com, etc.) are examples — substitute your own.


Contents

  1. First run
  2. Subnets & scanning
  3. Scheduled scans
  4. Change tracking & alerts
  5. Host liveness (offline/online)
  6. Timezone
  7. Topology view
  8. Hosts
  9. Search & export
  10. Services
  11. Service monitor (uptime)
  12. Notifications (ntfy)
  13. Public status page
  14. SSH key management
  15. AI assistant
  16. Login & security
  17. Backup & restore
  18. View levels

For every feature in more detail, see the Boltarr wiki.


First run

Open Boltarr at http://<your-host>:12100. On a new install it first asks you to create your admin login (or Skip for now — set it later in Settings); see Login & security.

The left sidebar holds the main pages — Topology, Services, Hosts, Subnets, Scans, SSH Keys — and the ⚙ Settings button at the bottom. Settings is a page with tabs (General, Alerts, Monitoring, Status page, AI, Login & Security, Data); change anything and a bar at the bottom offers Undo and Save. The top bar has the search box and 💬 Chat. On a phone the main pages are in a bar at the bottom.

Nothing is scanned yet. Start by adding a subnet.


Subnets & scanning

Add a subnet: open ⊞ Subnets, click + Add subnet and enter a name and a CIDR (e.g. 192.168.1.0/24), plus the DHCP pool if you have one. Each subnet row shows:

The Scans page has four sub-tabs: Run · Schedules · Scan Log · Changes.

Run is a visual nmap builder. Pick a target subnet and a scan profile, then tune the options — ports (none/top-1000/top-N/all/custom range), service & version detection (-sV), OS detection (-O), timing (T0–T5), skip host discovery (-Pn), UDP (-sU), and NSE scripts — with a live command preview. Save any combination as a reusable custom profile. Built-in profiles: Quick (discovery only), Standard (top-1000 + version/OS), Full (all ports). Time limit per host (default 15 minutes, 0 = no limit) skips a host that takes too long and leaves its ports as they were. Scan options are checked before they reach nmap; anything nmap doesn’t expect is refused with a message naming the setting.

Scans never overlap: a second scan waits in a queue.

Scan Log shows every run with live progress bars and elapsed timers while running, the duration and timestamp when done, and skipped runs with their reason. Scheduled runs are badged with the schedule name. A failed scan shows nmap’s own words in red; a scan where some hosts timed out shows completed with problems. Old runs are cleaned up after 90 days.

Probe a single host: from a host’s detail panel you can re-probe just that host — useful to refresh its open ports or pick up a newly-found MAC address. Once a scan finds a host’s MAC, the host is marked scanned (vs manual).

Static vs DHCP: set a subnet’s DHCP pool range (edit a subnet via the ✎ pencil) so hosts inside it are classified dynamic and those outside static. You can override a host’s classification in its edit dialog. Manually-added hosts are tagged manual until a scan confirms them.

DHCP warnings: with a pool set, Boltarr flags a host marked static whose IP is inside the pool, an important device (router, switch, server, NAS, printer, a host with monitored services…) on a pool address, and a pool 90% or more full. You see a ⚠ next to the host’s type, an amber DHCP pool N% full chip on the Hosts toolbar, and a ⚠ DHCP warnings filter. Has a DHCP reservation inside the pool? Use Don’t warn about this host.


Scheduled scans

The Scans → Schedules sub-tab runs scans for you automatically. Findings flow into Change tracking and alerts just like a manual scan.

Each schedule has:

Each row shows an enable/disable switch, last run and computed next run (absolute + relative, e.g. “Aug 1, 3:00 AM · in 6h”), plus Run now, edit and delete. Times are interpreted in your configured timezone. If a schedule comes due while a scan of that subnet is still running, the run is skipped (and logged in Scan Log) so scans never stack. Repeating schedules keep their clock time across daylight-saving changes, and a missed run is caught up within 5 minutes.


Change tracking & alerts

Every scan is diffed against the last known state. Settings → Monitoring → Changes history controls what’s recorded (new hosts, opened/closed ports, MAC/hostname changes, offline/online) and how long to keep it (retention days). Recorded changes show in the Scans → Changes feed and per-host Changes tab; click a row to jump to that host.

Settings → Alerts → Device & network alerts turns recorded changes into ntfy notifications, delivered as a per-scan summary and/or a daily digest at a time you set. Use “Alert for” to scope every alert type by host classification — Static / Dynamic / All (unknown-classified hosts never alert). This only controls the push; the Changes feed always keeps everything. Per-host opt-outs (no-MAC-alert, no-offline-alert) still apply, and all alerts respect quiet hours. Attach device MAC adds each host’s MAC to alerts (offline/online, scan summary, digest) — handy for spotting a roaming device that keeps its MAC while its IP changes across access points.

The daily digest can also list monitored-service outages (Include service outages), DHCP warnings, and an optional short AI summary at the top (Add a short AI summary to the digest, off by default). Preview digest shows what it would say right now; nothing is sent.

“Port closed” is only recorded for ports a scan actually covered, so a shallow scan never false-flags a deeper scan’s ports.


Host liveness (offline/online)

A light background ping sweep (nmap -sn) marks each known host online or offline — the coloured dot next to each IP in the Hosts table (green online / red offline / grey unknown). A host goes offline after a few consecutive missed sweeps and back online on the first response, so brief blips don’t false-alarm.

Configure it in Settings → Monitoring → Device up/down (enable, sweep interval, offline-after threshold). Offline/online transitions are recorded as changes and — for static hosts, unless opted out — fire an immediate ntfy alert. During quiet hours they are sent together as one summary when quiet hours end. First activation is silent (no alert storm); alerts only fire on a real later transition. If a subnet’s sweep fails or runs too long, that round is skipped instead of marking every host there offline.

Host uptime. A host’s panel (Info tab → Liveness) shows its current up/down plus 24h / 7d / 30d uptime % and recent outages, built from the same up/down history — the host equivalent of the service uptime view.


Timezone

Settings → General → Timezone sets an IANA timezone (e.g. Europe/London). It drives all time-of-day logic — schedule fire times, quiet hours, the daily digest — and how times are displayed throughout the app. Leave it as Server default to use the server’s own clock (UTC in most containers). Set it to your local zone so “03:00” means 3 AM where you are. With no timezone set, the AI chat says its times are UTC.


Topology view

The Topology tab is an interactive graph of your network (Cytoscape).


Hosts

The Hosts page has two views: List and IP History.

List is a sortable, filterable table of every discovered or manually-added device. Columns ▾ shows/hides columns; 📌 Pin keeps one visible on narrow screens (others hide by themselves when there’s no room). Click a row to open the host detail panel, with tabs for Info, Links, Ports, Services, Analysis, SSH and Changes. The panel remembers your tab when you switch hosts.

IP History lists every static-range IP (outside the DHCP pool) as In use / Recent / Stale / Gone / Never seen, so you can tell which addresses are free. Settings → Monitoring → IP History sets when an unseen IP reads as stale (default 30 days) or gone (default 60).

From the detail panel you can:


Search & export

Search: the box in the top bar (/ or Ctrl+K; 🔍 on phones) finds hosts and services as you type: IP, alias IPs, hostname, MAC (with or without separators), vendor, type, OS, notes, open-port services, service name, port and URL. Pick a result to open it. See all N results (or Shift+Enter) opens a Search page with every match. The Hosts and Services filter boxes use the same matching.

Export: ⤓ Export ▾ on Hosts, Services and IP History downloads the rows you see (search, filters and sort applied) as CSV or JSON, with every column, hidden ones included. The CSV opens cleanly in Excel or Google Sheets.


Services

The Services tab tracks the things running on your hosts (web apps, databases, media servers, etc.). It has two sub-tabs:

Add a service: click + Service, pick the host it runs on, and fill in name, port, URL, etc. A container quick-pick lets you attach services to container hosts fast, and ⊕ Bulk imports many container services at once.

Nested containers: the “runs on” dropdown includes container hosts (grouped separately), so you can register services that live inside a container that itself runs on another host.

Dependencies: from a service’s ⊕ Dependencies menu, tag which other services it depends on. These render as arrows in the services topology.

Service detail panel (click any service row) lets you edit everything, set its live-check status, toggle Monitor and Public status page, and view its uptime.


Service monitor (uptime)

Boltarr can actively watch a service and tell you when it goes down — like a built-in Uptime-Kuma.

Turn it on: open a service’s detail panel and tick Monitor. It’s off by default, so you only watch the services you care about.

Alerts are configured under Settings → Alerts (below).


Notifications (ntfy)

Boltarr sends push notifications via ntfy — the public ntfy.sh or your own self-hosted server.

Set up in ⚙ Settings → Alerts → Where alerts go (ntfy):

Reliable delivery: on a self-hosted ntfy, enable Instant Delivery for the topic in the ntfy app and exempt the app from battery optimization — otherwise Android may drop background pushes.

Down / recovery alerts: once a monitored service is down for longer than the “Alert after service down for N minutes” grace period (default 5), you get a down alert; when it recovers, a recovery alert with how long it was down. The grace period stops brief blips from nagging you. 0 = alert immediately.

Quiet hours: tick Quiet hours and set a from–to window (your local time). During it, alerts are held — but anything still down when the window ends alerts you then, so you wake up to what’s actually broken instead of a 3am buzz or a silent night. Devices going offline or online and services coming back are sent together in one summary.

Delivery: an alert counts as sent only once ntfy accepts it; failures are retried for a few rounds, and Settings shows the last notification error.


Public status page

Boltarr can feed a separate, public status page — showing your users which services are up — without exposing Boltarr itself. Boltarr only ever pushes a sanitized summary (public name, up/down, uptime, ticks — no IPs, ports, or internal detail) one-way over your LAN to a small separate status app.

The status app ships with Boltarr in ../statuspage/ — a tiny container you run on a separate host. See its README to deploy it (copy .env.example → .env, set a token, docker compose up -d). This section covers the Boltarr side (marking services public and configuring the push).

The page has up to three sections: Services, Hosts, and Networking (router/AP/switch/firewall gear) — each only shown when it has something public.

1. Mark services public. In a service’s detail panel, tick Public status page and optionally set a Public name (what strangers see, e.g. “Photos” instead of an internal hostname). Only services that are both monitored and public appear.

1b. Mark hosts public. In a host’s Edit dialog, tick Show on public status page and set a Public name. The host’s up/down + uptime appears on the page (under Networking if its device type is router/gateway/switch/ unmanaged-switch/firewall/AP, otherwise under Hosts). As with services, only the public name, status, uptime and ticks are pushed — never the IP.

2. Configure the push in ⚙ Settings → Status page:

Changing the Status app URL while a token is saved? See Saved secrets: type the token again or tick Send my saved status page token to this new address.

Boltarr pushes on any status change plus a heartbeat at least every ~60s (so the page stays fresh even if you lengthen the probe interval). The payload per item is: public name, up/down, uptime %, and tick bars for 1h / 24h / 7d / 30d, plus a sanitized incident list.

Security: the push travels only over your LAN. If you put the status app behind a reverse proxy for the public subdomain, block its receive path (e.g. deny /push) so the internet can’t post fake statuses — the LAN push bypasses the proxy and keeps working.

Status-page admin panel

The status app has its own admin panel — log in from the page (set STATUS_ADMIN_PASSWORD in the status app’s .env). It’s cookie-session + CSRF protected and rate-limits logins, so it’s safe to expose. Logged in, you get:


SSH key management

Boltarr can act as a small registry of SSH public keys and which hosts/users they should have access to.


AI assistant

AI is optional. Set it up in ⚙ Settings → AI: Provider (Ollama, OpenAI-compatible, or Anthropic), Base URL, API Key, Default Model, Timeout / Long timeout, and for Ollama Context (tokens). ⚡ Test AI checks the connection. Environment variables (LLM_*) override these.

With Ollama nothing leaves your network; with an online provider the network notes go to that provider.


Login & security


Backup & restore

Everything is in ⚙ Settings → Data. Boltarr’s data lives in data/ (boltarr.db + config.yaml).

Bulk delete: the Hosts and Services tables have a checkbox column + Select all + Delete selected for clearing many at once.

From a script: GET /api/backup downloads an unprotected backup; POST /api/restore (with the X-Boltarr: 1 header) restores in one step.

Mount ./data as a Docker volume to persist across container restarts (the provided compose files do this automatically).


View levels

Pick how much Boltarr shows: Basic (the essentials: what’s on my network, and is it working?), Intermediate (adds tools for running a homelab: schedules, hierarchy, status page) or Advanced (everything, with every option). Switch under View at the bottom of the sidebar (☰ on a phone) or in Settings → General. Each browser keeps its own level.

The level only changes what you see; everything keeps working the same. New installs start on Basic, upgrades on Advanced (so nothing moves). Things you use always show, with a small grey tag; rarer options sit under More options; and search lists anything your level hides under Features, opening it for that visit. See the wiki’s View Levels page.