Getting started

Installation

The following installation methods are supported:

Docker

Supported architectures

Starting with AppDaemon 4.1.0, multi-arch images are published on the official Docker Hub repository.

Currently supported architectures:

  • linux/arm/v6

  • linux/arm/v7

  • linux/arm64/v8

  • linux/amd64

To start a container named appdaemon, exposing the HADashboard on port 5050, use the following command:

$ docker run --name appdaemon \
    --detach \
    --restart=always \
    --network=host \
    -p 5050:5050 \
    -v <conf_folder>:/conf \
    -e HA_URL="http://homeassistant.local:8123" \
    -e TOKEN="my_long_liven_token" \
    acockburn/appdaemon

Configuration folder

AppDaemon uses the /conf directory to store its configuration data. To access this folder from the host system, you need to create a data directory outside the container and mount this to the directory used inside the container. This places the configuration files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files.

The following steps illustrate the procedure;

  1. Create a configuration directory on a suitable volume on your host system, e.g. /my/own/datadir.

  2. Start you AppDaemon container like this:

$ docker run --name appdaemon \
    --detach \
    --restart=always \
    --network=host \
    -p 5050:5050 \
    -v /my/own/datadir:/conf \
    -e HA_URL="http://homeassistant.local:8123" \
    -e TOKEN="my_long_liven_token" \
    acockburn/appdaemon

The -v /my/own/datadir:/conf part of the command mounts the /my/own/datadir directory from the underlying host system as /conf inside the container, where AppDaemon by default will write its data files.

The first you start the container, AppDaemon will write its own sample configuration files in this directory.

Environment variables

When you start the AppDaemon image, you can adjust some of its configuration variables by passing one or more environment variables on the docker run command:

Name

Description

HA_URL

The URL of your running Home Assistant instance

TOKEN

Long-Lived token to authenticates against Home Assistant

For a more in-depth guide to Docker, see the Docker tutorial.

Pip

Linux

Requirements: Python version 3.8, 3.9, 3.10 or 3.11.

NOTE: Do not install this in the same Python virtual environment as Home Assistant. If you do that, then Home Assistant will stop working due to conflicting dependencies.

$ pip install appdaemon

Note: There are some OS-specific instructions for Windows and Raspberry Pi OS users.

Raspberry Pi OS

Some users have reported the need to install these additional requirements:

$ sudo apt install python-dev
$ sudo apt install libffi-dev

Windows

AppDaemon under Windows has been tested with the official 3.8.1 release of Python. There are a couple of caveats:

  • The -d or --daemonize option is not supported owing to limitations in the Windows implementation of Python.

  • Some internal diagnostics are disabled. This is not user-visible but may hamper troubleshooting of internal issues, if any crop up

AppDaemon can be installed exactly as per the instructions using pip.

WSL (Windows subsystem for Linux)

Windows 10+ now supports a full Linux Bash environment that is capable of running Python. It allows to run a multitude of Linux distributions, virtualizing a full Linux OS.

It is possible to run AppDaemon in the same way as in a standard Linux distributions, and none of the above Windows caveats apply to this version. This is the recommended way to run AppDaemon in a Windows 10 and later environment.

Home Assistant add-on

The official AppDaemon add-on is available in the Home Assistant Community Add-ons Repository, maintained by frenck. Please see their official documentation for installation and configuration instructions.

Running

Pip

You can run AppDaemon from the command line as follows. Note: make sure first to create a directory to contain all AppDaemon configuration files!

$ appdaemon -c <path_to_config_folder>

You should see something like the following:

$ appdaemon -c <path_to_config_folder>
2016-08-22 10:08:16,575 INFO Got initial state
2016-08-22 10:08:16,576 INFO Loading Module: /home/homeassistant/conf/apps/hello.py
2016-08-22 10:08:16,578 INFO Loading Object hello_world using class HelloWorld from module hello
2016-08-22 10:08:16,580 INFO Hello from AppDaemon
2016-08-22 10:08:16,584 INFO You are now ready to run Apps!

CLI arguments

The following CLI arguments are available:

$ usage: appdaemon [-h] [-c CONFIG] [-p PIDFILE] [-t TIMEWARP] [-s STARTTIME] [-e ENDTIME] [-C CONFIGFILE] [-D {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [-m MODULEDEBUG MODULEDEBUG] [-v]

options:
-h, --help            show this help message and exit
-c CONFIG, --config CONFIG
                        full path to config directory
-p PIDFILE, --pidfile PIDFILE
                        full path to PID File
-t TIMEWARP, --timewarp TIMEWARP
                        speed that the scheduler will work at for time travel
-s STARTTIME, --starttime STARTTIME
                        start time for scheduler <YYYY-MM-DD HH:MM:SS|YYYY-MM-DD#HH:MM:SS>
-e ENDTIME, --endtime ENDTIME
                        end time for scheduler <YYYY-MM-DD HH:MM:SS|YYYY-MM-DD#HH:MM:SS>
-C CONFIGFILE, --configfile CONFIGFILE
                        name for config file
-D {DEBUG,INFO,WARNING,ERROR,CRITICAL}, --debug {DEBUG,INFO,WARNING,ERROR,CRITICAL}
                        global debug level
-m MODULEDEBUG MODULEDEBUG, --moduledebug MODULEDEBUG MODULEDEBUG
-v, --version           show program's version number and exit
--write_toml            use toml file format for writing new configuration files when creating apps

A brief description of them follows:

-c path to the configuration directory

If not specified, AppDaemon will look for a file named appdaemon.yaml under the following default locations:

  • ~/.homeassistant/

  • /etc/appdaemon

If no file is found in either location, AppDaemon will raise an exception. In addition, AppDaemon expects to find a dir named apps immediately subordinate to the config directory.

-C name of the configuration file (default: appdaemon.yaml or appdaemon.toml depending on the value of the --toml flag)

-d, -p used by the init file to start the process as a daemon

Not required if running from the command line.

-D increase the debug level for internal AppDaemon operations, and configure debug logs for the apps.

-s, -i, -t, -e time travel options

Useful only for testing. Described in more detail in the API documentation.

Starting At Reboot (Systemd)

To run AppDaemon at reboot, you can set it up to run as a systemd service. To run it with init.d instead, see the next section.

Systemd service file

Create a Systemd service file /etc/systemd/system/appdaemon@appdaemon.service and add the following content. Make sure to use the correct full path for your configuration directory and that you edit the User field to a valid user that can run AppDaemon, usually the same user that is running the Home Assistant process is a good choice.

[Unit]
Description=AppDaemon
After=home-assistant@homeassistant.service
[Service]
Type=simple
User=%I
ExecStart=/usr/local/bin/appdaemon -c <full path to config directory>
[Install]
WantedBy=multi-user.target

The above should work for Raspberry Pi OS, but if your homeassistant service is named something different you may need to change the After= lines to reflect the actual name.

Activate the service

$ sudo systemctl daemon-reload
$ sudo systemctl enable appdaemon@appdaemon.service --now

Now AppDaemon should be up and running and good to go.

Starting At Reboot (Init.d)

To run AppDaemon at reboot, you can set it up to run as an init.d service. To run it with systemd instead, see the previous section.

Add Init.d Service

First, create a new file using vi:

$ sudo vi /etc/init.d/appdaemon-daemon

Copy and paste the following script into the new file, making sure that the following variables are set according to your setup.

  • APPDAEMON_INSTALL_DIR
    • Location of appdaemon installation.

  • PRE_EXEC
    • Command for starting the python venv for appdaemon.

  • APPDAEMON_BIN
    • Location of appdaemon binary.

  • RUN_AS
    • Usually the same user you are using to run Home Assistant.

  • CONFIG_DIR
    • Location of Home Assistant config.

#!/bin/sh
### BEGIN INIT INFO
# Provides:          appdaemon
# Required-Start:    $local_fs $network $named $time $syslog
# Required-Stop:     $local_fs $network $named $time $syslog
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Description:       AppDaemon
### END INIT INFO

# /etc/init.d Service Script for AppDaemon
APPDAEMON_INSTALL_DIR="/srv/appdaemon"
PRE_EXEC="cd $APPDAEMON_INSTALL_DIR; python3.9 -m venv .; source bin/activate;"
APPDAEMON_BIN="/srv/appdaemon/bin/appdaemon"
RUN_AS="homeassistant"
PID_DIR="/var/run/appdaemon"
PID_FILE="$PID_DIR/appdaemon.pid"
CONFIG_DIR="/home/$RUN_AS/.homeassistant"
LOG_DIR="/var/log/appdaemon"
LOG_FILE="$LOG_DIR/appdaemon.log"
FLAGS="-c $CONFIG_DIR"
DAEMONIZE="daemonize -c $APPDAEMON_INSTALL_DIR -e $LOG_FILE.stderr -o $LOG_FILE.stdout -p $PID_FILE -l $PID_FILE -v"

start() {
create_piddir
if [ -f $PID_FILE ] && kill -0 $(cat $PID_FILE) 2> /dev/null; then
    echo 'Service already running' >&2
    return 1
fi
echo -n 'Starting service' >&2
local CMD="$PRE_EXEC $DAEMONIZE $APPDAEMON_BIN $FLAGS"
su -s /bin/bash -c "$CMD" $RUN_AS
if [ $? -ne 0 ]; then
    echo "Failed" >&2
else
    echo 'Done' >&2
fi
}

stop() {
if [ ! -f "$PID_FILE" ] || ! kill -0 $(cat "$PID_FILE") 2> /dev/null; then
    echo 'Service not running' >&2
    return 1
fi
echo -n 'Stopping service' >&2
kill $(cat "$PID_FILE")
while ps -p $(cat "$PID_FILE") > /dev/null 2>&1; do sleep 1;done;
rm -f $PID_FILE
echo 'Done' >&2
}

install() {
echo "Installing AppDaemon Daemon (appdaemon-daemon)"
update-rc.d appdaemon-daemon defaults
create_piddir
mkdir -p $CONFIG_DIR
chown $RUN_AS $CONFIG_DIR
mkdir -p $LOG_DIR
chown $RUN_AS $LOG_DIR
}

uninstall() {
echo "Are you really sure you want to uninstall this service? The INIT script will"
echo -n "also be deleted! That cannot be undone. [yes|No] "
local SURE
read SURE
if [ "$SURE" = "yes" ]; then
    stop
    remove_piddir
    echo "Notice: The config directory has not been removed"
    echo $CONFIG_DIR
    echo "Notice: The log directory has not been removed"
    echo $LOG_DIR
    update-rc.d -f appdaemon-daemon remove
    rm -fv "$0"
    echo "AppDaemon Daemon has been removed. AppDaemon is still installed."
fi
}

create_piddir() {
if [ ! -d "$PID_DIR" ]; then
    mkdir -p $PID_DIR
    chown $RUN_AS "$PID_DIR"
fi
}

remove_piddir() {
if [ -d "$PID_DIR" ]; then
    if [ -e "$PID_FILE" ]; then
    rm -fv "$PID_FILE"
    fi
    rmdir -v "$PID_DIR"
fi
}

case "$1" in
start)
    start
    ;;
stop)
    stop
    ;;
install)
    install
    ;;
uninstall)
    uninstall
    ;;
restart)
    stop
    start
    ;;
*)
    echo "Usage: $0 {start|stop|restart|install|uninstall}"
esac

Save the file and then make it executable:

$ sudo chmod +x /etc/init.d/appdaemon-daemon
Activate Init.d Service
$ sudo service appdaemon-daemon install

That’s it. After a restart, AppDaemon will start automatically.

If AppDaemon doesn’t start, check the log file output for errors at /var/log/appdaemon/appdaemon.log.

If you want to start/stop AppDaemon manually, use:

$ sudo service appdaemon-daemon <start|stop>

Updating AppDaemon

To update AppDaemon after a new release has been published, run the following command to update your local installation:

$ pip install --upgrade appdaemon

If you are using Docker, refer to the steps in the tutorial.

Versioning Strategy

AppDaemon follows a simple 3 point versioning strategy in the format x.y.z:

x: major version number

Incremented when very significant changes have been made to the platform, or sizeable new functionality has been added.

y: minor version number

Incremented when incremental new features have been added, or breaking changes have occurred

z: point version number

Point releases will typically contain bugfixes, and package upgrades

Users should be able to expect point release upgrades to be seamless, but should check release notes for breaking changes and new functionality for minor or major releases.

Next steps

Now that you have a working setup for AppDaemon, learn how to configure it in the next section: Configuration.