If you searched for a way to run Home Assistant on Proxmox, you probably landed on guides for Home Assistant OS first. That's the official appliance image, and it's a solid choice. But it also wants its own virtual machine, its own EFI disk, and a chunk of RAM that sits there whether you're using it or not. If you already run a homelab full of LXC containers and you'd rather keep Home Assistant lightweight, running it as a Docker container inside an LXC is the other real option, and it's the one nobody explains properly.
This guide walks through building that setup on Proxmox VE 8.x or 9.x: a Debian 12 LXC container, Docker installed inside it, and the official Home Assistant Container image running with the settings it actually needs to see your network. I'll also cover the two settings that trip up almost everyone the first time: nesting and keyctl.
What You Will Learn
- The difference between Home Assistant OS and Home Assistant Container, and which one fits your setup
- How to create an unprivileged Debian LXC container sized correctly for this job
- Why Docker needs nesting and keyctl enabled to run inside an LXC container at all
- How to install Docker and launch the official Home Assistant image with the right volumes and network mode
- What to do when the container won't start, can't reach your devices, or Docker refuses to run
What Is This Feature?
Home Assistant is open-source home automation software. It connects to smart devices — lights, thermostats, sensors, cameras — from dozens of brands and gives you one dashboard and one automation engine instead of five different apps that don't talk to each other.
It ships in a few different forms. Home Assistant OS is a full operating system image meant to run in its own VM or on dedicated hardware like a Raspberry Pi. It includes the Supervisor, a management layer that gives you an add-on store, one-click backups, and a built-in way to install things like the Mosquitto MQTT broker or the ESPHome dashboard.
Home Assistant Container is different. It's just Home Assistant itself, packaged as a Docker image, with none of the Supervisor layer around it. You run it with docker run or Docker Compose, same as any other containerized app. If you want MQTT or ESPHome, you run those as separate containers yourself.
An LXC container, in Proxmox terms, is a lightweight form of virtualization that shares the host's Linux kernel instead of emulating its own hardware like a VM does. That's why LXC containers boot in seconds and use a fraction of the RAM a comparable VM needs. The tradeoff is that anything running inside needs to be compatible with sharing a kernel — which is exactly why Docker inside LXC needs a couple of extra settings turned on before it will work.
Why Would You Use It?
Honestly, most people running a serious homelab already have Docker running somewhere, and they're already comfortable managing containers by hand. For that crowd, Home Assistant Container fits the workflow better than a dedicated VM does. You get the same core Home Assistant experience — same integrations, same automations, same dashboards — using a fraction of the resources an HAOS VM asks for.
It's also easier to back up in one sense: because the whole thing lives inside a single LXC container, a normal Proxmox backup job (vzdump) captures the entire environment, config and all, without needing Home Assistant's own snapshot feature.
The tradeoff is real, though. You lose the Supervisor, so there's no add-on store, no one-click Z-Wave/Zigbee integration installs, and no built-in backup UI inside Home Assistant itself. If any of that sounds like something you'd miss, Home Assistant OS in a VM is probably the better fit for you. This guide is for the folks who'd rather run one more `docker run` command than manage a second VM.
Prerequisites
- A working Proxmox VE 8.x or 9.x host with a Debian 12 (bookworm) LXC template already downloaded, or available to download from local storage > CT Templates > Templates
- At least 2 CPU cores and 2 GB of RAM free to assign to the container (4 GB is more comfortable if you plan to add more containers alongside it later)
- 8 GB or more of free disk space for the container's root disk
- Basic comfort with the Linux command line — you'll be typing commands inside the container's console
- Your smart home devices on the same network/VLAN the LXC container will be attached to, since most integrations rely on local network discovery
Step-by-Step Tutorial
Step 1: Create the LXC container
In the Proxmox web UI, click Create CT in the top right. Give it a hostname like homeassistant, set a root password, and on the Template tab pick the Debian 12 template. On the Resources tab, assign 2 cores, 2048 MB of RAM, and an 8 GB (or larger) disk. Leave Unprivileged container checked on the General tab — you don't need a privileged container for this, despite what some older guides suggest.
On the Network tab, set it to use DHCP or a static IP on your normal LAN bridge (usually vmbr0). Finish the wizard and let the container get created, but don't start it yet.
Step 2: Enable nesting and keyctl
This is the step almost every failed setup skips. Docker needs to create its own nested namespaces and manage kernel keyrings, and by default an LXC container isn't allowed to do either.
Select your new container in the Proxmox UI, go to Options, double-click Features, and check both Nesting and keyctl. Click OK to save. Alternatively, from the Proxmox host shell you can set the same thing with one command:
pct set 105 --features nesting=1,keyctl=1Swap 105 for your container's actual ID. Now start the container from the Proxmox UI or with pct start 105.
Step 3: Update the container and install Docker
Open the container's console (click >_ Console in the UI) and log in as root. First, update the package lists and installed packages:
apt update && apt upgrade -yThen install Docker using the official installation script, which is still the fastest reliable way to get a current Docker release on Debian:
curl -fsSL https://get.docker.com | shThis takes about a minute on a typical connection. When it finishes, confirm Docker is actually running:
docker --version
systemctl status dockerIf systemctl status docker shows active (running), you're clear to move on. If it doesn't, jump ahead to the Troubleshooting section before continuing — there's no point launching a container on top of a Docker daemon that isn't healthy.
Step 4: Create a config folder and run Home Assistant
Pick a location on the container's disk to store Home Assistant's configuration files, so they survive container updates:
mkdir -p /opt/homeassistant/configNow launch the official Home Assistant Container image:
docker run -d \
--name homeassistant \
--privileged \
--restart=unless-stopped \
-e TZ=America/New_York \
-v /opt/homeassistant/config:/config \
-v /run/dbus:/run/dbus:ro \
--network=host \
ghcr.io/home-assistant/home-assistant:stableChange TZ to your own time zone (for example Europe/Berlin or Asia/Kolkata) so schedules and logs use the right local time. The first pull takes a few minutes since the image is a few hundred megabytes.
Step 5: Watch it start and log in
Follow the startup logs to know when it's ready:
docker logs -f homeassistantYou're looking for a line that says something like "Starting Home Assistant" followed by no repeating errors. Once it settles down — usually 30 to 90 seconds on modest hardware — press Ctrl+C to stop following the logs, then open http://<container-ip>:8123 in your browser. You'll land on the onboarding wizard, where you create your admin account and it starts scanning your network for devices it recognizes.
Commands Explained
| Command / flag | What it actually does |
|---|---|
pct set 105 --features nesting=1,keyctl=1 | Turns on the two LXC features Docker needs: nested namespace support and access to the kernel's key management API. |
curl -fsSL https://get.docker.com | sh | Downloads and runs Docker's official install script, which adds Docker's apt repository and installs the current stable release. |
--privileged (on the docker run command) | Gives the Home Assistant container access to USB devices for things like Zigbee or Z-Wave dongles. This is a Docker-level flag, separate from Proxmox's own privileged/unprivileged container setting. |
--network=host | Shares the LXC container's own network stack directly with the Home Assistant container, instead of putting it behind Docker's internal NAT. Needed for mDNS/UPnP device discovery to work. |
-v /opt/homeassistant/config:/config | Maps a folder on the LXC's disk to Home Assistant's config directory inside the container, so your configuration and history survive image updates. |
-v /run/dbus:/run/dbus:ro | Gives Home Assistant read-only access to the host's D-Bus socket, used by integrations like Bluetooth. |
--restart=unless-stopped | Tells Docker to automatically restart the container after a crash or after the LXC container itself reboots, unless you manually stopped it. |
Common Errors
"Cannot connect to the Docker daemon at unix:///var/run/docker.sock" — Docker's service isn't running, usually because nesting wasn't enabled before Docker was installed. Enable nesting and keyctl, reboot the LXC container, then run systemctl restart docker.
"docker: Error response from daemon: error creating overlay mount" — Some kernel/storage combinations don't support the overlay2 storage driver inside an unprivileged LXC. You'll usually see this on ZFS-backed containers. Switching Docker's storage driver to vfs fixes it, at the cost of somewhat slower image operations.
Home Assistant loads but no devices are discovered — Almost always means --network=host wasn't actually applied, or the LXC's own network is set to a firewall zone that blocks multicast/mDNS traffic. Check the container's network settings and confirm the Proxmox firewall isn't enabled on that interface if you haven't configured rules for it yet.
The container restarts in a loop right after startup — Check docker logs homeassistant for a Python traceback. This is usually a corrupted configuration.yaml from a previous install you copied in, not a fresh-install problem.
Troubleshooting
Start by confirming nesting and keyctl actually took effect, since a lot of "Docker won't start" reports trace back to this:
pct config 105 | grep featuresYou should see features: keyctl=1,nesting=1 in the output. If it's missing, set it again and reboot the container — the features don't apply retroactively to an already-running container.
If Docker itself is running but the Home Assistant container keeps exiting, check its exit code and the last few log lines together:
docker ps -a
docker logs --tail 50 homeassistantAn exit code of 137 usually means it ran out of memory — bump the LXC's RAM allocation from the Proxmox UI (Hardware > Memory) and restart the container. An exit code of 1 with a Python traceback almost always points to a bad config file, not a Docker or Proxmox problem.
If you genuinely can't get Docker to run reliably inside the LXC after enabling nesting and keyctl, that's a sign your storage backend (some ZFS and Ceph configurations, in particular) doesn't play well with nested container runtimes. At that point, running Home Assistant Container in a small Debian VM instead is a perfectly reasonable fallback — you lose the RAM savings, but Docker behaves exactly like it does on bare metal.
Best Practices
Give this LXC container its own dedicated purpose. Don't pile other unrelated Docker workloads into the same container — if one misbehaves and eats all the CPU or fills the disk, you don't want it taking Home Assistant down with it.
Keep Start at boot enabled on the container (Options > Start at Boot) so Home Assistant comes back automatically after a host reboot, and pair it with --restart=unless-stopped on the docker run command so the container itself also recovers from crashes.
Back up the whole LXC container with a scheduled vzdump job, not just the /opt/homeassistant/config folder. A full container backup restores in minutes and gives you Docker, its images, and your Home Assistant config all in one shot, rather than having to rebuild the Docker install from scratch.
Update deliberately rather than automatically. Pull the new image, stop the old container, and start a new one from the updated image — don't let something silently auto-update your smart home controller in the middle of the night:
docker pull ghcr.io/home-assistant/home-assistant:stable
docker stop homeassistant
docker rm homeassistant
Then re-run the same docker run command from Step 4. Because your config lives on the mounted volume, nothing is lost when you recreate the container.
Frequently Asked Questions
Is this the same as Home Assistant OS?
No. You get the same Home Assistant core and the same integrations, but without the Supervisor, the add-on store, or the built-in backup UI. Anything Supervisor-specific (like one-click Mosquitto or ESPHome installs) has to be run as its own separate Docker container.
Do I need a privileged LXC container for this to work?
No. An unprivileged container with nesting and keyctl enabled is the recommended setup and it's what this guide uses. Privileged LXC containers share root-level access with the Proxmox host itself, which is a bigger security tradeoff than most homelabs need to take on just to run Docker.
Can I skip --network=host and use a regular Docker bridge instead?
You can, but most local network discovery — mDNS, UPnP, and several popular integrations — will stop working properly. If you only ever add devices manually by IP address, a bridge network will technically run, but I wouldn't recommend it as your default.
Can I still use HACS and third-party integrations?
Yes. HACS and the vast majority of integrations work identically to Home Assistant OS, since they run inside Home Assistant Core itself rather than depending on the Supervisor.
Will Home Assistant survive a Proxmox host reboot?
Yes, as long as you've enabled Start at Boot on the LXC container and used --restart=unless-stopped when you launched the Docker container. Both settings need to be in place — either one alone isn't enough.
Conclusion
Running Home Assistant as a Docker container inside an LXC gets you the same automation engine and the same dashboards as Home Assistant OS, using less RAM and disk than a dedicated VM would need. The catch is losing the Supervisor and its add-on store, so if you were counting on one-click add-ons, this probably isn't the right path for you.
For anyone already comfortable running Docker containers by hand, though, this setup fits right into an existing homelab workflow — and enabling nesting and keyctl before you install Docker is really the only step that isn't obvious the first time around.