Deploy Apus to production servers with apus-ansible, an automated installer with a security-first architecture.

Prerequisites

What you get

• Firewall-first security: UFW + Docker isolation (only SSH + Tailscale reachable)
• Tailscale VPN for remote access without exposing services publicly
• Docker for isolated sandbox containers with localhost-only bindings
• Systemd integration with hardening, auto-starting on boot
• One-command setup

Quick start

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

What gets installed

1. Tailscale (mesh VPN for secure remote access)
2. UFW firewall (SSH + Tailscale ports only)
3. Docker CE + Compose V2 (default agent sandbox backend)
4. Node.js and pnpm (Apus requires Node 24.22.1+ or 26.12.1+; Node 26 is recommended)
5. Apus, installed host-based, not containerized
6. A systemd service with security hardening

Post-install setup

```bash
sudo -i -u apus
```

The post-install script guides you through configuring Apus.

Log in to WhatsApp, Telegram, Discord, or Signal:
```bash
apus channels login --channel <name>
```

```bash
sudo systemctl status apus
sudo journalctl -u apus -f
```

Join your VPN mesh for secure remote access.

Quick commands

# Check service status
sudo systemctl status apus

# View live logs
sudo journalctl -u apus -f

# Restart gateway (run as apus user)
apus gateway restart

# Channel login (run as apus user)
sudo -i -u apus
apus channels login --channel <name>

apus gateway restart records managed restart intent. For a system-scope service, follow the exact sudo systemctl restart <unit> command it prints.

Security architecture

Four-layer defense model:

1. Firewall (UFW): only SSH (22) and Tailscale (41641/udp) exposed publicly
2. VPN (Tailscale): gateway reachable only via the VPN mesh
3. Docker isolation: DOCKER-USER iptables chain prevents external port exposure
4. Systemd hardening: NoNewPrivileges, PrivateTmp, unprivileged user

Verify your external attack surface:

nmap -p- YOUR_SERVER_IP

Only port 22 (SSH) should be open. Gateway and Docker stay locked down.

Docker is installed for agent sandboxes (isolated tool execution), not for running the gateway. See Multi-agent sandbox and tools for sandbox configuration.

Manual installation

```bash
sudo apt update && sudo apt install -y ansible git
```

```bash
git clone https://git.apuscorp.com/business/saas/erp/desktop-app/apusami-ansible.git
cd apus-ansible
```

```bash
ansible-galaxy collection install -r requirements.yml
```

```bash
./run-playbook.sh
```

Or run the playbook directly and then run the setup script manually:
```bash
ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/apus-setup.sh
```

Updating

The Ansible installer sets up Apus for manual updates; see Updating for the standard flow.

To re-run the playbook (for example, after configuration changes):

cd apus-ansible
./run-playbook.sh

This is idempotent and safe to run multiple times.

Troubleshooting

- Connect via Tailscale VPN first; the gateway is only reachable that way by design.
- SSH (port 22) is always allowed.

```bash
# Check logs
sudo journalctl -u apus -n 100

# Verify permissions
sudo ls -la /opt/apus

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

```bash
# Verify Docker is running
sudo systemctl status docker

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

# Build the sandbox image if missing (requires a source checkout)
cd /opt/apus/apus
sudo -u apus ./scripts/sandbox-setup.sh
# For npm installs without a source checkout, see
# https://ami-docs.dev.apuscorp.com/gateway/sandboxing#images-and-setup
```

Make sure you are running as the `apus` user:
```bash
sudo -i -u apus
apus channels login --channel <name>
```

Advanced configuration

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

• Security Architecture
• Technical Details
• Troubleshooting Guide

Related

• apus-ansible: full deployment guide
• Docker: containerized gateway setup
• Sandboxing: agent sandbox configuration
• Multi-agent sandbox and tools: per-agent isolation