Site-local discovery daemon for the FreeSDN platform.
License: MIT | Releases: GitHub Releases (checksummed) | Core: github.com/freesdn/freesdn
The agent runs on a host inside your network and handles the discovery work that a containerized backend cannot: Layer 2 scans, raw-socket protocols, and passive traffic listeners that need access to the actual wire.
- Active scanning - ARP, ICMP, TCP port, ONVIF WS-Discovery (cameras), Hikvision SADP, NetBIOS/SMB, SIP, mDNS, SSDP
- Discovery push - found hosts upserted into the FreeSDN backend, de-duplicated by site + MAC, auto-routed to the correct site by subnet match
- Adoption - operators promote a discovered host into a managed device row from the web UI or CLI; the agent suggests the driver
- Scheduled scans - cron-based, managed from the web UI, delivered to the agent over WebSocket on change
- Passive topology - LLDP listener (daemon mode) pushes Layer 2 edges to the topology view
- Auto-update - the agent checks for new releases on a configurable interval, downloads the binary, verifies SHA-256 and an ECDSA-P256 signature from the server, stages, and restarts with a rollback marker
All of this is reflected in the FreeSDN web UI: the Agents page shows connection state, recent runs, discovered hosts, and topology edges per agent. Per-agent Prometheus metrics are also available.
Download from the Releases page. Verify what you downloaded before running it - see Release integrity below.
Linux x86-64 gets a Debian package; Windows x86-64 and macOS Apple Silicon
(ARM64) ship as standalone binaries. The macOS daemon is experimental.
There is no MSI and no .pkg installer yet.
Linux (deb)
sudo dpkg -i freesdn-agent_*.deb
# Provision the service account's Secret Service and register as described
# in DEPLOYMENT.md, then approve the agent in the FreeSDN UI.
sudo systemctl enable --now freesdn-agentThe package installs a systemd unit that runs as a dedicated freesdn-agent
service user with AmbientCapabilities=CAP_NET_RAW, not as root.
Registration must use that account, /opt/freesdn-agent/config, and the same
unlocked Secret Service/D-Bus session as the service. The package does not
provision a credential store. Follow the Linux service runbook
and verify Stored in keyring before enabling the daemon.
Windows (standalone binary)
# Download win64-freesdn-agent.exe (or win64-freesdn-agent-gui.exe), then:
.\win64-freesdn-agent.exe register --server https://freesdn.example.com --site-id <uuid>
# Run in the foreground to verify. To run it as a Windows service, see DEPLOYMENT.md.
.\win64-freesdn-agent.exe daemonmacOS (standalone binary)
chmod +x macos-freesdn-agent
./macos-freesdn-agent register --server https://freesdn.example.com --site-id <uuid>
./macos-freesdn-agent daemonRun registration and the daemon as the same user with access to the same unlocked login keychain. A launchd service requires separate acceptance.
macOS binaries are not notarised, so Gatekeeper will block the first run.
Clear the quarantine attribute yourself if you accept that:
xattr -d com.apple.quarantine macos-freesdn-agent.
The register command prompts for your FreeSDN admin credentials, creates the
agent row in the backend, and stores the API key in the OS keyring (Windows
Credential Manager, macOS Keychain, Linux Secret Service). The key is never
written to the config file on disk.
After registering, approve the agent in the web UI under Site - Agent tab.
Two different mechanisms protect two different paths. Do not confuse them.
Downloads from this Releases page are checksummed, not signed. Every
binary has a .sha256 sidecar, and a combined SHA256SUMS.txt covers all of
the release assets including the .deb and the SBOM. Verify with:
sha256sum -c SHA256SUMS.txtThere are no detached signatures, no cosign bundles and no PGP signatures on these artifacts. A checksum served from the same host as the file it describes proves the download was not corrupted; it does not prove the host was not compromised.
The in-app auto-update feed is genuinely signed. When your own FreeSDN
instance serves a release to the agents it manages, it signs the binary with
ECDSA-P256 and the agent verifies that signature before staging the update. The
verification key is served by your instance at
GET /api/v1/agents/releases/public-key, independent of the binary itself, so a
compromised download source cannot swap binary and signature together without
also controlling the signing key.
freesdn-agent register --server URL --site-id UUID
freesdn-agent status
freesdn-agent daemon # run in foreground (or under a service manager)
freesdn-agent unregister
freesdn-agent scan --type quick --targets 192.168.1.0/24
freesdn-agent list-discovered
freesdn-agent adopt 192.168.1.50
freesdn-agent adopt all
freesdn-agent schedule list
freesdn-agent schedule add --name nightly --cron "0 2 * * *" --targets 10.0.0.0/24
Schedules created here sync to the FreeSDN backend. Schedules created in the web UI are pushed to the agent over WebSocket.
| Binary platform | Qualification scope |
|---|---|
| Windows x86-64 | Daemon/desktop builds and tests on the current hosted Windows runner; actual desktop initialization checked. Windows service installation is separate. |
| Ubuntu 22.04+ x86-64 | Built on Ubuntu 22.04; actual daemon package/service and controller connection exercised on Ubuntu 24.04. Desktop initialization checked. |
| macOS Apple Silicon (ARM64) | Experimental daemon, built and tested on the current hosted macOS runner. No Intel binary, notarization, launchd or older macOS acceptance. |
Source installation on another OS or architecture does not establish binary compatibility or expand this scope.
Raw-socket scans (LLDP, some ARP variants) need Administrator on Windows or root on Linux/macOS. Plain ping and TCP-connect scans work without elevated privileges.
Full deployment runbook, troubleshooting guide, and config reference: AGENT.md and DEPLOYMENT.md in this repo.
FreeSDN is developed in-house by the small team that runs it in production
and does not accept external code contributions; this repo follows the same
policy. Bug reports and real-hardware field reports are welcome via GitHub
Issues. Two optional ways to support development: donate hardware
(hardware@freesdn.org), or fuel the build - the team builds and reviews with
AI tooling, so gifting a Claude or OpenAI Codex subscription
(fuel@freesdn.org) directly funds that work. See the
core CONTRIBUTING guide
for the full reasoning.
MIT. See LICENSE. The FreeSDN core that this agent connects to is AGPL-3.0-only.