Can I self-host Home Assistant Cloud?

329 lines · 14,968 bytes

You are Claude Code on the user's machine. The user has completed Prompt Zero: `ssh vps` works,
Docker and Caddy are installed, the firewall is default-deny.

Run every command in this prompt on the server over `ssh vps` unless the step says otherwise.

Install Home Assistant 2026.7.4 on that server, reachable at https://<DOMAIN>, behind the
existing Caddy with automatic TLS.

## 1. Preflight

If `<DOMAIN>` is still literal, ask the user for the hostname once and stop until they answer.
Its A record must already point at this server.

Home Assistant needs 1024 MB of RAM available and 5 GB free on /srv. The 2026.7.4 image is
published for amd64 and arm64. Measure all four:

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
```

If available RAM is under 1024 MB or free disk is under 5 GB, print both numbers and stop. Do
not install and hope. If `dig +short` prints nothing, print that and stop: Caddy cannot certify
a hostname that does not resolve.

Say one thing to the user before anything installs. On a rented machine the integrations that
work are the ones reaching a device over the internet or over an address they type in. Nothing
on this server's network segment is theirs, so mDNS and SSDP discovery, Bluetooth and USB
radios are all out of reach. A hub for the sensors in their house belongs in their house.

## 2. Layout

Home Assistant writes its own configuration file on the first start, and this install cannot
let it, because the file has to name the reverse proxy before the first request arrives.
Upstream is explicit: a request from a proxy is blocked until the proxy is trusted. Write the
tree and all four files now.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/home-assistant /srv/home-assistant/backups
sudo install -d -m 750 /srv/home-assistant/config /srv/home-assistant/config/themes
sudo tee /srv/home-assistant/config/configuration.yaml >/dev/null <<'EOF'
# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

# Caddy terminates TLS on this host and forwards to 127.0.0.1:8107. Home
# Assistant rejects a proxied request with 400 until it is told which addresses
# are allowed to set X-Forwarded-For, which is why this block exists before the
# first start rather than after it. Docker rewrites the source address of a
# published-port connection to the gateway of the container's bridge network,
# and that gateway is assigned by Docker and moves when the network is
# recreated, so the range is what holds rather than one address.
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1/32
    - 172.16.0.0/12
  ip_ban_enabled: true
  login_attempts_threshold: 5

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml
EOF
printf '[]\n' | sudo tee /srv/home-assistant/config/automations.yaml >/dev/null
sudo touch /srv/home-assistant/config/scripts.yaml /srv/home-assistant/config/scenes.yaml
sudo ls -la /srv/home-assistant/config
```

Assert: `ls -la` lists `configuration.yaml`, `automations.yaml`, `scripts.yaml`, `scenes.yaml`
and `themes`, all owned by root. The container runs as root, so root owns this directory and
the user reads it with `sudo`. The two empty files and the empty list exist because the
include lines point at them and a missing include is a start-up error.

## 3. Secrets

Nothing is generated here and there is no `.env` file. Home Assistant's only credential is the
owner account, and it is created in a browser at step 7 rather than written into a file now.
That is why this block has nothing to run.

Say one thing to the user. Between the container starting and that account existing, the
onboarding form is open to whoever loads the hostname first, and the first person through it
owns the house. Step 7 makes that window as short as it can be, and it is a hard stop for that
reason.

## 4. compose.yml

```bash
cat > /srv/home-assistant/compose.yml <<'EOF'
# Home Assistant · the deterministic fallback. Authored by caniselfhostit from
# the upstream documentation, not copied from a repository:
#   container install .. https://www.home-assistant.io/installation/linux/
#   http integration ... https://www.home-assistant.io/integrations/http/
#   remote access ...... https://www.home-assistant.io/docs/configuration/remote/
#
# One container. Upstream's own example sets network_mode: host and
# privileged: true, because at home that is how Home Assistant finds devices
# over mDNS and SSDP and reaches a USB radio. A rented server has no devices on
# its network segment and no radio plugged into it, so this file drops both and
# publishes one loopback port instead. Everything lives under /config: the
# configuration file, the .storage directory holding the accounts, and the
# recorder database. Upstream pins the floating :stable tag; this file pins the
# 2026.7.4 release and the digest read from ghcr.io on 2026-08-06, published
# for linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:2026.7.4@sha256:5a531753cea96444200158fc2b0ac7ccd739291ec50414877b396de6e0bb29b3
    container_name: homeassistant
    restart: unless-stopped
    environment:
      # This labels the container's log timestamps. Home Assistant's own time
      # zone is a separate setting, chosen during onboarding.
      TZ: UTC
    volumes:
      # The image runs as root, so this directory and everything the container
      # writes into it belong to root on the host.
      - /srv/home-assistant/config:/config
    ports:
      # Loopback only. The host's Caddy is the only thing that reaches 8107.
      # 8123 is the port Home Assistant listens on inside the container.
      - "127.0.0.1:8107:8123"
EOF
cd /srv/home-assistant && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. Do not add `network_mode: host` or `privileged: true` from
the upstream example. Host networking would bind 8123 to every interface on a public machine,
which is the opposite of what step 6 is protecting, and the hardware access privileged mode
grants has nothing here to reach.

## 5. Caddy and TLS

Append the block below with `<DOMAIN>` replaced by the real hostname. Copy the file first: a
syntax error here takes down every other site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-home-assistant
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# Home Assistant · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://www.home-assistant.io/docs/configuration/remote/ and
# https://caddyserver.com/docs/automatic-https
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed,
# with <DOMAIN> replaced by the hostname pointed at this box. Caddy runs under
# systemd on the host; there is no Caddy container in this project.
#
# Caddy adds X-Forwarded-For on its own, and Home Assistant answers 400 to a
# request carrying that header until configuration.yaml lists the proxy under
# trusted_proxies. That file is written before the first start for exactly this
# reason, and this block cannot make up for a missing one.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# The dashboard holds a WebSocket open for as long as a tab is open. Caddy
	# negotiates that upgrade itself, so there are no Upgrade or Connection
	# headers to set by hand.
	#
	# 8107 is the loopback port compose publishes on this host. It is not a
	# container port and it is not open in the firewall.
	reverse_proxy 127.0.0.1:8107
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

Assert: `caddy validate` exits 0 and the reload exits 0. If validate fails, restore
/etc/caddy/Caddyfile.before-home-assistant, reload, and report what it objected to. Caddy
requests the certificate on the first request and renews it on its own, so there is no
renewal to schedule.

## 6. Firewall

Two ports open, both Caddy's. These are idempotent, so on a box Prompt Zero configured they
change nothing:

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

80/tcp answers the ACME challenge and redirects to HTTPS, 443/tcp is the only way in, and
443/udp is HTTP/3. 8107 stays closed because compose bound it to 127.0.0.1, so a rule for it
would cover traffic that cannot arrive; if one is there a previous run left it, and
`sudo ufw delete allow 8107` removes it. Assert: `ufw status verbose` prints `Status: active`,
shows 80, 443/tcp and 443/udp, and no rule for 8107 or 8123.

## 7. Start and verify

The first start is slow. Home Assistant installs the Python requirements for the integrations
`default_config` pulls in before it serves anything, and on a small server that takes minutes.
The loop below waits for it.

```bash
cd /srv/home-assistant
docker compose pull
docker compose up -d
for i in $(seq 1 40); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/api/onboarding); echo "$i $code"; [ "$code" = 200 ] && break; sleep 15; done
curl -sS https://<DOMAIN>/api/onboarding
echo
curl -sS -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/api/
```

Assert, all three, and print what you received for each. The loop ends printing `200`. The
onboarding response contains `"step":"user","done":false`. The last command prints `401`,
because that endpoint needs a token and refusing without one is the security assert in this
block.

If the loop returns `400` instead, stop: that is Home Assistant rejecting a request from an
untrusted proxy, so step 2 wrote the wrong file or wrote it after the first start. Check with
`sudo grep -A4 trusted_proxies /srv/home-assistant/config/configuration.yaml`, then
`docker compose restart`. If the loop returns `502` for the whole forty rounds, run
`docker compose logs --tail 40 homeassistant` and read it before touching anything else. A
running container is not success.

The first screen at https://<DOMAIN> shows the heading `Welcome!` and a button reading
`Create my smart home`. Until someone submits that form, anyone who loads the page can.

STOP: tell the user to open https://<DOMAIN> right now, create the owner account, and save the
password in their password manager. Wait until they confirm.

Then prove it closed:

```bash
curl -sS https://<DOMAIN>/api/onboarding
echo
```

Assert: the response now contains `"step":"user","done":true`. Have the user also open
https://<DOMAIN> in a private window and confirm they see a sign-in form and no
`Create my smart home` button. Both asserts must pass before you report success.

## 8. First backup and restore

Take the backup now, before the user adds a single device. Stop first: the recorder database
under /config is SQLite, and a copy taken mid-write is not a backup.

```bash
cd /srv/home-assistant
docker compose stop
sudo tar -czf /srv/home-assistant/backups/home-assistant-$(date +%F).tar.gz -C /srv/home-assistant config compose.yml -C /etc/caddy Caddyfile
docker compose start
ls -lh /srv/home-assistant/backups/
```

Assert: the archive exists and is non-empty. Print its size. Downtime is about ten seconds.
`config` is the whole install: the configuration file, the `.storage` directory holding the
owner account and every integration's credentials, and `home-assistant_v2.db` of history.

A backup on the same disk is not a backup, so run this from the user's machine:

```bash
mkdir -p ~/backups/home-assistant
scp vps:/srv/home-assistant/backups/*.tar.gz ~/backups/home-assistant/
```

To restore: `docker compose down`, `sudo rm -rf /srv/home-assistant/config`,
`sudo tar -C /srv/home-assistant -xzf` the archive, then `docker compose up -d`. Those four
commands are the whole disaster plan. Tell the user the `.storage` directory is the part that
matters most: it holds the tokens for every integration they will ever link, and losing it
means linking all of them again by hand.

## 9. Updating later

New versions are listed at https://github.com/home-assistant/core/releases. Take a backup
first, then edit the image line in /srv/home-assistant/compose.yml to the new tag and digest:

```bash
cd /srv/home-assistant
docker compose pull
docker compose up -d
docker compose logs --tail 30 homeassistant
```

Home Assistant migrates its own storage on the way up, so watch that log until it settles, then
re-run the check from step 7 before calling the update done.

One thing to tell the user before they take a release from the 2026.8 series or later. Those
releases move the HTTP settings out of `configuration.yaml` and into the interface, under
Settings then System then Network. The `http:` block written in step 2 is imported once on the
first start after the upgrade and then has to be confirmed there, and the confirmation window
is short. If the site starts answering 400 after an upgrade, the way back in is an SSH tunnel
to the loopback port, `ssh -L 8107:127.0.0.1:8107 vps`, and then http://localhost:8107 in a
browser to set the trusted proxies again.

## 10. What will probably go wrong

The first boot looks like a failure for several minutes. I brought this up, watched Caddy
return `502` for four minutes straight, decided the reverse proxy was wrong, and started
editing the Caddyfile while Home Assistant was still installing the Python packages that
`default_config` asks for. Nothing was broken. The container fetches and builds requirements
for two dozen integrations before it opens a socket, and on a one-core server that is slow
enough to be alarming. Let the loop in step 7 run all forty rounds before concluding anything,
and read `docker compose logs -f homeassistant` while you wait rather than changing files.

## 11. Out of scope

- Do not set `network_mode: host` or `privileged: true`. They are in the upstream example for a
  machine sitting on the user's home network; on a public server they bind 8123 to every
  interface and grant hardware access to nothing.
- Do not configure the Alexa or Google Assistant integrations. Upstream's manual route for each
  needs an AWS Lambda function or a Google Home Developer Console project, and that is a
  separate afternoon, not a step in this install.
- Do not install HACS or any add-on. Add-ons belong to the Home Assistant Operating System
  install type and do not exist in a container install.
- Do not configure SMTP or any notify platform. Home Assistant runs without mail, and the
  channels the user wants are accounts and tokens they pick in the interface.

This path is slower: you paste every command yourself, and there is nobody watching the
output but you. If you can run Claude Code, use the other tab.

You are installing Home Assistant 2026.7.4 on a VPS where Prompt Zero is done: `ssh vps`
works, Docker and Caddy are installed, the firewall is default-deny. Run everything over
`ssh vps` unless a step says otherwise, and replace `<DOMAIN>` with the hostname whose A
record already points at the box.

Read this before step 1, because it decides whether you want this install at all. On a rented
machine the integrations that work are the ones that reach a device over the internet or over
an address you type in. Nothing on the server's network segment is yours, so the discovery
that finds a Hue bridge or a Sonos speaker on its own will never fire here, and neither
Bluetooth nor a USB radio is reachable. A hub for the sensors in your house belongs in your
house. What this gives you is a Home Assistant with a public address, which is the half that
Home Assistant Cloud sells.

## 1. Preflight

```bash
free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}'
df -BG --output=avail /srv | tail -1
dpkg --print-architecture
dig +short <DOMAIN>
```

You should see: at least `1024` MB available, at least `5` G free, `amd64` or `arm64`, and your
server's IP on the last line.

If you do not: an empty last line means the A record does not exist yet. Add it, wait a minute,
run `dig +short <DOMAIN>` again. Caddy cannot get a certificate for a hostname that does not
resolve, and failed attempts count against a rate limit you cannot see. Under 1024 MB of
available RAM, stop and resize the server: the first boot installs a few dozen Python packages
and the OOM killer arrives in the middle of it, which looks like a random crash rather than a
machine that is too small.

## 2. Layout

Home Assistant writes its own configuration file on the first start, and this install cannot
let it, because the file has to name the reverse proxy before the first request arrives.
Upstream is explicit: a request from a proxy is blocked until the proxy is trusted. Paste the
whole block at once, including the last four lines.

```bash
sudo install -d -m 750 -o $(id -u) -g $(id -g) /srv/home-assistant /srv/home-assistant/backups
sudo install -d -m 750 /srv/home-assistant/config /srv/home-assistant/config/themes
sudo tee /srv/home-assistant/config/configuration.yaml >/dev/null <<'EOF'
# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

# Caddy terminates TLS on this host and forwards to 127.0.0.1:8107. Home
# Assistant rejects a proxied request with 400 until it is told which addresses
# are allowed to set X-Forwarded-For, which is why this block exists before the
# first start rather than after it. Docker rewrites the source address of a
# published-port connection to the gateway of the container's bridge network,
# and that gateway is assigned by Docker and moves when the network is
# recreated, so the range is what holds rather than one address.
http:
  use_x_forwarded_for: true
  trusted_proxies:
    - 127.0.0.1/32
    - 172.16.0.0/12
  ip_ban_enabled: true
  login_attempts_threshold: 5

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml
EOF
printf '[]\n' | sudo tee /srv/home-assistant/config/automations.yaml >/dev/null
sudo touch /srv/home-assistant/config/scripts.yaml /srv/home-assistant/config/scenes.yaml
sudo ls -la /srv/home-assistant/config
```

You should see: `configuration.yaml`, `automations.yaml`, `scripts.yaml`, `scenes.yaml` and
`themes`, all owned by `root`.

If you do not: root ownership is correct and not something to fix. The container runs as root,
so it writes root-owned files here, and you read them with `sudo`. If `scripts.yaml` or
`scenes.yaml` is missing, create it with `sudo touch`: the include lines at the bottom of
`configuration.yaml` point at those files, and a missing include stops Home Assistant from
starting with an error that names the file rather than the include.

## 3. Secrets

Nothing is generated here and there is no `.env` file. Home Assistant has one credential, the
owner account, and you create it in a browser at step 7.

Between the container starting and that account existing, the onboarding form is open to
whoever loads your hostname first, and the first person through it owns the house. Step 7 is
written to make that window short, which is why it asks you to stop reading and go create the
account the moment the checks pass.

Nothing in this guide asks you to paste a credential into this chat window. Do not paste the
owner password, the contents of anything under `/srv/home-assistant/config/.storage`, or the
output of any command containing either, at any point.

## 4. compose.yml

Paste the whole block at once, including the last two lines.

```bash
cat > /srv/home-assistant/compose.yml <<'EOF'
# Home Assistant · the deterministic fallback. Authored by caniselfhostit from
# the upstream documentation, not copied from a repository:
#   container install .. https://www.home-assistant.io/installation/linux/
#   http integration ... https://www.home-assistant.io/integrations/http/
#   remote access ...... https://www.home-assistant.io/docs/configuration/remote/
#
# One container. Upstream's own example sets network_mode: host and
# privileged: true, because at home that is how Home Assistant finds devices
# over mDNS and SSDP and reaches a USB radio. A rented server has no devices on
# its network segment and no radio plugged into it, so this file drops both and
# publishes one loopback port instead. Everything lives under /config: the
# configuration file, the .storage directory holding the accounts, and the
# recorder database. Upstream pins the floating :stable tag; this file pins the
# 2026.7.4 release and the digest read from ghcr.io on 2026-08-06, published
# for linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:2026.7.4@sha256:5a531753cea96444200158fc2b0ac7ccd739291ec50414877b396de6e0bb29b3
    container_name: homeassistant
    restart: unless-stopped
    environment:
      # This labels the container's log timestamps. Home Assistant's own time
      # zone is a separate setting, chosen during onboarding.
      TZ: UTC
    volumes:
      # The image runs as root, so this directory and everything the container
      # writes into it belong to root on the host.
      - /srv/home-assistant/config:/config
    ports:
      # Loopback only. The host's Caddy is the only thing that reaches 8107.
      # 8123 is the port Home Assistant listens on inside the container.
      - "127.0.0.1:8107:8123"
EOF
cd /srv/home-assistant && docker compose config >/dev/null && echo "compose OK"
```

You should see: `compose OK` and nothing else.

If you do not: `services must be a mapping` means the indentation was lost between the page and
your terminal. Run `rm /srv/home-assistant/compose.yml` and paste again in one go. Do not add
`network_mode: host` or `privileged: true` from the upstream example, however many guides tell
you to. Host networking would bind 8123 to every interface on a machine with a public IP, which
undoes step 6, and privileged mode grants hardware access to a server with no hardware attached.

## 5. Caddy and TLS

This appends one site block to the Caddy config Prompt Zero installed. Replace `<DOMAIN>` in
the block with your hostname before you paste. The first line takes a copy, because a syntax
error here takes down every other site on the box.

```bash
sudo cp /etc/caddy/Caddyfile /etc/caddy/Caddyfile.before-home-assistant
printf '\n' | sudo tee -a /etc/caddy/Caddyfile >/dev/null
sudo tee -a /etc/caddy/Caddyfile >/dev/null <<'EOF'
# Home Assistant · the Caddy site block for this service.
#
# Authored by caniselfhostit from
# https://www.home-assistant.io/docs/configuration/remote/ and
# https://caddyserver.com/docs/automatic-https
#
# Append this to /etc/caddy/Caddyfile, the Caddy that Prompt Zero installed,
# with <DOMAIN> replaced by the hostname pointed at this box. Caddy runs under
# systemd on the host; there is no Caddy container in this project.
#
# Caddy adds X-Forwarded-For on its own, and Home Assistant answers 400 to a
# request carrying that header until configuration.yaml lists the proxy under
# trusted_proxies. That file is written before the first start for exactly this
# reason, and this block cannot make up for a missing one.

<DOMAIN> {
	encode zstd gzip

	header {
		Strict-Transport-Security "max-age=31536000; includeSubDomains"
		X-Content-Type-Options "nosniff"
		X-Frame-Options "SAMEORIGIN"
		Referrer-Policy "no-referrer"
		-Server
	}

	# The dashboard holds a WebSocket open for as long as a tab is open. Caddy
	# negotiates that upgrade itself, so there are no Upgrade or Connection
	# headers to set by hand.
	#
	# 8107 is the loopback port compose publishes on this host. It is not a
	# container port and it is not open in the firewall.
	reverse_proxy 127.0.0.1:8107
}
EOF
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```

You should see: `Valid configuration` from validate, and no output at all from reload.

If you do not: run `sudo cp /etc/caddy/Caddyfile.before-home-assistant /etc/caddy/Caddyfile`,
reload, and paste again. The most common cause is a `<DOMAIN>` you forgot to replace, which
Caddy reports as an invalid site address. Caddy requests the certificate on the first request
and renews it on its own, so there is nothing to schedule.

## 6. Firewall

```bash
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw status verbose
```

You should see: `Status: active`, rules for `80/tcp`, `443/tcp` and `443/udp`, and no rule
mentioning `8107` or `8123`.

If you do not: delete anything for `8107` or `8123` with `sudo ufw delete allow 8107`. 8107 is
bound to 127.0.0.1 by the compose file, so a rule for it would cover traffic that cannot
arrive, and 8123 exists only inside the container. 80/tcp is there to redirect to HTTPS and to
answer the ACME challenge, 443/tcp is the only way in, and 443/udp is HTTP/3, which Caddy
offers by default. `Status: inactive` is a different problem: Prompt Zero left this firewall
enabled, so something has turned it off since, and `sudo ufw enable` puts it back before you go
any further.

## 7. Start and verify

The first start is slow. Home Assistant installs the Python requirements for the integrations
`default_config` pulls in before it serves anything, and on a small server that takes minutes.
The loop below waits for it, up to ten minutes.

```bash
cd /srv/home-assistant
docker compose pull
docker compose up -d
for i in $(seq 1 40); do code=$(curl -sS -o /dev/null -w '%{http_code}' https://<DOMAIN>/api/onboarding); echo "$i $code"; [ "$code" = 200 ] && break; sleep 15; done
curl -sS https://<DOMAIN>/api/onboarding
echo
curl -sS -o /dev/null -w '%{http_code}\n' https://<DOMAIN>/api/
```

You should see, in order: the loop counting up and reaching `200`, then a line containing
`"step":"user","done":false`, then `401`.

If you do not: the number the loop settles on tells you which step to look at. A `400` is Home
Assistant rejecting a request from a proxy it does not trust, which means step 2's
`configuration.yaml` is wrong or arrived after the first start. Check it with
`sudo grep -A4 trusted_proxies /srv/home-assistant/config/configuration.yaml`, fix it, and run
`docker compose restart`. A `502` that never clears is the container not listening yet, so run
`docker compose logs --tail 40 homeassistant` and read it: a first boot is a long list of
packages being installed, which is the container working rather than failing. A `401` from the
last command is the good outcome, not an error: that endpoint requires a token, and refusing
without one is the point. A running container is not success.

The first screen at https://<DOMAIN> shows the heading `Welcome!` and a button reading
`Create my smart home`. Until you submit that form, anyone who loads the page can.

Go and do it now, before you read the rest of this file: open https://<DOMAIN>, create the
owner account, and put the password in your password manager. Then come back and prove it
closed:

```bash
curl -sS https://<DOMAIN>/api/onboarding
echo
```

You should see: the same line, now containing `"step":"user","done":true`.

If you do not: `"done":false` means the form was never submitted, so the window is still open.
Also open https://<DOMAIN> in a private window and confirm you get a sign-in form and no
`Create my smart home` button.

## 8. First backup and restore

Take the backup now, before you add a single device. Stop first: the recorder database under
/config is SQLite, and a copy taken mid-write is not a backup.

```bash
cd /srv/home-assistant
docker compose stop
sudo tar -czf /srv/home-assistant/backups/home-assistant-$(date +%F).tar.gz -C /srv/home-assistant config compose.yml -C /etc/caddy Caddyfile
docker compose start
ls -lh /srv/home-assistant/backups/
```

You should see: one file, a few megabytes on a fresh install. Downtime is about ten seconds.

If you do not: an archive of a few hundred bytes means `tar` found nothing, which usually means
the paths after `-C` do not exist. `config` is the whole install: `configuration.yaml`, the
`.storage` directory that holds the owner account and every integration's credentials, and
`home-assistant_v2.db` with the history.

A backup on the same disk as the data is not a backup. Run this one on your own machine, not
the server:

```bash
mkdir -p ~/backups/home-assistant
scp vps:/srv/home-assistant/backups/*.tar.gz ~/backups/home-assistant/
```

You should see: one file copied, and it listed by `ls -lh ~/backups/home-assistant/`.

If you do not: `Permission denied (publickey)` means you ran it on the server. The `vps:`
prefix only means something on your own machine, where the `vps` alias Prompt Zero created
lives.

Now prove the restore, today, while the only thing at risk is an empty install:

```bash
cd /srv/home-assistant
docker compose down
sudo rm -rf /srv/home-assistant/config
sudo tar -C /srv/home-assistant -xzf /srv/home-assistant/backups/home-assistant-$(date +%F).tar.gz
docker compose up -d
sleep 90
curl -sS https://<DOMAIN>/api/onboarding
echo
```

You should see: `"step":"user","done":true` again, and your own account still working when you
sign in.

If you do not: `"done":false` means the archive was taken before you created the account, so
take another one now and repeat. Understand the stakes before you skip this. The `.storage`
directory holds the token for every integration you will ever link, and losing it means linking
all of them again by hand, one login at a time.

## 9. Updating later

New versions are listed at https://github.com/home-assistant/core/releases. Take a backup
first, then edit the `image:` line in /srv/home-assistant/compose.yml to the new tag and its
digest.

```bash
cd /srv/home-assistant
docker compose pull
docker compose up -d
docker compose logs --tail 30 homeassistant
```

You should see: storage migration lines, then the server starting, and no repeating restart.

If you do not: put the old tag and digest back and run the same three commands, then re-run
step 7's check. One thing to know before you take a release from the 2026.8 series or later.
Those releases move the HTTP settings out of `configuration.yaml` and into the interface, under
Settings then System then Network. The `http:` block from step 2 is imported once on the first
start after the upgrade and then has to be confirmed there, and the confirmation window is
short. If the site starts answering 400 after an upgrade, the way back in is an SSH tunnel to
the loopback port, `ssh -L 8107:127.0.0.1:8107 vps`, run on your own machine, and then
http://localhost:8107 in a browser to set the trusted proxies again.

## 10. What will probably go wrong

The first boot looks like a failure for several minutes. I brought this up, watched Caddy
return `502` for four minutes straight, decided the reverse proxy was wrong, and started
editing the Caddyfile while Home Assistant was still installing the Python packages that
`default_config` asks for. Nothing was broken. The container fetches and builds requirements
for two dozen integrations before it opens a socket, and on a one-core server that is slow
enough to be alarming. Let the loop in step 7 run all forty rounds before concluding anything,
and read `docker compose logs -f homeassistant` while you wait rather than changing files.

## 11. Out of scope

- Do not set `network_mode: host` or `privileged: true`. They are in the upstream example for a
  machine sitting on your home network; on a public server they bind 8123 to every interface
  and grant hardware access to nothing.
- Do not configure the Alexa or Google Assistant integrations. Upstream's manual route for each
  needs an AWS Lambda function or a Google Home Developer Console project, and that is a
  separate afternoon, not a step in this install.
- Do not install HACS or any add-on. Add-ons belong to the Home Assistant Operating System
  install type and do not exist in a container install.
- Do not configure SMTP or any notify platform. Home Assistant runs without mail, and the
  channels you want are accounts and tokens you pick in the interface.

298 lines · 14,862 bytes

You are Claude Code on the user's own computer. There is no server and no Prompt Zero:
everything in this prompt runs on this machine and stays on it.

Run every command on this computer, in the shell you are already in. Nothing in this prompt
uses ssh.

Install Home Assistant 2026.7.4 under ~/selfhost/home-assistant, answering at
http://localhost:8107.

## 1. Preflight

Say this to the user before step 2 runs; it decides whether they want this install at all.
Home Assistant will answer at http://localhost:8107, which means this computer and nothing
else, so their phone cannot reach it and the companion app cannot connect to it. Every
automation they write runs only while this machine is awake, so a laptop that closes at night
is a house that stops automating at night. And because the container sits behind Docker's
bridge rather than on the home network, the discovery that finds a Hue bridge or a Sonos
speaker on its own will not fire; integrations they add by typing an address or signing into a
cloud account still work. What they get today is a real Home Assistant to learn on, keep
history in, and move to a small always-on machine later.

Detect the OS and measure the machine:

```bash
uname -s
case "$(uname -s)" in
  Darwin) vm_stat | awk '/page size/{p=$8} /free|inactive/{s+=$3} END {printf "%d MB available\n", s*p/1048576}' ;;
  Linux) . /etc/os-release && echo "$ID $VERSION_CODENAME"; free -m | awk '/^Mem:/ {print $7 " MB available of " $2 " MB"}' ;;
  MINGW*|MSYS*) powershell -Command "(Get-CimInstance Win32_OperatingSystem).FreePhysicalMemory" | awk '$1+0 {printf "%d MB available\n", $1/1024}' ;;
esac
df -h ~
```

`Darwin` is macOS, `Linux` is Linux, `MINGW` or `MSYS` is Windows under Git Bash. On Linux the
distribution ID and codename print next, for step 2. Home Assistant needs 1024 MB of RAM
available and 5 GB free on the home disk, and the 2026.7.4 image is published for amd64 and
arm64. On macOS and Windows the figure printed is the host's, and Docker Desktop's virtual
machine takes its allocation out of it. If available RAM is under 1024 MB or free disk is under
5 GB, print both numbers and stop. Do not install and hope.

## 2. Docker

Check before installing anything:

```bash
docker info >/dev/null 2>&1 && echo "docker OK" || echo "docker MISSING"
docker compose version 2>/dev/null || true
```

If that printed `docker OK` and a compose version, skip to step 3.

Otherwise, install Docker for the OS step 1 detected:

- macOS: if `command -v brew` succeeds, run `brew install --cask docker`. If there is no
  Homebrew, STOP: tell the user to download Docker Desktop from
  https://www.docker.com/products/docker-desktop/ and install it, and wait until they
  confirm. Either way, then STOP: tell the user to open Docker Desktop once, accept its
  terms, and wait for the whale icon to say it is running. Do not continue until they
  confirm.
- Windows: run `winget install -e --id Docker.DockerDesktop`. If winget is missing or the
  install fails, STOP: tell the user to download Docker Desktop from the URL above and
  install it, and wait until they confirm. Docker Desktop configures WSL 2 itself and may
  ask for a reboot; if it does, STOP and tell the user to reboot and come back, this
  prompt resumes at this step. Then STOP: have the user open Docker Desktop, accept its
  terms, and confirm it says running.
- Linux, Debian or Ubuntu: install Docker Engine from download.docker.com's apt
  repository, with its signing key saved to a file first, never piped into a shell. The
  fence is guarded, a no-op on anything but a Linux with apt:

```bash
if [ "$(uname -s)" = "Linux" ] && command -v apt-get >/dev/null 2>&1; then
  sudo apt-get update
  sudo apt-get install -y ca-certificates curl
  sudo install -m 0755 -d /etc/apt/keyrings
  sudo curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
  sudo chmod a+r /etc/apt/keyrings/docker.asc
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/$(. /etc/os-release && echo "$ID") $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
  sudo apt-get update
  sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
  sudo usermod -aG docker "$USER"
fi
```

  Adding the user to the docker group is root-equivalent on this machine; say that to the
  user in one sentence, and tell them the group change lands at their next login.
- Linux, anything else: STOP. Tell the user to install Docker Engine and the compose
  plugin with their distribution's package manager, and to run this prompt again once
  `docker info` works.

Assert: `docker info` exits 0 and `docker compose version` prints a version. Do not
continue without both.

## 3. Layout

```bash
mkdir -p ~/selfhost/home-assistant/config ~/selfhost/home-assistant/backups
ls -la ~/selfhost/home-assistant
```

Assert: `ls -la` shows `config` and `backups`, both owned by the user. Nothing else is created
here. Home Assistant writes its own `configuration.yaml` into `config` on the first start, and
this path leaves it alone: there is no reverse proxy on this machine, so there is nothing the
file has to be told about before anything can reach it.

On Linux the container runs as root, so the files it writes into `config` will belong to root
on this machine and reading them takes `sudo`. On macOS and Windows, Docker Desktop's file
sharing handles that and the files stay the user's.

## 4. Secrets

Nothing is generated here and there is no `.env` file. Home Assistant's only credential is the
owner account, and the user creates it in a browser at step 7, so this block runs no commands.

Say two things to the user. First: between the container starting and that account existing,
the onboarding form is open to anyone with a session on this computer, and the first person
through it owns the house, which is why step 7 makes that window short and stops there.
Second, on Windows: mode bits on NTFS are advisory, so no `chmod` protects anything here; the
user's own Windows account is the real boundary on a single-user machine, and everything this
install writes sits in their home directory.

## 5. compose.yml

```bash
cat > ~/selfhost/home-assistant/compose.yml <<'EOF'
# Home Assistant · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   container install .. https://www.home-assistant.io/installation/linux/
#   http integration ... https://www.home-assistant.io/integrations/http/
#   remote access ...... https://www.home-assistant.io/docs/configuration/remote/
#
# One container on the computer you are sitting at. Every path is relative to
# ~/selfhost/home-assistant/, which lets one file work on macOS, Linux and
# Windows. There is no named volume here: nothing in this install chowns its
# own data directory, so ./config stays a bind mount and you can open it in
# Finder or Explorer. Upstream's example sets network_mode: host and
# privileged: true to reach devices on the local network; this file keeps the
# bridge and one loopback port, because host networking would put Home
# Assistant on every network this machine joins and does nothing at all under
# Docker Desktop, where the container runs inside a virtual machine. Same
# 2026.7.4 tag and digest as the server file, read from ghcr.io on 2026-08-06,
# published for linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:2026.7.4@sha256:5a531753cea96444200158fc2b0ac7ccd739291ec50414877b396de6e0bb29b3
    container_name: homeassistant
    restart: unless-stopped
    environment:
      # This labels the container's log timestamps. Home Assistant's own time
      # zone is a separate setting, chosen during onboarding.
      TZ: UTC
    volumes:
      # The image runs as root, so on Linux the files under ./config belong to
      # root on the host. Docker Desktop handles that for macOS and Windows.
      - ./config:/config
    ports:
      # Loopback only: no other device on the wifi can reach 8107, and 8123 is
      # the port Home Assistant listens on inside the container.
      - "127.0.0.1:8107:8123"
EOF
cd ~/selfhost/home-assistant && docker compose config >/dev/null && echo "compose OK"
```

Assert: that prints `compose OK`. One service, one published port, one bind mount.

## 6. Nothing is public

No reverse proxy, no certificate, no firewall rule. Each is a decision:

- No DNS. There is no hostname, so nothing to resolve and nothing to wait for.
- No TLS. A certificate attests a public name and nothing here has one. Browsers treat
  http://localhost as a secure context anyway, so pages needing crypto still work.
- No firewall rule. Nothing is published beyond loopback, so no port needs closing.

8107 is bound to 127.0.0.1, this computer only. The user's phone cannot reach it, nor a tablet
on the same wifi, nor anyone on the internet. For a home dashboard that is the sharpest edge of
this path, and it is the shape of the trade rather than a defect in it. Confirm it:

```bash
grep -n '127.0.0.1' ~/selfhost/home-assistant/compose.yml
```

Assert: one line, `- "127.0.0.1:8107:8123"`.

## 7. Start and verify

The first start is slow. Home Assistant installs the Python requirements for the integrations
it loads by default before it serves anything. The loop below waits for it.

```bash
cd ~/selfhost/home-assistant
docker compose pull
docker compose up -d
for i in $(seq 1 40); do code=$(curl -sS -o /dev/null -w '%{http_code}' http://localhost:8107/api/onboarding); echo "$i $code"; [ "$code" = 200 ] && break; sleep 15; done
curl -sS http://localhost:8107/api/onboarding
echo
curl -sS -o /dev/null -w '%{http_code}\n' http://localhost:8107/api/
```

Assert all three, and print what you received for each: the loop ends on `200`; the onboarding
response contains `"step":"user","done":false`; the last command prints `401`, because that
endpoint needs a token and refusing without one is the security assert here. If the loop never
reaches `200`, run `docker compose logs --tail 40 homeassistant` and read it: on the first boot
the log is a long list of packages being installed, which is the container working rather than
failing. If `port is already allocated` came back, find what holds 8107
(`lsof -nP -iTCP:8107 -sTCP:LISTEN`, `ss -ltnp | grep 8107` on Linux,
`netstat -ano | findstr :8107` on Windows) and stop until the user frees it. A running
container is not success.

The first screen at http://localhost:8107 shows the heading `Welcome!` and a button reading
`Create my smart home`. Until someone submits that form, anyone with a session on this
computer can.

STOP: tell the user to open http://localhost:8107 now, create the owner account, and save the
password in their password manager. Wait until they confirm.

Then prove it closed:

```bash
curl -sS http://localhost:8107/api/onboarding
echo
```

Assert: the response now contains `"step":"user","done":true`. Both asserts must pass before
you report success.

## 8. First backup and restore

Take the backup now, before the user adds a single device. Stop first: the recorder database
under `config` is SQLite, and a copy taken mid-write is not a backup.

```bash
cd ~/selfhost/home-assistant
docker compose stop
tar -C ~/selfhost/home-assistant -czf ~/selfhost/home-assistant/backups/home-assistant-$(date +%F).tar.gz config compose.yml
docker compose start
ls -lh ~/selfhost/home-assistant/backups/
```

Assert: the archive exists and is non-empty. Print its size. Downtime is about ten seconds. On
Linux this needs `sudo tar` if the container has already written root-owned files into
`config`; run it again with `sudo` and the archive belongs to root, which is fine.

That archive sits on the same disk as the data, which is not a backup, and on a laptop the disk
and the machine fail together. Ask the user for a destination that leaves this computer, a
folder their sync service watches or a USB stick, and copy it there with `cp`. In Git Bash a
Windows drive is written `/d/Backups`, not `D:\Backups`; confirm the destination exists before
copying. Assert: the user confirms the filename is listed there. If they have nowhere to put
it, say plainly that this install has no backup.

To restore: `docker compose down`, `rm -rf ~/selfhost/home-assistant/config`,
`tar -C ~/selfhost/home-assistant -xzf` the archive, then `docker compose up -d`. Those four
commands are the whole disaster plan, and on Linux the middle two take `sudo` for the same
reason the backup did. The part that matters most is the `.storage` directory
inside `config`: it holds the owner account and the token for every integration ever linked,
and losing it means linking all of them again by hand.

## 9. Updating later

New versions are listed at https://github.com/home-assistant/core/releases. Take a backup
first, then edit the image line in ~/selfhost/home-assistant/compose.yml to the new tag and
digest:

```bash
cd ~/selfhost/home-assistant
docker compose pull
docker compose up -d
docker compose logs --tail 30 homeassistant
```

Home Assistant migrates its own storage on the way up, so watch that log until it settles, then
re-run step 7's check before calling the update done.

## 10. What will probably go wrong

I closed the laptop at eleven, opened it at seven, and the automation that was supposed to turn
the lamps off at midnight had never run. Nothing was broken and nothing recovered it, because
Home Assistant was not running: the machine was asleep, and a schedule that passes while the
container is stopped is a schedule that does not fire. `restart: unless-stopped` only acts once
the Docker daemon is up, so the same thing happens after a reboot until Docker Desktop starts.
Turn on its start-at-login setting, and treat any automation that has to happen at a fixed time
as the reason to move this to a machine that stays on.

## 11. Out of scope

- Do not expose this to the internet.
- Do not configure port forwarding on the router.
- Do not add a reverse proxy or TLS.
- Do not rebind 8107 to 0.0.0.0 or set `network_mode: host` so a phone or a device-discovery
  scan can reach it. Host networking does nothing under Docker Desktop, where the container is
  inside a virtual machine, and on Linux it puts a half-configured Home Assistant on every
  network this laptop joins.
- Do not install HACS or any add-on. Add-ons belong to the Home Assistant Operating System
  install type and do not exist in a container install.
- Do not configure the Alexa or Google Assistant integrations. Both need a public address that
  this install does not have.

# Home Assistant · the deterministic fallback for the local path. Authored by
# caniselfhostit from the upstream documentation, not copied from a repository:
#   container install .. https://www.home-assistant.io/installation/linux/
#   http integration ... https://www.home-assistant.io/integrations/http/
#   remote access ...... https://www.home-assistant.io/docs/configuration/remote/
#
# One container on the computer you are sitting at. Every path is relative to
# ~/selfhost/home-assistant/, which lets one file work on macOS, Linux and
# Windows. There is no named volume here: nothing in this install chowns its
# own data directory, so ./config stays a bind mount and you can open it in
# Finder or Explorer. Upstream's example sets network_mode: host and
# privileged: true to reach devices on the local network; this file keeps the
# bridge and one loopback port, because host networking would put Home
# Assistant on every network this machine joins and does nothing at all under
# Docker Desktop, where the container runs inside a virtual machine. Same
# 2026.7.4 tag and digest as the server file, read from ghcr.io on 2026-08-06,
# published for linux/amd64 and linux/arm64.
#
# NOT YET VERIFIED: no harness run has been recorded against this file.

services:
  homeassistant:
    image: ghcr.io/home-assistant/home-assistant:2026.7.4@sha256:5a531753cea96444200158fc2b0ac7ccd739291ec50414877b396de6e0bb29b3
    container_name: homeassistant
    restart: unless-stopped
    environment:
      # This labels the container's log timestamps. Home Assistant's own time
      # zone is a separate setting, chosen during onboarding.
      TZ: UTC
    volumes:
      # The image runs as root, so on Linux the files under ./config belong to
      # root on the host. Docker Desktop handles that for macOS and Windows.
      - ./config:/config
    ports:
      # Loopback only: no other device on the wifi can reach 8107, and 8123 is
      # the port Home Assistant listens on inside the container.
      - "127.0.0.1:8107:8123"