Daemon Configuration

LinuxmacOSWindowsFreeBSD

Configuration Priority

Scanopy daemons use the following priority order (highest to lowest):

1. Command-line arguments (highest priority)
2. Environment variables
3. Configuration file
4. Default values (lowest priority)

Later sources override earlier ones. For example, an environment variable overrides the config file but is overridden by a command-line argument.

Configuration Methods

Command-line arguments (also accepted by scanopy-daemon install, which persists them to the config file — see Running as a Service):

scanopy-daemon --server-url http://192.168.1.100:60072 --daemon-api-key YOUR_KEY

Environment variables:

export SCANOPY_SERVER_URL=http://192.168.1.100:60072
export SCANOPY_DAEMON_API_KEY=YOUR_KEY
scanopy-daemon

Configuration file: where config.json lives depends on how the daemon runs. <name> is the daemon's install slot, scanopy-daemon for the first daemon on a host.

• Service (scanopy-daemon install): /etc/scanopy/daemon/<name>/config.json
• Run yourself (install --no-service or a plain scanopy-daemon): ~/.config/daemon/config.json, or ~/.config/daemon/<name>/config.json for a second daemon

A background service runs under a different profile than whoever installed it, so install writes the config to a system directory and points the service at it with --config-dir. The install command prints the config and log paths it used.

Use --config-dir to override the directory holding config.json.

The config file stores runtime state (daemon ID, host ID) alongside your settings. Command-line and environment variables take priority over the file.

Parameter Reference

Secrets from Files

Any SCANOPY_ variable can be read from a file instead: set SCANOPY_<NAME>_FILE to the file's path, for example SCANOPY_DAEMON_API_KEY_FILE=/run/secrets/daemon_api_key. A trailing newline is trimmed. Setting both forms of the same variable, or pointing _FILE at a file that can't be read, stops the daemon at startup with an error naming the variable.

SCANOPY_LOG_FILE is itself a setting (the log path), not a secret file. To read the log path from a file, use SCANOPY_LOG_FILE_FILE.

Trusted CA Certificates

--trusted-ca-bundle / SCANOPY_TRUSTED_CA_BUNDLE

A PEM file of CA certificates the daemon trusts in addition to its built-in public roots. It applies to the daemon's connection to the Scanopy server and to the UniFi controller and Proxmox VE integrations. Use it when any of them has a certificate from a private CA, such as a Proxmox VE cluster's own CA, so certificate verification stays on.

The path refers to a file on the daemon host. install saves it to the config file. If the file is missing or contains no usable CA certificate, the daemon does not start, and the error names the path.

Network scanning does not use the bundle. Probes of scanned hosts follow Accept Invalid Scan Certificates (SCANOPY_ACCEPT_INVALID_SCAN_CERTS).

Seeding Credentials at Registration

--credential-id / SCANOPY_CREDENTIAL_IDS

Seeds one or more credentials for the daemon to use on its first scan, so it collects everything a credential unlocks before you assign anything in the UI. Provide them as a repeatable --credential-id flag or as a comma-separated SCANOPY_CREDENTIAL_IDS environment variable.

Each entry is a credential ID, optionally targeted at specific IP addresses:

To target the daemon's own host — for example a local Docker or Podman socket credential — use its loopback address: <uuid>@127.0.0.1.

# CLI (repeatable)
scanopy-daemon --credential-id [email protected] --credential-id [email protected]

# Environment (comma-separated)
export SCANOPY_CREDENTIAL_IDS="[email protected],[email protected]"

After the first scan, seeded credentials are auto-assigned to the matching hosts and used on every subsequent scan.

Logging

The daemon logs to stdout and stderr on all platforms; where that output lands depends on how you run it. For reading logs on each platform and capturing them to a file, see Checking Daemon Logs.

Set the log level with --log-level or SCANOPY_LOG_LEVEL:

# CLI
scanopy-daemon --log-level debug

# Environment
export SCANOPY_LOG_LEVEL=debug