Installing and Registering the Agent

Alpha status

freesdn-agent v1.0.0 is alpha software. Installation paths, CLI flags, and packaging formats may change. Test in a non-production environment first.

Prerequisites

• Python 3.11 or later on the agent machine, for the pip / from-source path only. The released binaries and the .deb are self-contained PyInstaller builds and need no system Python.
• Outbound HTTPS (port 443) to your FreeSDN server
• Administrator / root privileges are required for ARP scanning and all passive listeners (LLDP, CDP, SNMP traps, syslog, DHCP)
• On Linux: the systemd unit shipped by the .deb runs as a dedicated freesdn-agent service user with AmbientCapabilities=CAP_NET_RAW, and the package’s postinst also sets cap_net_raw+ep on the binary, so the daemon does not run as root on that path
• On Windows: the service runs as SYSTEM; Npcap must be installed for raw-socket (ARP/ONVIF/SADP) scanners

Installation

What the v1.0.0 release actually ships

The v1.0.0 release publishes one native package and a set of standalone, self-contained binaries. Everything else is built from source.

Platform	Daemon	Desktop GUI	Native package
Windows x64	win64-freesdn-agent.exe	win64-freesdn-agent-gui.exe	none yet
Linux amd64	linux-amd64-freesdn-agent	linux-amd64-freesdn-agent-gui	freesdn-agent_1.0.0_amd64.deb
macOS	macos-freesdn-agent	none yet	none yet

The release also carries a .sha256 file per binary, a combined SHA256SUMS.txt, and an SPDX SBOM. Verify a download before running it:

sha256sum -c SHA256SUMS.txt

The Administration → Agent Downloads page in the FreeSDN UI serves whatever binaries an operator has uploaded on the Administration → Agent Releases page. It does not mirror the GitHub release automatically, so it is empty until someone populates it.

Ubuntu / Debian (native package)

The .deb is the only native installer published today, and it is the smoothest path on Linux:

sudo dpkg -i freesdn-agent_1.0.0_amd64.deb

Installs the binary to /opt/freesdn-agent/bin/, symlinks it onto PATH at /usr/local/bin/freesdn-agent, and writes a systemd unit at /etc/systemd/system/freesdn-agent.service.

Windows (standalone binary)

Download win64-freesdn-agent.exe from the release, put it wherever you want it to live, and run it from an Administrator prompt. It is self-contained and needs no Python on the host.

# Example: install under Program Files (create the folder as Administrator)
New-Item -ItemType Directory -Force "C:\Program Files\FreeSDN\Agent"
Move-Item .\win64-freesdn-agent.exe "C:\Program Files\FreeSDN\Agent\freesdn-agent.exe"

& "C:\Program Files\FreeSDN\Agent\freesdn-agent.exe" --version

Nothing is added to PATH and no Windows Service is created; both are manual steps. See Starting the daemon - Windows below to register the service.

The released binaries are not code-signed, so SmartScreen may warn on first run.

The MSI installer is not published yet

A WiX-based MSI build script exists in the source tree (packaging/installers/build_msi.ps1 in the freesdn-agent repository), but it is not wired into the release workflow, so no .msi is attached to v1.0.0. Use the standalone .exe above. If you build the MSI yourself it installs to C:\Program Files\FreeSDN\Agent\ and adds that directory to the system PATH, and it still does not create the Windows Service.

macOS (standalone binary)

Download macos-freesdn-agent from the release, make it executable, and run it. The binary is unsigned and un-notarized, so Gatekeeper will quarantine it on first run; clear the quarantine attribute or approve it under System Settings → Privacy & Security.

chmod +x macos-freesdn-agent
xattr -d com.apple.quarantine macos-freesdn-agent   # if Gatekeeper blocks it
sudo ./macos-freesdn-agent --version

The .pkg installer is not published yet

A pkgbuild script exists in the source tree (packaging/installers/build_pkg.sh in the freesdn-agent repository), but it is not wired into the release workflow, so no .pkg is attached to v1.0.0. If you build it yourself it installs to /Applications/FreeSDN Agent/, symlinks /usr/local/bin/freesdn-agent, and writes a launchd plist at /Library/LaunchDaemons/com.freesdn.agent.plist. There is no macOS desktop GUI build.

RHEL / Fedora and other Linux distributions

There is no RPM

FreeSDN does not build or publish an .rpm, and no RPM packaging exists in the source tree. Do not expect rpm -i or dnf install to work.

Use the standalone linux-amd64-freesdn-agent binary instead. It is self-contained and needs no system Python:

chmod +x linux-amd64-freesdn-agent
sudo install -m 755 linux-amd64-freesdn-agent /usr/local/bin/freesdn-agent
sudo freesdn-agent --version

Raw-socket scanners (ARP, ONVIF, SADP) need CAP_NET_RAW. Either run the daemon as root or grant the capability directly:

sudo setcap cap_net_raw+ep /usr/local/bin/freesdn-agent

You must write your own systemd unit on this path; the .deb is what ships one.

Development / pip install

For development or platforms without a native package, install from source:

git clone https://github.com/freesdn/freesdn-agent.git
cd freesdn-agent

python -m venv venv
# Windows:
venv\Scripts\activate
# Linux / macOS:
source venv/bin/activate

pip install -r requirements.txt
pip install -e .

# Run CLI:
freesdn-agent --version

Registering the agent

Registration creates the agent record in the FreeSDN database and issues the agent key. You need a site_admin (or higher) account on the FreeSDN instance.

freesdn-agent register --server https://freesdn.example.com --name "Branch-A Agent" --site-id <your-site-uuid>

The site UUID is visible in the FreeSDN UI under Sites - copy it from the address bar or the site detail panel. The --site-id flag is required: the server rejects registration without a site UUID (HTTP 422).

The CLI prompts for your FreeSDN email and password interactively (credentials are not saved):

Admin email: [email protected]
Admin password:
Registering agent 'Branch-A Agent' with https://freesdn.example.com …
Agent key stored in system keyring.

Registration successful!
  Agent ID:  a3f7c891-...
  Server:    https://freesdn.example.com
  WebSocket: wss://freesdn.example.com/api/v1/agents/ws/a3f7c891-...

Next steps:
  1. Ask your admin to approve this agent in the FreeSDN UI
  2. Run:  freesdn-agent daemon

Flags:

Flag	Default	Description
--name	hostname	Display name shown in the UI
--site-id	required	UUID of the site to assign this agent to - the server returns HTTP 422 without it
--agent-type	site	Type tag: site, scanner, or collector
--description	(empty)	Free-text description. When blank, the CLI fills in a description derived from the agent host’s name and OS (e.g. Agent on myhost (Linux)) before sending to the server.

After registration the agent ID is stored in the config file and the agent key is saved in the OS keyring. The key is shown once during registration - it is hashed in the database and cannot be recovered. If you lose it, re-register the agent.

Approving the agent in the UI

New agents start in a pending state - no tasks are dispatched until an admin approves them. This is an intentional human-in-the-loop gate.

1. Go to Agents in the FreeSDN sidebar
2. Find the agent in the Agents list (it will show a Pending Approval badge in its Status column)
3. Open its action menu (…) and click Approve Agent

The agent status changes to online within one heartbeat interval (default 30 s).

Starting the daemon

Linux (systemd)

sudo systemctl enable --now freesdn-agent
sudo systemctl status freesdn-agent

Windows (Service Control Manager)

Nothing on the Windows path creates the service for you, so you must register it first. Run the following commands in an Administrator PowerShell or Command Prompt, substituting the location where you placed freesdn-agent.exe:

# 1. Create the service (adjust the path to wherever you put the binary)
sc create FreeSDNAgent binPath= "\"C:\Program Files\FreeSDN\Agent\freesdn-agent.exe\" daemon" start= auto
sc description FreeSDNAgent "FreeSDN Network Discovery Agent"

# 2. Start the service
sc start FreeSDNAgent

# 3. Confirm it is running
sc query FreeSDNAgent

Or through Services (services.msc) after step 1.

NSSM alternative

For more robust service management (automatic restart on crash, stdout/stderr log capture), install NSSM and run:

nssm install FreeSDNAgent "C:\Program Files\FreeSDN\Agent\freesdn-agent.exe" daemon
nssm set FreeSDNAgent DisplayName "FreeSDN Agent"
nssm set FreeSDNAgent Description "FreeSDN Network Discovery Agent"
nssm set FreeSDNAgent Start SERVICE_AUTO_START
nssm start FreeSDNAgent

macOS (launchd)

The launchd plist ships inside the .pkg, which is not published yet, so on the standalone-binary path you have to write /Library/LaunchDaemons/com.freesdn.agent.plist yourself (pointing ProgramArguments at your binary followed by daemon). Once the plist is in place:

sudo launchctl load -w /Library/LaunchDaemons/com.freesdn.agent.plist
sudo launchctl list | grep freesdn

Until then, run the daemon in the foreground as shown below.

Foreground (any platform)

freesdn-agent daemon

Runs in the foreground - useful for debugging. Ctrl-C stops it.

Checking status

freesdn-agent status

Example output:

FreeSDN Agent v1.0.0
  Config:    /home/user/.config/FreeSDN Agent/config.json

  Agent ID:  a3f7c891-...
  Server:    https://freesdn.example.com
  Site ID:   b9e12c44-...
  Heartbeat: every 30s
  Log level: INFO
  Key:       Stored in keyring

Config file location

The agent config (config.json) is stored at the platform-specific application config directory:

Platform	Path
Windows	%LOCALAPPDATA%\FreeSDN\FreeSDN Agent\config.json
Linux	~/.config/FreeSDN Agent/config.json
macOS	~/Library/Application Support/FreeSDN Agent/config.json

The file contains all settings except the agent key, which is stored in the OS keyring only.

Unregistering

To remove the agent registration from the local machine (does not delete the record in FreeSDN):

freesdn-agent unregister

To delete the agent from FreeSDN entirely, remove it from Administration → Agents in the UI.

Key rotation

There is currently no in-UI key regeneration. To rotate a compromised agent key, delete the agent record from Administration → Agents in the UI, then re-register the agent on the machine:

freesdn-agent unregister
freesdn-agent register --server https://freesdn.example.com --site-id <your-site-uuid>

Desktop app

The desktop application (PySide6 GUI) is a separate download: win64-freesdn-agent-gui.exe on Windows and linux-amd64-freesdn-agent-gui on Linux. There is no macOS GUI build in v1.0.0. It uses the same scanner engine for interactive on-demand scans. Registration is performed via the CLI (freesdn-agent register) rather than the GUI. It is primarily for use by network technicians doing on-site work; for always-on remote discovery, prefer the daemon.