Security and Access

GearBeacon is a private, single-owner application. There is no public registration, hosted GearBeacon database, required third-party cloud login, or automatic checkout. Choose the narrowest access mode that meets your needs and keep the host itself protected.

Access modes

Mode	Initial bind	Owner password	Intended use
local	127.0.0.1	Optional	Browser on the same computer
private	0.0.0.0	Required	Trusted LAN/VPN, service, or container
proxy	127.0.0.1	Required	HTTPS reverse proxy on the same host

Local unauthenticated mode cannot bind beyond loopback. Proxy mode also requires loopback, with forwarded headers accepted only from a loopback proxy connection. Private mode requires owner authentication and does not enable forwarded-header trust.

Native automatic-start installers use private mode as their initial default. Compose also uses private mode internally but publishes only host loopback. Access/bind/region changes saved in the browser require a restart. A public URL configures links and security behavior; it does not create network connectivity or TLS.

Use trusted LAN/VPN access where practical. For access over an untrusted network, terminate HTTPS at a maintained, restricted reverse proxy and control firewall sources. Do not expose an unauthenticated local installation or publish the backend directly to unrestricted internet access. See Reverse proxy.

Owner setup and sessions

Authenticated first run prints a random one-time setup token. Enter it to create the owner password; it is consumed after setup. Automated deployments can seed a fixed GEARBEACON_SETUP_TOKEN or use an initial password file, but these are sensitive bootstrap material.

Owner passwords use versioned scrypt hashing; valid legacy credentials are upgraded on sign-in. Sessions use protected cookies and server-side token hashes. Cookies are HttpOnly and SameSite=Strict; HTTPS configuration enables Secure. Settings > Security provides password/session management. The default session lifetime is 168 hours, configurable at process startup.

State-changing authenticated API calls require the session's X-CSRF-Token. Host/origin checks, bounded HTTP resources, and response security headers also apply. API tokens and arbitrary origins are not substitutes for the owner session.

Recover owner access

1. Stop GearBeacon and create a strong replacement password in a protected local file readable by the process identity.
2. Set GEARBEACON_OWNER_PASSWORD_FILE to that file and GEARBEACON_RESET_OWNER_PASSWORD=1 in the process's actual environment.
3. Start the same installation/data directory and sign in with the replacement password.
4. Remove the reset flag and password-file override, remove the temporary plaintext file when no longer needed, then restart normally.

Recovery revokes existing sessions. Do not leave the reset flag enabled or record a real password in shell history, Git, or Compose examples. For Docker, the password file must be mounted inside the container and the variables explicitly mapped into its environment. Service environment changes likewise must reach the service identity, not just an interactive shell.

Protect stored and exported data

Saved notification credentials are encrypted using a generated secrets.key outside SQLite with restricted permissions. Keep the key with compatible SQLite recovery material. Portable JSON exports exclude owner credentials, sessions, and local integration secrets; encrypted exports additionally protect their content with a passphrase.

Raw SQLite backups, notification endpoints, recipient addresses, owner sessions, Activity exports, and logs are private. A redacted Support bundle is a separate diagnostic artifact designed to exclude secrets, local paths, host addresses, and product/watch/collection data. Review it before sharing. See Backups and recovery.

External connections and privacy

GearBeacon reads public Ubiquiti regional catalogs and product images, checks the configured release/manifest source for updates, and sends notifications to the channels you configure. Product image handling uses restricted public hosts; email attachments enforce fetch time, type, redirect, and size limits. SMTP requires secure transport for credentials, validates certificates by default, and supports implicit TLS/STARTTLS.

There is no GearBeacon telemetry, analytics, hosted relay, account scraping, or collection of store credentials. Third-party services you choose receive the notification data sent to them under their own policies. Browser notification permission is local to the browser; it is separate from external server channels.

Report a security issue

Use the repository's private vulnerability-reporting process. Do not put credentials, tokens, unredacted logs, backups, or exploit-sensitive installation details in a public issue.