Dashboard Configuration
Most AMUD settings are managed in the web UI under Settings (admin login required). This page covers appearance layout and media integrations.
Appearance
Open Settings → Appearance to customize the dashboard look and layout.
Grid columns
The Grid columns dropdown controls how many app cards appear per row on desktop screens:
| Value | Use case |
|---|---|
| 2 | Large cards, fewer columns |
| 3 | Default balanced layout |
| 4 | Dense homelab with many services |
| 5 | Maximum density on wide monitors |
The setting is stored as grid_columns in the SQLite settings table (default: 3). On smaller viewports, the layout automatically reflows to fewer columns for mobile and tablet screens.
Other appearance options on the same tab include accent color, glass blur/opacity, background image, logo, and bento card radius.
Media integrations (Jellyfin & Plex)
Open Settings → Integrations to connect live stream detection for Jellyfin and Plex cards on the dashboard.
When credentials are missing, stream badges show NOT CONFIGURED. When configured, badges start as CHECKING... and update from live session polling plus LXC/Docker telemetry.
Jellyfin
| Field | Description |
|---|---|
| Jellyfin URL | Base URL of your server, e.g. http://jellyfin.local:8096 |
| Jellyfin API Key | API key from Jellyfin admin |
Create an API key in Jellyfin:
- Open Jellyfin as an administrator.
- Go to Dashboard → Advanced → API Keys.
- Click + to create a key (e.g. name it
AMUD). - Paste the key into AMUD Settings → Integrations.
AMUD polls:
GET /Sessions
X-Emby-Token: <your-api-key>
The API key is sent in the X-Emby-Token header (Emby/Jellyfin convention), not as a query parameter.
Plex
| Field | Description |
|---|---|
| Plex URL | Base URL of your Plex server, e.g. http://plex.local:32400 |
| Plex Token | X-Plex-Token for your account |
Find your Plex token:
- Sign in to plex.tv and open your server, or
- Use Plex's documented token claim flow for your account, or
- Inspect an authenticated Plex web request in browser DevTools for the
X-Plex-Tokenheader.
AMUD polls:
GET /status/sessions
X-Plex-Token: <your-token>
When multiple clients are streaming, the badge may show the primary title plus (+N more).
Smart Home Integration (Home Assistant)
Connect your dashboard to Home Assistant to view live sensor telemetry directly inside the Home Assistant app card.
- Open Settings → Smart Home.
- Enter your Home Assistant URL (e.g.
http://homeassistant.local:8123). - Enter your Long-Lived Access Token (created from your user profile in HA).
If you have an application named exactly Home Assistant on your dashboard, its telemetry will now include the number of active lights, switches, and average home temperature.
AMUD polls Home Assistant using the lightweight Template API (POST /api/template) to compute those counts on the HA host, falling back to the full /api/states dump only when template rendering is unavailable.
Custom CSS Injection
Make the dashboard truly yours by overriding the default styling.
- Open Settings → Appearance → Custom CSS.
- Copy CSS from the Theme Gallery (preview screenshots help you pick a theme), or write your own.
- Paste into the Custom CSS field and click Save. Changes apply immediately for all users.
(Note: If invalid CSS breaks the layout, see Troubleshooting for recovery.)
Browse themes with preview screenshots on the Theme Gallery — click Copy CSS, paste, and save. See also the CSS variable reference.
Proxmox and container control
Live RUNNING / STOPPED badges and start/stop controls require:
- A valid Proxmox API token under Settings → Proxmox VE
- Matching container IDs or Docker names on app cards
- A working amud-agent on the hypervisor host
See Proxmox VE Installation for token setup.
Environment variables
These are set on the server or agent process (Docker environment:, systemd unit, or shell). Most day-to-day options live in the SQLite settings table via the UI.
| Variable | Component | Default | Description |
|---|---|---|---|
PORT | Server | 8000 | HTTP listen port |
BIND_ADDR | Server | 127.0.0.1 | Bind address. Use 0.0.0.0 in Docker so the container accepts external traffic. |
DB_PATH | Server | data/amud.db | SQLite database file path |
AMUD_SECRETS_KEY | Server | auto-generated file | 32-byte key (base64url or 64-char hex) for encrypting integration tokens at rest in SQLite. If unset, AMUD writes data/.amud-secrets-key on first boot — back it up with amud.db. |
AMUD_AGENT_SECRET | Both | (required) | Shared secret for agent ↔ server IPC authentication |
AMUD_SOCKET_PATH | Both | /var/run/amud/amud.sock | Unix socket path for agent IPC |
AMUD_ENABLE_PROXMOX | Server | false | Set true on a Proxmox LXC host to show the Proxmox settings tab |
AMUD_DOCKER | Agent | 0 | Set 1 to enable Docker socket monitoring (requires socket mount) |
PVE_NODE | Agent | hostname | Proxmox node name for LXC API calls when it differs from /etc/hostname |
PVE_API_TOKEN | Agent | (none) | Proxmox API token; prefer setting on the agent host instead of over IPC |
Public telemetry
In Settings → Privacy & Access, the Guest system telemetry visibility toggle stores telemetry_public in SQLite. When enabled, anonymous visitors and Guest-role users see host CPU model, usage, memory, GPU (when reported by the agent), and network stats on the dashboard. Container names, VMIDs, per-app metrics, streams, and admin controls stay hidden.
Troubleshooting configuration issues
| Symptom | See |
|---|---|
| Streams show NOT CONFIGURED | Media Integrations |
| Apps stuck on CHECKING... | Troubleshooting — Proxmox token and agent IPC |
| Old UI after upgrade | PWA / Browser Cache |
| Dashboard UI is broken | Custom CSS Recovery |