Skip to content
BranchesTags

Repository files navigation

Home Assistant Logo

Home Assistant on StartOS

Upstream docs: https://www.home-assistant.io/docs/

Everything not listed in this document should behave the same as upstream Home Assistant Container. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Home Assistant is an open-source home automation platform that puts local control and privacy first. It supports thousands of devices and services for smart home automation.

Important: This is the Container installation type, not Home Assistant OS. Some features available in Home Assistant OS are not available in Container installations.

Table of Contents

Image and Container Runtime

Property Value
Image ghcr.io/home-assistant/home-assistant (upstream unmodified)
Architectures x86_64, aarch64
Installation Type Container (not Home Assistant OS)

Volume and Data Layout

Volume Mount Point Purpose
main /data Home Assistant data
config /config Configuration files (configuration.yaml, etc.)

StartOS-specific files:

  • configuration.yaml — Home Assistant writes the standard upstream default on first install (default_config, frontend.themes, !include directives for automations.yaml/scripts.yaml/scenes.yaml). Every setting in it is user-editable via SSH.
  • .storage/http — Home Assistant's own web server settings, which it manages from Settings → System → Network and reads back on every start. Home Assistant is the only writer: when the file is absent, bootstrapHa runs Home Assistant once to author it before touching it. Init then makes sure 10.0.3.0/24 is in trusted_proxies, appending it if it isn't and enabling use_x_forwarded_for only when that key is absent, so the StartOS reverse proxy stays trusted without disturbing proxies or preferences the user set.

Installation and First-Run Flow

Step Upstream StartOS
Installation Docker pull + compose Install from marketplace
Initial setup Create owner account at first access Same as upstream
Configuration Edit configuration.yaml Same as upstream

First-run steps:

  1. Install Home Assistant from StartOS marketplace
  2. Access the web UI
  3. Create your owner account through the onboarding wizard
  4. Configure integrations and devices

Configuration Management

Home Assistant configuration is managed through upstream methods:

  • Web UI — Settings, integrations, automations, dashboards
  • configuration.yaml — Advanced configuration (in /config volume)
  • YAML files — Automations, scripts, scenes can be file-based

StartOS does not expose any Home Assistant settings through actions, and configuration.yaml is entirely user-managed. The one setting the package maintains is the reverse proxy trust in Home Assistant's own web server settings store — see Volume and Data Layout.

Network Access and Interfaces

Interface Port Protocol Purpose
Web UI 8123 HTTP Home Assistant dashboard

Access methods (StartOS 0.4.0):

  • LAN IP with unique port
  • <hostname>.local with unique port
  • Tor .onion address
  • Custom domains (if configured)

Actions (StartOS UI)

Action When to Use Notes
Reset Password You've lost the password to a Home Assistant account Service must be stopped before running. Pick the username from the dropdown; a freshly generated password is returned.
Set Up HACS Bootstrap the HACS community store Extracts bundled assets/hacs.zip into config/custom_components/hacs/; restarts HA if running. Doesn't activate HACS (manual GitHub OAuth in the HA UI). Hidden once installed. See Community store (HACS).
Remove HACS Remove HACS Deletes the HACS files; restarts HA if running. Shown only when HACS is installed. See Community store (HACS).

All other configuration is done within Home Assistant's web interface.

Why "stopped" only: Home Assistant caches the auth provider state in memory and rewrites .storage/auth_provider.homeassistant on graceful shutdown. Resetting the password while the service is running would be silently overwritten when the service stops.

Community store (HACS)

The Set Up HACS (set-up-hacs) and Remove HACS (remove-hacs) actions bootstrap HACS. Both are allowedStatuses: 'any' and restart Home Assistant only if it is running.

  • Set Up extracts the bundled assets/hacs.zip into config/custom_components/hacs/ (no network — the release is vendored). Remove deletes config/custom_components/hacs/ and config/.storage/hacs/; components HACS pulled in (custom_components/, www/community/) are left alone.
  • Mutually exclusive via a hacsInstalled flag in store.json, read reactively in each action's metadata — so Set Up can't re-run and downgrade a self-updated HACS.
  • The actions only move files. Activation is manual: the user adds the integration in the HA UI and completes a GitHub device-code OAuth flow (GitHub account required). HACS self-updates afterward, and cannot manage add-ons (Container has no Supervisor).

See the in-app Instructions for the user-facing walkthrough.

Dependencies

None. Home Assistant is a standalone application.

Backups and Restore

Included in backup:

  • main volume — Home Assistant data
  • config volume — All configuration files

Restore behavior:

  • Full configuration, automations, and history restored
  • Integrations and devices preserved
  • User accounts restored

Note: This is StartOS backup, not Home Assistant's built-in backup feature (which is not available in Container installations).

Health Checks

Check Display Name Method Grace Period
Web UI Web Interface Port 8123 listening 60 seconds

Messages:

  • Success: "The web interface is ready"
  • Error: "The web interface is not ready"

Limitations and Differences

These limitations apply to all Home Assistant Container installations, not just StartOS:

  1. No Add-ons/Apps — The Home Assistant Add-on store is not available (requires Home Assistant OS/Supervised). This is distinct from HACS, which is available (community integrations, cards, and themes) via the Set Up HACS action — see Community store (HACS).
  2. No Supervisor — Cannot manage the system through Home Assistant
  3. Limited Thread support — Thread border router requires add-ons
  4. Limited Z-Wave support — Z-Wave JS requires manual setup (no add-on)
  5. No built-in backups — Home Assistant's backup UI is not available (use StartOS backups instead)

StartOS-specific notes:

  • Updates are managed through StartOS, not Home Assistant's update mechanism
  • Device access (USB, Bluetooth) depends on StartOS hardware permissions

What Is Unchanged from Upstream

  • Full Home Assistant Core functionality
  • All integrations (2000+)
  • Automations, scripts, and scenes
  • Dashboards and Lovelace UI
  • Energy management
  • Voice assistant support
  • Mobile app companion support
  • REST API and WebSocket API
  • MQTT support
  • Configuration via YAML or UI
  • User and permission management

Contributing

Build and development workflow follow the StartOS packaging guide: https://docs.start9.com/packaging. Keep README.md, instructions.md, and AGENTS.md in sync with any change to user-visible behavior or package structure.

Quick Reference for AI Consumers

package_id: home-assistant
image: ghcr.io/home-assistant/home-assistant
architectures: [x86_64, aarch64]
volumes:
  main: /data
  config: /config
ports:
  ui: 8123
dependencies: none
startos_managed_env_vars: none
actions:
  - reset-password # multi-user; only-stopped
  - set-up-hacs # add bundled HACS files; restart if running; any status; hidden once installed; does NOT activate HACS (manual GitHub device auth)
  - remove-hacs # delete HACS files; restart if running; any status; shown only when installed

About

Home Assistant for StartOS

Resources

Readme
Apache-2.0 license
Activity
Custom properties

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages

Generated from Start9Labs/hello-world-startos