Boltarr

A self-hosted network dashboard for mapping, monitoring, and analyzing your local network. Scan subnets, visualize topology, track devices, manage VLANs, and chat with an AI assistant that knows your network.

Features

• Topology view — interactive Cytoscape.js graph with drag-and-drop layout, VLAN coloring, connection types (wired/wifi/fiber/DAC/virtual)
• Network scanning — nmap-powered host and port discovery
• Device management — add/edit/delete hosts, merge multi-homed devices, annotate with notes
• Services registry — track running services per host with status and URLs
• VLAN management — define VLANs, assign them to connections, visualize on topology
• AI analysis — per-host and network-wide analysis; AI chat assistant with full network context
• AI optional — works without AI; supports Ollama, OpenAI-compatible APIs, and Anthropic

Quick start (Docker)

curl -O https://raw.githubusercontent.com/brq-ae/boltarr/master/docker-compose.yml
docker compose up -d

Open http://localhost:12100

Or if you prefer to clone the full repo:

git clone https://github.com/brq-ae/boltarr.git
cd boltarr
docker compose up -d

With bundled Ollama (local AI)

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

# Pull a model after startup
docker exec boltarr-ollama-1 ollama pull llama3.2

Then open ⚙ AI Settings in the app and set the model to llama3.2.

AI configuration

AI is optional. Configure it from the ⚙ AI Settings button in the sidebar, or via environment variables.

Supported providers

Environment variable configuration (Docker)

# in docker-compose.yml environment section:
LLM_PROVIDER: ollama          # none | ollama | openai | anthropic
LLM_BASE_URL: http://my-ollama:11434
LLM_MODEL: llama3.2
LLM_API_KEY: ""               # only for openai / anthropic
LLM_TIMEOUT: 120
LLM_LONG_TIMEOUT: 600

Env vars override the UI settings when set.

AI chat behind a reverse proxy

If you access Boltarr through a reverse proxy (Nginx Proxy Manager, Caddy, Traefik, etc.) and see errors in the AI chat — especially with larger models — the proxy is likely timing out before the model responds. Increase the proxy timeout for /api/chat to at least 120–300 seconds.

Nginx Proxy Manager: add proxy_read_timeout 300; and proxy_send_timeout 300; as custom Nginx config for the proxy host.

Caddy: add timeouts { read 5m } to the reverse_proxy block.

Config file

Copy data/config.yaml.example to data/config.yaml and edit:

llm:
  provider: openai
  base_url: https://api.openai.com/v1
  api_key: sk-...
  model: gpt-4o

Proxmox / LXC

A ready-made compose file is provided for unprivileged LXC containers:

curl -O https://raw.githubusercontent.com/brq-ae/boltarr/master/docker-compose.lxc.yml
docker compose -f docker-compose.lxc.yml up -d

What's different from the standard compose?

Unprivileged LXC containers cannot load AppArmor profiles into the host kernel, so Docker's default profile fails. The LXC compose file adds:

security_opt:
  - apparmor=unconfined

This is safe because Proxmox applies its own AppArmor profile to the entire LXC, and user-namespace mapping ensures root inside the container has no privileges on the Proxmox host.

LXC pre-requisites (Proxmox UI → your LXC → Options)

• Enable Nesting (nesting=1)
• Enable keyctl (keyctl=1)

Note: Ubuntu LXC templates often ship without curl. If the Docker install script fails immediately, run apt install -y curl first.

Unraid

Install via Community Applications (search boltarr) once the template is listed, or add it manually:

1. In Unraid, go to Docker → Add Container → Template URL
2. Paste:

   https://raw.githubusercontent.com/brq-ae/boltarr/master/templates/unraid.xml
   

3. Set your data path (default: /mnt/user/appdata/boltarr) and optionally fill in AI settings
4. Click Apply

Data persists in the mapped appdata folder. AI is optional — configure it from the ⚙ AI Settings button in the app.

Manual install (without Docker)

Requires Python 3.11+ and nmap.

# Install nmap
sudo apt install nmap       # Debian/Ubuntu
brew install nmap           # macOS

# Run
bash run.sh

App starts at http://localhost:12100

Data

All data is stored in data/:

• boltarr.db — SQLite database (hosts, ports, connections, VLANs, scan history)
• config.yaml — AI settings (auto-created by the UI, or copy from config.yaml.example)

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

Updating

git pull
docker compose up -d --build

License

Apache 2.0

This project was built with the assistance of AI tools.