Access & Authentication

Reaching the dashboard

ProxMenux Monitor binds to 0.0.0.0:8008. There are three common ways to reach it:

# 1) Direct on the LAN
http://<proxmox-ip>:8008

# 2) Behind a reverse proxy with a dedicated host name (recommended off-LAN)
https://monitor.example.com

# 3) Through Secure Gateway (Tailscale) — same LAN URL, from anywhere
http://<proxmox-lan-ip>:8008      # works from any device on your tailnet

Direct access matches what the systemd unit ships out of the box. The reverse-proxy and Secure Gateway sections below cover the other two. The Monitor honours X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host so URLs and CORS work behind any of them without manual configuration.

First-launch flow

The first time you open the dashboard, the frontend calls GET /api/auth/status. If the auth config has never been written (configured: false), a single dialog appears titled "Protect Your Dashboard?" with two choices:

Creating the first user

Clicking Yes, Setup Password opens a single form that creates the account and, optionally, seeds the user's profile in one go so the avatar appears in the header right after saving. The fields are:

Avatar menu and profile page

Once authentication is configured, an avatar circle appears at the top-right of every dashboard page next to the theme toggle. Clicking it opens a small dropdown with shortcuts to the profile page and the Security tab, plus a Sign out action — closing the session can be done from here or from the Security tab, whichever is closer to where you are.

The profile page itself is a small card with an avatar preview, the username (read-only), and the display name with an inline edit button. Avatar uploads, replacements and removals are atomic — the header avatar refreshes automatically when any of them succeed, so there is no need to reload the page. The same set of endpoints documented in the next section are used by both the create-user form and the profile page.

Password authentication

After Set up, every API call (except the few public endpoints listed below) requires a JWT in Authorization: Bearer <token>:

• Session token (login): 24-hour expiration. Issued by POST /api/auth/login.
• API token (integrations): 365-day expiration. Issued by POST /api/auth/generate-api-token. Documented separately in the next section.

Login flow

# Without 2FA
curl -X POST http://<host>:8008/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<password>"}'

# Response
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

With 2FA enabled, the same call returns requires_totp: true first. Re-issue with the 6-digit code:

curl -X POST http://<host>:8008/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"<user>","password":"<password>","totp_token":"123456"}'

Public endpoints (no token)

These are the only endpoints that work without authentication, even when auth is enabled:

• /api/auth/login, /api/auth/status, /api/auth/setup — the auth flow itself, by necessity.
• /api/system-info — lightweight system snapshot (hostname, uptime, health.status). The right endpoint for external probes (Uptime Kuma, load-balancer health checks, status pages).

Cryptography and storage

ProxMenux Monitor is open source — none of this is secret. Documenting the stack here explicitly is a deliberate choice: operators who store credentials on their host deserve to know how those credentials are protected before they decide to trust them. The algorithms below are the same ones the code in scripts/auth_manager.py uses; this section is a contract, not a marketing promise.

Recovering a lost password

There is no online "forgot password" flow — by design, since the dashboard runs on the operator's own host and the recovery path is shell access to that host. ProxMenux ships a guided reset inside the configuration menu so you don't have to hand-edit auth.json:

# 1. Run the ProxMenux menu as root
menu

# 2. Settings → Reset ProxMenux Monitor Password
#    The menu will:
#     - Back up auth.json to auth.json.bak-<UTC timestamp>
#     - Stop the proxmenux-monitor service
#     - Clear username / password_hash / TOTP secret / backup codes
#     - Keep jwt_secret and api_tokens intact
#     - Restart the service

# 3. Open the dashboard at http://<host>:8008
#    The setup wizard appears — create a new admin account.

Two-Factor Authentication (TOTP)

2FA adds a second factor on top of your password: a 6-digit code that rotates every 30 seconds, generated on a phone or password manager you control. Even if someone obtains the password, they still can't log in without the code from your device. ProxMenux Monitor implements the standard TOTP protocol (RFC 6238), so any authenticator app works.

Pick an authenticator app

If you already use one for Google / GitHub / your bank, that one will work — skip to the setup walkthrough. If not, here's a survey of common options. All of them are free; the differences are mainly about which platforms they run on and how (or whether) they back up your secrets.

Step-by-step setup from the dashboard

1. Install the authenticator app on your phone (or open your password manager). One of the apps from the table above. You only need to do this once — the same app will hold codes for every service you protect.
2. Log into the dashboard with your username and password.
3. Open the Security tab in the dashboard sidebar, then click Enable 2FA. A dialog opens with a QR code, a long string in Base32 format and ten short codes labelled "backup codes".
4. Add the entry to the authenticator app:
   • Easy path: in the app, tap Add account → Scan QR code, point the camera at the QR on the screen. The app names the entry automatically (something like ProxMenux Monitor (your-username)) and starts showing a 6-digit code that refreshes every 30 seconds.
   • Manual fallback (when scanning isn't possible — e.g. setting up on the same phone you opened the dashboard with): tap Add account → Enter setup key. Type any name (e.g. Proxmox Monitor), paste the Base32 string from the dialog, leave Type as Time-based, save.
5. Save the backup codes. Copy the ten codes somewhere safe — a password manager, an encrypted note, a printed copy in a drawer. Treat them like spare keys: each works exactly once and gets you in if your phone is gone or broken.
6. Confirm by typing the current 6-digit code from the app into the "Verification code" field of the setup dialog and submit. Codes refresh every 30 seconds, so if it expires while you're typing, just enter the next one.
7. Done. 2FA is now active. Next time you log in, the dashboard asks for the password first; once it's accepted it asks for the current 6-digit code.

Lost authenticator

Three escape hatches, in order of how disruptive they are:

• Use a backup code. At the login screen, in the TOTP field, type one of the ten codes you saved at setup time. Each works once and is then consumed; the remaining codes still work. Once you're in, regenerate 2FA from Settings to get a fresh ten.
• Restore the authenticator from cloud / backup. If your app has a cloud sync (Google, Microsoft, Authy, Apple Passwords via iCloud Keychain, Ente, 2FAS) install it on a new device, sign in, and the entries reappear. If your app uses an encrypted export file (Aegis, Raivo, FreeOTP+), install the app on the new device and import the file.
• Disable 2FA from the host shell. When the previous options aren't available, edit /root/.config/proxmenux-monitor/auth.json on the Proxmox host (you need root SSH or console access), set totp_enabled to false, save, and restart the service:

  systemctl restart proxmenux-monitor.service

You can log in with username + password only, then re-enable 2FA from Settings.

Disable 2FA

From the dashboard, open the Security tab and click Disable 2FA. The endpoint POST /api/auth/totp/disable requires the current password as confirmation, then deletes the TOTP secret and clears the backup codes. Remember to also remove the entry in the authenticator app — the app doesn't know the server side is gone, so the dead entry will sit there forever otherwise.

API tokens (long-lived)

Browser sessions expire after 24 hours. For unattended integrations (Homepage widgets, Home Assistant sensors, Grafana scrapers, Uptime Kuma probes…) you generate a separate API token that lives 365 days. The token is a JWT signed with the same secret as the session token, but its token_name claim makes it easy to track and revoke individually.

Generate a token

From the dashboard:

1. Navigate to the Security tab → API Access Tokens section.
2. Type a descriptive name (e.g. "Home Assistant").
3. Re-enter your password. If 2FA is on, also the current 6-digit code.
4. Click Generate Token. The token appears once — copy it immediately.

From the command line:

curl -X POST http://<host>:8008/api/auth/generate-api-token \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "<your-password>",
    "totp_token": "123456",
    "token_name": "Home Assistant"
  }'

# Response — the "token" field is the only place the token appears.
{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_name": "Home Assistant",
  "expires_in": "365 days"
}

Use a token

curl -H "Authorization: Bearer <api-token>" \
  http://<host>:8008/api/system

Revoke a token

From the panel above: each row has a Revoke action that adds the token hash to revoked_tokens in auth.json. Revoked tokens fail validation immediately on the next request.

# Same operation via API
curl -X DELETE http://<host>:8008/api/auth/api-tokens/<token-id> \
  -H "Authorization: Bearer <session-token>"

Full storage best-practices and integration recipes live in API Reference → Token Management and Integrations.

HTTPS

Two paths to TLS:

1. Reverse proxy (recommended). Terminate TLS on Nginx / Caddy / Traefik and forward HTTP on port 8008 to the Flask process. Snippets below.
2. Direct HTTPS in the AppImage. Configure a certificate via POST /api/ssl/configure (UI: Settings → SSL). When SSL is configured the process switches from Flask's dev server to gevent.pywsgi with the gevent-websocket handler so WebSocket terminal also works over WSS. The cert files live wherever you point them; the paths are stored in the SSL config.

Secure Gateway (Tailscale)

Reverse proxies are the classic answer to "reach the dashboard from outside" but they require a public domain, certificate, and an open port on the edge. Secure Gateway is the zero-port alternative shipped inside the Monitor itself — a pre-built deployable app that spins up an Alpine LXC running Tailscale as a subnet router. Once joined to your tailnet, every device on it can hit the Monitor at the host's own LAN IP — from a laptop on holiday, a phone on 5G, or another node — without exposing TCP 8008 to the internet.

The deploy flow is one screen — pick the host LXC storage, paste a Tailscale auth-key (generated at login.tailscale.com/admin/settings/keys), choose which subnets to advertise, click Deploy. The LXC takes ~30 seconds to bootstrap and registers in the tailnet automatically.

Step-by-step deployment, subnet-routes configuration, Tailscale ACLs and Exit Node mode are documented separately in Dashboard → Security → Secure Gateway — that's where the deploy wizard lives in the dashboard UI. This page only covers the access pattern.

Reverse proxy snippets

The simplest layout is a dedicated host name for the Monitor (e.g. monitor.example.com) pointing at port 8008 on the Proxmox host. Snippets below use that pattern. Sub-path mounts (example.com/proxmenux-monitor/) are possible but require extra rewriting and are not the default — see the callout at the end.

Nginx

# /etc/nginx/sites-available/proxmenux-monitor.conf
server {
    listen 443 ssl http2;
    server_name monitor.example.com;

    ssl_certificate     /etc/letsencrypt/live/monitor.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/monitor.example.com/privkey.pem;

    location / {
        proxy_pass         http://127.0.0.1:8008;
        proxy_http_version 1.1;

        # WebSocket upgrade (terminal tab)
        proxy_set_header   Upgrade           $http_upgrade;
        proxy_set_header   Connection        "upgrade";

        # Real client IP — required for the auth log + Fail2Ban hook
        proxy_set_header   Host              $host;
        proxy_set_header   X-Real-IP         $remote_addr;
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_set_header   X-Forwarded-Host  $host;

        # Long-running terminal sessions
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
    }
}

Caddy

# Caddyfile
monitor.example.com {
    reverse_proxy 127.0.0.1:8008 {
        # Caddy auto-handles WebSocket upgrades and forwards X-Forwarded-* by default.
        header_up Host {host}
        header_up X-Real-IP {remote}
    }
}

Traefik (labels — Docker / Kubernetes)

# docker-compose snippet, or equivalent IngressRoute on Kubernetes
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.proxmenux.rule=Host(`monitor.example.com`)"
  - "traefik.http.routers.proxmenux.tls=true"
  - "traefik.http.routers.proxmenux.tls.certresolver=letsencrypt"
  - "traefik.http.services.proxmenux.loadbalancer.server.port=8008"
  # WebSocket and forwarded headers are on by default in Traefik.

Audit log

Every authentication event (success and failure) is appended to /var/log/proxmenux-auth.log in a single line, syslog-style format:

# Failed login from 192.0.2.10 (real IP recovered from X-Forwarded-For)
2026-04-24 14:32:11 WARNING proxmenux.auth: authentication failure; rhost=192.0.2.10 user=admin

# Successful login
2026-04-24 14:32:18 INFO    proxmenux.auth: authentication success;  rhost=192.0.2.10 user=admin

Tail it the usual way: tail -F /var/log/proxmenux-auth.log. The file is rotated by logrotate if a config drop-in is added; the Monitor itself does not rotate it.

Optional: Fail2Ban jail

When Fail2Ban is installed, the ProxMenux integration ships a [proxmenux] jail that:

• Reads /var/log/proxmenux-auth.log.
• Matches the authentication failure; rhost=<ip> pattern with a dedicated filter.
• Bans the offending IP at the kernel firewall level by default.
• Is queried by the Flask before_request hook every 30 s — so even when the firewall can't block (because the connection comes from the reverse proxy), the application returns HTTP 403 to banned IPs based on what Fail2Ban knows.

Configuration, ban time tuning and unban procedures are in Security → Fail2Ban.

Troubleshooting

rm /root/.config/proxmenux-monitor/auth.json
systemctl restart proxmenux-monitor.service

curl -H "Authorization: Bearer <token>" \
  http://<host>:8008/api/system | jq .

Where to next

• API Reference → Token Management — full lifecycle of API tokens (generate / list / revoke), security best-practices, secrets storage patterns.
• Integrations — Homepage, Home Assistant, Grafana / Prometheus, Uptime Kuma, generic cURL.
• Dashboard → Security → Secure Gateway — deploy the Tailscale gateway LXC step by step (subnet routes, ACLs, Exit Node mode).
• Security → Fail2Ban — how to install and configure the optional jail.
• Settings → ProxMenux Monitor — start / stop the systemd service from the ProxMenux TUI.