Kamal
Docker-based deployment tool for Rails and any web app — SSH into servers, deploy Docker containers, manage rolling deployments, and configure Traefik reverse proxy. Kamal 2 features: deploy.yml configuration, `kamal setup` for initial server setup (installs Docker, Traefik), `kamal deploy` for zero-downtime rolling deployments, `kamal rollback` for instant rollback, health checks before traffic switchover, secrets management via .kamal/secrets, accessory services (PostgreSQL, Redis alongside app), multi-host deployment, environment-specific configs, and SSH-based execution (no Kubernetes required). Created by Basecamp as alternative to Heroku for self-hosted VPS deployment of Rails agent apps.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
SSH key access to production agent servers is high privilege; use dedicated deploy key with minimum required permissions. .kamal/secrets must never be committed to version control. Traefik handles TLS termination; configure Let's Encrypt auto-cert in deploy.yml proxy.ssl for agent HTTPS. Docker registry credentials in CI must be rotated regularly for agent deployment security.
⚡ Reliability
Best When
You want Heroku-like one-command deployment for your Rails agent app to your own VPS without Kubernetes complexity — Kamal provides zero-downtime Docker deployment via SSH with Traefik reverse proxy.
Avoid When
You need Kubernetes orchestration, managed PaaS, or non-Docker deployment strategies.
Use Cases
- • Agent Rails deployment to VPS — deploy.yml with image: registry.example.com/agent-app, servers: ['10.0.0.1', '10.0.0.2'], proxy: { host: agent.example.com }; `kamal deploy` builds Docker image, pushes to registry, SSHs to servers, starts new containers, waits for health check, switches Traefik to new containers
- • Agent zero-downtime deployment — Kamal deploys new container alongside old, waits for health check to pass, switches Traefik routing, then removes old container; agent service has no downtime during deployment with rolling update
- • Agent rollback — `kamal rollback` switches Traefik back to previous container (still running); instant rollback without rebuild; previous agent version served within seconds of identifying deployment issue
- • Accessory services — accessories: { db: { image: postgres:16, host: 10.0.0.3 }, redis: { image: redis:7 } } manages PostgreSQL and Redis containers on separate hosts via Kamal accessory commands; agent infrastructure as code alongside app deployment
- • Agent secrets management — .kamal/secrets with RAILS_MASTER_KEY, DATABASE_URL, REDIS_URL; secrets not stored in deploy.yml; `kamal secrets print` shows resolved values; agent production secrets injected at deploy time via environment
Not For
- • Kubernetes environments — Kamal deploys to plain Docker on SSH-accessible servers; for Kubernetes use Helm, ArgoCD, or Flux
- • Managed PaaS hosting — Kamal requires SSH-accessible VPS; for Heroku/Render/Fly.io managed hosting use platform-specific CLI tools
- • Non-containerized deployments — Kamal assumes Docker; for Capistrano-style git-based deployment on bare metal use Capistrano
Interface
Authentication
SSH key authentication to servers. Docker registry auth (docker login). .kamal/secrets for app-level secrets injection at deployment. No agent user-facing auth.
Pricing
Kamal is MIT licensed, maintained by Basecamp/37signals. Free for all use. VPS hosting costs are your infrastructure.
Agent Metadata
Known Gotchas
- ⚠ Health check must respond before cutover — Kamal waits for health_check path (default /up) to return 200 before switching traffic; agent Rails apps without /up endpoint configured in routes or health check path mismatch cause deployment to wait indefinitely and rollback; add get '/up', to: proc { [200, {}, ['OK']] } to agent routes
- ⚠ Docker registry push required before deploy — Kamal pushes built image to registry then SSH servers pull from registry; CI must authenticate to registry before kamal deploy; agent CI pipelines using kamal deploy need KAMAL_REGISTRY_PASSWORD/USERNAME in CI environment variables before kamal deploy command
- ⚠ deploy.yml secrets reference .kamal/secrets — secrets: ['RAILS_MASTER_KEY'] in deploy.yml references .kamal/secrets file; .kamal/secrets not committed to git; each developer and CI must have .kamal/secrets populated; CI agents need kamal secrets env create to populate from CI environment variables
- ⚠ Kamal 2 breaking changes from Kamal 1 — Kamal 2 renamed proxy (Traefik config) and changed accessory syntax; agent deploy.yml from Kamal 1 (kamal-deploy gem v1.x) doesn't work with Kamal 2; migration guide required when upgrading; pin kamal gem version in Gemfile to prevent unexpected Kamal 2 upgrade
- ⚠ Accessory data volumes persist across deploys — kamal accessory reboot db recreates PostgreSQL container but volume data persists; kamal accessory remove db --volumes deletes data permanently; agent operators must understand this distinction to avoid accidental data loss during agent infrastructure changes
- ⚠ SSH key must be on all servers — Kamal connects via SSH using key specified in deploy.yml ssh.keys or default key; agent servers added to fleet must have deploy SSH key in authorized_keys before `kamal server bootstrap`; missing key causes SSH connection refused for new agent servers
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for Kamal.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-07.