​

VPS Deployment

1. VPS cloud provider (provider: "vps") — manage the VPS from your local machine via SSH. Images are built on the VPS, credentials pushed over SSH, scheduler deployed as a Docker container. Set up with al setup cloud.
2. Manual deployment — install Action Llama directly on the VPS and run al start with the --expose flag. Simpler, but requires SSH’ing into the server to manage.

​

Approach 1: VPS Cloud Provider (Recommended)

​

Quick Start

# From your local machine:
al setup cloud -p .         # Select "VPS (Vultr, etc.)" → connect or provision
al doctor -p .              # Ensure credentials are configured locally
al cloud deploy -p .        # Deploy scheduler to VPS

​

Setup Options

​

Connect to an existing server

1. Enter the server IP, SSH user, port, and key path
2. Action Llama validates SSH connectivity and checks Docker is installed
3. Configuration is written to your environment file

• SSH access to the server
• Docker installed on the server (curl -fsSL https://get.docker.com | sh)

​

Provision a new Vultr VPS

1. Configure vultr_api_key credential first: al creds add vultr_api_key
2. Run al setup cloud and select “Provision a new Vultr VPS”
3. Pick region, plan (minimum 2 vCPU / 2GB RAM), and SSH key
4. Instance is created with cloud-init that installs Docker automatically
5. Action Llama waits for the instance to become ready

​

Provision a new Hetzner VPS

1. Configure hetzner_api_key credential first: al creds add hetzner_api_key
2. Run al setup cloud and select “Provision a new Hetzner VPS”
3. Pick server type, location, OS image, and SSH key
4. Server is created with cloud-init that installs Docker automatically
5. Action Llama waits for the server to become ready

​

How It Works

​

Configuration

[cloud]
provider = "vps"
host = "5.6.7.8"
sshUser = "root"          # default: "root"
sshPort = 22              # default: 22
sshKeyPath = "~/.ssh/id_rsa"  # default: "~/.ssh/id_rsa"

# Set automatically if provisioned via Vultr:
# vultrInstanceId = "abc123"
# vultrRegion = "ewr"

​

Teardown

al teardown cloud -p .

​

Approach 2: Manual Deployment

​

Quick Start

# Install Action Llama
npm install -g @action-llama/action-llama

# Set up your project (or clone from git)
al new my-project
cd my-project

# Configure credentials and check setup
al doctor

# Start with public gateway binding
al start -w --expose --headless

​

Key Features

• Binding gateway to 0.0.0.0 — makes webhooks accessible from external services
• Preserving local-mode features — web UI, control routes, filesystem credentials, SQLite state
• No cloud infrastructure required — works on any Linux VPS

​

TLS Setup with Caddy

​

1. Install Caddy

# Ubuntu/Debian
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update && sudo apt install caddy

​

2. Configure Caddy

your-domain.com {
    reverse_proxy localhost:8080
}

​

3. Start Caddy

sudo systemctl enable caddy
sudo systemctl start caddy

​

Process Management with systemd

[Unit]
Description=Action Llama Scheduler
After=network.target

[Service]
Type=simple
User=action-llama
WorkingDirectory=/home/action-llama/my-project
Environment=NODE_ENV=production
ExecStart=/usr/local/bin/al start -w --expose --headless
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable action-llama
sudo systemctl start action-llama

​

Alternative: nohup

nohup al start -w --expose --headless > action-llama.log 2>&1 &

​

Firewall Configuration

• Port 22 (SSH)
• Port 80 (HTTP, for Caddy)
• Port 443 (HTTPS, for Caddy)
• Port 8080 only if not using a reverse proxy

sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

​

Security Considerations

• Use TLS in production — Don’t expose port 8080 directly without HTTPS
• Gateway API key — Action Llama generates an API key for dashboard access (run al doctor to view it)
• Credentials isolation — Each agent runs in a Docker container with only its required credentials
• User separation — Run Action Llama as a non-root user
• SSH key security — The VPS cloud provider uses your SSH key for all operations. Protect it with a passphrase and restrict access.

​

Monitoring

# systemd (manual deployment)
sudo systemctl status action-llama

# Cloud provider deployment
al stat -c

# Logs
al logs scheduler
al logs dev -c              # Cloud provider: view agent logs via SSH
journalctl -u action-llama -f

​

Cost Comparison

​

Troubleshooting

​

Gateway not accessible externally

• Check firewall settings
• Verify --expose flag is used (manual deployment)

​

Docker issues

# Check Docker daemon
sudo systemctl status docker

# Test Docker access
docker ps

​

SSH connection issues (cloud provider)

# Test SSH manually
ssh -o ConnectTimeout=10 root@your-vps-ip echo ok

# Check SSH key permissions
chmod 600 ~/.ssh/id_rsa

​

Webhook delivery failures

• Check reverse proxy configuration
• Verify TLS certificate is valid
• Test webhook URL accessibility from external services

​

Out of disk space

• Clean up old Docker images: docker system prune -a
• Rotate logs: configure systemd journal limits
• Monitor disk usage: df -h