KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

haos-one

★ 55 Open GitHub ↗

Home Assistant Operating System: Single‑Container Image

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <h1><img alt="Home Assistant" height="48" src="https://cdn.simpleicons.org/homeassistant/41BDF5" /> haos-one</h1>
  <p>Home Assistant Operating System <br /> Single‑Container Docker Image</p>
  <h2>✨ Full HAOS Vibes, Inside Docker ✨</h2>
  <p>Run a fully featured HAOS instance in a single Docker container</p>
  <p>Keep the same experience you’d get on dedicated hardware or a VM.</p>
  <p>
    <h4>
    <a href="https://github.com/hassio-addons">
      <img alt="Add-ons"  src="https://avatars.githubusercontent.com/u/30772201?s=16&v=4" />
      Add-ons supported, no compromises.
    </a>
    </h4>
  </p>
</div>

<br />

- [Run HA OS without sacrificing a whole computer to it.](https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems/)
- 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
- Kubernetes? Sure. [Helm chart included](./charts/haos-one).

## 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:

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

Or install from the local chart:

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

Values and configuration options: see [`charts/haos-one/README.md`](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:

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

then, push it to new instance:

```bash
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:

```bash
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 the dummy responder inside `haos-one-compat` | `1` |
| `USE_UDEV_SHIM` | Inject an idle Supervisor udev monitor when needed (`auto`, `force`, or `off`) | `auto` |
| `DEV` | Used for development purposes - mount live `haos-one-compat` code volume | `0` |

When the udev shim is enabled, upgrading an existing installation automatically
recreates `hassio_supervisor` once if its stored container configuration lacks
the shim. Data in `/mnt/data/supervisor` is preserved.

## Troubleshooting

- Drop into HA CLI: `docker attach haos`
  > (detach with `Ctrl-p` + `Ctrl-q`) — more details: [here](https://docs.docker.com/reference/cli/docker/container/attach/#attach-to-and-detach-from-a-running-container)
- 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](docs) for details.

## Security Considerations

- Runs with `--privileged`, granting full access between host and container — see [more](https://docs.docker.com/enterprise/security/hardened-desktop/enhanced-container-isolation/#secured-privileged-containers).
- `--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](#recipes)). |
| Ubuntu 25.10 (Questing Quokka) | x86_64 | Docker Engine 29.1.3 (client/server) <br />*(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) | ✅ | — |
| Proxmox VE 9.2.2 | x86_64 | Unprivileged LXC running nested Docker Engine 26.1.5+dfsg1 (client/server) <br />*(rootless & rootfull)* | ✅ | - |

## 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`~~
in-container udev is masked automatically.

## TODOs & Progress:

See [project page](https://github.com/users/qweritos/projects/2) for details.

## License

Apache License 2.0 (see `LICENSE`).

## Disclaimer

Not affiliated with [Home Assistant](https://github.com/home-assistant).

haos-one

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README