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
• 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 runs as root with CAP_NET_RAW and CAP_NET_BIND_SERVICE declared
• On Windows: the service runs as SYSTEM; Npcap must be installed for raw-socket (ARP/ONVIF/SADP) scanners

Installation

Windows

Download the MSI installer from Administration → Agent Downloads in the FreeSDN UI, or from the releases page of the agent repository. Run the installer as Administrator:

# Run the MSI  -  installs to C:\Program Files\FreeSDN\Agent\
.\freesdn-agent-1.0.0-win64.msi

The installer:

• Places the agent binary at C:\Program Files\FreeSDN\Agent\ and adds that directory to the system PATH
• Does not create a Windows Service - you must register the service manually after installation (see Starting the daemon - Windows below)

Ubuntu / Debian

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

Installed to /opt/freesdn-agent/ with a systemd unit file at /etc/systemd/system/freesdn-agent.service.

RHEL / Fedora

sudo rpm -i freesdn-agent-1.0.0.x86_64.rpm

macOS

sudo installer -pkg freesdn-agent-1.0.0.pkg -target /

Installs to /Applications/FreeSDN Agent/ with a launchd plist at /Library/LaunchDaemons/com.freesdn.agent.plist.

Development / pip install

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

cd 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: admin@example.com
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)

Because the installer does not create the Windows Service, you must register it first. Run the following commands in an Administrator PowerShell or Command Prompt:

# 1. Create the service (adjust the path if you chose a custom install location)
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)

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

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

Desktop app

The desktop application (PySide6 GUI) is a separate download. 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.