Homy is a modular, self-hosted homepage dashboard with drag-and-drop widgets, multi-tab layouts, integrations, and a full admin area — built for homelab and daily-driver use.
Warning
This project is currently in alpha and may contain various bugs. Any help with identifying and reporting issues is greatly appreciated.
Homy separates integrations (credentials & APIs) from widgets (what you see on the grid). Configure Pi-hole, Jellyfin, Zabbix, arr, Discord, and more once, then drop widgets on any tab.
# Install (production)
pip install .
# Start dashboard (Waitress, port 8080)
homy
# Custom port
homy -p 9090
# or
homy --port 9090
# Development server (hot reload)
homy --dev
# Verbose terminal logs
homy --debug
# Reset a local user's password (CLI only, then exit)
homy -rP myuser
# or
homy --reset-password myuserOpen http://localhost:8080. On first run, create the admin account in the setup wizard. Data lives under ~/.homy/homy.db (override with DATA_DIR).
| Flag | Description |
|---|---|
-p / --port |
Listen port (default: 8080, env PORT) |
--host |
Listen host (default: 0.0.0.0, env HOST) |
--debug |
Verbose logging (favicon cache, HTTP, modules) |
--dev |
Flask dev server instead of Waitress |
-rP / --reset-password |
Reset local user password interactively, then exit |
| Feature | Homy |
|---|---|
| Drag-and-drop grid (24 columns) | Yes, per tab |
| Multi-user + roles | Yes |
| Integration credential vault | Yes |
| Built-in + ZIP integrations | Yes |
| Widget builder from JSON paths | Yes |
| Silent background refresh | Yes |
| Themes + custom per-user colors | Yes |
| Tab backgrounds (media library) | Yes |
| Password reset (SMTP + 6-digit code) | Yes |
| OIDC / SAML / LDAP / MFA | Yes (admin) |
| Docker | Yes |
Everything runs in one single-page app (frontend/), shared with the browser add-on:
- Dashboard:
Eedit mode, drag by the header, resize at the corner, arrows/Shift+arrows move/resize the focused widget, Undo instead of confirm dialogs,Ctrl+K//command palette, fit-to-screen row height. - Tabs: all tabs are rendered in the background (instant switching); per-tab background image, rename, duplicate, reorder (edit mode → double-click or right-click a tab). Desktop, mobile and public layouts.
- Widget appearance: hide header, hide action buttons, fully transparent, background opacity, title/body font size, accent color, refresh interval — same config keys as before, so existing layouts keep their look.
- Pages: Favorites, Integrations (with connection test), Settings (appearance, wallpaper, profile, password, 2FA, notifications, media, layout backup, add-on tokens) and Administration (health, system, users & groups, sign-in incl. LDAP/OIDC/SAML, mail & API, security, activity log, services & jobs, modules/integrations/ZIP packages, media, full backup/restore). Lists are paginated (20 per page).
- Guests: visitors who are not signed in get a start page (clock, search, sign-in, password reset, registration, first-run setup) — or the public layout when Administration → System → Guests see the public layout is on.
- Background preloading: the server refreshes widget data on a schedule (Preload widget data, default 120 s), so dashboards and the add-on show current values instantly even when nobody had Homy open.
- Browser add-on: standalone start page with local tabs, optionally synced with Homy; paints from its local copy
immediately and refreshes in the background every 10 minutes (see
browser-extension/README.md). - The classic UI stays reachable at
/classicduring the transition.
Building the frontend needs Node.js 22 (cd frontend && npm ci && npm run build); the Docker image builds it automatically.
API v2 (/api/v2/bootstrap, /api/v2/layout, /api/v2/tokens, /api/v2/public) also accepts Authorization: Bearer homy_pat_….
Integrations — configure under Integrationen (URL, API keys).
Widgets — add to the dashboard; they reference integration_id or use display modules (metric_display, favorites, clock, …).
Service-specific UIs (Pi-hole, Zabbix host status, Discord, Overseerr, …) ship under homy/integrations/<id>/widgets/.
| Group | Examples |
|---|---|
| arr | Radarr, Sonarr, Lidarr, Prowlarr, Bazarr |
| Download | qBittorrent, SABnzbd |
| Media | Jellyfin, Emby, Plex, Tautulli, Overseerr, Immich |
| Network | Pi-hole, AdGuard Home |
| Monitoring | Zabbix, Grafana, Uptime Kuma, Glances, Proxmox |
| Other | Discord, Home Assistant, Weather, JSON API, RSS |
docker compose up -dMaps 8080:8080. Persist data with a volume on DATA_DIR (default in container: configure via env).
When you bump version in pyproject.toml and push to main/master, GitHub Actions creates a release and publishes:
ghcr.io/<owner>/homy:<version> and :latest
Example (replace owner/repo):
docker pull ghcr.io/<owner>/homy:latest
docker run -d --name homy -p 8080:8080 \
-v homy-data:/app/data \
-e SECRET_KEY=change_me \
ghcr.io/<owner>/homy:latestManual re-run: Actions → Release & Docker → Run workflow (optional Force release).
- Raise
versioninpyproject.toml(e.g.0.1.0→0.2.0). - Commit and push to
mainormaster. - Workflow
.github/workflows/release.ymltagsv<version>, creates a GitHub Release, and pushes the Docker image to GHCR.
| Variable | Purpose |
|---|---|
PORT |
HTTP port (default 8080) |
HOST |
Bind address (default 0.0.0.0) |
SECRET_KEY |
Flask session secret (required in production) |
DATA_DIR |
SQLite, uploads, favicon cache (default ~/.homy) |
FLASK_ENV |
production or development |
WAITRESS_THREADS |
Worker threads (default 8) |
# Windows
.\scripts\run-dev.ps1# Linux / macOS
./scripts/run-dev.shEditable install: pip install -e . then homy --dev.
The Homy Companion extension (Firefox, Chrome, Opera) lives in browser-extension/. It connects to your Homy server, syncs selected favorites to browser bookmarks, caches the desktop dashboard for the new-tab page, and can download layout backups locally.
cd browser-extension && npm run buildRelease builds attach homy-<version>-chrome.zip, homy-<version>-firefox.zip, and homy-<version>-opera.zip to GitHub Releases. See browser-extension/README.md.
Issues and pull requests are welcome. For larger changes, open an issue first to align scope.
See repository license file. Homy is provided as is
This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details.