Security

Anyone who can reach your dashboard can look at it; that's by design, so the whole household can keep an eye on things. Everything that changes something is locked behind the admin password: Settings, the layout editor, the card showcase, the Controls page and the REST API. Settings → Security lets you add a second step to that sign-in.

The admin passwordCopy Anchor Link

You choose the admin password in the first step of the setup wizard.

• To change it, sign in, open /setup, and set a new password in the first step. Generate a strong password will make one for you.
• On Docker with SETTINGS_PASSWORD, the password comes from the compose file and can't be changed in the app. Edit it there and run docker compose up -d.
• If you've forgotten it, see Password and factory reset on EpilykosOS. On Docker, set SETTINGS_PASSWORD under environment: in the compose file.

Use at least 12 characters. Epilykos won't open to the internet (with Tailscale's Open to the internet or a Cloudflare Tunnel) with a shorter password. A shorter password you set earlier still signs you in, but change it before you switch on remote access.

Epilykos uses a few different passwords, each with its own rules:

Two-step sign-inCopy Anchor Link

Two-step sign-in asks for a 6-digit code from an authenticator app (Google Authenticator, Microsoft Authenticator, 1Password and the like) after your password. It's free and works without an internet connection.

A few things worth knowing:

• Codes only match if the box's clock is within about a minute of your phone's. A box without internet can slowly drift; if a code is refused, the sign-in page shows you the box's time, and a recovery code always works.
• Each code works only once, so nobody can reuse one they've seen, and after five wrong codes you're sent back to the password.
• The setting is kept in data/two-step.json, with its secret encrypted by the app's encryption key. A database backup doesn't include it, so a restored box starts with two-step sign-in off.

Locked out of two-step sign-inCopy Anchor Link

Resetting the admin password also switches two-step sign-in off, so a lost phone never locks you out for good.

• On EpilykosOS, put a dashboard-password.txt file on the boot drive, or run sudo epilykos-reset-password on the console. See Password and factory reset.
• On Docker, use the RESET_TWO_STEP switch:

Saved passwords and tokensCopy Anchor Link

The passwords and tokens you save in Settings (for Solcast, MQTT, Home Assistant, Tuya, notification channels, the Cloudflare tunnel and so on) are stored encrypted, with a key kept in data/encryption-key. To move them to another box, see Backup and restore.