​
Ansible Installation

Deploy Pllan to production servers with pllan-ansible — an automated installer with security-first architecture.
The pllan-ansible repo is the source of truth for Ansible deployment. This page is a quick overview.

​
Prerequisites

RequirementDetails
OSDebian 11+ or Ubuntu 20.04+
AccessRoot or sudo privileges
NetworkInternet connection for package installation
Ansible2.14+ (installed automatically by the quick-start script)

​
What You Get

  • Firewall-first security — UFW + Docker isolation (only SSH + Tailscale accessible)
  • Tailscale VPN — secure remote access without exposing services publicly
  • Docker — isolated sandbox containers, localhost-only bindings
  • Defense in depth — 4-layer security architecture
  • Systemd integration — auto-start on boot with hardening
  • One-command setup — complete deployment in minutes

​
Quick Start

One-command install: 
curl -fsSL https://raw.githubusercontent.com/pllan/pllan-ansible/main/install.sh | bash

​
What Gets Installed

The Ansible playbook installs and configures:
  1. Tailscale — mesh VPN for secure remote access
  2. UFW firewall — SSH + Tailscale ports only
  3. Docker CE + Compose V2 — for agent sandboxes
  4. Node.js 24 + pnpm — runtime dependencies (Node 22 LTS, currently 22.16+, remains supported)
  5. Pllan — host-based, not containerized
  6. Systemd service — auto-start with security hardening
The gateway runs directly on the host (not in Docker), but agent sandboxes use Docker for isolation. See Sandboxing for details.

​
Post-Install Setup

1

Switch to the pllan user

sudo -i -u pllan
2

Run the onboarding wizard

The post-install script guides you through configuring Pllan settings.
3

Connect messaging providers

Log in to WhatsApp, Telegram, Discord, or Signal:
pllan channels login
4

Verify the installation

sudo systemctl status pllan
sudo journalctl -u pllan -f
5

Connect to Tailscale

Join your VPN mesh for secure remote access.

​
Quick Commands

# Check service status
sudo systemctl status pllan

# View live logs
sudo journalctl -u pllan -f

# Restart gateway
sudo systemctl restart pllan

# Provider login (run as pllan user)
sudo -i -u pllan
pllan channels login

​
Security Architecture

The deployment uses a 4-layer defense model:
  1. Firewall (UFW) — only SSH (22) + Tailscale (41641/udp) exposed publicly
  2. VPN (Tailscale) — gateway accessible only via VPN mesh
  3. Docker isolation — DOCKER-USER iptables chain prevents external port exposure
  4. Systemd hardening — NoNewPrivileges, PrivateTmp, unprivileged user
To verify your external attack surface: 
nmap -p- YOUR_SERVER_IP
Only port 22 (SSH) should be open. All other services (gateway, Docker) are locked down. Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway itself. See Multi-Agent Sandbox and Tools for sandbox configuration.

​
Manual Installation

If you prefer manual control over the automation:
1

Install prerequisites

sudo apt update && sudo apt install -y ansible git
2

Clone the repository

git clone https://github.com/pllan/pllan-ansible.git
cd pllan-ansible
3

Install Ansible collections

ansible-galaxy collection install -r requirements.yml
4

Run the playbook

./run-playbook.sh
Alternatively, run directly and then manually execute the setup script afterward:
ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/pllan-setup.sh

​
Updating

The Ansible installer sets up Pllan for manual updates. See Updating for the standard update flow. To re-run the Ansible playbook (for example, for configuration changes): 
cd pllan-ansible
./run-playbook.sh
This is idempotent and safe to run multiple times.

​
Troubleshooting

  • Ensure you can access via Tailscale VPN first
  • SSH access (port 22) is always allowed
  • The gateway is only accessible via Tailscale by design
# Check logs
sudo journalctl -u pllan -n 100

# Verify permissions
sudo ls -la /opt/pllan

# Test manual start
sudo -i -u pllan
cd ~/pllan
pllan gateway run

# Verify Docker is running
sudo systemctl status docker

# Check sandbox image
sudo docker images | grep pllan-sandbox

# Build sandbox image if missing
cd /opt/pllan/pllan
sudo -u pllan ./scripts/sandbox-setup.sh
Make sure you are running as the pllan user:
sudo -i -u pllan
pllan channels login

​
Advanced Configuration

For detailed security architecture and troubleshooting, see the pllan-ansible repo: