Managing Daemons

Requirements

• Linux: Docker with host networking OR standalone binary (installable as a systemd service)
• macOS: Standalone binary — Docker Desktop doesn't allow access to host interfaces. Installs as a launchd service.
• Windows: Standalone binary — Docker Desktop doesn't allow access to host interfaces. Installs as a Windows service (native SCM), or via the signed MSI.
• FreeBSD: Standalone binary, installable as an rc.d service.

On Linux, macOS, Windows, and FreeBSD the daemon installs as a native background service — see Running as a Service.

Creating a Daemon

Go to Discover > Scan > Daemons and click Create Daemon. The wizard walks you through:

1. Setup — network, polling mode, and daemon name
2. Integrations — optionally add SNMP, Docker, and Podman credentials, targeting all hosts or specific hosts. These are auto-assigned to discovered hosts after the first scan. See Credentials for details.
3. Install — a ready-to-copy scanopy-daemon install command with the correct API key, server URL, daemon name, and any --credential-id flags

For help choosing a polling mode and planning where to place daemons, see Planning Daemon Deployment.

Running as a Service

The recommended way to install the daemon is the scanopy-daemon install command. It places the binary, writes the daemon's config.json, and registers a native background service — systemd on Linux, launchd on macOS, the Service Control Manager on Windows, and rc.d on FreeBSD — that starts immediately and on every reboot. The install command shown on the wizard's Install step already includes this; copy and run it on the host.

You can also run it yourself with the connection flags (the same flags the daemon accepts):

sudo scanopy-daemon install --server-url https://scanopy.example.com --daemon-api-key <key>

Everything else — network, interfaces, ports — is read from config.json, so no secrets appear in the service definition or process arguments. Re-running install is idempotent, and a non-elevated invocation prints the exact sudo/administrator command to re-run.

Verify the service and view its logs:

• Linux: systemctl status scanopy-daemon · logs via journalctl -u scanopy-daemon -f
• macOS: sudo launchctl print system/com.scanopy.daemon · logs at /var/log/scanopy/scanopy-daemon.out.log and ~/Library/Logs/scanopy/scanopy-daemon.log
• Windows: Get-Service scanopy-daemon · logs at %ProgramData%\scanopy\scanopy-daemon.log
• FreeBSD: service scanopy-daemon status

To stop and remove the service, use sudo scanopy-daemon uninstall — see Removing a Daemon.

Windows MSI

On Windows you can also install with the signed MSI — the platform-standard wizard. It installs the binary and registers the same service. For unattended deployment (GPO/Intune), install silently:

msiexec /qn /i scanopy-daemon-windows-amd64.msi SERVERURL="https://scanopy.example.com" APIKEY="<key>"

The MSI also handles upgrades in place and can be removed with msiexec /qn /x scanopy-daemon-windows-amd64.msi.

Manually installed or older daemons

Daemons that predate the scanopy-daemon install subcommand, or that you set up by hand, are managed with the platform's native service tools directly. Use these instructions if scanopy-daemon install isn't available in your daemon version. (For current versions, prefer install/uninstall above.)

Linux (systemd, manual) — download the systemd unit, set your flags in ExecStart (or rely on config.json), then enable it:

sudo curl -o /etc/systemd/system/scanopy-daemon.service \
  https://raw.githubusercontent.com/scanopy/scanopy/main/scanopy-daemon.service
sudo systemctl daemon-reload
sudo systemctl enable --now scanopy-daemon

macOS (launchd, manual) — create a launch daemon plist and load it:

sudo tee /Library/LaunchDaemons/com.scanopy.daemon.plist > /dev/null <<EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.scanopy.daemon</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/scanopy-daemon</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/var/log/scanopy/scanopy-daemon.out.log</string>
    <key>StandardErrorPath</key>
    <string>/var/log/scanopy/scanopy-daemon.out.log</string>
</dict>
</plist>
EOF
sudo launchctl bootstrap system /Library/LaunchDaemons/com.scanopy.daemon.plist

Windows (NSSM, manual) — older setups used NSSM to run the executable as a service:

nssm install ScanopyDaemon "C:\Path\To\scanopy-daemon.exe"
nssm set ScanopyDaemon AppStdout "C:\ProgramData\scanopy\daemon.log"
nssm set ScanopyDaemon AppStderr "C:\ProgramData\scanopy\daemon.log"
nssm start ScanopyDaemon

Integrated Daemon (Self-Hosted)

Self-hosted Docker Compose deployments include an integrated daemon that runs alongside the server. This daemon is managed as part of your Compose stack — it upgrades when you upgrade the server and doesn't need separate installation or API key setup. For upgrading the integrated daemon along with your server, see Upgrading a Self-Hosted Server.

Upgrading

When an update is available, the daemon card in Discover > Scan > Daemons shows an Update button. Click it to see platform-specific upgrade steps: download the latest binary (or run the latest MSI on Windows), then restart the service (systemctl restart / launchctl kickstart -k / sc.exe stop + start / service … restart). Configuration is preserved across upgrades.

For upgrading self-hosted server and integrated daemon together, see Upgrading.

Updating Daemon Properties

You can update daemon properties after creation by editing the daemon config file. Restart the daemon's service for changes to take effect — sudo systemctl restart scanopy-daemon (Linux), sudo launchctl kickstart -k system/com.scanopy.daemon (macOS), sc.exe stop scanopy-daemon then sc.exe start scanopy-daemon (Windows), or sudo service scanopy-daemon restart (FreeBSD). For a foreground daemon, just restart the process.

The daemon's name is the only property that propagates to the server. All other config properties are local to the daemon.

Each daemon also reports its capabilities to the server: whether it has Docker or Podman socket access (for container discovery) and which subnets it has network interfaces on (for default scan targets). To update capabilities after changing the host's network configuration or Docker access, run a SelfReport discovery.

Removing a Daemon

To fully remove a daemon, delete it from the UI and uninstall it from the host.

Delete from the UI: Go to Discover > Scan > Daemons and click the delete icon on the daemon card.

Uninstall from the host — for a daemon installed with scanopy-daemon install, run:

sudo scanopy-daemon uninstall

This stops and deregisters the service and deletes its config.json. Add --purge to also delete the installed binary, and --name <name> to target a specific instance. On Windows, run it from an elevated PowerShell, or uninstall the MSI: msiexec /qn /x scanopy-daemon-windows-amd64.msi.

Docker:

docker stop scanopy-daemon
docker rm scanopy-daemon

# systemd (Linux)
sudo systemctl stop scanopy-daemon && sudo systemctl disable scanopy-daemon
sudo rm /etc/systemd/system/scanopy-daemon.service && sudo systemctl daemon-reload

# launchd (macOS)
sudo launchctl bootout system /Library/LaunchDaemons/com.scanopy.daemon.plist
# (older setups: launchctl unload ~/Library/LaunchAgents/com.scanopy.daemon.plist)

# Remove binary and configuration
sudo rm /usr/local/bin/scanopy-daemon
rm -rf ~/.config/scanopy/                                    # Linux
rm -rf ~/Library/Application\ Support/com.scanopy.daemon/    # macOS

Can I migrate a daemon?

No. Daemons discover host-specific data (network interfaces, Docker containers, local services) tied to the machine they run on. Moving a daemon's identity to a different host would produce inaccurate data.

If you're replacing a host, create a new daemon on the new machine and delete the old one.