kamal - SKILL.md Agent Skill

name: kamal description: Deploy containerized web applications to any Linux server using Kamal 2. Use when users need to deploy, configure, debug, or manage Kamal deployments including initial setup, configuration of deploy.yml, deployment workflows, rollbacks, managing accessories (databases, Redis, Litestream), troubleshooting deployment issues, CI/CD integration, multi-environment setups, or understanding Kamal commands and best practices. Also use when working with Kamal Proxy, Docker-based deployments, zero-downtime deploys, or 37signals deployment tooling.

Kamal Deployment

Kamal is a zero-downtime deployment tool for containerized applications, built by 37signals. It combines SSH, Docker, and Kamal Proxy to deploy any containerized web app to bare Linux servers.

Key components: SSH/SSHKit (remote execution), Docker (containers), Kamal Proxy (zero-downtime routing), Accessories (supporting services).

Quick Start

gem install kamal
cd your-app && kamal init          # Generate config/deploy.yml and .kamal/secrets
# Edit config/deploy.yml and .kamal/secrets
kamal setup                         # Bootstrap servers, install Docker, deploy

Minimal deploy.yml

service: myapp
image: username/myapp

servers:
  web:
    - 192.168.1.10

registry:
  server: ghcr.io
  username: myuser
  password:
    - KAMAL_REGISTRY_PASSWORD

env:
  secret:
    - RAILS_MASTER_KEY
  clear:
    RAILS_ENV: production

proxy:
  ssl: true
  host: example.com

For complete configuration options (registry variants, builder, proxy, accessories, SSH, volumes, aliases, healthchecks, rollout strategies), see references/configuration.md.

Essential Commands

kamal deploy                    # Build, push, deploy with zero downtime
kamal deploy -d staging         # Deploy to specific environment
kamal rollback VERSION          # Rollback to previous version
kamal app logs -f               # Follow application logs
kamal app exec -i --reuse "bin/rails console"  # Interactive console
kamal app maintenance           # Enable maintenance mode
kamal app live                  # Disable maintenance mode
kamal config                    # Show parsed configuration
kamal lock release              # Release stuck deployment lock

For complete command reference with all options, see references/commands.md.

Common Workflows

Deploy with Database Migration

Create .kamal/hooks/pre-deploy:

#!/bin/bash
kamal app exec -p -q "bin/rails db:migrate"

Then chmod +x .kamal/hooks/pre-deploy && kamal deploy.

Rollback

kamal app containers            # List available versions
kamal rollback abc123def        # Rollback to specific version

Debugging Failed Deployments

kamal app logs -n 500 — check application logs
kamal server exec "docker ps -a" — check container status
kamal app exec "curl localhost:3000/up" — test health endpoint
kamal config — verify configuration
kamal lock release — clear stuck locks

Multiple Environments

Create config/deploy.staging.yml, then:

kamal setup -d staging && kamal deploy -d staging

For detailed workflows (CI/CD, scaling, backups, security, canary deploys, monitoring), see references/workflows.md.

Limitations

No state reconciliation — removing servers from config does not decommission containers
No dynamic provisioning — cannot auto-scale or provision servers
Single-server load balancing — Kamal Proxy balances containers per server; use an external LB across servers