From 14748c28fbd01673e86023d47a3dd139f1be850d Mon Sep 17 00:00:00 2001
From: Jeroen Ubbink <jeroen@blackbyte.nl>
Date: Fri, 26 Jun 2026 14:33:09 +0200
Subject: [PATCH] docs: document ROUTSTR_SECRET_KEY and first-run admin
 password

Explain that ROUTSTR_SECRET_KEY is now mandatory (with the generation command)
and describe the first-run flow where a temporary admin password is logged once.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .env.example | 13 +++++++++++--
 README.md    | 19 +++++++++++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/.env.example b/.env.example
index 81138cc6..e0dbae73 100644
--- a/.env.example
+++ b/.env.example
@@ -5,7 +5,17 @@ UPSTREAM_API_KEY=your-upstream-api-key
 # Tinfoil (confidential inference enclaves, EHBP)
 # TINFOIL_API_KEY=your-tinfoil-api-key
 
-# ADMIN_PASSWORD=secure-admin-password
+# Secret key used to encrypt secrets at rest (REQUIRED). The node refuses to
+# start without it. Generate one with:
+#   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+ROUTSTR_SECRET_KEY=
+
+# The admin password and the Nostr identity (nsec) are NOT set here. The admin
+# password is generated and logged once on first start (read it from the logs to
+# sign in); both are managed afterwards from the admin UI and stored encrypted in
+# the database. ADMIN_PASSWORD / NSEC are still read once as a legacy seed for
+# existing deployments, but new nodes should set them in the UI — a value left in
+# .env is ignored once the node has been configured.
 
 # Database
 # DATABASE_URL=sqlite+aiosqlite:///keys.db
@@ -13,7 +23,6 @@ UPSTREAM_API_KEY=your-upstream-api-key
 # Node Information
 # NAME=My Routstr Node
 # DESCRIPTION=Fast AI API access with Bitcoin payments
-# NSEC=nsec1...
 # HTTP_URL=https://api.mynode.com
 # ONION_URL=http://mynode.onion (auto fetched from compose)
 # RELAYS="wss://relay.damus.io,wss://relay.nostr.band,wss://eden.nostr.land,wss://relay.routstr.com"
diff --git a/README.md b/README.md
index da66b107..767bacae 100644
--- a/README.md
+++ b/README.md
@@ -55,19 +55,34 @@ If you are a node runner, start a Routstr Core instance using Docker Compose:
 
 1. **Prepare your `.env`**:
    ```bash
-   ADMIN_PASSWORD=mysecretpassword
+   # Required: encrypts secrets at rest. The node won't start without it.
+   ROUTSTR_SECRET_KEY=<generated-key>
    NAME="My AI Node"
    DESCRIPTION="Fast access to models"
    NSEC=yournsec
    RECEIVE_LN_ADDRESS=yourname@wallet.com
    ```
 
+   Generate `ROUTSTR_SECRET_KEY` once and keep it stable — changing it makes
+   previously encrypted secrets unreadable:
+   ```bash
+   python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+   ```
+
 2. **Start the services**:
    ```bash
    docker compose up -d
    ```
 
-3. **Configure**:
+3. **Get your admin password**:
+   On first start the node generates an admin password and logs it once with the
+   `/admin` URL. Read it from the logs:
+   ```bash
+   docker compose logs routstr | grep -i admin
+   ```
+   (Lost it? Reset with `python scripts/reset_admin_password.py --regenerate`.)
+
+4. **Configure**:
    Open [http://localhost:8000/admin/](http://localhost:8000/admin/) to connect your AI providers and set pricing.
 
 For full instructions, see the **[Provider Quick Start Guide](https://docs.routstr.com/provider/quickstart/)**.