If you've already got a dozen self-hosted apps running on your Proxmox box — Jellyfin here, Pi-hole there, maybe a *arr stack tucked away on its own container — you've probably lost track of which IP address goes with which service. That's the exact itch Homarr is built to scratch, and it's different enough from the other homelab dashboards out there that it deserves its own walkthrough rather than a footnote on someone else's guide.
This is a from-scratch tutorial. You don't need to have touched Homarr, Docker, or even LXC containers before. We'll build the container, run the installer, log in for the first time, and get a working board with a couple of real integrations wired up.
What You Will Learn
- What Homarr actually is and how it's different from similar dashboard tools
- Why you might want it running on Proxmox VE specifically
- How to deploy it as an LXC container using the community-scripts installer
- How to create your admin account and finish first-time setup
- How to connect the Proxmox VE integration so your dashboard shows real VM and node stats
- What to do when the install hiccups, and how to keep the container healthy long term
What Is This Feature?
Homarr is a self-hosted start page — a single web dashboard where you put links, widgets, and live status tiles for every service you run. Instead of bookmarking twelve different admin panels, you open one page and everything's laid out in a grid you control.
Where it splits from tools like Homepage or Dashy is the engine underneath. Homarr isn't just a static page rendered from a config file. It runs on Node.js, stores your boards and users in a real SQLite database, and uses Redis for caching and session handling. That means it has actual user accounts with logins, a drag-and-drop board editor in the browser, and a permissions system if more than one person in your house needs access.
We're going to run it inside an LXC container. If you're new to Proxmox, an LXC container is a lightweight, Linux-only virtual environment — it shares the host's kernel instead of emulating its own hardware like a full VM does, so it starts in a second or two and uses a fraction of the RAM a VM would need for the same job. For something like Homarr, which is a single web app with modest requirements, an LXC container is the obvious fit.
Why Would You Use It?
The honest answer: because typing IP addresses and port numbers from memory gets old fast. Once you've got six or seven services running, a dashboard stops being a nice-to-have and starts being the thing that makes your homelab actually usable day to day.
Homarr's specific selling point is integrations. Beyond static bookmarks, it can talk to the services it's showing — pull download queues from your *arr apps, show container states from Docker or Portainer, and, relevant to this guide, pull live stats straight from Proxmox VE itself. You can have a tile on your board showing CPU load, memory usage, and running VM count for your node without opening the Proxmox web UI at all.
It's also genuinely multi-user in a way Homepage isn't. If your partner or roommate wants their own board with their own bookmarks and widget layout, Homarr supports that out of the box with separate logins. That's overkill for a single-person setup, honestly, but it's there if you need it.
I'll add one opinion here: if you just want a dead-simple page of links with zero setup fuss, Homepage is still the faster path. Homarr asks a little more of you up front — an admin account, a couple of onboarding screens — in exchange for a much more capable dashboard once it's running.
Prerequisites
Before you start, make sure you've got:
- A working Proxmox VE host — this guide was tested against Proxmox VE 9.2, running on Debian 13.5 "Trixie"
- Root access to the Proxmox shell, either through the web UI's Shell button on your node or SSH
- At least 8 GB of free storage and roughly 2 GB of RAM available for the new container (these are the script's defaults — more on that below)
- A stable internet connection on the Proxmox host, since the installer downloads Node.js and the Homarr release directly from GitHub
- About ten minutes, most of which is just watching the installer work
You don't need Docker installed anywhere for this. The community-scripts version of Homarr runs natively inside the container using Node.js, not inside a Docker container — which sidesteps the usual headaches people run into trying to nest Docker inside an LXC container.
Step-by-Step Tutorial
Step 1: Open the Proxmox VE shell
Log in to the Proxmox web UI, click on your node in the left-hand tree, and open Shell from the top-right menu. You can also SSH in as root if you'd rather work from your own terminal.
Step 2: Run the community-scripts installer
Paste this one-liner into the shell and hit enter:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/homarr.sh)"This pulls down the official Homarr install script maintained by the community-scripts project — the same team behind most of the one-line LXC installers you'll see referenced across the Proxmox forums. It's worth a quick habit: never run a script like this without knowing where it comes from. This one's open source and widely used, so it's a reasonable one to trust, but that shouldn't be your default assumption for every curl-to-bash command you find online.
Step 3: Choose Default or Advanced settings
The script will ask whether you want Default or Advanced settings. Default is fine for most people and gives you:
- 2 vCPU cores
- 2048 MB of RAM
- 8 GB disk
- Debian 13 as the container OS
- DHCP networking
Pick Advanced if you want a static IP set during creation, a different container ID, or more resources up front. I'd only bump the RAM if you're planning to run a lot of integrations at once — 2 GB comfortably handles Homarr plus Redis for a normal homelab board.
Step 4: Wait for the build to finish
The script creates the container, installs Node.js, sets up Redis and Nginx inside it, downloads the latest Homarr release, and configures it as a systemd service. This takes somewhere around three to six minutes depending on your internet speed — most of that is the Node.js and npm dependency install. Don't close the shell while it's running.
When it's done, you'll see a summary with the container's IP address and the port to use.
Step 5: Open Homarr in your browser
Head to http://<container-ip>:7575 in a browser on the same network. Port 7575 is Homarr's default — there's no port 3000 confusion here like you'll hit with some other self-hosted apps.
Step 6: Create your admin account
This is where Homarr diverges from a lot of dashboard tools: the first thing you'll see is an onboarding screen asking you to create an admin username and password. This is a real account, not a placeholder — write the password down somewhere, because Homarr doesn't ship with a default login you can fall back on.
Once you're logged in, Homarr walks you through a short guided tour of the management area: boards, apps, integrations, and users. You can skip it, but it's short enough to be worth the two minutes.
Step 7: Add the Proxmox VE integration
To get live node and VM stats on your board, go to Manage → Integrations → New Integration and pick Proxmox VE. You'll need an API token for this.
Back in the Proxmox web UI, go to Datacenter → Permissions → API Tokens and create one. The important detail people miss here: create the user for this token under the pve realm, not pam. Proxmox's API doesn't play well with PAM-based authentication for this kind of token, and you'll get authentication failures if you try it. Give the token read-only permissions (PVEAuditor role is enough) unless you specifically need Homarr to control VMs from the dashboard.
Paste your Proxmox host address, the token ID, and the token secret into Homarr's integration form, save it, then drag the Proxmox widget onto your board. Give it thirty seconds or so to pull its first round of stats.
Commands Explained
You'll mostly interact with Homarr through the web UI, but a few shell commands are worth knowing for day-to-day management. Run these inside the Homarr container, not on the Proxmox host — get there with pct enter <container-id> from the Proxmox shell.
| Command | What it does |
|---|---|
systemctl status homarr | Shows whether the Homarr service is running, and the last few log lines if it's crashed |
systemctl restart homarr | Restarts the Homarr process — the first thing to try after an update or a config change |
journalctl -u homarr -n 100 | Shows the last 100 log lines for the Homarr service, useful for tracking down startup errors |
systemctl status redis-server | Checks Redis, which Homarr depends on for caching — if this is down, Homarr won't start cleanly |
pct enter <container-id> | Run from the Proxmox host shell to drop into the container's own shell |
Redis, if you haven't run into it before, is an in-memory data store — think of it as a very fast temporary scratchpad that Homarr uses for sessions and caching so it doesn't have to hit the SQLite database for every single request.
Common Errors
A handful of things trip people up during setup, most of them fixable in under a minute.
The install script exits partway through with a pnpm or Node error. A small number of users hit this on fresh Debian 13 containers, usually tied to how the Node.js dependency resolution behaves on that particular kernel and glibc combination. If this happens, just re-run the exact same install command — it's almost always a transient network or timing issue during the dependency install, and a second pass finishes cleanly.
The dashboard loads but integrations show "unreachable." Nine times out of ten this is a Proxmox API token created under the wrong realm. Double-check it's a pve realm user, not pam.
Port 7575 doesn't respond at all. Give the container an extra minute after the install finishes — Homarr's first boot needs to initialize its SQLite database and can take longer than the systemd service takes to report "active." Check systemctl status homarr before assuming something's broken.
You forgot the admin password from onboarding. There's no CLI reset shortcut for this one. Your best options are deleting and recreating the container (it's a two-minute rebuild) or checking Homarr's own documentation for the current password-reset flow, since it's changed between versions.
Troubleshooting
If Homarr won't start at all after a reboot of the container, check Redis first. Homarr depends on it, and if Redis fails to come up — usually from a filesystem permission issue after an unclean shutdown — Homarr will sit there failing silently. systemctl status redis-server followed by systemctl restart redis-server then systemctl restart homarr resolves this in most cases.
If the board loads but widgets stay blank or show a loading spinner forever, open your browser's developer console (F12) and check for network errors. This is almost always either a wrong API token, a typo in the integration's host address, or a firewall rule on the Proxmox host blocking the container from reaching the API on port 8006.
For anything database-related — boards not saving, weird 500 errors on the management pages — the SQLite file lives at /opt/homarr_db/db.sqlite inside the container. It's rare you'd need to touch it directly, but knowing where it lives matters if you're setting up your own backup job for the container, which you should be doing regardless.
Best Practices
Take a Proxmox backup of the container right after your initial setup, once you've got your admin account and integrations working. It's a small container, so the backup job takes seconds, and it saves you from redoing the onboarding flow if something goes wrong later.
Use a read-only Proxmox API token for the integration unless you have a specific reason to let Homarr control VM power states from the dashboard. There's rarely a good reason to hand a dashboard app write access to your hypervisor.
If you're exposing Homarr outside your home network — and I'd think carefully before doing that with something that has direct API access to your hypervisor — put it behind a reverse proxy with its own authentication layer, and don't forward port 7575 straight to the internet.
Keep the container updated. Re-run the same install one-liner from the Proxmox shell periodically; the community-scripts installer detects an existing Homarr container and offers to update it in place rather than building a new one.
Frequently Asked Questions
Do I need Docker to run Homarr on Proxmox?
No. The community-scripts LXC installer runs Homarr natively with Node.js, Redis, and Nginx directly inside the container — no Docker layer involved.
How is Homarr different from Homepage?
Homepage is a static dashboard driven by YAML config files with no login system. Homarr is database-backed, has real user accounts, and lets you edit boards through the browser instead of editing config files by hand.
Can more than one person have their own board?
Yes. Homarr supports multiple user accounts, each with their own board layout and permissions, which you manage from the Users section under Manage.
Why does my Proxmox integration say it's unreachable?
Almost always an API token created under the wrong authentication realm. It needs to be a pve realm token, not pam.
How much RAM does this actually need?
The installer defaults to 2048 MB, and that's comfortable for a normal homelab board with a handful of integrations. You can trim it down if resources are tight, but I wouldn't go below 1 GB.
Is my dashboard reachable from outside my home network?
Not unless you set that up yourself. By default, Homarr only listens on the container's local network address — nothing forwards it to the internet automatically.
Conclusion
Homarr takes a few more minutes to set up than the simplest dashboard tools out there, mostly because of the admin account and integration steps. What you get for that extra effort is a dashboard that actually talks to your infrastructure instead of just linking to it — Proxmox stats, service health, and a board layout you can rearrange without touching a config file.
Once it's running, the maintenance is close to zero. Back it up with the rest of your VMs, keep it updated with the same one-liner you used to install it, and it'll quietly sit there being the first page you open every time you need to check on your homelab.