LNBits Admin UI

What you can do · First Run · Enable/Disable · Reset · Allowed Users · Guides

We introduced the Admin UI as the new default to make setup simpler and more straightforward. Instead of hand editing the .env file, you configure key server settings directly in the frontend with clear labels and guardrails.

On a fresh install the Admin UI is enabled by default, and at first launch you are prompted to create Super User credentials so that sensitive operations, such as switching funding sources, remain in trusted hands. When the Admin UI is enabled, configuration is written to and read from the database; for all settings managed by the UI, the parameters in .env are largely no longer used. If you disable the Admin UI, the .env file becomes the single source of truth again.

For privileged actions and role details see Super User & User Roles For a complete reference of legacy variables consult .env.example.

[!WARNING] Some settings remain .env only. Use .env.example as the authoritative reference for those variables.

What you can do with the Admin UI

• Switch funding sources and other server level settings
• Manage who can access LNbits (Allowed Users)
• Promote or demote Admin Users
• Gate extensions to Admins only or disable them globally
• Adjust balances with credit or debit
• Adjust site customization

[!NOTE] See Super User for the role and permission differences compared to Admin Users.

Onchain payments and key recovery

The super user can enable server-managed Bitcoin wallets in the Watchonly extension and core onchain wallets from Settings → Payments → Onchain payments:

1. Select Generate encryption key.
2. Download the key backup, store it securely, and confirm the backup.
3. Enable Allow onchain payments and select Save.

LNbits saves the generated key in .onchain_key inside LNBITS_DATA_FOLDER with owner-only file permissions. No environment variable or launch flag is required. The same key must be retained across restarts. All workers must share this key. The key encrypts hot wallet recovery phrases; it is excluded from ordinary settings responses. Disabling the toggle stops hot wallet creation and signing, while keeping wallet recovery available. Hardware/watch-only wallets are unaffected.

Download backup includes the generated key along with the data folder. Treat that archive as wallet recovery material. Keep a separate key recovery file as well, particularly when backing up only the database. Restore the database and data folder together; if the key file is missing, upload the original lnbits-onchain-key.json using Restore an encryption key in Payments settings. LNbits checks the key against the database and refuses a different key. Resetting settings preserves the key and its backup record.

Deployments using a secret manager can optionally set LNBITS_ONCHAIN_MASTER_KEY in the environment or .env (base64-encoded, 32 random bytes). The earlier WATCHONLY_MASTER_KEY name is also supported. Back up and confirm that key through the same UI before enabling hot wallets. Environment variables are not included in the full data-folder backup, so retain the separate key recovery file. Never replace a key that is already used by wallets.

First run and Super User ID

On first start with the Admin UI enabled you will be prompted to generate a Super User.

If you need to read it from disk later:

cat /lnbits/data/.super_user
# example
123de4bfdddddbbeb48c8bc8382fe123

[!WARNING] For security reasons, Super Users and Admin users must authenticate with credentials (username and password).

After login you will see Settings and Users in the sidebar between Wallets and Extensions, plus a role badge in the top left.

Enabling or disabling the Admin UI

The Admin UI is enabled by default on new installs. To change the state:

1. Stop LNbits

   sudo systemctl stop lnbits.service
   

2. Edit your .env

   cd ~/lnbits
   sudo nano .env
   

3. Set one of

   # Enable Admin UI
   LNBITS_ADMIN_UI=true
   
   # Disable Admin UI
   LNBITS_ADMIN_UI=false
   

4. Start LNbits

   sudo systemctl start lnbits.service
   

[!NOTE] With the Admin UI enabled, config is DB-backed and UI-managed settings ignore .env. Disable it to revert to .env as the single source of truth.

Reset to defaults

Using Reset to defaults in the Admin UI wipes stored settings. After a restart, a new Super User is created and the old one is no longer valid.

Allowed Users

When set at least one, LNbits becomes private: only the listed users and Admins can access the frontend. Account creation is disabled automatically. You can also disable account creation explicitly.

[!WARNING] Assign your own account first when enabling Allowed Users to avoid locking yourself out. If you do get locked out, use your Super User to recover access.

Additional Guides

• Backend Wallets — Explore options to fund your LNbits instance.
• User Roles — Overview of existing roles in LNbits.
• Funding sources — What is available and how to configure each.
• Install LNbits — Choose your preferred way to install LNbits.

Powered by LNbits

LNbits empowers everyone with modular, open source tools for building Bitcoin based systems — fast, free, and extendable.

If you like this project, send some tip love or visit our Shop