Getting Started

Installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 and git installed and execute the following code in a console:

git clone --recursive https://github.com/balloob/home-assistant.git
cd home-assistant
python3 -m pip install -r requirements.txt
python3 -m homeassistant --open-ui

Running these commands will:

Download Home Assistant
Navigate to downloaded files
Install the dependencies
Launch Home Assistant and serve web interface on http://localhost:8123

If you run into any issues, please see the troubleshooting page.

You can run Home Assistant in demo mode by appending --demo-mode to line 4.

If you want to update to the latest version in the future, run: scripts/update.

Installation with Docker is straightforward. Adjust the following command so that /path/to/your/config/ points at the folder where you want to store your config and run it:

docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant

This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone)

Home Assistant uses Python 3.4. This makes installation on a Raspberry Pi a bit more difficult as it is not available in the package repository. Please follow the following instructions to get it up and running.

Step 1. Install pyenv

curl -L https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer | bash

After the installation is done, run:

nano ~/.bashrc

Then add these lines to the end of the file and save:

export PATH="$HOME/.pyenv/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Step 2. Install requirements

sudo apt-get install python3-dev
sudo apt-get install libsqlite3-dev libreadline-dev

Log out and then back in so your bashrc is reloaded.

NOTE: the rest of the commands are not being run as sudo and will install python etc under you user’s home directory.

Step 3. Install python 3.4.2 (this will take a few hours)

pyenv install 3.4.2

Step 4. Create Python Virtual Environment

pyenv virtualenv 3.4.2 homeassistant

Step 5. Clone the source

git clone --recursive https://github.com/balloob/home-assistant.git

Step 6. Set the virtual environment

cd home-assistant
pyenv local homeassistant

Step 6. Finish the install

python3 -m pip install -r requirements.txt

Step 7. Start it up

python3 -m homeassistant

It will be up and running on port 8123

You can run Home Assistant in demo mode by appending --demo-mode to line 4.

If you want to update to the latest version in the future, run: scripts/update.

Configuring Home Assistant

The configuration for Home Assistant lives by default in the config folder. The file configuration.yaml is the main file that contains which components will be loaded and what their configuration is. An example configuration file is located at config/configuration.yaml.example.

When launched for the first time, Home Assistant will write a default configuration enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the interface.

You will have to restart Home Assistant for changes in configuration.yaml to take effect.

Password protecting the web interface

The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file /config/configuration.yaml and add the following to the bottom:

http:
  api_password: YOUR_PASSWORD

Adding devices and services

Home Assistant will be able to automatically discover and configure any Google Chromecasts, Belkin WeMo switches and Philips Hue bridges in your network if you have the discovery component enabled (which is by default).

Not all devices can be discovered, so if you have any of the following devices or services, please see their respective pages for installation instructions:

Setting up Home Automation

When all your devices are set up it’s time to put the cherry on the pie: automation. There are many ways to automate your home with Home Assistant so we have divided it into a couple of topics:

Automatic light control based on the sun and if people are home (built-in component)
Intruder alerts (built-in component)
Setup your own automation rules (using configuration file)
Create your own automation component (writing Python code)

Setting up your phone or tablet

Home Assistant runs as a self hosted web application. Home Assistant contains support to be added to your homescreen. If you’re on Android you can follow the visual guide. For other devices, open Home Assistant on your mobile browser and click on the add to homescreen option.