Security Model¶
Eight.ly's security architecture is designed for appliance-style deployments where the server is a trusted device on your network.
Security Hardening Checklist¶
Before doing anything else, run through this list after your first login:
- Change the default admin password (Settings > Users)
- Change the default Grafana password if monitoring is enabled
- Create named user accounts instead of sharing the admin login
- Generate API keys for mobile and script access instead of sharing passwords
- Enable firewall rules on the host (see below)
- If exposing the dashboard to the internet, put it behind Traefik + Authelia or Cloudflare Tunnel
Don't skip the defaults
The number one cause of compromised homelabs is unchanged default credentials. Eight.ly ships with a setup wizard that forces a password, but Grafana has its own separate credentials that must be changed manually.
Authentication¶
Session cookies¶
Eight.ly uses HMAC-SHA256 signed cookies for browser sessions — not JWT. Cookies are HttpOnly, Secure (when TLS is configured), and SameSite=Lax. A session lasts 12 hours by default, or 30 days if you tick "Remember this device" at login. Logging out, changing your password, or having your role changed invalidates every existing session immediately, regardless of how much of that window was left.
API keys¶
A parallel authentication path for mobile apps and scripts. API keys bypass the cookie flow entirely and authenticate via the Authorization: Bearer header. See API Keys for details.
Session key rotation¶
If you suspect your session signing key has been compromised, rotate it from Settings > Security > Rotate Secret. Rotation is graceful — you are not logged out. Eight.ly generates a new signing key but keeps the previous key active, so cookies signed with the old key still verify. Existing sessions stay valid and continue working; only new logins are signed with the new key.
Rotation alone does not evict a stolen cookie
Because the old key is still accepted, a rotation does not immediately invalidate sessions signed with it. Eight.ly retains exactly one previous key, so rotate a second time to drop the original key and force every session signed under it to fail verification. To revoke a single user immediately instead, bump their token version (change their password or delete/recreate the account).
Password and key derivation¶
Login passwords are hashed with bcrypt (cost 12) — the raw password is never stored. Backup encryption (EBS) derives its key with PBKDF2-SHA256 at 600,000 iterations, matching the OWASP 2026 recommendation.
Authorization (RBAC)¶
Eight.ly uses role-based access control with three roles:
| Role | Capabilities |
|---|---|
| Admin | Full access — user management, settings, destructive operations |
| Operator | Deploy apps, manage containers, view storage — no user management or security settings |
| Viewer | Read-only access — dashboard, monitoring, logs |
Principle of least privilege
Create Operator accounts for family members or friends who help manage containers. Reserve Admin for yourself. Use Viewer accounts for monitoring-only access (e.g., a wall-mounted dashboard tablet).
TLS and certificate pinning¶
TOFU cert pinning¶
Eight.ly uses Trust On First Use (TOFU) certificate pinning for agent and EBS connections. The first time an agent or backup server connects, its TLS certificate fingerprint is recorded. Future connections from that endpoint must present the same certificate.
Manage pinned certificates from Settings > Security > Certificate Pins:
- View all pinned certificates with their fingerprints and endpoints
- Clear a pin if you've rotated a certificate on the remote end
- Pins are stored locally and never transmitted
Agent enrollment¶
Agents (including the mobile app) connect to Eight.ly using single-use enrollment tokens:
- Tokens are generated from Settings > Security
- Each token expires after 1 hour
- Each token can only be used once
- Agent tokens are SHA256 hashed at rest
WebSocket security¶
Eight.ly's WebSocket endpoints (terminal, real-time updates) enforce an origin allowlist to prevent Cross-Site WebSocket Hijacking (CSWSH). Only origins matching your configured server URLs are accepted.
Terminal access¶
The web terminal provides root shell access. This is intentional — Eight.ly follows the appliance model used by Unraid, TrueNAS, and Proxmox where the admin has full system access. Reaching it requires the Admin role specifically (Operator is not enough), and the box has no SSH shell by default — the web terminal is the way in. See Web Terminal for session behavior and limits.
Firewall Rules¶
Eight.ly's built-in host firewall (see Firewall) is off by default, and turning it on won't lock you out: SSH and the dashboard port are always allowed ahead of any rule you add, and a policy change that could cut off access is applied behind a confirm-or-revert countdown. If you'd rather lock things down further than the defaults, add rules from Infrastructure > Node > Firewall — no separate tool needed.
Docker and the host firewall
Docker modifies the kernel's packet-filtering rules directly, which can bypass firewall rules aimed at a container's published port. If you need strict control over container access, bind containers to 127.0.0.1 in their compose files and use Traefik as a reverse proxy. See the Traefik & Domain Setup guide.
Internet-Exposed Dashboards¶
If you need to access Eight.ly outside your LAN, do not expose port 8080 directly to the internet. Use one of these approaches:
| Method | Complexity | Notes |
|---|---|---|
| Tailscale | Low | Mesh VPN, no open ports, works on mobile. Recommended for personal use |
| Cloudflare Tunnel | Medium | Free, no open ports, adds Cloudflare's WAF. Good for sharing with others |
| Traefik + Authelia | Higher | Full reverse proxy with SSO, MFA, and access policies. Best for multi-service setups |
Never expose raw ports
Running Eight.ly on a public IP without a reverse proxy or VPN is asking for trouble. Bots scan the entire IPv4 space constantly. You will be found within hours.
Network Segmentation¶
For homelabs with IoT devices, cameras, or untrusted hardware, VLANs keep your infrastructure safe:
- Management VLAN — Eight.ly server, switches, access points. Only you access this.
- Trusted VLAN — workstations, laptops, phones. Can reach the dashboard.
- IoT VLAN — smart home devices, cameras. Isolated from management. No access to Eight.ly.
- Guest VLAN — visitor devices. Internet only, no local access.
Most managed switches (Ubiquiti, MikroTik, TP-Link Omada) support VLAN tagging. Configure inter-VLAN firewall rules on your router to control what can talk to what.
Audit Logging¶
Eight.ly keeps its own tamper-evident audit trail — every row is chained to the one before it, so deleting or editing an entry breaks the chain and is detectable. It records:
- Login attempts (success and failure)
- Container and VM changes, share and storage mutations, cluster membership changes
- Nova AI actions — every tool call Nova makes, with its arguments and outcome, including a mutating call it refused
- User management changes — account creation, role changes, deletions
- Session rotations and certificate pin changes
View it at Settings > Security > Audit Log.
This is separate from the request-level logs (Traefik access log, Authelia login attempts, container stdout/stderr) that the Monitoring Stack collects into Loki when enabled — that's the place to search raw log lines with LogQL; the Audit Log is the place to answer "what changed and who did it."