kamal-skills

Inspect a Linux server Kamal deploys to and harden it — automated security updates, firewall/port lockdown, auto-blocking of repeated SSH auth failures, and safe SSH configuration — while keeping the ports Kamal needs open. Use when the user says "harden my server," "lock down my VPS," "secure my Kamal server," "audit server security," "close open ports," "set up automatic updates," "is my server exposed to the internet," or before putting a new box into production. Interviews the user before changing anything, explains how to undo every change, and verifies the result afterward. For provisioning Docker itself, see setup. For the servers/roles Kamal targets, see servers. For the SSH settings Kamal itself uses to connect, see ssh. For accessory port exposure, see accessories.

Run and manage accessory services — databases, Redis, search, and other long-lived dependencies your app needs — through Kamal's `accessories:` configuration and the `kamal accessory` command. Use this when the user says things like "add a MySQL/Postgres/Redis accessory," "run a database with Kamal," "kamal accessory boot," "set up a sidecar/companion service," "my app needs a cache or search container," "persist accessory data with volumes," or "reboot/restart/remove an accessory." Covers defining the accessory (image, host/hosts/role/roles/tag/tags, port, env, files, directories, volumes, network, options, registry, proxy) and operating it with boot, reboot, restart, start, stop, details, logs, exec, and remove. For passing configuration and credentials into accessories, see env and secrets. For scheduled jobs, see cron.

Install Kamal and ship your first deploy on a new project. Use when the user is starting with Kamal for the first time and says "install Kamal," "set up Kamal on this project," "kamal init," "get started with Kamal," "deploy my app for the first time," "bootstrap my servers," or "run kamal setup." Covers `gem install kamal`, the dockerized install alias, `kamal init` (config/deploy.yml, .kamal/secrets, .kamal/hooks), writing the first config (service, image, servers, registry, builder, env), filling in .kamal/secrets, bootstrapping Docker with `kamal server bootstrap`, and the first `kamal setup`. For the full set of configuration keys, see config. For routine releases after setup, see deploy. For secrets files and vault adapters, see secrets. For registry providers, see registry.

Configure Kamal builders and build then push your app image. Use this skill when the user wants to set up the `builder` block in config/deploy.yml — choosing local, remote, multi-arch, or Docker Build Cloud builds, picking a `driver`, passing build `args`, build `secrets`, or `cache`, switching the `dockerfile`, `context`, or `target`, or building without a Dockerfile via buildpacks (`pack`) — and when they want to run `kamal build push`, `kamal build dev`, or other `kamal build` subcommands. Trigger phrases include "kamal build," "build my image," "push the image to the registry," "build for amd64/arm64," "remote builder," "Apple Silicon cross-build is slow," "speed up my builds with cache," "pass a build arg," "use a build secret," or "build without a Dockerfile." For configuring the container registry, see registry. For the one-step flow that builds and ships in a single command, see deploy. For managing the secret values that build secrets reference, see secrets.

Configure and operate kamal-proxy, the reverse proxy that gives Kamal zero-downtime deploys on ports 80 and 443. Use when the user wants to route a domain (host/hosts), enable automatic HTTPS via Let's Encrypt (ssl), point the proxy at their app's port (app_port), tune the deploy healthcheck (/up), or adjust response_timeout and buffering — and when they say things like "configure the kamal proxy," "set up SSL for my domain," "add my custom domain," "the proxy isn't routing," "reboot the proxy," "upgrade kamal-proxy," or run kamal proxy boot/reboot/start/stop/details/logs. Covers the proxy config block and the kamal proxy command. For full deploys, see deploy. For enabling the proxy per role, see servers. For starting and stopping the app container, see app. For migrating from Kamal 1.x to kamal-proxy, see upgrade.

Manage secrets for a Kamal deployment — the `.kamal/secrets` file, dotenv variable and command substitution, and the `kamal secrets` vault helpers (1Password, Bitwarden, LastPass, Bitwarden Secrets Manager, AWS Secrets Manager, Doppler, GCP Secret Manager, Passbolt). Use when the user says "kamal secrets," "where do I put my registry password," "manage secrets," "pull secrets from 1Password/Bitwarden/LastPass/Doppler," "kamal secrets fetch/extract/print," "secrets-common," "secrets.<destination>," "secrets_path," "secret vs clear env keys," "RAILS_MASTER_KEY," or "migrate from .env / kamal envify," "migrate local or file-based secrets into 1Password / a vault," or "move plaintext secret files into a password manager." Covers wiring secrets into `env.secret`/`env.clear` in deploy.yml, per-destination secrets files, and aliased secrets. For setting plain non-secret env values, see env. For registry login and KAMAL_REGISTRY_PASSWORD, see registry. For build-time secrets and args, see build.

Define custom command aliases under the top-level `aliases` key in `config/deploy.yml` so a long, repeated `kamal` invocation becomes a single `kamal <name>`. Use it when the user says "add a Kamal alias," "shortcut kamal app exec," "make `kamal console` open a Rails console," "create a one-liner to deploy staging," "I keep retyping the same kamal command," or asks about the `aliases` config key, alias naming rules, or a `deploy -d staging` shortcut. Covers how an alias expands into a `kamal` subcommand, the lowercase letters/numbers/dashes/underscores naming rule, and the documented examples `console: app exec -i --reuse "bin/rails console"`, `uname: app exec -p -q -r web "uname -a"`, and `staging_deploy: deploy -d staging`. For the rest of `config/deploy.yml` and DRYing it up with YAML anchors, see config. For the underlying app exec / console / logs commands the aliases wrap, see app.

Operate and inspect already-running Kamal apps without redeploying. Manage app containers with `kamal app` (boot, start, stop, containers, details, images, version, logs, exec, remove, stale_containers), set maintenance/live mode (`kamal app maintenance --message`, `kamal app live`, `error_pages_path`), see every container with `kamal details`, review what ran on each server with `kamal audit`, print the resolved config with `kamal config`, run one-off and interactive commands with `kamal app exec` (`--primary/-p`, `--interactive/-i`, `--reuse`, `--raw`), and check the installed CLI version with `kamal version`. Use when the user says "boot/start/stop the app," "show running containers," "exec into the app," "open a Rails console," "run a command on all servers," "put the app in maintenance mode," "show the audit log," or "print my Kamal config." For shipping releases, see deploy. For reverting a release, see rollback. For log-driver and OTel/file config, see logging. For kamal-proxy, see proxy.

Understand and write your Kamal configuration in config/deploy.yml. Use when the user says "set up config/deploy.yml," "what goes in my deploy.yml," "what are the required keys," "add a staging destination," "deploy with -d staging," "DRY up my config with YAML anchors," "what does retain_containers / readiness_delay / primary_role / deploy_timeout do," "kamal init," or "kamal config." Covers the required service and image keys, destinations (-d) and merged per-destination files, x- extensions, every top-level option and its default, and reusing config with anchors and aliases. For configuring servers and roles, see servers. For env and secrets, see env. For command shortcuts, see aliases. For a first deployment, see setup.

Run recurring, scheduled, or cron jobs on a Kamal deployment. Use when the user says "run a cron job," "schedule a recurring task," "nightly job," "hourly job," "periodic task," "set up cron with Kamal," "scheduled jobs," "run cron in a container," or asks how to keep a crontab running on their servers. Covers defining a dedicated `cron` role under the `servers:` key with a `cmd` that loads a `config/crontab` file and runs `cron -f`, and propagating environment variables into the crontab (cron does not pass them through on its own). For configuring web and worker job roles or targeting hosts/roles, see servers. For running databases, Redis, or other supporting services, see accessories. For setting `env:` values and secrets the jobs need, see env.

Run Kamal deploys end to end — a full `kamal deploy` (build, push, pull, boot, health-check on GET /up, zero-downtime cutover via kamal-proxy, then prune) and a faster `kamal redeploy` that skips bootstrapping, kamal-proxy startup, pruning, and registry login. Covers targeting with `--hosts`, `--roles`, `--version`, and `--primary`, plus `--skip-push` and `--skip-hooks`, and managing the deploy lock with `kamal lock acquire/release/status` and `--lock-wait`/`--lock-wait-timeout`/`--lock-wait-interval`. Use when the user says "deploy my app," "kamal deploy," "ship a release," "push to production," "redeploy," "deploy only to web/workers," "deploy a specific version," "skip the build," "skip hooks," "the deploy lock is stuck," or "lock deploys for a maintenance window." For building and pushing images, see build. For pre/post-deploy scripts, see hooks. For reverting a bad release, see rollback. For managing already-running containers, see app.

Configure environment variables in your Kamal deploy.yml — the `env` block with `clear` values, `secret` references loaded from `.kamal/secrets`, `tags` for per-host overrides, and per-role `env`. Use when the user says things like "add an env var to Kamal," "set DATABASE_URL in deploy.yml," "pass a secret to my container," "how do I keep my API key out of git," "different env vars per server or role," "clear vs secret env," "aliased secrets," or asks about `env.clear`, `env.secret`, `env.tags`, or `kamal secrets fetch`/`extract`. Covers how clear values are passed to `docker run` while secret values are written to an env file on the host. For managing the secret values themselves and password-manager helpers, see secrets. For tagging hosts and defining roles, see servers. For the overall deploy.yml structure, see config.

Write and wire up Kamal deploy hooks — scripts in `.kamal/hooks` (docker-setup, pre-connect, pre-build, pre-deploy, post-deploy, pre-app-boot, post-app-boot, pre-proxy-reboot, post-proxy-reboot) that run at fixed points in a deploy, plus the `KAMAL_*` env vars (`KAMAL_VERSION`, `KAMAL_PERFORMER`, `KAMAL_HOSTS`, `KAMAL_RECORDED_AT`) passed to them for audit reporting, deploy notifications, CI gates, and load-balancer draining. Use when the user says "add a deploy hook," "run a script before/after deploy," "post-deploy notification," "fail the deploy if CI hasn't passed," "block deploys unless I'm on the VPN," "run a script when kamal-proxy reboots," "where do hooks live," "hooks_path," "hooks_output," "skip hooks," or "what are the KAMAL_ env vars." Covers the `.kamal/hooks` folder from `kamal init`, naming rules, non-zero exit aborting the command, `hooks_path`/`hooks_output`, and `--skip-hooks`. For the deploy sequence these fire within, see deploy. For builds, see build.

Configure how logs flow in a Kamal deployment — the Docker logging driver and options for your app containers (the `logging:` key, where `driver` is passed to Docker as `--log-driver` and `options` as `--log-opt`, e.g. `json-file` with `max-size`), and Kamal's own output loggers that ship deploy/command logs to an OpenTelemetry endpoint or write them to a file on disk (the `output:` key, with `otel.endpoint` and `file.path`). Use when the user says things like "configure Docker logging," "set a log driver," "rotate or cap container logs with max-size," "docker logs are filling the disk," "set logging per role," "ship deploy logs to OpenTelemetry/OTel/OTLP," "send Kamal logs to a collector," or "write deploy logs to a file." For viewing running app and accessory logs with `kamal app logs` / `kamal accessory logs`, see app. For where these keys sit in config/deploy.yml alongside other top-level options, see config.

Prune old Kamal containers and images and control how many Kamal keeps around. Kamal retains the last 5 deployed containers and the images they use; everything older is removed. Use when the user says "prune old images," "clean up old containers," "my servers are running out of disk," "free up space on my servers," "remove unused Docker images," "kamal prune," "how many old releases does Kamal keep," or "change how many containers I keep." Covers `kamal prune all`, `kamal prune containers`, `kamal prune images`, and tuning retention with the `retain_containers` config key (default 5). For running a full deploy, which prunes automatically at the end, see deploy. For inspecting and managing already-running app containers, see app.

Configure the Docker registry Kamal pushes your app image to and pulls it from — Docker Hub (the default), AWS ECR, GCP Artifact Registry, a local registry, or any custom/self-hosted registry such as GHCR — and log in or out with `kamal registry login` / `logout`. Use when the user says "set up my Docker registry," "kamal registry login," "configure ECR/GCR/GHCR for Kamal," "where does Kamal push my image," "docker login failed on deploy," "use a private Docker Hub repo," or needs the `registry` block (`server`, `username`, `password`) in `config/deploy.yml` wired to a `KAMAL_REGISTRY_PASSWORD` secret. For building and pushing the image itself, see build. For storing the registry password safely, see secrets. For first-time project setup, see setup.

Tear down a Kamal deployment with `kamal remove` — it removes the kamal-proxy, app, and accessory containers from your servers and logs out of the Docker registry, prompting for confirmation unless you pass `-y`. Covers full teardown plus removing components piece by piece with `kamal app remove`, `kamal accessory remove [NAME]`, `kamal proxy remove`, and `kamal registry logout`, and scoping a teardown to one environment with `-d/--destination`. Use when the user says "remove my deployment," "tear down the app," "kamal remove," "decommission this server," "uninstall Kamal from these hosts," "delete the proxy and accessory containers," "clean up the staging deploy," "nuke my Kamal setup," or "log out of the registry on my servers." For deploying or redeploying, see deploy. For managing running app containers, see app. For accessory lifecycle and data, see accessories. For the kamal-proxy container, see proxy.

Roll back a Kamal deployment to a previous image when a release goes bad, and identify or check which versions are deployed. Use when the user says "roll back," "rollback," "revert to the previous version," "go back to the last working deploy," "the deploy is broken, undo it," "which version is running," or "what versions can I roll back to." Covers `kamal rollback [VERSION]`, finding rollback targets with `kamal app containers -q`, and checking versions with `kamal app version` and `kamal version`. For building and shipping new releases, see deploy. For inspecting, stopping, starting, and managing running app containers, see app.

Control how Kamal boots new containers across many servers during a deploy — rolling the release out in batches instead of restarting every host at once. Use when the user mentions "boot limit," "boot strategy," "rolling deploy," "deploy in batches," "restart a few hosts at a time," "stagger the deploy," "boot 25% at a time," "wait between servers," "thundering herd on deploy," or the `boot`, `boot.limit`, `boot.wait`, or `boot.parallel_roles` config keys in config/deploy.yml. For running the deploy itself, see deploy. For how servers map to roles (which matters for parallel_roles), see servers.

Define and structure the servers Kamal deploys to — a simple list of hosts, multiple custom roles (such as web and workers/job hosts), the primary role, tagged hosts, and per-role options. Use when the user says things like "add a workers role," "run background jobs on separate servers," "split web and job servers," "configure multiple servers," "set the primary role," "only some servers should run the proxy," or is editing the `servers:` block in `config/deploy.yml`. Covers the implicit `web` role, role-specific `hosts`, `cmd`, `options`, `logging`, `proxy`, `labels`, `env`, and `asset_path`, plus the root keys `primary_role` and `allow_empty_roles`. For the overall config file, see config. For tuning kamal-proxy, see proxy. For tags and secret/clear env, see env. For rollout order across hosts, see rollout.

Configure how Kamal connects to servers over SSH and tune SSHKit connection handling. Use when the user sets the SSH `user` or `port`, authenticate with specific `keys`/`key_data`, force `keys_only`, control agent forwarding (`forward_agent`), load an OpenSSH `config` file, connect through a jump/bastion host with `proxy` or `proxy_command`, debug connection problems with `log_level: debug`, or tune concurrency and pooling (`max_concurrent_starts`, `pool_idle_timeout`, `dns_retries`) when deploying to many hosts. Also use when they say "kamal can't connect to my server," "permission denied (publickey)," "deploy as a non-root user," "kamal through a bastion/jump host," "SSH timeouts deploying to lots of servers," or "change the SSH port for kamal." These map to the `ssh:` and `sshkit:` blocks in `config/deploy.yml`. For first-time project setup, see setup. For defining the hosts and roles you connect to, see servers.

Walk through upgrading an existing Kamal 1.x project to Kamal 2.0 with `kamal upgrade` — the move from Traefik to kamal-proxy, the new custom `kamal` Docker network, backward-incompatible configuration changes (the `traefik` block becoming `proxy`, the `app_port` default changing from 3000 to 80, the removed `healthcheck` section, and required `builder` `arch`), and migrating secrets from `.env`/`.env.rb` to `.kamal/secrets`. Use when the user says "upgrade Kamal to 2.0," "migrate from Kamal 1 to 2," "kamal upgrade," "kamal downgrade," "my traefik config stopped working," "how do I do a rolling upgrade," "convert my deploy.yml for Kamal 2," or "keep using Traefik on Kamal 2." Covers validating config with `kamal config`, the `kamal upgrade --rolling` sequence, downgrading back to Kamal 1.9, and running Traefik as an accessory in front of kamal-proxy. For configuring kamal-proxy itself, see proxy. For the `.kamal/secrets` format, see secrets. For the full Kamal 2 config reference, see config.