Requirements
- Python 3.8–3.14 — all minor versions are tested and supported
- pip — Python package installer
PAI has been tested on Ubuntu Server 16.04+, Raspberry Pi 3, NanoPi NEO, and OrangePi 2G-IOT. It runs on any Linux system with a supported Python version.
Installation methods
pip (stable)
Docker
From source
Install the latest stable release from PyPI:pip install paradox-alarm-interface
pai-service command and all core dependencies:
construct, paho-mqtt, pyserial-asyncio, python-slugify, pytz, and requests.On systems where python3 is the default, use pip3 instead of pip.
PAI provides official multi-architecture Docker images on Docker Hub.Supported architectures: 386, amd64, armv6, armv7, arm64This covers x86 servers, Raspberry Pi (all generations), NanoPi, and OrangePi boards.Pull the latest image:docker pull paradoxalarminterface/pai
docker run -d \
--name pai \
-v /etc/pai:/etc/pai \
-v /var/log/pai:/var/log/pai \
paradoxalarminterface/pai
/etc/pai/pai.conf by default (controlled by the PAI_CONFIG_FILE environment variable inside the container).To pass a device for serial connection, add the --device flag:docker run -d \
--name pai \
--device /dev/ttyUSB0 \
-v /etc/pai:/etc/pai \
-v /var/log/pai:/var/log/pai \
paradoxalarminterface/pai
10000/tcp for the IP socket interface (IP_INTERFACE_ENABLE = True) and port 18839/tcp for the MQTT client bind port (MQTT_BIND_PORT).The Docker image includes a default pai.conf copied from the example config. Mount your own /etc/pai volume to override it with your real settings before starting the container.
Clone the repository and install in editable mode:git clone https://github.com/ParadoxAlarmInterface/pai.git
cd pai
pip install -e .
pip install -e ".[YAML,Pushbullet,Signal]"
python3 -m paradox.console_scripts.pai_run
When installing from source, use a virtual environment to avoid conflicts with system packages:python3 -m venv .venv && source .venv/bin/activate
pip install -e .
Configuration file locations
At startup, PAI searches for a configuration file in the following locations, in order:
| Path | Notes |
|---|
./pai.conf | Current working directory |
~/.local/etc/pai.conf | User-level config |
/etc/pai/pai.conf | System-wide config (recommended for services) |
/usr/local/etc/pai/pai.conf | Alternative system-wide location |
pai.jsonpai.yaml (requires the YAML extra)
To override the search entirely, set the PAI_CONFIG_FILE environment variable:
export PAI_CONFIG_FILE=/opt/pai/my-config.conf
pai-service
--config flag:
pai-service --config /opt/pai/my-config.conf
Running as a systemd service
To run PAI automatically on boot and keep it running if it crashes, create a systemd unit file:
/etc/systemd/system/pai.service
[Unit]
Description=PAI - Paradox Alarm Interface
After=network.target
[Service]
Type=simple
User=pai
ExecStart=/usr/local/bin/pai-service
Restart=on-failure
RestartSec=5
Environment=PAI_CONFIG_FILE=/etc/pai/pai.conf
[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable pai
sudo systemctl start pai
sudo systemctl status pai
sudo journalctl -u pai -f
Create a dedicated system user for PAI (sudo useradd -r -s /bin/false pai) and add it to the dialout group if using a serial connection (sudo usermod -aG dialout pai).
