All chapters

Configuration

Huntress reads appsettings.json shipped with the release, then the files in the configuration folder (appsettings.Production.json), then environment variables. Later sources win. Put your changes in the configuration folder so updates never overwrite them.

Where to set things#

A file. appsettings.Production.json in the configuration folder, in the same JSON shape as the shipped file.
An environment variable. Replace each : with __: Registration:InvitationKey becomes Registration__InvitationKey. On Linux the service reads /etc/huntress/huntress.env.
HUNTRESS_DATA_DIR and HUNTRESS_CONFIG_DIR (environment only) place the data and configuration folders. Both default to the install folder in a flat install.
Relative paths in settings resolve against the install folder, never the working directory.

Secrets (the SMTP password, the invitation key, update tokens) belong in the configuration folder or the environment, never in the shipped appsettings.json.

Core#

Core settings
Setting	Default	Purpose
`AppBaseUrl`	empty	The public address, for example `https://huntress.example.com`. Required in production: reset links, Pulse links and passkey origins are built from it.
`AllowedHosts`	`*`	The host names the server answers to.
`ConnectionStrings:DefaultConnection`	`Data Source=huntress.db`	The database file.
`BlobStorage:Path`	`blobs.db`	The picture store.
`DataProtection:KeysPath`	`keys`	Where the signing keys are kept; must survive restarts.
`ForwardedHeaders:KnownProxies, KnownNetworks`	empty	Proxies trusted to set `X-Forwarded-For` and `-Proto`. Loopback is always trusted.
`Registration:InvitationKey`	empty	Self-service sign-up key. Registration is closed while empty.
`System:AdminTenantId`	1	The organisation whose Owners and Admins administer the installation.
`RawRequests:Enabled`	true	Store every inbound payload with its source address.

Mail#

Mail settings
Setting	Default	Purpose
`Notifications:Smtp:Host`	empty	The outgoing mail server. Empty disables sending: rule e-mails and password resets are skipped.
`Notifications:Smtp:Port`	465	Its port.
`Notifications:Smtp:EnableSsl`	true	Use TLS.
`Notifications:Smtp:From, Username, Password`	empty	Sender and credentials.

Listeners#

Listener settings
Setting	Default	Purpose
`HuntressMqtt:Enabled, Port`	true, 1883	The MQTT broker.
`HuntressSmtp:Enabled, Port, MaxMessageBytes`	true, 25, 10485760	The SMTP receiver.
`HuntressTcp:Enabled, SiaPort, CidPort`	true, 2000, 2001	SIA DC-09 and Contact ID.

Data and retention#

Retention settings
Setting	Default	Purpose
`Retention:EventDays`	90	Readings, events, person events, raw requests, rule firings.
`Retention:ImageDays`	30	Pictures and detections.
`Retention:ResolvedIncidentDays`	365	Resolved incidents.
`Retention:ClipDays`	30	Video clips.

Cameras, detection and clips#

Camera settings
Setting	Default	Purpose
`Snapshots:ArchiveIntervalSeconds`	30	How often a live camera's picture is stored (0 = every picture). Per camera override on its settings page.
`LocalEdge:Enabled`	true	Set false on a hosted server so it never opens RTSP streams itself.
`Detection:Enabled`	true	Object detection can be switched on per camera.
`Detection:ModelPath`	built in	Another ONNX model, with its `.json` sidecar.
`Detection:ExecutionProvider`	Auto	`Auto`, `Cpu`, `Cuda` or `DirectML`; GPU needs `Detection:NativeLibraryPath`.
`Detection:MaxBusyPercent, MinIntervalSeconds, IntraOpThreads`	50, 2, 0	CPU cap, shortest interval, threads (0 = automatic).
`Clips:Enabled, Path`	true, `clips`	Video clips and their folder (relative to the data directory).
`Clips:MaxClipSeconds`	120	How far later detections may extend a clip (30 to 600).
`Clips:MaxRingMegabytes, MaxUploadMegabytes`	64, 512	Pre-roll buffer per local camera; the largest clip an edge may upload.
`Clips:MaxTotalGigabytes, MinFreeDiskMegabytes`	20, 2048	Delete the oldest clips above this size (0 = no cap); start no clip below this free space.

Automation#

Automation settings
Setting	Default	Purpose
`Rules:TickSeconds`	30	How often time-based rule conditions are evaluated.
`Schedules:TickSeconds`	10	How often schedule switches are looked for (1 to 300).
`Schedules:CatchUpMinutes`	5	How far back after a restart a missed switch is still handled (0 to 120; 0 = never).
`Zigbee:Enabled`	true	Run the Zigbee coordinators configured on the Devices page.
`Webhooks:AllowedHosts, AllowPrivateAddresses`	empty, false	Exceptions to the outbound policy for rule webhooks.
`Outputs:AllowedHosts, AllowPrivateAddresses, Polling`	empty, false, true	Exceptions for HTTP outputs (a separate policy from webhooks), and whether status addresses are polled. Never allow private addresses on a server shared by organisations that do not trust each other.

API#

API settings
Setting	Default	Purpose
`ApiKeys:MaxActivePerTenant`	20	Active keys per organisation.
`ApiKeys:RequestsPerMinute`	120	Requests per key per minute.
`ApiKeys:FailedAttemptsPerWindow, FailedAttemptWindowMinutes`	20, 5	Failed authentications tolerated per client.
`ApiKeys:RequireHttps`	true	False only for a trusted plain-HTTP setup; behind a proxy it needs `ForwardedHeaders` to restore the scheme.

Updates#

Update settings
Setting	Default	Purpose
`Updates:Role`	Server	`Server` or `Edge`.
`Updates:Mode`	Approve (server), Auto (edge)	`Off`, `Approve` or `Auto`.
`Updates:Channel`	stable	`stable`, `beta` or `canary`.
`Updates:Window`	02:00-05:00	When updates may be installed, `HH:mm-HH:mm`.
`Updates:CheckIntervalMinutes, HealthTimeoutSeconds`	240, 120	Check frequency and the health gate.
`Updates:PinVersion, ManifestUrl, AuthToken, KeepReleases`	—, GitHub channel, —, 3	Hold a version, a custom manifest location, a token for a private repository, releases kept.

Edge#

Edge settings
Setting	Purpose
`HuntressEdge:HuntressUrl`	The address of your server.
`HuntressEdge:Cameras, ZigbeeGateways, HttpRelays`	What this edge serves, each with its token and edge secret; see Deployment.
`HuntressEdge:Snapshots, Clips`	Picture size and quality; clip ring limits.

Logging#

Logging is configured under Serilog. By default: information level, a console sink and a daily file in logs/ with a 14-day, 100 MB limit.