Home Assistant Guide

What Is Home Assistant OS?

Home Assistant OS is a minimal operating system that comes pre-packaged with everything you need to run Home Assistant, including the Home Assistant Core software and a supervisor to manage updates and add-ons. You don't need to install Linux or Docker separately - it's all built in.

Pre-Installed Options

For some popular Home Assistant hardware, HA OS comes pre-installed and ready to go out of the box. This is the easiest way to get started, and you can be up and running in minutes:

• Home Assistant Green – Ready to use out of the box. Just plug it in and follow the quick-start guide.
• Home Assistant Yellow – Also comes pre-flashed with HA OS. (Just make sure to insert your storage card if required.)
• Odroid N2+ (Home Assistant Bundle) – Sold with HA OS pre-installed; simply power it up and connect.

Tip: If you have one of these devices, skip to the first-boot and setup instructions in your device's manual. You don't need to flash anything yourself.

Installing Home Assistant OS Yourself

If you're installing on other hardware (like a Raspberry Pi, a virtual machine, Intel NUC, or a generic x86-64 PC), you'll need to download and flash Home Assistant OS to a storage device (usually an SD card or SSD).

1. Choose Your Hardware:
   • Raspberry Pi (Pi 4 is recommended for best performance)
   • Intel NUC or other x86-64 PC
   • Virtual Machine (VMware, VirtualBox, Proxmox, etc.)
2. Download the Correct Image:
   Visit the Home Assistant Installation page and choose the image that matches your hardware.
3. Flash the Image to Your Storage Device:
   Use a tool like balenaEtcher to write the downloaded image file to your SD card, USB drive, or SSD.
4. Insert and Boot:
   Plug the flashed device into your hardware (e.g., SD card into your Raspberry Pi), connect to your network with an Ethernet cable for best results, and power it on.
5. First Boot & Setup:
   Wait a few minutes for Home Assistant OS to start. Then, open a web browser on your computer and go to http://homeassistant.local:8123. If this doesn't work, find the device's IP address from your router and use http://<ip-address>:8123.

The setup wizard will guide you through the rest of the process (setting up your account, adding integrations, etc.), but some key steps are outlined below.

Setup & Onboarding: First Time After Login

Once you've logged into HA after flashing or with pre-installed hardware, you'll be guided through a setup wizard. Here's what to expect:

1. Preparing Home Assistant
   HA downloads the latest core release - this may take a few minutes depending on your hardware.
2. Owner Account Creation or Restore
   • New Setup: Create your main administrator account - you'll need a display name, a lowercase username (no spaces), and a strong password. • Restore: You can instead upload a backup from a previous system (e.g., from HA Green or Yellow).
3. Home Location & Units
   Enter your address to set timezone and units, and establish your "home" zone radius (~100 m).
4. Analytics Opt-In
   Choose whether to share anonymous usage data to help the HA project.
5. Device Discovery
   HA will scan your network for devices. Review the list and click Finish.

Once completed, you'll see your default dashboard with any automatically discovered devices.

What to Do Next? Tips & Tricks for Easier Setup

Once onboarding is done, here are some smart moves to make your HA experience smoother:

• Add Family Accounts – Go to Settings → System → Users to create separate logins with appropriate permissions. Great for guests or kids.
• Install Companion Apps – Download the Android or iOS Home Assistant companion app for notifications, location-based automations, and voice control.
• Finalize Settings – Visit Settings → System to adjust home location, units, language, and time format.
• Create Your First Backup – Use Settings → System → Backups to export your configuration - handy before making upgrades or changes.
• Set Up Basic Automations – A classic: turn lights on at sunset. Head to Settings → Automations & Scenes → Create Automation, choose "Sunset" as trigger, and define your action.
• Organize with Areas & Devices – Group devices into physical zones (e.g. "Living Room") to ease automation and dashboard setup.
• Explore Add‑ons – If using HA OS or Supervisor, browse the Add‑on Store for tools like File Editor, Mosquitto Broker, and Zigbee2MQTT.
• Learn YAML Editing – Most options can be handled in the UI, but advanced users often tweak configuration.yaml directly. Backup before editing!
• Join the Community – Find inspiration, custom dashboards, automations, and help in the Home Assistant Forums and Reddit.
• Enable Voice Control – If you want voice commands, set up Assist in the companion app or add Google Assistant / Siri integrations later.

These steps help you build a solid foundation - and save you headaches later if you expand or tweak your setup.

Tips & Troubleshooting

• If you see nothing on your screen, give it a few minutes - initial setup may take a little while, especially on first boot.
• If homeassistant.local doesn't work, try using the actual IP address of the device on your network.
• For best results, use a wired Ethernet connection when setting up for the first time (especially with Raspberry Pi).
• For Wi-Fi setup (advanced), see the Home Assistant documentation for editing the CONFIG file on your SD card before first boot.

Summary

• Home Assistant OS is the recommended, hassle-free way to run Home Assistant.
• Some devices (like Home Assistant Green, Yellow, and Odroid bundles) come with HA OS already installed - just plug in and go!
• For other hardware, you'll need to download and flash the right image before starting setup.

Don't worry if you're new to this - just follow each step carefully. If you run into trouble, check out the Home Assistant Community Forums for friendly help.