Restarts and Unlocking
Overview
Your node keeps its protected secrets locked when it starts. With the default setup, a node that has restarted is running but locked: it serves the admin console, but not Safes. An Administrator must sign in to /admin and choose Unlock Node before Safes are available again.
Signing in and unlocking are separate steps. A running container alone does not mean the node is serving Safe traffic.
What happens after a restart
The launcher creates the container with Docker's unless-stopped restart policy, so Docker normally starts the container again when the server reboots. The node then starts in the locked state.
While the node is locked, only a narrow public surface is available: health, capabilities, the admin assets and admin bootstrap, plus the files an existing browser installation needs to recover. Safe APIs, archive transfers, other hosted client content and federation services stay unavailable until the node is unlocked.
Unlock the node
- Open
https://node.example.com/admin, using your permanent hostname. - Choose Sign in with an admin key and use a registered admin passkey or security key and PIN.
- Choose Unlock Node.
- Open Diagnostics and refresh Node Health.
- Open the Safe app and confirm a Safe opens.
Tip
Test a restart and unlock with your separate recovery security key before you rely on it. In Access, register the key, verify a fresh sign-in, then restart the node and use that key for the first unlock.
Stop, start and restart the node
These commands use the default container name unolock-node:
sudo docker stop unolock-node
sudo docker start unolock-node
sudo docker restart unolock-node
sudo docker logs --since 10m --tail 500 unolock-node
The launcher can also start an existing stopped container and print its admin URL:
sudo sh packaging/docker/run-node.sh --engine docker
Starting an existing container keeps its hostname, data and image. It does not reinstall the node or apply an upgrade. Sign in and unlock after every start.
Warning
Do not delete or recreate the persistent volume during an ordinary restart. Never run two containers against the same data volume.
Unlock policies
The node's startup unlock policy is one of:
| Policy | Use |
|---|---|
admin-required |
The default. An Administrator signs in and explicitly unlocks the node after every start. |
tpm-unattended |
Unattended unlock using TPM hardware sealing, where explicitly configured and supported by the host. |
unlocked |
Development posture only. |
Key protection for a production node is one of tpm, admin-unlock or admin-unlock-tpm, chosen to match the deployment. dev key protection is for local testing only, and production startup rejects it.
Optional TPM 2.0 hardware sealing
Unattended hardware sealing is optional. It needs a TPM 2.0 device and tpm2-tools on the host. Admin-required unlock without a TPM remains the default.
If you use TPM-backed key protection:
- The container needs access to the TPM device and tools. If the node does not start, check the TPM device and tools along with the other startup checks in Troubleshooting.
- Any maintenance container you run against the node's volume for an
admin-unlock-tpmdeployment must be given the same TPM device access as the node.
Changes that need a restart
Configuration saved in Settings is staged as pending configuration and promoted on the next start. After saving, restart the node, sign in and unlock to apply and verify it. Then repeat the Setup and Diagnostics checks. See Configuration.
FAQs
My Safe page is unavailable after a restart. What do I do?
Open /admin, sign in, and choose Unlock Node. The node is running but locked until an Administrator unlocks it.
Does signing in to the admin console unlock the node?
No. Signing in and unlocking are separate steps. After you sign in, choose Unlock Node explicitly.
Do I need a TPM?
No. A TPM is optional. Admin-required unlock without a TPM is the default. A TPM 2.0 device with tpm2-tools is needed only if you configure unattended hardware sealing.
Does a promoted standby unlock itself after a restart?
No. Restarting a promoted member still requires administrator sign-in and an explicit unlock. See Active/Standby and Failover.
Will restarting the node give me a new admin setup code?
No. Restarting an unconfigured node does not issue or print a replacement code. See Troubleshooting.