If you run more than a couple of services in your homelab, you've probably had one go down without you noticing for hours. Maybe it was Pi-hole silently crashing, or a VM that lost network access after a host reboot. You find out when someone complains the internet is "broken," not when it actually breaks. That gap is exactly what Uptime Kuma is built to close, and it happens to run great in a small Proxmox VE LXC container.
This guide walks through creating that container from scratch and getting Uptime Kuma running on Proxmox VE 9.2, without Docker, without a helper script doing the work for you behind the scenes. You'll type every command yourself, so you actually understand what's happening on the container when something eventually goes wrong.
What You'll Learn
By the end of this tutorial you'll have a working Uptime Kuma instance monitoring your first service, plus enough context to keep it running long-term. Specifically, you'll learn how to:
- Create a lightweight Debian 13 LXC container sized correctly for Uptime Kuma
- Install Node.js and the other dependencies Uptime Kuma needs
- Install and configure Uptime Kuma so it survives a container reboot
- Reach the web dashboard from your LAN and create your admin account
- Fix the handful of errors that trip people up during this exact setup
What Is Uptime Kuma?
Uptime Kuma is a free, open-source monitoring tool that checks whether your websites, VMs, containers, and other network devices are actually up. You give it a list of things to watch — a URL, an IP address, a port, even a Docker container — and it pings or requests each one on a schedule you set. When something stops responding, it flags it as down and can notify you through Discord, Telegram, email, Gotify, or dozens of other services.
It's the self-hosted, no-subscription alternative to services like UptimeRobot or Pingdom. The dashboard is clean, the setup is genuinely fast once you know the steps, and unlike a lot of monitoring software it doesn't demand a database server or a pile of configuration files before it'll do anything useful.
Why Run Uptime Kuma in an LXC Container?
You could install Uptime Kuma directly on your Proxmox host, but that's a bad idea — the host should stay dedicated to running VMs and containers, not application workloads. An LXC container gives you isolation without the overhead of a full VM. Proxmox VE's containers share the host's kernel instead of virtualizing their own hardware, so they start in under a second and use a fraction of the RAM a VM would need for the same job.
Uptime Kuma is also a lightweight Node.js application, not a resource hog. Giving it a dedicated container means you can snapshot it, back it up with vzdump, move it to another node, or blow it away and rebuild it in five minutes — all without touching anything else on your Proxmox host. That kind of disposability is exactly what containers are good for.
Prerequisites
Before you start, make sure you have the following:
- Proxmox VE 8.x or 9.x installed and reachable through the web interface (this guide was written against 9.2)
- A Debian 13 "Trixie" (or Debian 12 "Bookworm") LXC template downloaded on your storage — you'll download it during the tutorial if you don't have it yet
- At least 4 GB of free storage and 1 GB of free RAM on the host to allocate to the new container
- Basic comfort typing commands in a Linux shell — you don't need to be an expert, just willing to follow along
- Network access from your workstation to the Proxmox host on your LAN
You don't need a public domain name or SSL certificate for this tutorial. We'll access Uptime Kuma over your local network first; you can put it behind a reverse proxy later if you want it reachable from outside.
Step-by-Step: Installing Uptime Kuma in an LXC Container
Step 1: Download the Debian 13 template
In the Proxmox web interface, click your node in the left sidebar, then go to local (Storage) > CT Templates > Templates. Search for "debian-13" and download the standard template. It's roughly 130 MB, so this takes under a minute on most connections.
Prefer the command line? SSH into your Proxmox host and run:
pveam update
pveam available | grep debian-13
pveam download local debian-13-standard_13.1-1_amd64.tar.zstThe exact filename changes as Proxmox updates its template list, so check the output of the search command before downloading.
Step 2: Create the container
Click Create CT in the top-right corner of the web interface. Walk through the wizard with these settings:
- General: Give it a hostname like
uptime-kuma, set a root password, and leave "Unprivileged container" checked — there's no reason this workload needs privileged access to the host - Template: Select the debian-13-standard template you just downloaded
- Disk: 4 GB is plenty for Uptime Kuma and its SQLite database
- CPU: 1 core is enough. Uptime Kuma doesn't need much compute unless you're monitoring hundreds of endpoints at once
- Memory: Set 1024 MB. You can technically get away with 512 MB, but the initial npm build step is memory-hungry and will fail on anything smaller
- Network: Bridge to
vmbr0(or whichever bridge your other VMs and containers use) with DHCP, unless you already have a static IP scheme you follow - DNS: Leave the defaults unless your network has a specific DNS server you need containers to use
Review the summary and click Finish. Then select the new container in the sidebar and click Start.
Step 3: Update the container and install dependencies
Open the container's console (click >_ Console in the web UI, or run pct enter 100 from the host shell, swapping in your actual container ID). Update the package lists first:
apt update && apt upgrade -y
apt install -y curl git sudoDebian 13's default repositories ship Node.js 20.x, but it's worth confirming rather than assuming. Uptime Kuma needs Node.js 18 or newer, plus a matching npm version. Add the NodeSource repository to be sure you get a current release:
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs
node -v
npm -vYou should see something like v20.x.x printed back. If the version starts with anything below 18, the setup script above didn't run correctly — re-check your container's internet access before continuing.
Step 4: Download and set up Uptime Kuma
Clone the official repository into /opt, which is the conventional place to keep third-party applications on a Linux system:
cd /opt
git clone https://github.com/louislam/uptime-kuma.git
cd uptime-kuma
npm run setupThe setup command installs all of Uptime Kuma's dependencies and builds the frontend. On a 1-core, 1 GB container this takes roughly three to five minutes. It's normal for the console to sit quietly during the build step — resist the urge to Ctrl+C it.
Step 5: Run Uptime Kuma as a persistent service
Starting Uptime Kuma with node server/server.js works fine for testing, but it dies the moment you close your console session. You want it running as a proper systemd service so it starts automatically and survives reboots. Create the service file:
nano /etc/systemd/system/uptime-kuma.servicePaste in the following, adjusting the path if you cloned Uptime Kuma somewhere other than /opt/uptime-kuma:
[Unit]
Description=Uptime Kuma
After=network.target
[Service]
Type=simple
WorkingDirectory=/opt/uptime-kuma
ExecStart=/usr/bin/node server/server.js
Restart=always
RestartSec=10
User=root
[Install]
WantedBy=multi-user.targetSave the file, then reload systemd and start the service:
systemctl daemon-reload
systemctl enable --now uptime-kuma
systemctl status uptime-kumaYou should see "active (running)" in green. If it says "failed" instead, jump to the Troubleshooting section below before moving on.
Step 6: Access the dashboard
Find your container's IP address by running ip a inside the container, or checking the Summary tab in the Proxmox web UI. Open a browser on any device on your LAN and go to:
http://<container-ip>:3001The first time you load this page, Uptime Kuma asks you to create an admin username and password. Do this immediately — until you set credentials, anyone on your network who finds that IP and port can access the dashboard. After that, you'll land on the main dashboard where you can click Add New Monitor to start watching your first service.
Commands Explained
| Command | What it does |
|---|---|
pveam update | Refreshes the list of LXC templates available for download from Proxmox's repositories |
pct enter 100 | Opens a root shell directly inside container ID 100 from the Proxmox host, no SSH needed |
apt update && apt upgrade -y | Refreshes Debian's package index, then installs any available updates without prompting for confirmation |
npm run setup | Uptime Kuma's own install script — installs Node dependencies and compiles the web frontend |
systemctl enable --now uptime-kuma | Registers the service to start on boot (enable) and starts it immediately in the same command (--now) |
systemctl status uptime-kuma | Shows whether the service is running, and prints its most recent log lines if it crashed |
Common Errors
"npm ERR! code ELIFECYCLE" during npm run setup. This almost always means the container ran out of memory mid-build. It's the single most common failure people hit with this setup. Shut the container down, bump memory to at least 1024 MB in Hardware > Memory, and run npm run setup again.
Dashboard loads but shows a blank white page. Usually a leftover browser cache from a failed build. Hard-refresh with Ctrl+Shift+R, or check journalctl -u uptime-kuma -n 50 for frontend build errors and re-run npm run setup.
"This site can't be reached" when opening port 3001. Either the service isn't actually running, or something on the network path is blocking it. Confirm the service status first, then check the Proxmox firewall (covered below).
apt update fails inside the container with a DNS or connection error. The container isn't getting network access from the bridge. Double-check the container's network configuration matches a working VM or container on the same bridge, and confirm the Proxmox host itself has working internet access.
Troubleshooting
Start any troubleshooting session with the service's own logs — they tell you more than guessing ever will:
journalctl -u uptime-kuma -n 100 --no-pagerIf the service won't stay running, check that Node.js is actually on the path systemd expects. The service file above assumes Node lives at /usr/bin/node; confirm that with:
which nodeIf it returns a different path, update ExecStart in the service file to match, then run systemctl daemon-reload and restart the service.
If the dashboard loads locally on the container but not from other devices on your LAN, the Proxmox firewall is the usual suspect. Check Datacenter > Firewall and your container's own Firewall tab — if the firewall is enabled with a default-deny policy, you'll need to add a rule allowing TCP traffic on port 3001, or disable the firewall on that container if you're not using it for anything else.
One more thing that catches people out: if you rebooted the Proxmox host and the container didn't come back up, check whether "Start at boot" is enabled under the container's Options tab. It's off by default.
Best Practices
A few habits will save you a headache down the line:
- Take a Proxmox snapshot before running
git pullto update Uptime Kuma to a new version. Updates are generally smooth, but a snapshot means a bad one costs you thirty seconds to roll back instead of an afternoon - Don't expose port 3001 directly to the internet through port forwarding. If you want remote access, put it behind a reverse proxy like Nginx Proxy Manager with a proper SSL certificate instead
- Back up the container regularly with vzdump or Proxmox Backup Server — Uptime Kuma stores all your monitors and history in a single SQLite database file, so a container-level backup covers everything
- Set up at least one notification channel (Telegram and Discord are the easiest to configure) so you actually hear about downtime instead of having to check the dashboard manually
Honestly, most homelab users never touch the advanced settings beyond this. Uptime Kuma works well out of the box, and over-tuning it rarely buys you much.
Frequently Asked Questions
How much RAM does Uptime Kuma actually need to run?
Once it's built and running, 256–512 MB is enough for monitoring a modest number of endpoints. The 1 GB allocation in this guide exists to get through the initial npm build without failing.
Can I monitor my Proxmox VMs and containers with it?
Yes, as long as they respond to a ping, an HTTP request, or a TCP port check. Uptime Kuma doesn't hook into the Proxmox API directly, so it can't read VM status the way the Proxmox dashboard does — it just checks whether the service inside is reachable.
Does Uptime Kuma need a separate database server?
No. It uses an embedded SQLite database by default, which is exactly why the setup here is so short. There's also an option to connect it to MySQL or PostgreSQL if you're running a larger deployment, but almost nobody in a homelab needs that.
Is Uptime Kuma really free?
Yes, it's fully open source under the MIT license. There's no paid tier, no monitor limit, and no account requirement.
How do I update it later?
Stop the service, pull the latest code, rerun setup, and restart:
systemctl stop uptime-kuma
cd /opt/uptime-kuma
git pull
npm run setup
systemctl start uptime-kumaConclusion
You now have a monitoring dashboard watching your homelab from its own isolated container, running as a systemd service that'll survive reboots and keep going without you babysitting it. The next move is usually adding a notification channel and pointing Uptime Kuma at everything else you run — your Pi-hole instance, your reverse proxy, any VM that would actually cause you trouble if it went down quietly. It only takes a few minutes per monitor, and it's the kind of small setup step that pays for itself the first time it catches an outage before someone else does.