@action-llama/action-llama 0.12.2 → 0.13.1

package/docs/vps-deployment.md

@@ -1,285 +0,0 @@
-# VPS Deployment
-
-Deploy Action Llama on any VPS (DigitalOcean, Vultr, Hetzner, etc.) for cost-effective remote hosting.
-
-There are two approaches:
-
-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)
-
-The VPS cloud provider lets you manage your VPS deployment from your local machine, just like AWS or GCP.
-
-### Quick Start
-
-```bash
-# From your local machine:
-al setup cloud -p .         # Select "VPS (Vultr, etc.)" → connect or provision
-al doctor -c -p .           # Push credentials to VPS via SSH
-al cloud deploy -p .        # Deploy scheduler to VPS
-```
-
-### Setup Options
-
-The `al setup cloud` wizard offers two paths:
-
-#### Connect to an existing server
-
-Works with any VPS provider (DigitalOcean, Hetzner, Linode, etc.) or any server you can SSH into:
-
-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
-
-Requirements:
-- SSH access to the server
-- Docker installed on the server (`curl -fsSL https://get.docker.com | sh`)
-
-#### Provision a new Vultr VPS
-
-Automated provisioning with Vultr as a supported backend:
-
-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
-
-Automated provisioning with Hetzner Cloud:
-
-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
-
-| Operation | Implementation |
-|-----------|---------------|
-| Image builds | `tar -c . \| ssh docker build -t <tag> -` (built on VPS, no registry) |
-| Credential storage | Filesystem on VPS (`~/.action-llama/credentials/`) via SSH |
-| Credential push | `al doctor -c` copies credentials over SSH |
-| Scheduler deploy | `docker run -d --restart unless-stopped` on VPS |
-| IAM reconciliation | No-op (SSH access = full access) |
-| Log streaming | Real-time via SSH (`docker logs -f`) |
-
-### Configuration
-
-In your environment file (`~/.action-llama/environments/<name>.toml`):
-
-```toml
-[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
-
-```bash
-al teardown cloud -p .
-```
-
-This stops all Action Llama containers and cleans up remote credentials. If the instance was provisioned via Vultr, you'll be offered the option to delete it.
-
-## Approach 2: Manual Deployment
-
-Install Action Llama directly on your VPS and run it there. Simpler but requires managing the server directly.
-
-### Quick Start
-
-On your VPS:
-
-```bash
-# 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
-
-The `--expose` flag enables VPS deployment by:
-
-- **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
-
-For production, put a reverse proxy in front with TLS termination:
-
-### 1. Install Caddy
-
-```bash
-# 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
-
-Edit `/etc/caddy/Caddyfile`:
-
-```
-your-domain.com {
-    reverse_proxy localhost:8080
-}
-```
-
-### 3. Start Caddy
-
-```bash
-sudo systemctl enable caddy
-sudo systemctl start caddy
-```
-
-## Process Management with systemd
-
-For the manual deployment approach, create `/etc/systemd/system/action-llama.service`:
-
-```ini
-[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
-```
-
-Start the service:
-
-```bash
-sudo systemctl enable action-llama
-sudo systemctl start action-llama
-```
-
-## Alternative: nohup
-
-For simpler setups, use `nohup`:
-
-```bash
-nohup al start -w --expose --headless > action-llama.log 2>&1 &
-```
-
-## Firewall Configuration
-
-Ensure your VPS firewall allows:
-
-- Port 22 (SSH)
-- Port 80 (HTTP, for Caddy)
-- Port 443 (HTTPS, for Caddy)
-- Port 8080 only if not using a reverse proxy
-
-Example with `ufw`:
-
-```bash
-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
-
-Check service status:
-
-```bash
-# 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
-
-| Provider | vCPU | RAM | Storage | Price/month |
-|----------|------|-----|---------|-------------|
-| DigitalOcean | 1 | 1GB | 25GB SSD | $6 |
-| Vultr | 1 | 1GB | 25GB SSD | $6 |
-| Hetzner | 1 | 2GB | 20GB SSD | €4.15 |
-| Linode | 1 | 1GB | 25GB SSD | $5 |
-
-Compare to managed cloud solutions that may cost $50+ per month for similar agent workloads.
-
-## Troubleshooting
-
-### Gateway not accessible externally
-
-- Check firewall settings
-- Verify `--expose` flag is used (manual deployment)
-
-### Docker issues
-
-```bash
-# Check Docker daemon
-sudo systemctl status docker
-
-# Test Docker access
-docker ps
-```
-
-### SSH connection issues (cloud provider)
-
-```bash
-# 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`

package/docs/web-dashboard.md

@@ -1,113 +0,0 @@
-# Web Dashboard
-
-Action Llama includes an optional web-based dashboard for monitoring agents in your browser. It provides a live view of agent statuses and streaming logs — similar to the terminal TUI, but accessible from any browser.
-
-## Enabling the Dashboard
-
-Pass `-w` or `--web-ui` to `al start`:
-
-```bash
-al start -w
-al start -w -p ./my-project
-```
-
-The dashboard URL is shown in the TUI header and in headless log output once the scheduler starts:
-
-```
-Dashboard: http://localhost:8080/dashboard
-```
-
-The port is controlled by the `[gateway].port` setting in `config.toml` (default: `8080`).
-
-## Authentication
-
-The dashboard is protected by a gateway API key. The same key is used for both browser sessions and CLI access.
-
-**Key location:** `~/.action-llama/credentials/gateway_api_key/default/key`
-
-The key is generated automatically by `al doctor` or on first `al start`. To view or regenerate it, run `al doctor`.
-
-### Browser login
-
-Navigate to `http://localhost:8080/dashboard`. You'll be redirected to a login page where you paste your API key. On success, an `al_session` cookie is set (HttpOnly, SameSite=Strict) so all subsequent requests — including SSE streams — are authenticated automatically.
-
-A **Logout** link is available in the dashboard header.
-
-### CLI access
-
-CLI commands (`al stat`, `al pause`, `al resume`, `al kill`) automatically read the API key from the credential store and send it as a `Bearer` token in the `Authorization` header.
-
-### What's protected
-
-The following routes require authentication:
-
-- `/dashboard` and `/dashboard/*` — all dashboard pages and SSE streams
-- `/control/*` — scheduler and agent control endpoints (pause, resume, kill, trigger, enable/disable)
-- `/locks/status` — active lock information
-
-Health checks (`/health`), webhook endpoints (`/webhooks/*`), and container management routes are **not** protected.
-
-### Migrating from `AL_DASHBOARD_SECRET`
-
-The old `AL_DASHBOARD_SECRET` environment variable (HTTP Basic Auth) is no longer used. If it's still set, a deprecation warning is logged. Remove it from your environment and run `al doctor` to set up the new API key.
-
-## Dashboard Pages
-
-### Main Page — `/dashboard`
-
-Displays a live overview of all agents:
-
-| Column | Description |
-|--------|-------------|
-| Agent | Agent name (click to view logs) |
-| State | Current state: idle, running, building, or error |
-| Status | Latest status text or error message |
-| Last Run | Timestamp of the most recent run |
-| Duration | How long the last run took |
-| Next Run | When the next scheduled run will happen |
-| Actions | **Run** (trigger an immediate run) and **Enable/Disable** (toggle the agent) |
-
-The header also includes:
-
-- **Pause/Resume** button — pauses or resumes the scheduler (all cron jobs)
-- **Logout** link — clears the session cookie and redirects to the login page
-
-Below the table, a **Recent Activity** section shows the last 20 log lines across all agents.
-
-All data updates in real time via Server-Sent Events (SSE) — no manual refresh needed.
-
-### Agent Logs — `/dashboard/agents/<name>/logs`
-
-Displays a live-streaming log view for a single agent. Logs follow automatically by default (new entries scroll into view as they arrive).
-
-Features:
-- **Follow mode** — enabled by default, auto-scrolls to the latest log entry. Scrolling up pauses follow; scrolling back to the bottom re-enables it.
-- **Clear** — clears the log display (does not delete log files).
-- **Connection status** — shows whether the SSE connection is active.
-- **Log levels** — color-coded: green for INFO, yellow for WARN, red for ERROR.
-
-On initial load, the last 100 log entries from the agent's log file are displayed, then new entries stream in as they are written.
-
-## How It Works
-
-The dashboard is served by the same gateway that handles webhooks and container communication. When `--web-ui` is enabled, the gateway starts even if Docker and webhooks are not configured.
-
-Live updates use **Server-Sent Events (SSE)** on two endpoints:
-
-- `GET /dashboard/api/status-stream` — pushes agent status and scheduler info whenever state changes
-- `GET /dashboard/api/logs/<agent>/stream` — streams log lines for a specific agent by tailing its log file (500ms poll interval)
-
-Dashboard actions (Run, Enable/Disable, Pause/Resume) call the control API endpoints:
-
-- `POST /control/trigger/<name>` — trigger an immediate agent run
-- `POST /control/agents/<name>/enable` — enable a disabled agent
-- `POST /control/agents/<name>/disable` — disable an agent (pauses its cron job)
-- `POST /control/agents/<name>/pause` — pause an agent (alias for disable)
-- `POST /control/agents/<name>/resume` — resume an agent (alias for enable)
-- `POST /control/agents/<name>/kill` — kill all running instances of an agent
-- `POST /control/pause` — pause the scheduler
-- `POST /control/resume` — resume the scheduler
-
-All control requests use `credentials: 'same-origin'` to carry the session cookie.
-
-No additional dependencies or frontend build steps are required. The dashboard is rendered as plain HTML with inline CSS and JavaScript.

package/docs/webhooks.md

@@ -1,152 +0,0 @@
-# Webhooks
-
-Action Llama agents can be triggered by webhooks in addition to (or instead of) cron schedules.
-
-## Defining Webhook Sources
-
-Webhook sources are defined once in the project's `config.toml`. Each source has a name, a provider type, and an optional credential for signature validation:
-
-```toml
-[webhooks.my-github]
-type = "github"
-credential = "MyOrg"          # credential instance name (github_webhook_secret:MyOrg)
-
-[webhooks.my-sentry]
-type = "sentry"
-credential = "SentryProd"     # credential instance name (sentry_client_secret:SentryProd)
-
-[webhooks.my-linear]
-type = "linear"
-credential = "LinearMain"     # credential instance name (linear_webhook_secret:LinearMain)
-```
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `type` | string | Yes | Provider type: `"github"`, `"sentry"`, or `"linear"` |
-| `credential` | string | No | Credential instance name for HMAC signature validation. Omit for unsigned webhooks. |
-
-## Agent Webhook Triggers
-
-Agents reference a webhook source by name and add filters in their `agent-config.toml`:
-
-```toml
-[[webhooks]]
-source = "my-github"
-repos = ["acme/app"]
-events = ["issues"]
-actions = ["labeled"]
-labels = ["agent"]
-
-# Filter by organization
-[[webhooks]]
-source = "my-github"
-orgs = ["acme", "example-org"]
-events = ["issues"]
-
-# Or using the singular form
-[[webhooks]]
-source = "my-github"
-org = "acme"
-events = ["pull_request"]
-```
-
-Each `[[webhooks]]` entry is a trigger. The `source` field (referencing a name from `config.toml`) is required. All filter fields (`repos`, `events`, `actions`, `labels`, etc.) are optional — omit all of them to trigger on everything from that source.
-
-An agent must have at least one of `schedule` or `webhooks` (or both).
-
-## GitHub Webhooks
-
-### Filter Fields (all optional)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `repos` | string[] | Only trigger for these repos |
-| `orgs` | string[] | Only trigger for these organizations |
-| `org` | string | Only trigger for this organization (singular form) |
-| `events` | string[] | GitHub event types (issues, pull_request, push, etc.) |
-| `actions` | string[] | Event actions (opened, labeled, closed, etc.) |
-| `labels` | string[] | Only when issue/PR has these labels |
-| `assignee` | string | Only when assigned to this user |
-| `author` | string | Only for this author |
-| `branches` | string[] | Only for these branches |
-
-### Setup
-
-1. In your GitHub repo, go to **Settings > Webhooks > Add webhook**
-2. Set the payload URL to your Action Llama gateway (e.g. `https://your-server:8080/webhooks/github`)
-3. Set content type to `application/json`
-4. Set the secret to match the `github_webhook_secret` credential instance referenced by the webhook source in `config.toml`
-5. Select the events you want to receive
-
-### Using ngrok for Local Development
-
-```bash
-ngrok http 8080
-```
-
-Use the ngrok URL as your webhook payload URL in GitHub.
-
-## Sentry Webhooks
-
-### Filter Fields
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `resources` | string[] | Resource types: event_alert, metric_alert, issue, error, comment |
-
-### Setup
-
-1. In Sentry, go to **Settings > Developer Settings > New Internal Integration**
-2. Set the webhook URL to your gateway (e.g. `https://your-server:8080/webhooks/sentry`)
-3. Copy the client secret to `~/.action-llama/credentials/sentry_client_secret/<instance>/secret`
-4. Select the resource types you want to receive
-
-## How Webhooks Work at Runtime
-
-1. The gateway receives a webhook POST request at `/webhooks/<type>` (e.g. `/webhooks/github`)
-2. It verifies the payload signature using secrets loaded from the credential instances defined in `config.toml` webhook sources
-3. It parses the event into a `WebhookContext` (source, event, action, repo, etc.)
-4. It matches the context against each agent's webhook triggers
-5. Matching agents are triggered with the webhook context injected into their prompt
-
-## Linear Webhooks
-
-### Filter Fields (all optional)
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `organizations` | string[] | Only trigger for these Linear organizations |
-| `events` | string[] | Linear event types (issues, issue_comment, etc.) |
-| `actions` | string[] | Event actions (create, update, delete, etc.) |
-| `labels` | string[] | Only when issue has these labels |
-| `assignee` | string | Only when assigned to this user (email) |
-| `author` | string | Only for this author (email) |
-
-### Setup
-
-1. In Linear, go to **Settings > Workspace > Webhooks**
-2. Click **Create webhook**
-3. Set the URL to your Action Llama gateway (e.g. `https://your-server:8080/webhooks/linear`)
-4. Set the secret to match the `linear_webhook_secret` credential instance referenced by the webhook source in `config.toml`
-5. Select the resource types you want to receive (Issues, Comments, etc.)
-
-### Example Configuration
-
-```toml
-# In config.toml
-[webhooks.linear-main]
-type = "linear"
-credential = "main-workspace"
-
-# In agent-config.toml
-[[webhooks]]
-source = "linear-main"
-events = ["issues", "issue_comment"]
-actions = ["create", "update"]
-organizations = ["your-org-id"]
-labels = ["bug", "ready-for-dev"]
-```
-
-## Hybrid Agents
-
-Agents can have both `schedule` and `webhooks`. Scheduled runs poll for work; webhook runs respond to events immediately.