Skip to content

Admin dashboard

An optional web console for self-hosters who want to manage users, inspect audit logs, and watch signups. It is a separate container (VoltiusApp/admin-dashboard) and is not required to run the server.

Designed for private networks

The dashboard ships behind a shared email+password login and is meant to be exposed only on a private network (Tailscale, VPN, LAN). Do not put it on the public internet.

What you can do

  • View user accounts, devices, and presence.
  • Search, filter, ban/unban, and soft-delete users.
  • Extend trials, follow the promo funnel on the hosted service (offers shown, trials activated, trial-to-paid), and set per-user feature flags.
  • Inspect the admin audit log.
  • Track signups and churn over time.
  • Clear a user's two-factor authentication. For someone who lost every second factor and their recovery codes. It removes the authenticator app and all passkeys. Accounts with two-factor on show a Two-factor authentication section on the user panel; Clear asks for a second click, is written to the admin audit log and ends that user's sessions. They still need their master password to sign in. Check who is asking first: there is no other reset path, by design.
  • Set a user's handle. On a user's page, type a new handle and save. The old one is retired and can't be reused. This works whether or not HANDLES_FROM_EMAIL is on.
  • Derive handles from email. With HANDLES_FROM_EMAIL=true, the Handles page lists every account whose handle doesn't match its email, and what it would become. Apply renames the accounts it can, oldest first. The rest are marked "set by hand": their handle is taken by someone else, reserved, or not valid. Any account whose email isn't verified yet will be renamed automatically once it verifies.

When the dashboard detects the backend is self-hosted (via GET /v1/meta), all Lemon Squeezy widgets — MRR, paying subscribers, revenue, recent orders — and the promo funnel, which only applies to the hosted service, are hidden automatically. You only see operational metrics that actually apply to a self-hosted setup.

Run it

The backend needs ADMIN_SECRET set so it accepts admin requests:

# server/.env
JWT_SECRET=...
ADMIN_SECRET=<32-byte hex, same value as the dashboard>

Then in a separate directory:

git clone https://github.com/VoltiusApp/admin-dashboard
cd admin-dashboard

cat > .env <<EOF
ADMIN_API_URL=http://<server-host-ip>:14372
ADMIN_SECRET=<same value as server/.env>
ADMIN_EMAILS=you@example.com
ADMIN_PASSWORD=$(openssl rand -hex 16)
COOKIE_SECURE=false
EOF

docker compose up -d

voltius-server:8080 works only if you attach the dashboard to the server's Docker network (networks: [voltius-server_default], declared external); the two compose projects don't share one by default.

The dashboard binds to host port 3001 on every interface. Open http://<tailscale-ip>:3001/admin/login and sign in with one of the emails in ADMIN_EMAILS plus the shared ADMIN_PASSWORD.

Required environment

Variable Purpose
ADMIN_API_URL URL of the Voltius backend as the dashboard container can reach it (e.g. http://<server-host-ip>:14372)
ADMIN_SECRET Shared secret sent to the backend as X-Admin-Key. Must match the server's ADMIN_SECRET.
ADMIN_EMAILS Comma-separated list of emails allowed to log in
ADMIN_PASSWORD Shared password for all admin emails
COOKIE_SECURE true if you serve the dashboard over HTTPS, otherwise false

Warning

ADMIN_SECRET grants full control over every account on your server — reading account data, changing tiers and handles, banning and deleting users. Treat it like any other production secret, never commit it, and don't expose port 3001 to the internet.