Vibecode Home Assistant Cloud

You are building a lean indie version of Home Assistant Cloud.

Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt.

===== README.md =====
# Home Assistant Cloud · indie build

Home Assistant reachable from anywhere through an outbound tunnel or a private network, with certificates, an authentication layer in front, two factor authentication enabled, and backups that go somewhere other than the machine in your cupboard.

Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts.

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Platform | Home Assistant, self-hosted | the thing you are keeping; only the remote access is being replaced |
| Remote access | An outbound tunnel, or a private mesh network | both avoid opening an inbound port, which is the entire security argument |
| Certificates | Automatic certificates through the tunnel or a reverse proxy | a browser warning teaches your household to click through warnings |
| Authentication | Home Assistant's own accounts with two factor, plus a layer in front for the public path | the application's login is not designed to be the only thing on the public internet |
| Backups | Automated snapshots copied off the machine | a home automation setup is months of configuration and it lives on one memory card |

## Before you start

Have every one of these ready. The plan assumes them from step one.

- [ ] **A working Home Assistant installation** · free software; the hardware is usually a small computer costing under 100 USD
  - Why: This build is about reaching it, not creating it. If it is not already working locally, that is a different project.
  - Get it: Follow the official installation for your hardware. Note which method you used, because it determines backup and update procedures.
  - Verify: It is reachable on your local network and controls a real device
- [ ] **A choice between an outbound tunnel and a private mesh** · both have usable free tiers for a household
  - Why: They have different tradeoffs for guests, for complexity and for what is exposed. Choosing after building means redoing the work.
  - Get it: A tunnel gives a public hostname that anyone can reach, so it needs the front layer in Phase 4. A mesh network is private to your enrolled devices and simpler to secure, but a guest cannot use it without being enrolled.
  - Verify: The decision and its reasoning are written down before Phase 3
- [ ] **A domain name, if you chose a tunnel** (optional) · roughly 10 to 15 USD a year
  - Why: Certificates need a hostname, and a memorable one matters when household members type it.
  - Get it: Any registrar, then follow your tunnel provider's instructions for pointing it.
  - Verify: The hostname resolves and serves a valid certificate
- [ ] **A backup destination that is not the Home Assistant machine** · free with a spare drive; a few USD a month for object storage
  - Why: The machine is usually a small computer with a memory card, and memory cards fail. Months of configuration live on it.
  - Get it: Another machine on the network plus an offsite copy, or object storage. Two destinations rather than one.
  - Verify: A backup has been restored onto different hardware
- [ ] **Spare hardware for the restore drill** · free if you have anything spare
  - Why: Phase 1 restores onto different hardware, and that drill is what makes everything after it recoverable.
  - Get it: Any spare machine, or a virtual machine. It only needs to run long enough to prove the restore.
  - Verify: A restored instance controls a device

## Quick start

```sh
nmap -Pn YOUR_HOME_IP
```

Then copy `.env.example` to `.env` and fill in the values it documents.

## Honest limits

This build deliberately does not replace:

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.
- managed remote access, voice integrations, funding for open source, and low-maintenance security
- frictionless family sync
- retailer and smart-home integrations
- large recipe or product database
- mobile polish

If one of those is essential to you, that is the reason to keep paying for Home Assistant Cloud, and the README should say so rather than pretend.

===== BRIEF.md =====
# Build brief · Home Assistant Cloud

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me remote access to your own Home Assistant, through a tunnel you control, without opening a port to replace Home Assistant Cloud. Build it in phases, in the order below.
Do not write the whole thing in one pass. Finish a phase, run its "Done when"
check, fix what fails, and only then start the next phase.

### Rule zero
Do not build a smart home platform. Home Assistant is the platform and this is about
reaching it from outside your house safely. The subscription you are replacing pays for
managed remote access, voice assistant integrations, and the funding that keeps the
open source project alive. The last of those is worth saying out loud: if you can
afford the subscription, it is one of the more directly useful ones in this catalogue.
Never open a port on your router to expose Home Assistant directly. It is the single
most common way these installations are compromised, and the alternatives below are
not meaningfully harder.

### Stack (fixed, do not substitute)
- Platform: Home Assistant, self-hosted · the thing you are keeping; only the remote access is being replaced
- Remote access: An outbound tunnel, or a private mesh network · both avoid opening an inbound port, which is the entire security argument
- Certificates: Automatic certificates through the tunnel or a reverse proxy · a browser warning teaches your household to click through warnings
- Authentication: Home Assistant's own accounts with two factor, plus a layer in front for the public path · the application's login is not designed to be the only thing on the public internet
- Backups: Automated snapshots copied off the machine · a home automation setup is months of configuration and it lives on one memory card

### Data model (create this before Phase 1)
- This is infrastructure, so the state worth recording is operational.
- instance · the Home Assistant host, its version, and what it controls
- access paths · the tunnel or mesh, the hostname, and who can reach it
- accounts · household members, their permissions, and which have two factor enabled
- backups · schedule, destination, retention, and the date of the last restore
- The rule that shapes everything: nothing inbound. Every path is either an outbound tunnel or a private network.

### Phase 1 · A local installation you have backed up
Build: Install or confirm Home Assistant on your own hardware. Set up automated backups and
  copy them off the machine. Restore one onto a different machine before you expose
  anything, because the restore is what makes the rest of this recoverable.
Trap: Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
Done when: Home Assistant is reachable on the local network. Automated backups run on a schedule and land off the machine. A backup has been restored onto different hardware and the restored instance controls a device, and the date is recorded.
Do not build yet: No remote access at all yet. Local and recoverable first.

### Phase 2 · Accounts and two factor, before anything is exposed
Build: Create individual accounts for household members rather than sharing one. Enable two
  factor authentication on every account that will have remote access. Review what each
  account can control and restrict where it makes sense.
Trap: A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
Done when: Every household member has their own account. Two factor is enabled on every account with remote access, verified by signing in from a private window. A restricted account cannot control devices outside its permissions, tested rather than assumed.
Do not build yet: Still nothing exposed. The gate before the door.

### Phase 3 · Remote access without an open port
Build: Choose between an outbound tunnel, which gives a public hostname, and a private mesh
  network, which gives access only to your own devices. Set it up, confirm it works from
  a mobile connection, and confirm your router still forwards nothing.
Trap: Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
Done when: The instance is reachable from a mobile connection with the local network unavailable. The router's port forwarding table is empty, verified by looking at it. An external port scan of your home address shows nothing open. Certificates are valid and no browser warning appears.
Do not build yet: No extra authentication layer or notifications yet.

### Phase 4 · A layer in front of the public path
Build: For a tunnel with a public hostname, put an authentication layer in front. Rate limit
  and ban repeated failures. Ensure the mobile application still works, which usually
  means a bypass path with its own credential rather than an interactive login.
Trap: An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
Done when: An unauthenticated request to the public hostname does not reach the application. Repeated failed attempts result in a temporary ban. The mobile application works from a mobile connection with the layer in place, tested on a real device. Home Assistant's own ban list is enabled as well.
Do not build yet: No notifications or voice yet.

### Phase 5 · Notifications and the things the subscription did
Build: Configure notifications through a self-hosted or free service rather than the
  subscription's. Then write down honestly what you are not getting: the managed voice
  assistant integrations in particular, which are genuinely difficult to replace.
Trap: Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
Done when: A notification triggered by an automation reaches a phone away from home. The notification path works when the household internet is up but the phone is on a mobile connection. A written list records which subscription features are not replaced, with voice integration named specifically.
Do not build yet: Operations and updates come last.

### Phase 6 · Updates, monitoring and the household
Build: A documented update procedure that backs up first. Monitoring that tells you the
  instance is down before your household does. A written note for the household covering
  how to reach it and what to do if it stops working.
Trap: Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.
Done when: An update procedure is documented and has been followed once, with a backup taken first. An uptime check alerts when the instance stops responding, tested by stopping it. A household note exists explaining how to reach the system and who to contact. A rollback to the previous version has been tested.
Do not build yet: Nothing after this.

### Out of scope (and why)
- Managed voice assistant integrations. These need reviewed relationships with each assistant platform and are the hardest part of the subscription to replace.
- Someone else keeping the remote access path patched and secure. That is now you, permanently.
- The frictionless setup for household members who are not technical, which matters more than it sounds when something breaks while you are away.
- Funding the open source project. The subscription pays for Home Assistant's development, and replacing it removes that contribution.

### README must contain
- That no inbound port is open, and how that was verified
- Which remote access method was chosen and what it means for guests
- That every remotely reachable account has two factor enabled
- The backup schedule, destination, and the date of the last restore onto different hardware
- Which subscription features are not replaced, with voice integration named

===== AGENTS.md =====
# Agent instructions · Home Assistant Cloud indie build

- Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Home Assistant, self-hosted, An outbound tunnel, or a private mesh network, Automatic certificates through the tunnel or a reverse proxy, Home Assistant's own accounts with two factor, plus a layer in front for the public path, Automated snapshots copied off the machine. Do not substitute.
- Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes.
- Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name.
- Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced.
- Do not invent cryptography, security guarantees, APIs or compliance claims.
- Add a focused test for every destructive, security-sensitive or data-loss path the plan names.
- Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".

## Known traps

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

===== BUILD_PLAN.md =====
# Build plan · Home Assistant Cloud

Home Assistant reachable from anywhere through an outbound tunnel or a private network, with certificates, an authentication layer in front, two factor authentication enabled, and backups that go somewhere other than the machine in your cupboard.

Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note.

## Phase 1 · A local installation you have backed up

Home Assistant runs, and losing the machine would not lose your configuration.

### Steps

1. Confirm the installation and version
   Note the installation method, because it determines how you back up and how you update.
   Files: `README.md`
2. Automate backups off the machine
   Scheduled snapshots copied to another machine or object storage. On the device is not off the device.
   Files: `scripts/backup.sh`
3. Restore onto different hardware
   Before exposing anything. A restore you have not done is a plan, not a backup.
   Files: `README.md`

### Done when

- [ ] Home Assistant is reachable locally
- [ ] Backups run on a schedule and land off the machine
- [ ] A restore onto different hardware has been performed and dated
- [ ] The restored instance controls a real device

### Watch out

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.

## Phase 2 · Accounts and two factor, before anything is exposed

Every account that could reach this from outside has a second factor.

### Steps

1. Create individual accounts
   One per person. Shared credentials cannot be revoked individually, which matters when a phone is lost.
2. Enable two factor everywhere
   On every account that will be reachable remotely. Verify each by signing in fresh.
3. Restrict where sensible
   Not everyone needs to control the door lock. Test the restriction rather than trusting the setting.

### Done when

- [ ] Each household member has their own account
- [ ] Two factor is verified on every remotely reachable account
- [ ] A restricted account is confirmed unable to exceed its permissions
- [ ] No shared account remains with remote access

### Watch out

- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.

## Phase 3 · Remote access without an open port

You can reach it from outside, and your router has no forwarded port.

### Steps

1. Choose tunnel or mesh deliberately
   A tunnel gives a public hostname anyone could reach, so it needs the layer in Phase 4. A mesh is private to your devices and simpler but harder for guests.
   Files: `docs/access.md`
2. Set it up and get certificates
   Automatic certificates through whichever you chose. A warning page is not acceptable for something your household uses daily.
3. Verify nothing is inbound
   Check the router's forwarding table and scan your home address from outside. Both, because either alone can mislead.

   ```sh
   nmap -Pn YOUR_HOME_IP
   ```


### Done when

- [ ] Reachable from a mobile connection with local network off
- [ ] The router forwards no ports
- [ ] An external scan of the home address shows nothing open
- [ ] Certificates are valid with no browser warning

### Watch out

- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.

## Phase 4 · A layer in front of the public path

If the hostname is public, something stands in front of the application's own login.

### Steps

1. Add the front layer
   Basic authentication at minimum, an identity proxy if you want more. Something before the application's login.
   Files: `Caddyfile`
2. Enable banning at both levels
   The proxy and Home Assistant's own failed login banning. They catch different things.
   Files: `configuration.yaml`
3. Make the mobile application work
   A token or client certificate path, tested on a real phone from a mobile connection before anyone else depends on it.

### Done when

- [ ] An unauthenticated public request does not reach the application
- [ ] Repeated failures produce a temporary ban
- [ ] The mobile application works through the layer on a real phone
- [ ] Home Assistant's own ban list is enabled

### Watch out

- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.

## Phase 5 · Notifications and the things the subscription did

You get alerts away from home, and you know which convenience features you gave up.

### Steps

1. Set up a notification path
   A self-hosted push service or a free tier one. Test from outside the house rather than from the sofa.
   Files: `configuration.yaml`
2. Test the failure modes
   Phone on mobile data, and the case where your home connection drops entirely, which is when you most want the alert and least likely to get it.
3. Write down what you gave up
   Voice integrations, managed certificates, and someone else handling security updates for the remote access path.
   Files: `docs/tradeoffs.md`

### Done when

- [ ] An automation notification reaches a phone away from home
- [ ] Notifications work with the phone on mobile data
- [ ] The behaviour when the home connection drops is documented
- [ ] The list of unreplaced features names voice integration

### Watch out

- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

## Not in this build

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.

## After v1, if you want it

- A local voice pipeline, accepting that it is a substantial project of its own
- A second tunnel or mesh path as a failover, since remote access failing while away is the annoying case
- Automated verification that the newest backup actually restores, rather than only that it exists

===== .env.example =====
# Copy to .env and fill in. Never commit .env; this file documents it.

# Required. The local address. Used by backup scripts and monitoring on the local network.
HA_LOCAL_URL=http://homeassistant.local:8123

# Optional. Only if you chose a tunnel. The public hostname.
HA_REMOTE_HOSTNAME=home.example.com

# Optional · secret. Your tunnel provider's credential. Lives on the Home Assistant machine only.
TUNNEL_TOKEN=replace-with-provider-token

# Required. Where snapshots are copied. Not the Home Assistant machine.
BACKUP_DEST=s3://your-bucket/homeassistant

# Required. How many snapshots to keep. Enough to go back past a bad update.
BACKUP_RETAIN=14

# Required. What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.
UPTIME_CHECK_URL=https://home.example.com/manifest.json

You are building a lean indie version of Home Assistant Cloud.

Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt.

===== README.md =====
# Home Assistant Cloud · indie build

Home Assistant reachable from anywhere through an outbound tunnel or a private network, with certificates, an authentication layer in front, two factor authentication enabled, and backups that go somewhere other than the machine in your cupboard.

Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts.

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Platform | Home Assistant, self-hosted | the thing you are keeping; only the remote access is being replaced |
| Remote access | An outbound tunnel, or a private mesh network | both avoid opening an inbound port, which is the entire security argument |
| Certificates | Automatic certificates through the tunnel or a reverse proxy | a browser warning teaches your household to click through warnings |
| Authentication | Home Assistant's own accounts with two factor, plus a layer in front for the public path | the application's login is not designed to be the only thing on the public internet |
| Backups | Automated snapshots copied off the machine | a home automation setup is months of configuration and it lives on one memory card |

## Before you start

Have every one of these ready. The plan assumes them from step one.

- [ ] **A working Home Assistant installation** · free software; the hardware is usually a small computer costing under 100 USD
  - Why: This build is about reaching it, not creating it. If it is not already working locally, that is a different project.
  - Get it: Follow the official installation for your hardware. Note which method you used, because it determines backup and update procedures.
  - Verify: It is reachable on your local network and controls a real device
- [ ] **A choice between an outbound tunnel and a private mesh** · both have usable free tiers for a household
  - Why: They have different tradeoffs for guests, for complexity and for what is exposed. Choosing after building means redoing the work.
  - Get it: A tunnel gives a public hostname that anyone can reach, so it needs the front layer in Phase 4. A mesh network is private to your enrolled devices and simpler to secure, but a guest cannot use it without being enrolled.
  - Verify: The decision and its reasoning are written down before Phase 3
- [ ] **A domain name, if you chose a tunnel** (optional) · roughly 10 to 15 USD a year
  - Why: Certificates need a hostname, and a memorable one matters when household members type it.
  - Get it: Any registrar, then follow your tunnel provider's instructions for pointing it.
  - Verify: The hostname resolves and serves a valid certificate
- [ ] **A backup destination that is not the Home Assistant machine** · free with a spare drive; a few USD a month for object storage
  - Why: The machine is usually a small computer with a memory card, and memory cards fail. Months of configuration live on it.
  - Get it: Another machine on the network plus an offsite copy, or object storage. Two destinations rather than one.
  - Verify: A backup has been restored onto different hardware
- [ ] **Spare hardware for the restore drill** · free if you have anything spare
  - Why: Phase 1 restores onto different hardware, and that drill is what makes everything after it recoverable.
  - Get it: Any spare machine, or a virtual machine. It only needs to run long enough to prove the restore.
  - Verify: A restored instance controls a device

## Quick start

```sh
nmap -Pn YOUR_HOME_IP
```

Then copy `.env.example` to `.env` and fill in the values it documents.

## Honest limits

This build deliberately does not replace:

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.
- managed remote access, voice integrations, funding for open source, and low-maintenance security
- frictionless family sync
- retailer and smart-home integrations
- large recipe or product database
- mobile polish

If one of those is essential to you, that is the reason to keep paying for Home Assistant Cloud, and the README should say so rather than pretend.

===== BRIEF.md =====
# Build brief · Home Assistant Cloud

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me remote access to your own Home Assistant, through a tunnel you control, without opening a port to replace Home Assistant Cloud. Build it in phases, in the order below.
Do not write the whole thing in one pass. Finish a phase, run its "Done when"
check, fix what fails, and only then start the next phase.

### Rule zero
Do not build a smart home platform. Home Assistant is the platform and this is about
reaching it from outside your house safely. The subscription you are replacing pays for
managed remote access, voice assistant integrations, and the funding that keeps the
open source project alive. The last of those is worth saying out loud: if you can
afford the subscription, it is one of the more directly useful ones in this catalogue.
Never open a port on your router to expose Home Assistant directly. It is the single
most common way these installations are compromised, and the alternatives below are
not meaningfully harder.

### Stack (fixed, do not substitute)
- Platform: Home Assistant, self-hosted · the thing you are keeping; only the remote access is being replaced
- Remote access: An outbound tunnel, or a private mesh network · both avoid opening an inbound port, which is the entire security argument
- Certificates: Automatic certificates through the tunnel or a reverse proxy · a browser warning teaches your household to click through warnings
- Authentication: Home Assistant's own accounts with two factor, plus a layer in front for the public path · the application's login is not designed to be the only thing on the public internet
- Backups: Automated snapshots copied off the machine · a home automation setup is months of configuration and it lives on one memory card

### Data model (create this before Phase 1)
- This is infrastructure, so the state worth recording is operational.
- instance · the Home Assistant host, its version, and what it controls
- access paths · the tunnel or mesh, the hostname, and who can reach it
- accounts · household members, their permissions, and which have two factor enabled
- backups · schedule, destination, retention, and the date of the last restore
- The rule that shapes everything: nothing inbound. Every path is either an outbound tunnel or a private network.

### Phase 1 · A local installation you have backed up
Build: Install or confirm Home Assistant on your own hardware. Set up automated backups and
  copy them off the machine. Restore one onto a different machine before you expose
  anything, because the restore is what makes the rest of this recoverable.
Trap: Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
Done when: Home Assistant is reachable on the local network. Automated backups run on a schedule and land off the machine. A backup has been restored onto different hardware and the restored instance controls a device, and the date is recorded.
Do not build yet: No remote access at all yet. Local and recoverable first.

### Phase 2 · Accounts and two factor, before anything is exposed
Build: Create individual accounts for household members rather than sharing one. Enable two
  factor authentication on every account that will have remote access. Review what each
  account can control and restrict where it makes sense.
Trap: A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
Done when: Every household member has their own account. Two factor is enabled on every account with remote access, verified by signing in from a private window. A restricted account cannot control devices outside its permissions, tested rather than assumed.
Do not build yet: Still nothing exposed. The gate before the door.

### Phase 3 · Remote access without an open port
Build: Choose between an outbound tunnel, which gives a public hostname, and a private mesh
  network, which gives access only to your own devices. Set it up, confirm it works from
  a mobile connection, and confirm your router still forwards nothing.
Trap: Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
Done when: The instance is reachable from a mobile connection with the local network unavailable. The router's port forwarding table is empty, verified by looking at it. An external port scan of your home address shows nothing open. Certificates are valid and no browser warning appears.
Do not build yet: No extra authentication layer or notifications yet.

### Phase 4 · A layer in front of the public path
Build: For a tunnel with a public hostname, put an authentication layer in front. Rate limit
  and ban repeated failures. Ensure the mobile application still works, which usually
  means a bypass path with its own credential rather than an interactive login.
Trap: An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
Done when: An unauthenticated request to the public hostname does not reach the application. Repeated failed attempts result in a temporary ban. The mobile application works from a mobile connection with the layer in place, tested on a real device. Home Assistant's own ban list is enabled as well.
Do not build yet: No notifications or voice yet.

### Phase 5 · Notifications and the things the subscription did
Build: Configure notifications through a self-hosted or free service rather than the
  subscription's. Then write down honestly what you are not getting: the managed voice
  assistant integrations in particular, which are genuinely difficult to replace.
Trap: Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
Done when: A notification triggered by an automation reaches a phone away from home. The notification path works when the household internet is up but the phone is on a mobile connection. A written list records which subscription features are not replaced, with voice integration named specifically.
Do not build yet: Operations and updates come last.

### Phase 6 · Updates, monitoring and the household
Build: A documented update procedure that backs up first. Monitoring that tells you the
  instance is down before your household does. A written note for the household covering
  how to reach it and what to do if it stops working.
Trap: Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.
Done when: An update procedure is documented and has been followed once, with a backup taken first. An uptime check alerts when the instance stops responding, tested by stopping it. A household note exists explaining how to reach the system and who to contact. A rollback to the previous version has been tested.
Do not build yet: Nothing after this.

### Out of scope (and why)
- Managed voice assistant integrations. These need reviewed relationships with each assistant platform and are the hardest part of the subscription to replace.
- Someone else keeping the remote access path patched and secure. That is now you, permanently.
- The frictionless setup for household members who are not technical, which matters more than it sounds when something breaks while you are away.
- Funding the open source project. The subscription pays for Home Assistant's development, and replacing it removes that contribution.

### README must contain
- That no inbound port is open, and how that was verified
- Which remote access method was chosen and what it means for guests
- That every remotely reachable account has two factor enabled
- The backup schedule, destination, and the date of the last restore onto different hardware
- Which subscription features are not replaced, with voice integration named

===== AGENTS.md =====
# Agent instructions · Home Assistant Cloud indie build

- Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Home Assistant, self-hosted, An outbound tunnel, or a private mesh network, Automatic certificates through the tunnel or a reverse proxy, Home Assistant's own accounts with two factor, plus a layer in front for the public path, Automated snapshots copied off the machine. Do not substitute.
- Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes.
- Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name.
- Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced.
- Do not invent cryptography, security guarantees, APIs or compliance claims.
- Add a focused test for every destructive, security-sensitive or data-loss path the plan names.
- Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".

## Known traps

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

===== BUILD_PLAN.md =====
# Build plan · Home Assistant Cloud

Home Assistant reachable from anywhere through an outbound tunnel or a private network, with certificates, an authentication layer in front, two factor authentication enabled, and backups that go somewhere other than the machine in your cupboard.

Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note.

## Phase 1 · A local installation you have backed up

Home Assistant runs, and losing the machine would not lose your configuration.

### Steps

1. Confirm the installation and version
   Note the installation method, because it determines how you back up and how you update.
   Files: `README.md`
2. Automate backups off the machine
   Scheduled snapshots copied to another machine or object storage. On the device is not off the device.
   Files: `scripts/backup.sh`
3. Restore onto different hardware
   Before exposing anything. A restore you have not done is a plan, not a backup.
   Files: `README.md`

### Done when

- [ ] Home Assistant is reachable locally
- [ ] Backups run on a schedule and land off the machine
- [ ] A restore onto different hardware has been performed and dated
- [ ] The restored instance controls a real device

### Watch out

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.

## Phase 2 · Accounts and two factor, before anything is exposed

Every account that could reach this from outside has a second factor.

### Steps

1. Create individual accounts
   One per person. Shared credentials cannot be revoked individually, which matters when a phone is lost.
2. Enable two factor everywhere
   On every account that will be reachable remotely. Verify each by signing in fresh.
3. Restrict where sensible
   Not everyone needs to control the door lock. Test the restriction rather than trusting the setting.

### Done when

- [ ] Each household member has their own account
- [ ] Two factor is verified on every remotely reachable account
- [ ] A restricted account is confirmed unable to exceed its permissions
- [ ] No shared account remains with remote access

### Watch out

- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.

## Phase 3 · Remote access without an open port

You can reach it from outside, and your router has no forwarded port.

### Steps

1. Choose tunnel or mesh deliberately
   A tunnel gives a public hostname anyone could reach, so it needs the layer in Phase 4. A mesh is private to your devices and simpler but harder for guests.
   Files: `docs/access.md`
2. Set it up and get certificates
   Automatic certificates through whichever you chose. A warning page is not acceptable for something your household uses daily.
3. Verify nothing is inbound
   Check the router's forwarding table and scan your home address from outside. Both, because either alone can mislead.

   ```sh
   nmap -Pn YOUR_HOME_IP
   ```


### Done when

- [ ] Reachable from a mobile connection with local network off
- [ ] The router forwards no ports
- [ ] An external scan of the home address shows nothing open
- [ ] Certificates are valid with no browser warning

### Watch out

- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.

## Phase 4 · A layer in front of the public path

If the hostname is public, something stands in front of the application's own login.

### Steps

1. Add the front layer
   Basic authentication at minimum, an identity proxy if you want more. Something before the application's login.
   Files: `Caddyfile`
2. Enable banning at both levels
   The proxy and Home Assistant's own failed login banning. They catch different things.
   Files: `configuration.yaml`
3. Make the mobile application work
   A token or client certificate path, tested on a real phone from a mobile connection before anyone else depends on it.

### Done when

- [ ] An unauthenticated public request does not reach the application
- [ ] Repeated failures produce a temporary ban
- [ ] The mobile application works through the layer on a real phone
- [ ] Home Assistant's own ban list is enabled

### Watch out

- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.

## Phase 5 · Notifications and the things the subscription did

You get alerts away from home, and you know which convenience features you gave up.

### Steps

1. Set up a notification path
   A self-hosted push service or a free tier one. Test from outside the house rather than from the sofa.
   Files: `configuration.yaml`
2. Test the failure modes
   Phone on mobile data, and the case where your home connection drops entirely, which is when you most want the alert and least likely to get it.
3. Write down what you gave up
   Voice integrations, managed certificates, and someone else handling security updates for the remote access path.
   Files: `docs/tradeoffs.md`

### Done when

- [ ] An automation notification reaches a phone away from home
- [ ] Notifications work with the phone on mobile data
- [ ] The behaviour when the home connection drops is documented
- [ ] The list of unreplaced features names voice integration

### Watch out

- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

## Not in this build

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.

## After v1, if you want it

- A local voice pipeline, accepting that it is a substantial project of its own
- A second tunnel or mesh path as a failover, since remote access failing while away is the annoying case
- Automated verification that the newest backup actually restores, rather than only that it exists

===== .env.example =====
# Copy to .env and fill in. Never commit .env; this file documents it.

# Required. The local address. Used by backup scripts and monitoring on the local network.
HA_LOCAL_URL=http://homeassistant.local:8123

# Optional. Only if you chose a tunnel. The public hostname.
HA_REMOTE_HOSTNAME=home.example.com

# Optional · secret. Your tunnel provider's credential. Lives on the Home Assistant machine only.
TUNNEL_TOKEN=replace-with-provider-token

# Required. Where snapshots are copied. Not the Home Assistant machine.
BACKUP_DEST=s3://your-bucket/homeassistant

# Required. How many snapshots to keep. Enough to go back past a bad update.
BACKUP_RETAIN=14

# Required. What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.
UPTIME_CHECK_URL=https://home.example.com/manifest.json

You are building a production product version of Home Assistant Cloud.

Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt.

===== PRODUCT.md =====
# Home Assistant Cloud · product brief

## Problem

The core loop is buildable, but a dependable replacement becomes a real weekend or multi-day project. For Home Assistant Cloud, self-host smart-home control and use a user-owned remote-access tunnel. The hard boundary is managed remote access, voice integrations, funding for open source, and low-maintenance security, plus sync, integrations, and household adoption.

## Product outcome

Home Assistant reachable from anywhere with no inbound port, every remote account behind two factor, backups off the machine that have actually been restored, and an honest written record of what the subscription did that this does not.

## Target user

A builder who needs a maintainable product foundation, not a one-off demo.

## Required capabilities

- modern browser
- local or self-hosted storage
- optional email notifications

## Explicit non-goals for v1

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.
- managed remote access, voice integrations, funding for open source, and low-maintenance security
- frictionless family sync
- retailer and smart-home integrations
- large recipe or product database
- mobile polish

## Success criteria

- An external scan confirms no inbound port is open
- Two factor is verified on every remotely reachable account
- The mobile application is confirmed working through the front layer on a real phone
- A restore onto different hardware has been performed and dated
- The tradeoffs document names voice integration explicitly

===== BRIEF.md =====
# Build brief · Home Assistant Cloud

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me remote access to your own Home Assistant, through a tunnel you control, without opening a port to replace Home Assistant Cloud. Build it in phases, in the order below.
Do not write the whole thing in one pass. Finish a phase, run its "Done when"
check, fix what fails, and only then start the next phase.

### Rule zero
Do not build a smart home platform. Home Assistant is the platform and this is about
reaching it from outside your house safely. The subscription you are replacing pays for
managed remote access, voice assistant integrations, and the funding that keeps the
open source project alive. The last of those is worth saying out loud: if you can
afford the subscription, it is one of the more directly useful ones in this catalogue.
Never open a port on your router to expose Home Assistant directly. It is the single
most common way these installations are compromised, and the alternatives below are
not meaningfully harder.

### Stack (fixed, do not substitute)
- Platform: Home Assistant, self-hosted · the thing you are keeping; only the remote access is being replaced
- Remote access: An outbound tunnel, or a private mesh network · both avoid opening an inbound port, which is the entire security argument
- Certificates: Automatic certificates through the tunnel or a reverse proxy · a browser warning teaches your household to click through warnings
- Authentication: Home Assistant's own accounts with two factor, plus a layer in front for the public path · the application's login is not designed to be the only thing on the public internet
- Backups: Automated snapshots copied off the machine · a home automation setup is months of configuration and it lives on one memory card

### Data model (create this before Phase 1)
- This is infrastructure, so the state worth recording is operational.
- instance · the Home Assistant host, its version, and what it controls
- access paths · the tunnel or mesh, the hostname, and who can reach it
- accounts · household members, their permissions, and which have two factor enabled
- backups · schedule, destination, retention, and the date of the last restore
- The rule that shapes everything: nothing inbound. Every path is either an outbound tunnel or a private network.

### Phase 1 · A local installation you have backed up
Build: Install or confirm Home Assistant on your own hardware. Set up automated backups and
  copy them off the machine. Restore one onto a different machine before you expose
  anything, because the restore is what makes the rest of this recoverable.
Trap: Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
Done when: Home Assistant is reachable on the local network. Automated backups run on a schedule and land off the machine. A backup has been restored onto different hardware and the restored instance controls a device, and the date is recorded.
Do not build yet: No remote access at all yet. Local and recoverable first.

### Phase 2 · Accounts and two factor, before anything is exposed
Build: Create individual accounts for household members rather than sharing one. Enable two
  factor authentication on every account that will have remote access. Review what each
  account can control and restrict where it makes sense.
Trap: A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
Done when: Every household member has their own account. Two factor is enabled on every account with remote access, verified by signing in from a private window. A restricted account cannot control devices outside its permissions, tested rather than assumed.
Do not build yet: Still nothing exposed. The gate before the door.

### Phase 3 · Remote access without an open port
Build: Choose between an outbound tunnel, which gives a public hostname, and a private mesh
  network, which gives access only to your own devices. Set it up, confirm it works from
  a mobile connection, and confirm your router still forwards nothing.
Trap: Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
Done when: The instance is reachable from a mobile connection with the local network unavailable. The router's port forwarding table is empty, verified by looking at it. An external port scan of your home address shows nothing open. Certificates are valid and no browser warning appears.
Do not build yet: No extra authentication layer or notifications yet.

### Phase 4 · A layer in front of the public path
Build: For a tunnel with a public hostname, put an authentication layer in front. Rate limit
  and ban repeated failures. Ensure the mobile application still works, which usually
  means a bypass path with its own credential rather than an interactive login.
Trap: An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
Done when: An unauthenticated request to the public hostname does not reach the application. Repeated failed attempts result in a temporary ban. The mobile application works from a mobile connection with the layer in place, tested on a real device. Home Assistant's own ban list is enabled as well.
Do not build yet: No notifications or voice yet.

### Phase 5 · Notifications and the things the subscription did
Build: Configure notifications through a self-hosted or free service rather than the
  subscription's. Then write down honestly what you are not getting: the managed voice
  assistant integrations in particular, which are genuinely difficult to replace.
Trap: Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
Done when: A notification triggered by an automation reaches a phone away from home. The notification path works when the household internet is up but the phone is on a mobile connection. A written list records which subscription features are not replaced, with voice integration named specifically.
Do not build yet: Operations and updates come last.

### Phase 6 · Updates, monitoring and the household
Build: A documented update procedure that backs up first. Monitoring that tells you the
  instance is down before your household does. A written note for the household covering
  how to reach it and what to do if it stops working.
Trap: Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.
Done when: An update procedure is documented and has been followed once, with a backup taken first. An uptime check alerts when the instance stops responding, tested by stopping it. A household note exists explaining how to reach the system and who to contact. A rollback to the previous version has been tested.
Do not build yet: Nothing after this.

### Out of scope (and why)
- Managed voice assistant integrations. These need reviewed relationships with each assistant platform and are the hardest part of the subscription to replace.
- Someone else keeping the remote access path patched and secure. That is now you, permanently.
- The frictionless setup for household members who are not technical, which matters more than it sounds when something breaks while you are away.
- Funding the open source project. The subscription pays for Home Assistant's development, and replacing it removes that contribution.

### README must contain
- That no inbound port is open, and how that was verified
- Which remote access method was chosen and what it means for guests
- That every remotely reachable account has two factor enabled
- The backup schedule, destination, and the date of the last restore onto different hardware
- Which subscription features are not replaced, with voice integration named

===== ARCHITECTURE.md =====
# Architecture · Home Assistant Cloud

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Platform | Home Assistant, self-hosted | the thing you are keeping; only the remote access is being replaced |
| Remote access | An outbound tunnel, or a private mesh network | both avoid opening an inbound port, which is the entire security argument |
| Certificates | Automatic certificates through the tunnel or a reverse proxy | a browser warning teaches your household to click through warnings |
| Authentication | Home Assistant's own accounts with two factor, plus a layer in front for the public path | the application's login is not designed to be the only thing on the public internet |
| Backups | Automated snapshots copied off the machine | a home automation setup is months of configuration and it lives on one memory card |

## Modules

Each module has one owner concern and a documented way to replace it.

| Module | Owns | How to replace it |
| --- | --- | --- |
| Platform | The home automation itself. | Home Assistant is what you are keeping. Nothing here replaces it. |
| Access | Reaching it from outside without inbound exposure. | Tunnel and mesh are interchangeable in principle and differ for guests. The no-inbound-port rule survives either. |
| Front layer | Standing in front of the application's own login on a public path. | Any proxy or identity layer, provided the mobile application still works. |
| Backups | Snapshots off the machine. | Destination is replaceable; being off the machine is not. |
| Monitoring | Knowing before the household tells you. | Any external uptime service. It must check from outside so a tunnel failure is caught. |

## Configuration

Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists.

- `HA_LOCAL_URL` · required · The local address. Used by backup scripts and monitoring on the local network.
- `HA_REMOTE_HOSTNAME` · optional · Only if you chose a tunnel. The public hostname.
- `TUNNEL_TOKEN` · optional, secret · Your tunnel provider's credential. Lives on the Home Assistant machine only.
- `BACKUP_DEST` · required · Where snapshots are copied. Not the Home Assistant machine.
- `BACKUP_RETAIN` · required · How many snapshots to keep. Enough to go back past a bad update.
- `UPTIME_CHECK_URL` · required · What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.

## Production baseline

- Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives.
- Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised.
- Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts.
- Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists.
- Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path.

## Decision records

For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.

===== AGENTS.md =====
# Agent instructions · Home Assistant Cloud product build

- Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Home Assistant, self-hosted, An outbound tunnel, or a private mesh network, Automatic certificates through the tunnel or a reverse proxy, Home Assistant's own accounts with two factor, plus a layer in front for the public path, Automated snapshots copied off the machine.
- Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit.
- Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present.
- Never invent cryptography or silently weaken a requirement to make a check pass.
- Put every external service behind an interface with a deterministic fake for tests.
- Add migrations and rollback or recovery notes for every persistent data change.
- Log useful operational context without credentials, tokens, passwords or personal data.
- Update documentation and run every check before completing a milestone.

## Known traps

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
- Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.

===== MILESTONES.md =====
# Delivery milestones · Home Assistant Cloud

Estimated effort: **weekend** for the indie phases; the production-only milestones add the trust and operability layer.

## M1 · A local installation you have backed up

Home Assistant runs, and losing the machine would not lose your configuration.

### Steps

1. Confirm the installation and version
   Note the installation method, because it determines how you back up and how you update.
   Files: `README.md`
2. Automate backups off the machine
   Scheduled snapshots copied to another machine or object storage. On the device is not off the device.
   Files: `scripts/backup.sh`
3. Restore onto different hardware
   Before exposing anything. A restore you have not done is a plan, not a backup.
   Files: `README.md`

### Done when

- [ ] Home Assistant is reachable locally
- [ ] Backups run on a schedule and land off the machine
- [ ] A restore onto different hardware has been performed and dated
- [ ] The restored instance controls a real device

### Watch out

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.

## M2 · Accounts and two factor, before anything is exposed

Every account that could reach this from outside has a second factor.

### Steps

1. Create individual accounts
   One per person. Shared credentials cannot be revoked individually, which matters when a phone is lost.
2. Enable two factor everywhere
   On every account that will be reachable remotely. Verify each by signing in fresh.
3. Restrict where sensible
   Not everyone needs to control the door lock. Test the restriction rather than trusting the setting.

### Done when

- [ ] Each household member has their own account
- [ ] Two factor is verified on every remotely reachable account
- [ ] A restricted account is confirmed unable to exceed its permissions
- [ ] No shared account remains with remote access

### Watch out

- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.

## M3 · Remote access without an open port

You can reach it from outside, and your router has no forwarded port.

### Steps

1. Choose tunnel or mesh deliberately
   A tunnel gives a public hostname anyone could reach, so it needs the layer in Phase 4. A mesh is private to your devices and simpler but harder for guests.
   Files: `docs/access.md`
2. Set it up and get certificates
   Automatic certificates through whichever you chose. A warning page is not acceptable for something your household uses daily.
3. Verify nothing is inbound
   Check the router's forwarding table and scan your home address from outside. Both, because either alone can mislead.

   ```sh
   nmap -Pn YOUR_HOME_IP
   ```


### Done when

- [ ] Reachable from a mobile connection with local network off
- [ ] The router forwards no ports
- [ ] An external scan of the home address shows nothing open
- [ ] Certificates are valid with no browser warning

### Watch out

- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.

## M4 · A layer in front of the public path

If the hostname is public, something stands in front of the application's own login.

### Steps

1. Add the front layer
   Basic authentication at minimum, an identity proxy if you want more. Something before the application's login.
   Files: `Caddyfile`
2. Enable banning at both levels
   The proxy and Home Assistant's own failed login banning. They catch different things.
   Files: `configuration.yaml`
3. Make the mobile application work
   A token or client certificate path, tested on a real phone from a mobile connection before anyone else depends on it.

### Done when

- [ ] An unauthenticated public request does not reach the application
- [ ] Repeated failures produce a temporary ban
- [ ] The mobile application works through the layer on a real phone
- [ ] Home Assistant's own ban list is enabled

### Watch out

- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.

## M5 · Notifications and the things the subscription did

You get alerts away from home, and you know which convenience features you gave up.

### Steps

1. Set up a notification path
   A self-hosted push service or a free tier one. Test from outside the house rather than from the sofa.
   Files: `configuration.yaml`
2. Test the failure modes
   Phone on mobile data, and the case where your home connection drops entirely, which is when you most want the alert and least likely to get it.
3. Write down what you gave up
   Voice integrations, managed certificates, and someone else handling security updates for the remote access path.
   Files: `docs/tradeoffs.md`

### Done when

- [ ] An automation notification reaches a phone away from home
- [ ] Notifications work with the phone on mobile data
- [ ] The behaviour when the home connection drops is documented
- [ ] The list of unreplaced features names voice integration

### Watch out

- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

## M6 · Updates, monitoring and the household (production only)

It keeps working, and someone other than you can get in when you are away.

### Steps

1. Document and follow the update procedure
   Back up, read breaking changes, update, verify a device responds. Follow it once and record how long it took.
   Files: `docs/updates.md`
2. Monitor from outside
   An external uptime check against the remote hostname, so a failure of the tunnel is caught as well as a failure of the application.
3. Write the household note
   How to reach it, what to do if it is down, and who to contact. Somewhere findable without the system working.
   Files: `docs/household.md`

### Done when

- [ ] The update procedure has been followed and timed
- [ ] An uptime check alerts when the instance is stopped
- [ ] A rollback to the previous version has been tested
- [ ] The household note exists and is findable without the system

### Watch out

- Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.

===== OPERATIONS.md =====
# Operations · Home Assistant Cloud

## Backup

Scheduled snapshots copied off the machine, retained long enough to go back past a bad update. The tunnel credential and any front layer configuration belong in the backup too, because a restore without them has no remote access.

## Restore

Restore onto hardware, reconnect the tunnel, verify a device responds and that remote access works. Doing this once a year is reasonable for a household system and the date belongs in the README.

Do a restore drill before the first real user, and write the date here when it passes.

## Monitoring

External uptime against a real endpoint, plus disk or memory card health on the host. A memory card degrading is the most common physical failure in this setup and it is detectable before it is fatal.

## Incident checklist

For a failed update, restore the snapshot taken immediately before it rather than debugging remotely. For lost remote access, the local network path should still work, which is why it is never removed. For a compromised account, revoke its sessions and rotate the front layer credential.

1. Contain the issue without destroying evidence or user data.
2. Record the timeline and affected scope.
3. Rotate exposed secrets and revoke compromised sessions or credentials.
4. Restore from a verified backup when needed.
5. Document the root cause, the remediation and the regression test.

## Release gate

- [ ] An external scan confirms no inbound port is open
- [ ] Two factor is verified on every remotely reachable account
- [ ] The mobile application is confirmed working through the front layer on a real phone
- [ ] A restore onto different hardware has been performed and dated
- [ ] The tradeoffs document names voice integration explicitly

## Launch constraint

Do not market omitted Home Assistant Cloud capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.

===== .env.example =====
# Copy to .env and fill in. Never commit .env; this file documents it.

# Required. The local address. Used by backup scripts and monitoring on the local network.
HA_LOCAL_URL=http://homeassistant.local:8123

# Optional. Only if you chose a tunnel. The public hostname.
HA_REMOTE_HOSTNAME=home.example.com

# Optional · secret. Your tunnel provider's credential. Lives on the Home Assistant machine only.
TUNNEL_TOKEN=replace-with-provider-token

# Required. Where snapshots are copied. Not the Home Assistant machine.
BACKUP_DEST=s3://your-bucket/homeassistant

# Required. How many snapshots to keep. Enough to go back past a bad update.
BACKUP_RETAIN=14

# Required. What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.
UPTIME_CHECK_URL=https://home.example.com/manifest.json

# Home Assistant Cloud · indie build

Home Assistant reachable from anywhere through an outbound tunnel or a private network, with certificates, an authentication layer in front, two factor authentication enabled, and backups that go somewhere other than the machine in your cupboard.

Estimated effort: **weekend**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts.

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Platform | Home Assistant, self-hosted | the thing you are keeping; only the remote access is being replaced |
| Remote access | An outbound tunnel, or a private mesh network | both avoid opening an inbound port, which is the entire security argument |
| Certificates | Automatic certificates through the tunnel or a reverse proxy | a browser warning teaches your household to click through warnings |
| Authentication | Home Assistant's own accounts with two factor, plus a layer in front for the public path | the application's login is not designed to be the only thing on the public internet |
| Backups | Automated snapshots copied off the machine | a home automation setup is months of configuration and it lives on one memory card |

## Before you start

Have every one of these ready. The plan assumes them from step one.

- [ ] **A working Home Assistant installation** · free software; the hardware is usually a small computer costing under 100 USD
  - Why: This build is about reaching it, not creating it. If it is not already working locally, that is a different project.
  - Get it: Follow the official installation for your hardware. Note which method you used, because it determines backup and update procedures.
  - Verify: It is reachable on your local network and controls a real device
- [ ] **A choice between an outbound tunnel and a private mesh** · both have usable free tiers for a household
  - Why: They have different tradeoffs for guests, for complexity and for what is exposed. Choosing after building means redoing the work.
  - Get it: A tunnel gives a public hostname that anyone can reach, so it needs the front layer in Phase 4. A mesh network is private to your enrolled devices and simpler to secure, but a guest cannot use it without being enrolled.
  - Verify: The decision and its reasoning are written down before Phase 3
- [ ] **A domain name, if you chose a tunnel** (optional) · roughly 10 to 15 USD a year
  - Why: Certificates need a hostname, and a memorable one matters when household members type it.
  - Get it: Any registrar, then follow your tunnel provider's instructions for pointing it.
  - Verify: The hostname resolves and serves a valid certificate
- [ ] **A backup destination that is not the Home Assistant machine** · free with a spare drive; a few USD a month for object storage
  - Why: The machine is usually a small computer with a memory card, and memory cards fail. Months of configuration live on it.
  - Get it: Another machine on the network plus an offsite copy, or object storage. Two destinations rather than one.
  - Verify: A backup has been restored onto different hardware
- [ ] **Spare hardware for the restore drill** · free if you have anything spare
  - Why: Phase 1 restores onto different hardware, and that drill is what makes everything after it recoverable.
  - Get it: Any spare machine, or a virtual machine. It only needs to run long enough to prove the restore.
  - Verify: A restored instance controls a device

## Quick start

```sh
nmap -Pn YOUR_HOME_IP
```

Then copy `.env.example` to `.env` and fill in the values it documents.

## Honest limits

This build deliberately does not replace:

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.
- managed remote access, voice integrations, funding for open source, and low-maintenance security
- frictionless family sync
- retailer and smart-home integrations
- large recipe or product database
- mobile polish

If one of those is essential to you, that is the reason to keep paying for Home Assistant Cloud, and the README should say so rather than pretend.

# Build brief · Home Assistant Cloud

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me remote access to your own Home Assistant, through a tunnel you control, without opening a port to replace Home Assistant Cloud. Build it in phases, in the order below.
Do not write the whole thing in one pass. Finish a phase, run its "Done when"
check, fix what fails, and only then start the next phase.

### Rule zero
Do not build a smart home platform. Home Assistant is the platform and this is about
reaching it from outside your house safely. The subscription you are replacing pays for
managed remote access, voice assistant integrations, and the funding that keeps the
open source project alive. The last of those is worth saying out loud: if you can
afford the subscription, it is one of the more directly useful ones in this catalogue.
Never open a port on your router to expose Home Assistant directly. It is the single
most common way these installations are compromised, and the alternatives below are
not meaningfully harder.

### Stack (fixed, do not substitute)
- Platform: Home Assistant, self-hosted · the thing you are keeping; only the remote access is being replaced
- Remote access: An outbound tunnel, or a private mesh network · both avoid opening an inbound port, which is the entire security argument
- Certificates: Automatic certificates through the tunnel or a reverse proxy · a browser warning teaches your household to click through warnings
- Authentication: Home Assistant's own accounts with two factor, plus a layer in front for the public path · the application's login is not designed to be the only thing on the public internet
- Backups: Automated snapshots copied off the machine · a home automation setup is months of configuration and it lives on one memory card

### Data model (create this before Phase 1)
- This is infrastructure, so the state worth recording is operational.
- instance · the Home Assistant host, its version, and what it controls
- access paths · the tunnel or mesh, the hostname, and who can reach it
- accounts · household members, their permissions, and which have two factor enabled
- backups · schedule, destination, retention, and the date of the last restore
- The rule that shapes everything: nothing inbound. Every path is either an outbound tunnel or a private network.

### Phase 1 · A local installation you have backed up
Build: Install or confirm Home Assistant on your own hardware. Set up automated backups and
  copy them off the machine. Restore one onto a different machine before you expose
  anything, because the restore is what makes the rest of this recoverable.
Trap: Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
Done when: Home Assistant is reachable on the local network. Automated backups run on a schedule and land off the machine. A backup has been restored onto different hardware and the restored instance controls a device, and the date is recorded.
Do not build yet: No remote access at all yet. Local and recoverable first.

### Phase 2 · Accounts and two factor, before anything is exposed
Build: Create individual accounts for household members rather than sharing one. Enable two
  factor authentication on every account that will have remote access. Review what each
  account can control and restrict where it makes sense.
Trap: A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
Done when: Every household member has their own account. Two factor is enabled on every account with remote access, verified by signing in from a private window. A restricted account cannot control devices outside its permissions, tested rather than assumed.
Do not build yet: Still nothing exposed. The gate before the door.

### Phase 3 · Remote access without an open port
Build: Choose between an outbound tunnel, which gives a public hostname, and a private mesh
  network, which gives access only to your own devices. Set it up, confirm it works from
  a mobile connection, and confirm your router still forwards nothing.
Trap: Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
Done when: The instance is reachable from a mobile connection with the local network unavailable. The router's port forwarding table is empty, verified by looking at it. An external port scan of your home address shows nothing open. Certificates are valid and no browser warning appears.
Do not build yet: No extra authentication layer or notifications yet.

### Phase 4 · A layer in front of the public path
Build: For a tunnel with a public hostname, put an authentication layer in front. Rate limit
  and ban repeated failures. Ensure the mobile application still works, which usually
  means a bypass path with its own credential rather than an interactive login.
Trap: An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
Done when: An unauthenticated request to the public hostname does not reach the application. Repeated failed attempts result in a temporary ban. The mobile application works from a mobile connection with the layer in place, tested on a real device. Home Assistant's own ban list is enabled as well.
Do not build yet: No notifications or voice yet.

### Phase 5 · Notifications and the things the subscription did
Build: Configure notifications through a self-hosted or free service rather than the
  subscription's. Then write down honestly what you are not getting: the managed voice
  assistant integrations in particular, which are genuinely difficult to replace.
Trap: Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
Done when: A notification triggered by an automation reaches a phone away from home. The notification path works when the household internet is up but the phone is on a mobile connection. A written list records which subscription features are not replaced, with voice integration named specifically.
Do not build yet: Operations and updates come last.

### Phase 6 · Updates, monitoring and the household
Build: A documented update procedure that backs up first. Monitoring that tells you the
  instance is down before your household does. A written note for the household covering
  how to reach it and what to do if it stops working.
Trap: Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.
Done when: An update procedure is documented and has been followed once, with a backup taken first. An uptime check alerts when the instance stops responding, tested by stopping it. A household note exists explaining how to reach the system and who to contact. A rollback to the previous version has been tested.
Do not build yet: Nothing after this.

### Out of scope (and why)
- Managed voice assistant integrations. These need reviewed relationships with each assistant platform and are the hardest part of the subscription to replace.
- Someone else keeping the remote access path patched and secure. That is now you, permanently.
- The frictionless setup for household members who are not technical, which matters more than it sounds when something breaks while you are away.
- Funding the open source project. The subscription pays for Home Assistant's development, and replacing it removes that contribution.

### README must contain
- That no inbound port is open, and how that was verified
- Which remote access method was chosen and what it means for guests
- That every remotely reachable account has two factor enabled
- The backup schedule, destination, and the date of the last restore onto different hardware
- Which subscription features are not replaced, with voice integration named

# Agent instructions · Home Assistant Cloud indie build

- Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Home Assistant, self-hosted, An outbound tunnel, or a private mesh network, Automatic certificates through the tunnel or a reverse proxy, Home Assistant's own accounts with two factor, plus a layer in front for the public path, Automated snapshots copied off the machine. Do not substitute.
- Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes.
- Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name.
- Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced.
- Do not invent cryptography, security guarantees, APIs or compliance claims.
- Add a focused test for every destructive, security-sensitive or data-loss path the plan names.
- Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".

## Known traps

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

# Build plan · Home Assistant Cloud

Home Assistant reachable from anywhere through an outbound tunnel or a private network, with certificates, an authentication layer in front, two factor authentication enabled, and backups that go somewhere other than the machine in your cupboard.

Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note.

## Phase 1 · A local installation you have backed up

Home Assistant runs, and losing the machine would not lose your configuration.

### Steps

1. Confirm the installation and version
   Note the installation method, because it determines how you back up and how you update.
   Files: `README.md`
2. Automate backups off the machine
   Scheduled snapshots copied to another machine or object storage. On the device is not off the device.
   Files: `scripts/backup.sh`
3. Restore onto different hardware
   Before exposing anything. A restore you have not done is a plan, not a backup.
   Files: `README.md`

### Done when

- [ ] Home Assistant is reachable locally
- [ ] Backups run on a schedule and land off the machine
- [ ] A restore onto different hardware has been performed and dated
- [ ] The restored instance controls a real device

### Watch out

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.

## Phase 2 · Accounts and two factor, before anything is exposed

Every account that could reach this from outside has a second factor.

### Steps

1. Create individual accounts
   One per person. Shared credentials cannot be revoked individually, which matters when a phone is lost.
2. Enable two factor everywhere
   On every account that will be reachable remotely. Verify each by signing in fresh.
3. Restrict where sensible
   Not everyone needs to control the door lock. Test the restriction rather than trusting the setting.

### Done when

- [ ] Each household member has their own account
- [ ] Two factor is verified on every remotely reachable account
- [ ] A restricted account is confirmed unable to exceed its permissions
- [ ] No shared account remains with remote access

### Watch out

- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.

## Phase 3 · Remote access without an open port

You can reach it from outside, and your router has no forwarded port.

### Steps

1. Choose tunnel or mesh deliberately
   A tunnel gives a public hostname anyone could reach, so it needs the layer in Phase 4. A mesh is private to your devices and simpler but harder for guests.
   Files: `docs/access.md`
2. Set it up and get certificates
   Automatic certificates through whichever you chose. A warning page is not acceptable for something your household uses daily.
3. Verify nothing is inbound
   Check the router's forwarding table and scan your home address from outside. Both, because either alone can mislead.

   ```sh
   nmap -Pn YOUR_HOME_IP
   ```


### Done when

- [ ] Reachable from a mobile connection with local network off
- [ ] The router forwards no ports
- [ ] An external scan of the home address shows nothing open
- [ ] Certificates are valid with no browser warning

### Watch out

- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.

## Phase 4 · A layer in front of the public path

If the hostname is public, something stands in front of the application's own login.

### Steps

1. Add the front layer
   Basic authentication at minimum, an identity proxy if you want more. Something before the application's login.
   Files: `Caddyfile`
2. Enable banning at both levels
   The proxy and Home Assistant's own failed login banning. They catch different things.
   Files: `configuration.yaml`
3. Make the mobile application work
   A token or client certificate path, tested on a real phone from a mobile connection before anyone else depends on it.

### Done when

- [ ] An unauthenticated public request does not reach the application
- [ ] Repeated failures produce a temporary ban
- [ ] The mobile application works through the layer on a real phone
- [ ] Home Assistant's own ban list is enabled

### Watch out

- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.

## Phase 5 · Notifications and the things the subscription did

You get alerts away from home, and you know which convenience features you gave up.

### Steps

1. Set up a notification path
   A self-hosted push service or a free tier one. Test from outside the house rather than from the sofa.
   Files: `configuration.yaml`
2. Test the failure modes
   Phone on mobile data, and the case where your home connection drops entirely, which is when you most want the alert and least likely to get it.
3. Write down what you gave up
   Voice integrations, managed certificates, and someone else handling security updates for the remote access path.
   Files: `docs/tradeoffs.md`

### Done when

- [ ] An automation notification reaches a phone away from home
- [ ] Notifications work with the phone on mobile data
- [ ] The behaviour when the home connection drops is documented
- [ ] The list of unreplaced features names voice integration

### Watch out

- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

## Not in this build

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.

## After v1, if you want it

- A local voice pipeline, accepting that it is a substantial project of its own
- A second tunnel or mesh path as a failover, since remote access failing while away is the annoying case
- Automated verification that the newest backup actually restores, rather than only that it exists

# Copy to .env and fill in. Never commit .env; this file documents it.

# Required. The local address. Used by backup scripts and monitoring on the local network.
HA_LOCAL_URL=http://homeassistant.local:8123

# Optional. Only if you chose a tunnel. The public hostname.
HA_REMOTE_HOSTNAME=home.example.com

# Optional · secret. Your tunnel provider's credential. Lives on the Home Assistant machine only.
TUNNEL_TOKEN=replace-with-provider-token

# Required. Where snapshots are copied. Not the Home Assistant machine.
BACKUP_DEST=s3://your-bucket/homeassistant

# Required. How many snapshots to keep. Enough to go back past a bad update.
BACKUP_RETAIN=14

# Required. What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.
UPTIME_CHECK_URL=https://home.example.com/manifest.json

# Home Assistant Cloud · product brief

## Problem

The core loop is buildable, but a dependable replacement becomes a real weekend or multi-day project. For Home Assistant Cloud, self-host smart-home control and use a user-owned remote-access tunnel. The hard boundary is managed remote access, voice integrations, funding for open source, and low-maintenance security, plus sync, integrations, and household adoption.

## Product outcome

Home Assistant reachable from anywhere with no inbound port, every remote account behind two factor, backups off the machine that have actually been restored, and an honest written record of what the subscription did that this does not.

## Target user

A builder who needs a maintainable product foundation, not a one-off demo.

## Required capabilities

- modern browser
- local or self-hosted storage
- optional email notifications

## Explicit non-goals for v1

- Managed voice assistant integrations, which are the hardest part to replace.
- Someone else patching the remote access path.
- Frictionless setup for non-technical household members.
- Financial support for the open source project the subscription funds.
- managed remote access, voice integrations, funding for open source, and low-maintenance security
- frictionless family sync
- retailer and smart-home integrations
- large recipe or product database
- mobile polish

## Success criteria

- An external scan confirms no inbound port is open
- Two factor is verified on every remotely reachable account
- The mobile application is confirmed working through the front layer on a real phone
- A restore onto different hardware has been performed and dated
- The tradeoffs document names voice integration explicitly

# Build brief · Home Assistant Cloud

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me remote access to your own Home Assistant, through a tunnel you control, without opening a port to replace Home Assistant Cloud. Build it in phases, in the order below.
Do not write the whole thing in one pass. Finish a phase, run its "Done when"
check, fix what fails, and only then start the next phase.

### Rule zero
Do not build a smart home platform. Home Assistant is the platform and this is about
reaching it from outside your house safely. The subscription you are replacing pays for
managed remote access, voice assistant integrations, and the funding that keeps the
open source project alive. The last of those is worth saying out loud: if you can
afford the subscription, it is one of the more directly useful ones in this catalogue.
Never open a port on your router to expose Home Assistant directly. It is the single
most common way these installations are compromised, and the alternatives below are
not meaningfully harder.

### Stack (fixed, do not substitute)
- Platform: Home Assistant, self-hosted · the thing you are keeping; only the remote access is being replaced
- Remote access: An outbound tunnel, or a private mesh network · both avoid opening an inbound port, which is the entire security argument
- Certificates: Automatic certificates through the tunnel or a reverse proxy · a browser warning teaches your household to click through warnings
- Authentication: Home Assistant's own accounts with two factor, plus a layer in front for the public path · the application's login is not designed to be the only thing on the public internet
- Backups: Automated snapshots copied off the machine · a home automation setup is months of configuration and it lives on one memory card

### Data model (create this before Phase 1)
- This is infrastructure, so the state worth recording is operational.
- instance · the Home Assistant host, its version, and what it controls
- access paths · the tunnel or mesh, the hostname, and who can reach it
- accounts · household members, their permissions, and which have two factor enabled
- backups · schedule, destination, retention, and the date of the last restore
- The rule that shapes everything: nothing inbound. Every path is either an outbound tunnel or a private network.

### Phase 1 · A local installation you have backed up
Build: Install or confirm Home Assistant on your own hardware. Set up automated backups and
  copy them off the machine. Restore one onto a different machine before you expose
  anything, because the restore is what makes the rest of this recoverable.
Trap: Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
Done when: Home Assistant is reachable on the local network. Automated backups run on a schedule and land off the machine. A backup has been restored onto different hardware and the restored instance controls a device, and the date is recorded.
Do not build yet: No remote access at all yet. Local and recoverable first.

### Phase 2 · Accounts and two factor, before anything is exposed
Build: Create individual accounts for household members rather than sharing one. Enable two
  factor authentication on every account that will have remote access. Review what each
  account can control and restrict where it makes sense.
Trap: A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
Done when: Every household member has their own account. Two factor is enabled on every account with remote access, verified by signing in from a private window. A restricted account cannot control devices outside its permissions, tested rather than assumed.
Do not build yet: Still nothing exposed. The gate before the door.

### Phase 3 · Remote access without an open port
Build: Choose between an outbound tunnel, which gives a public hostname, and a private mesh
  network, which gives access only to your own devices. Set it up, confirm it works from
  a mobile connection, and confirm your router still forwards nothing.
Trap: Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
Done when: The instance is reachable from a mobile connection with the local network unavailable. The router's port forwarding table is empty, verified by looking at it. An external port scan of your home address shows nothing open. Certificates are valid and no browser warning appears.
Do not build yet: No extra authentication layer or notifications yet.

### Phase 4 · A layer in front of the public path
Build: For a tunnel with a public hostname, put an authentication layer in front. Rate limit
  and ban repeated failures. Ensure the mobile application still works, which usually
  means a bypass path with its own credential rather than an interactive login.
Trap: An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
Done when: An unauthenticated request to the public hostname does not reach the application. Repeated failed attempts result in a temporary ban. The mobile application works from a mobile connection with the layer in place, tested on a real device. Home Assistant's own ban list is enabled as well.
Do not build yet: No notifications or voice yet.

### Phase 5 · Notifications and the things the subscription did
Build: Configure notifications through a self-hosted or free service rather than the
  subscription's. Then write down honestly what you are not getting: the managed voice
  assistant integrations in particular, which are genuinely difficult to replace.
Trap: Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
Done when: A notification triggered by an automation reaches a phone away from home. The notification path works when the household internet is up but the phone is on a mobile connection. A written list records which subscription features are not replaced, with voice integration named specifically.
Do not build yet: Operations and updates come last.

### Phase 6 · Updates, monitoring and the household
Build: A documented update procedure that backs up first. Monitoring that tells you the
  instance is down before your household does. A written note for the household covering
  how to reach it and what to do if it stops working.
Trap: Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.
Done when: An update procedure is documented and has been followed once, with a backup taken first. An uptime check alerts when the instance stops responding, tested by stopping it. A household note exists explaining how to reach the system and who to contact. A rollback to the previous version has been tested.
Do not build yet: Nothing after this.

### Out of scope (and why)
- Managed voice assistant integrations. These need reviewed relationships with each assistant platform and are the hardest part of the subscription to replace.
- Someone else keeping the remote access path patched and secure. That is now you, permanently.
- The frictionless setup for household members who are not technical, which matters more than it sounds when something breaks while you are away.
- Funding the open source project. The subscription pays for Home Assistant's development, and replacing it removes that contribution.

### README must contain
- That no inbound port is open, and how that was verified
- Which remote access method was chosen and what it means for guests
- That every remotely reachable account has two factor enabled
- The backup schedule, destination, and the date of the last restore onto different hardware
- Which subscription features are not replaced, with voice integration named

# Architecture · Home Assistant Cloud

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Platform | Home Assistant, self-hosted | the thing you are keeping; only the remote access is being replaced |
| Remote access | An outbound tunnel, or a private mesh network | both avoid opening an inbound port, which is the entire security argument |
| Certificates | Automatic certificates through the tunnel or a reverse proxy | a browser warning teaches your household to click through warnings |
| Authentication | Home Assistant's own accounts with two factor, plus a layer in front for the public path | the application's login is not designed to be the only thing on the public internet |
| Backups | Automated snapshots copied off the machine | a home automation setup is months of configuration and it lives on one memory card |

## Modules

Each module has one owner concern and a documented way to replace it.

| Module | Owns | How to replace it |
| --- | --- | --- |
| Platform | The home automation itself. | Home Assistant is what you are keeping. Nothing here replaces it. |
| Access | Reaching it from outside without inbound exposure. | Tunnel and mesh are interchangeable in principle and differ for guests. The no-inbound-port rule survives either. |
| Front layer | Standing in front of the application's own login on a public path. | Any proxy or identity layer, provided the mobile application still works. |
| Backups | Snapshots off the machine. | Destination is replaceable; being off the machine is not. |
| Monitoring | Knowing before the household tells you. | Any external uptime service. It must check from outside so a tunnel failure is caught. |

## Configuration

Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists.

- `HA_LOCAL_URL` · required · The local address. Used by backup scripts and monitoring on the local network.
- `HA_REMOTE_HOSTNAME` · optional · Only if you chose a tunnel. The public hostname.
- `TUNNEL_TOKEN` · optional, secret · Your tunnel provider's credential. Lives on the Home Assistant machine only.
- `BACKUP_DEST` · required · Where snapshots are copied. Not the Home Assistant machine.
- `BACKUP_RETAIN` · required · How many snapshots to keep. Enough to go back past a bad update.
- `UPTIME_CHECK_URL` · required · What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.

## Production baseline

- Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives.
- Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised.
- Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts.
- Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists.
- Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path.

## Decision records

For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.

# Agent instructions · Home Assistant Cloud product build

- Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Home Assistant, self-hosted, An outbound tunnel, or a private mesh network, Automatic certificates through the tunnel or a reverse proxy, Home Assistant's own accounts with two factor, plus a layer in front for the public path, Automated snapshots copied off the machine.
- Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit.
- Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present.
- Never invent cryptography or silently weaken a requirement to make a check pass.
- Put every external service behind an interface with a deterministic fake for tests.
- Add migrations and rollback or recovery notes for every persistent data change.
- Log useful operational context without credentials, tokens, passwords or personal data.
- Update documentation and run every check before completing a milestone.

## Known traps

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.
- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.
- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.
- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.
- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.
- Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.

# Delivery milestones · Home Assistant Cloud

Estimated effort: **weekend** for the indie phases; the production-only milestones add the trust and operability layer.

## M1 · A local installation you have backed up

Home Assistant runs, and losing the machine would not lose your configuration.

### Steps

1. Confirm the installation and version
   Note the installation method, because it determines how you back up and how you update.
   Files: `README.md`
2. Automate backups off the machine
   Scheduled snapshots copied to another machine or object storage. On the device is not off the device.
   Files: `scripts/backup.sh`
3. Restore onto different hardware
   Before exposing anything. A restore you have not done is a plan, not a backup.
   Files: `README.md`

### Done when

- [ ] Home Assistant is reachable locally
- [ ] Backups run on a schedule and land off the machine
- [ ] A restore onto different hardware has been performed and dated
- [ ] The restored instance controls a real device

### Watch out

- Home Assistant on a memory card in a small computer is the common setup and memory cards fail without warning, usually after a year or two of constant writing. Back up off the device from the first day rather than after the first failure, because the configuration represents months of work.

## M2 · Accounts and two factor, before anything is exposed

Every account that could reach this from outside has a second factor.

### Steps

1. Create individual accounts
   One per person. Shared credentials cannot be revoked individually, which matters when a phone is lost.
2. Enable two factor everywhere
   On every account that will be reachable remotely. Verify each by signing in fresh.
3. Restrict where sensible
   Not everyone needs to control the door lock. Test the restriction rather than trusting the setting.

### Done when

- [ ] Each household member has their own account
- [ ] Two factor is verified on every remotely reachable account
- [ ] A restricted account is confirmed unable to exceed its permissions
- [ ] No shared account remains with remote access

### Watch out

- A shared household account with a memorable password is fine on a local network and is the weak point the moment anything is reachable from outside. Individual accounts with two factor are the prerequisite for remote access, not an improvement to make later.

## M3 · Remote access without an open port

You can reach it from outside, and your router has no forwarded port.

### Steps

1. Choose tunnel or mesh deliberately
   A tunnel gives a public hostname anyone could reach, so it needs the layer in Phase 4. A mesh is private to your devices and simpler but harder for guests.
   Files: `docs/access.md`
2. Set it up and get certificates
   Automatic certificates through whichever you chose. A warning page is not acceptable for something your household uses daily.
3. Verify nothing is inbound
   Check the router's forwarding table and scan your home address from outside. Both, because either alone can mislead.

   ```sh
   nmap -Pn YOUR_HOME_IP
   ```


### Done when

- [ ] Reachable from a mobile connection with local network off
- [ ] The router forwards no ports
- [ ] An external scan of the home address shows nothing open
- [ ] Certificates are valid with no browser warning

### Watch out

- Port forwarding is the approach every old guide describes and it puts a login page for your house on the public internet, where it is found by scanners within days. An outbound tunnel makes the connection from inside your network outward, so there is nothing inbound to find.

## M4 · A layer in front of the public path

If the hostname is public, something stands in front of the application's own login.

### Steps

1. Add the front layer
   Basic authentication at minimum, an identity proxy if you want more. Something before the application's login.
   Files: `Caddyfile`
2. Enable banning at both levels
   The proxy and Home Assistant's own failed login banning. They catch different things.
   Files: `configuration.yaml`
3. Make the mobile application work
   A token or client certificate path, tested on a real phone from a mobile connection before anyone else depends on it.

### Done when

- [ ] An unauthenticated public request does not reach the application
- [ ] Repeated failures produce a temporary ban
- [ ] The mobile application works through the layer on a real phone
- [ ] Home Assistant's own ban list is enabled

### Watch out

- An authentication layer that blocks the mobile application makes the whole setup useless for the household, and the usual response is removing the layer. Solve it properly with a token or a client certificate the application can carry, and test on a real phone before rolling it out to anyone else.

## M5 · Notifications and the things the subscription did

You get alerts away from home, and you know which convenience features you gave up.

### Steps

1. Set up a notification path
   A self-hosted push service or a free tier one. Test from outside the house rather than from the sofa.
   Files: `configuration.yaml`
2. Test the failure modes
   Phone on mobile data, and the case where your home connection drops entirely, which is when you most want the alert and least likely to get it.
3. Write down what you gave up
   Voice integrations, managed certificates, and someone else handling security updates for the remote access path.
   Files: `docs/tradeoffs.md`

### Done when

- [ ] An automation notification reaches a phone away from home
- [ ] Notifications work with the phone on mobile data
- [ ] The behaviour when the home connection drops is documented
- [ ] The list of unreplaced features names voice integration

### Watch out

- Voice assistant integration is the part of the subscription that is hardest to replicate, because it requires a reviewed relationship with each assistant platform rather than a technical workaround. If your household relies on voice control, that may be enough reason to keep paying, and this build should say so rather than pretending otherwise.

## M6 · Updates, monitoring and the household (production only)

It keeps working, and someone other than you can get in when you are away.

### Steps

1. Document and follow the update procedure
   Back up, read breaking changes, update, verify a device responds. Follow it once and record how long it took.
   Files: `docs/updates.md`
2. Monitor from outside
   An external uptime check against the remote hostname, so a failure of the tunnel is caught as well as a failure of the application.
3. Write the household note
   How to reach it, what to do if it is down, and who to contact. Somewhere findable without the system working.
   Files: `docs/household.md`

### Done when

- [ ] The update procedure has been followed and timed
- [ ] An uptime check alerts when the instance is stopped
- [ ] A rollback to the previous version has been tested
- [ ] The household note exists and is findable without the system

### Watch out

- Home Assistant updates frequently and occasionally introduces breaking changes to integrations, so an unattended automatic update can leave your heating uncontrollable while you are away. Back up before updating, read the release notes for breaking changes, and do not update remotely without a way to roll back.

# Operations · Home Assistant Cloud

## Backup

Scheduled snapshots copied off the machine, retained long enough to go back past a bad update. The tunnel credential and any front layer configuration belong in the backup too, because a restore without them has no remote access.

## Restore

Restore onto hardware, reconnect the tunnel, verify a device responds and that remote access works. Doing this once a year is reasonable for a household system and the date belongs in the README.

Do a restore drill before the first real user, and write the date here when it passes.

## Monitoring

External uptime against a real endpoint, plus disk or memory card health on the host. A memory card degrading is the most common physical failure in this setup and it is detectable before it is fatal.

## Incident checklist

For a failed update, restore the snapshot taken immediately before it rather than debugging remotely. For lost remote access, the local network path should still work, which is why it is never removed. For a compromised account, revoke its sessions and rotate the front layer credential.

1. Contain the issue without destroying evidence or user data.
2. Record the timeline and affected scope.
3. Rotate exposed secrets and revoke compromised sessions or credentials.
4. Restore from a verified backup when needed.
5. Document the root cause, the remediation and the regression test.

## Release gate

- [ ] An external scan confirms no inbound port is open
- [ ] Two factor is verified on every remotely reachable account
- [ ] The mobile application is confirmed working through the front layer on a real phone
- [ ] A restore onto different hardware has been performed and dated
- [ ] The tradeoffs document names voice integration explicitly

## Launch constraint

Do not market omitted Home Assistant Cloud capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.

# Copy to .env and fill in. Never commit .env; this file documents it.

# Required. The local address. Used by backup scripts and monitoring on the local network.
HA_LOCAL_URL=http://homeassistant.local:8123

# Optional. Only if you chose a tunnel. The public hostname.
HA_REMOTE_HOSTNAME=home.example.com

# Optional · secret. Your tunnel provider's credential. Lives on the Home Assistant machine only.
TUNNEL_TOKEN=replace-with-provider-token

# Required. Where snapshots are copied. Not the Home Assistant machine.
BACKUP_DEST=s3://your-bucket/homeassistant

# Required. How many snapshots to keep. Enough to go back past a bad update.
BACKUP_RETAIN=14

# Required. What the external monitor requests. A real endpoint, not the login page, so a broken application is detected.
UPTIME_CHECK_URL=https://home.example.com/manifest.json

$ choose a build depth, inspect the files, then open the complete pack in your agent