haos-one

Home Assistant Operating System
Single‑Container Docker Image

✨ Full HAOS Vibes, Inside Docker ✨

Run a fully featured HAOS instance in a single Docker container

Keep the same experience you’d get on dedicated hardware or a VM.

Add-ons supported, no compromises.

🚧 Work In Progress 🚧

• Run HA OS without sacrificing a whole computer to it.
• Avoid VM performance overhead and hypervisor complexity.
• Use host hardware (like USB devices) directly without passthrough.
• Use host networking for service autodiscovery, simpler routing, and lower latency.
• x86_64 and aarch64 images available.
• Rootless containers support (experimental)
• Kubernetes? Sure. Helm chart included.

How

Simple as one command:

docker run --name haos -ti --privileged -p 8123:8123 qweritos/haos-one

You can pin a specific Home Assistant OS version tag (including prereleases), for example qweritos/haos-one:17.0.rc2 For available HAOS versions, see: https://github.com/home-assistant/operating-system/releases

Replace -p 8123:8123 with --network host if you want host networking (required for autodiscovery features).

Wait for http://localhost:8123 to be available. Now you can create new House or restore from existing backup.

First startup can take a while as it pulls all required images — please be patient.

Kubernetes install with Helm

Install from the OCI registry:

helm install haos-one oci://registry.andrey.wtf/charts/haos-one

Or install from the local chart:

helm install haos-one ./charts/haos-one

Values and configuration options: see charts/haos-one/README.md.

Migration from deprecated Supervised installation method

Method 1: Backup restore

• Create a full backup in your existing install (Settings → System → Backups).
• Download the backup to your host.
• Start this container and restore the backup during onboarding.
• Confirm add-ons and integrations come back after restore.

Method 2: Manual /usr/share/hassio copy via host

Making consistent 1:1 clone of your HA instance.

All commands to be executed from host

Get your /usr/share/hassio contents from existing Supervised installation:

cp -r /usr/share/hassio ./old-config

then, push it to new instance:

docker exec -it haos sh -c 'mv /mnt/data/supervisor /mnt/data/supervisor.bak && mkdir -p /mnt/data/supervisor'
docker cp ./old-config/. haos:/mnt/data/supervisor/

Finally, restart all Home Assistant containers:

docker exec -it haos systemctl restart docker

Recipes

• Host networking (best for autodiscovery):

  docker run --name haos -ti --privileged --network host qweritos/haos-one
  

• to make your data persistent, mount a volume into container's path /mnt/data

    docker run --name haos -ti --privileged -p 8123:8123 -v ./data:/mnt/data qweritos/haos-one
  

• macOS: use a named volume (overlay2 feature gaps with bind mounts):

  docker volume create haos-data
  docker run --name haos -ti --privileged -p 8123:8123 -v haos-data:/mnt/data qweritos/haos-one
  

Env vars

Name	Description	Default
USE_DUMMY_NETWORKMANAGER	Disable NetworkManager and enable haos-one-compat	1
DISABLE_UDEV	Disable in-container udev services	1
DEV	Used for development purposes - mount live haos-one-compat code volume	0

Troubleshooting

• Drop into HA CLI: docker attach haos

  (detach with Ctrl-p + Ctrl-q) — more details: here

• Systemd logs (incl. containers logs): docker exec -it haos journalctl -xb
• Container status: docker exec -it haos docker ps -a

How it works

See docs for details.

Security Considerations

• Runs with --privileged, granting full access between host and container — see more.
• --network host exposes services directly on the host network.
• Protect ./data/ because it contains HA configuration and secrets.
• AppArmor may be unavailable depending on your environment.

Tested Environments

OS	Arch	Env	Status	Notes
macOS 15.6 (24G84)	x86_64	Docker Desktop 4.55.0, Docker Engine 29.1.3 (client/server)	✅	AppArmor unavailable; use named volume (see Recipes).
Ubuntu 25.10 (Questing Quokka)	x86_64	Docker Engine 29.1.3 (client/server) (rootless & rootfull)	✅	—
Ubuntu 25.10 (Questing Quokka)	x86_64	Podman 5.4.2	✅	—
Armbian OS 25.02.0 (bullseye)	aarch64	Docker Engine 28.0.0 (client/server)	✅	—

Known Issues

• --network host lets HA manage host networking and may cause misconfiguration. USE_DUMMY_NETWORKMANAGER=1 is enabled by default.
• "Unsupported system - Network Manager issues" warning - fix in progress.
• Failed to get outbound IP, retrying in 5s: can't get default interface from Supervisor: {"result":"error","message":"Interface default does not exist" in journal (with non-host networking) - fix in progress.
• Docker Desktop on MacOS becomes inaccessible if run with --network=host use -e DISABLE_UDEV=1 for workaround (flag is enabled by default)

TODOs & Progress:

See project page for details.

License

Apache License 2.0 (see LICENSE).

Disclaimer

Not affiliated with Home Assistant.