If you run more than two or three self-hosted apps on Proxmox, you already know the problem. You end up with a browser bookmarks folder full of IP addresses and ports, and you can never remember which one is Pi-hole and which one is your NAS. A dashboard fixes that by giving every service a tile with an icon, a name, and sometimes a live status widget, all on one page.
Homepage (also called "gethomepage") is one of the more popular options for this, and it happens to install in about five minutes using the Proxmox community-scripts project. This guide walks through the whole thing on Proxmox VE 9.2, from running the install command to fixing the one error almost everyone hits on their first try.
What You Will Learn
By the end of this tutorial you'll have a working Homepage dashboard running in its own LXC container, reachable from any device on your network. You'll know how to:
- Deploy the Homepage LXC using the community-scripts installer
- Find your container's IP address and open the dashboard in a browser
- Edit the YAML config files that control bookmarks, services, and widgets
- Fix the "Host validation failed" error that trips up almost every first-time user
- Keep the container updated and backed up
What Is This Feature?
Homepage is an open-source, self-hosted start page. Instead of a search engine or a blank new-tab page, you get a grid of tiles pointing at your own services: Proxmox itself, Pi-hole, Jellyfin, your router, whatever you run. Some tiles are just bookmarks. Others are "widgets" that pull live data, like Pi-hole's blocked-query count or a container's CPU usage, straight onto the tile.
It's built with Next.js and configured entirely through a handful of YAML files, so there's no database and nothing to click through in a setup wizard beyond the very first launch. You edit a text file, save it, and the dashboard usually updates without even needing a restart.
On Proxmox, the easiest way to run it is inside an LXC container. An LXC container is a lightweight, Linux-only virtual environment that shares the host's kernel instead of emulating its own hardware like a full VM does. That makes it start almost instantly and use a fraction of the RAM a VM would need for the same job, which is exactly what you want for something as small as a dashboard.
Why Would You Use It?
Honestly, you don't need Homepage for a homelab with two services. It starts paying off once you're past five or six, and it becomes genuinely useful once you're past ten, which happens faster than most people expect once they discover the *arr stack, a couple of monitoring tools, and three or four random utilities they installed at 1 a.m.
A few concrete reasons people set it up:
- One URL to remember instead of a dozen IP:port combinations
- Live widgets mean you can glance at disk space, download queues, or ad-block stats without opening each app
- It's a good default landing page for a browser new tab on a homelab-heavy machine
- Grouping and bookmarks make it easy to hand a limited view to family members who just want to open Jellyfin or request a movie
Prerequisites
Before you start, make sure you have:
- Proxmox VE 8.x or 9.x installed and reachable at
https://<your-ip>:8006 - Root access to the Proxmox web interface, or SSH access to the host
- At least 3 GB of free space on the storage where new containers get created, plus a bit of headroom for the Debian 13 template if you haven't downloaded one before
- A basic sense of your network's IP range, since you'll either let the container grab a DHCP address or assign it a static one
You don't need Docker knowledge or Node.js experience. The install script handles all of that inside the container for you.
Step-by-Step Tutorial
Step 1: Open the Proxmox VE shell
Log in to the Proxmox web interface, click your node in the left-hand tree, then click >_ Shell near the top of the page. This drops you into a root terminal on the Proxmox host itself, not inside any container.
Step 2: Run the community-scripts installer
Paste this into the shell and press Enter:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/homepage.sh)"This downloads the Homepage install script from the community-scripts GitHub repository and runs it immediately. You'll see a green Proxmox VE Helper-Scripts banner appear, followed by a prompt asking whether you want Default Settings or Advanced Settings.
Step 3: Choose Default or Advanced Settings
Default Settings is fine for a first run. It creates an unprivileged container, picks the next free container ID automatically, sets up networking over DHCP on the vmbr0 bridge, and allocates 2 CPU cores, 1 GB of RAM, and 3 GB of disk on your default storage.
Advanced Settings lets you pick the container ID, hostname, a static IP instead of DHCP, a different storage location, or more resources. If you already know you want a static IP so the dashboard's address never changes, go Advanced and set it here rather than fixing it later.
Step 4: Wait for the build to finish
The script downloads a Debian 13 template if you don't already have one cached, creates the container, installs Node.js inside it, clones the Homepage source, builds it, and sets up a systemd service to keep it running. This usually takes two to four minutes depending on your internet connection and disk speed.
When it's done, the script prints a summary with the container ID and the URL to reach your new dashboard, something like http://192.168.1.150:3000.
Step 5: Open the dashboard
Copy that URL into a browser on any device on the same network. You should see a default Homepage layout with a search bar and a small set of placeholder bookmarks. That's expected. The real work now is replacing those placeholders with your own services.
Step 6: Edit the config files
The container's config lives at /opt/homepage/config/. There are four files you'll touch most:
| File | What it controls |
|---|---|
bookmarks.yaml | Simple links with no live data, grouped under headings |
services.yaml | Tiles for your actual apps, optionally with live-data widgets attached |
widgets.yaml | Page-level widgets like a clock, weather, or system resources for the Homepage container itself |
settings.yaml | Overall look and feel: theme, layout columns, background |
You can edit these directly from the Proxmox shell with pct enter <ctid> followed by nano /opt/homepage/config/services.yaml, or mount the path over a network share and use your normal text editor. Either way works. A minimal services.yaml entry for a Jellyfin server looks like this:
- Media:
- Jellyfin:
href: http://192.168.1.120:8096
icon: jellyfin.png
description: Movies and TVSave the file. Homepage watches the config directory and reloads it within a few seconds, no restart needed for YAML changes.
Step 7: Fix the allowed-hosts warning before you forget about it
If you access the dashboard by IP and it works fine but later shows a blank page or a "Host validation failed" message after you set a hostname or reverse proxy, you'll need to add that hostname to HOMEPAGE_ALLOWED_HOSTS in /opt/homepage/.env. More on this in the Common Errors section below, but it's worth doing now while it's fresh, especially if you're planning to put this behind Nginx Proxy Manager or a similar reverse proxy later.
Commands Explained
| Command | What it does |
|---|---|
bash -c "$(curl -fsSL .../homepage.sh)" | Downloads and runs the Homepage install script from the community-scripts repository |
pct list | Run on the Proxmox host, lists every LXC container and its current status |
pct enter <ctid> | Drops you into a root shell inside the specified container; replace <ctid> with the container's ID number |
update | Typed inside the Homepage container's console, this community-scripts shortcut pulls the latest Homepage release and restarts the service |
systemctl status homepage | Run inside the container, shows whether the Homepage service is running or has crashed |
journalctl -u homepage -f | Streams the live log for the Homepage service, useful when a widget won't load or the page won't start |
Common Errors
"Host validation failed. See logs for more details." This is the single most common issue new Homepage users run into, and it isn't a Proxmox problem at all. Homepage checks the hostname in the request against an allow-list for security reasons. If you access it by an IP address that doesn't match what's in HOMEPAGE_ALLOWED_HOSTS, or later switch to a domain name behind a reverse proxy, you'll get a blank page and this error in the logs. Fix it by adding every hostname or IP:port combination you use to reach the dashboard into that variable, comma-separated, then restart the service.
A red "API Error" badge on a service tile almost always means the URL or API key you put in services.yaml is wrong, or the target service is on a different subnet the Homepage container can't reach. Double-check the address works from a browser first before assuming Homepage is broken.
If the page won't load at all and the browser just times out, the container itself may not have started, or it grabbed a different DHCP address than the one you're trying. Check both from the Proxmox host.
Troubleshooting
Start by confirming the container is actually running. From the Proxmox shell, run pct list and look for your container's status. If it says stopped, start it with pct start <ctid>.
Next, confirm the IP address hasn't changed. Click the container in the Proxmox web UI, open the Summary tab, and check the IP shown there. DHCP leases can shift after a reboot if you didn't set a static IP or a DHCP reservation, and that's a common reason "it worked yesterday and doesn't today."
If the container is up and the IP is right but the page still won't load, enter the container with pct enter <ctid> and check the service directly:
systemctl status homepage
journalctl -u homepage -fA YAML syntax error in one of the config files is a frequent cause of a service that starts but immediately crashes. YAML is picky about indentation, it uses spaces only, never tabs, and two-space steps are the convention Homepage's own examples use. If you just edited a config file and things broke right after, that's the first place to look. The journal log will usually name the exact file and line.
Finally, verify something is actually listening on port 3000 inside the container:
ss -tlnp | grep 3000If nothing shows up, the service isn't running, and the systemctl and journalctl output above should tell you why.
Best Practices
Give the container a static IP or a DHCP reservation on your router. Dashboards are exactly the kind of thing you bookmark once and forget about, so an address that changes on you is more annoying here than almost anywhere else.
Don't expose port 3000 straight to the internet. Homepage has no built-in login screen by default, which is fine on a trusted home network but not something you want reachable from outside without a reverse proxy and some form of authentication in front of it.
Back up the container regularly with Proxmox's built-in vzdump, either on a schedule through Datacenter > Backup or manually before any major config change. The whole thing is small, so backups are fast and cheap.
Keep an eye on updates by running the update command inside the container every so often. Homepage development moves quickly, and new widget integrations get added often enough that it's worth checking in every month or two.
Use groups in your YAML files even if you only have a handful of services right now. It's a lot less painful to add structure early than to reorganize forty entries later once your homelab has grown past what you expected.
Frequently Asked Questions
Is Homepage free and open source?
Yes. It's MIT-licensed and available on GitHub under the gethomepage organization, with no paid tier or account requirement.
Do I need Docker to run this on Proxmox?
No. The community-scripts installer sets it up as a native systemd service inside a Debian LXC container, so there's no Docker layer involved at all.
Can Homepage show stats from Proxmox itself?
Yes, Homepage has a Proxmox integration widget that can display node and guest status using an API token, which is worth setting up once you're comfortable with the basic config files.
How much RAM does this actually need for a small homelab?
The default 1 GB is generous for typical use. A dashboard with a dozen tiles and a few widgets usually sits well under 200 MB of active memory.
Is my dashboard visible to anyone outside my network?
Not by default. It only listens on your local network unless you specifically set up port forwarding or a reverse proxy that exposes it externally, which isn't something this guide covers or recommends without adding authentication first.
Can I run this alongside Nginx Proxy Manager or another reverse proxy?
Yes, and it's a common setup. Just remember to add your custom domain to HOMEPAGE_ALLOWED_HOSTS in the .env file, or you'll hit the host validation error described above the moment you switch from a raw IP address to a hostname.
Conclusion
Homepage is one of those small quality-of-life tools that feels unnecessary right up until you have it, and then you wonder how you managed a dozen self-hosted services without it. The install itself takes minutes. The config takes a bit longer only because you'll keep thinking of one more service to add.
Start with three or four of your most-used apps in services.yaml, get the allowed-hosts setting right the first time, and build the rest out as you go. It's much easier to expand a working dashboard than to get everything perfect before you've even opened it once.