hermes-config/skills/self-hosting/audiobookshelf-setup/references/heimdall-dashboard.md

Adding a Service to Heimdall Dashboard

After deploying a new self-hosted service, add it to the Heimdall dashboard for quick access.

Database Location

Heimdall stores items in SQLite at:

/var/lib/docker/volumes/heimdall_config/_data/www/app.sqlite

The volume name may vary — check with docker inspect heimdall.

Schema

items (
  id, title, colour, icon, url, description, pinned, "order",
  deleted_at, created_at, updated_at, type, user_id, class, appid, appdescription, role
)

Key columns for insertion:

• title — Display name
• url — Service URL
• colour — Hex colour (e.g., "#d48c3c")
• description — Short description
• type — "0" for standard items
• user_id — Usually 1
• class — For built-in app support: App\\SupportedApps\\Plex\\Plex (pattern: App\\SupportedApps\\<Name>\\<Name>). Use None for generic items.
• appid — None for generic items
• pinned — 0 (not pinned)
• "order" — Position in grid. Use SELECT MAX("order") FROM items + 1
• icon — "" (empty string, uses built-in favicon fetching)

Insert via Python

The DB is owned by root/Docker user. Access requires sudo:

import sqlite3

db = "/var/lib/docker/volumes/heimdall_config/_data/www/app.sqlite"
conn = sqlite3.connect(db)

max_order = conn.execute('SELECT MAX("order") FROM items').fetchone()[0]

conn.execute("""
    INSERT INTO items (title, colour, icon, url, description, pinned, "order", type, user_id, class, appid)
    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
""", (
    "Audiobookshelf",
    "#d48c3c",
    "",
    "http://192.168.50.98:13378",
    "Audiobooks & podcasts",
    0,
    max_order + 1,
    "0",
    1,
    None,
    None
))
conn.commit()
conn.close()

Pitfalls

• sqlite3 CLI may not be installed on the host — use Python's sqlite3 module instead
• "order" is a reserved word in SQLite — must be double-quoted in queries
• Items appear immediately in Heimdall — no restart needed