| name | app |
| description | 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. |
| metadata | {"version":"1.0.0"} |
App Operations with Kamal
You are an expert in operating applications deployed with Kamal. Your goal is to inspect, control, and troubleshoot the containers that are already running on your servers — without redeploying. kamal app manages running apps, while kamal details, kamal audit, and kamal config tell you what is running, what happened, and how Kamal is configured.
To deploy new versions, see the deploy skill; to revert a bad release, see rollback.
Before You Start
Read the project's Kamal config before asking the user questions — it tells you the roles, hosts, and destinations these commands run against.
config/deploy.yml — defines your servers, roles, registry, and build settings.config/deploy.<destination>.yml — destination-specific config, selected with -d, --destination..kamal/secrets — where deploy secrets are read from.
To see the values Kamal will actually use, run kamal config (covered below) instead of guessing from the raw YAML.
The kamal app Command
kamal app manages your running apps. Run it with no subcommand to list everything it can do:
| Subcommand | What it does |
|---|
kamal app boot | Boot app on servers (or reboot app if already running) |
kamal app start | Start existing app container on servers |
kamal app stop | Stop app container on servers |
kamal app remove | Remove app containers and images from servers |
kamal app containers | Show app containers on servers |
kamal app details | Show details about app containers |
kamal app images | Show app images on servers |
kamal app version | Show app version currently running on servers |
kamal app logs | Show log lines from app on servers (use --help to show options) |
kamal app exec [CMD...] | Execute a custom command on servers within the app container |
kamal app maintenance | Set the app to maintenance mode |
kamal app live | Set the app to live mode |
kamal app stale_containers | Detect app stale containers |
For the full listing with notes on each, see references/app-command-reference.md. kamal app exec is covered under Running Commands on Servers.
Walk-Through: See What's Running
Step 1 — Every container on every host
kamal details
Shows details of all your containers — proxy, app, and accessory containers — grouped by host.
Step 2 — Just the app containers
kamal app details
kamal app containers
Step 3 — Images and running version
kamal app images
kamal app version
Step 4 — Recent logs
kamal app logs
kamal app logs --help
Run kamal app logs --help to see all log options. To configure the log driver or ship logs to OpenTelemetry or a file, see the logging skill.
Walk-Through: Control the Running App
These subcommands manage the app container directly, without running a full deploy.
| Goal | Command |
|---|
| Boot the app (or reboot if already running) | kamal app boot |
| Start a stopped app container | kamal app start |
| Stop the running app container | kamal app stop |
| Remove app containers and images | kamal app remove |
| Detect stale app containers | kamal app stale_containers |
kamal app boot boots the app on servers, or reboots it if it's already running. kamal app start and kamal app stop start and stop the existing container without rebuilding. kamal app remove removes app containers and images from the servers.
Maintenance Mode and Live Mode
Take the app offline for users while you work, then bring it back.
kamal app maintenance
While in maintenance mode, kamal-proxy intercepts requests and returns 503 responses using a built-in HTML error page.
Customize the message shown on that page:
kamal app maintenance --message "Scheduled maintenance window from ..."
To serve your own error pages instead of the built-in template, set the error_pages_path config option — a directory (relative to the app root) holding pages named after their HTTP status code, e.g. 503.html:
error_pages_path: public
Bring the app back:
kamal app live
This sets the app back to live mode.
Running Commands on Servers
kamal app exec runs a command inside the app container on your servers. Use it for one-off tasks, inspecting the environment, or opening an interactive console. Define aliases in your config for commands you run often.
Run on all servers
kamal app exec 'ruby -v'
Run on the primary server only
kamal app exec --primary 'cat .ruby-version'
kamal app exec -p 'bin/rails runner "puts Rails.application.config.time_zone"'
Open an interactive session
Interactive commands (a Rails console, a bash session) default to the primary host — use --hosts to connect to another.
kamal app exec -i 'bin/rails console'
kamal app exec -i --reuse bash
-i / --interactive runs the command interactively over SSH. --reuse runs in the currently running container instead of a fresh one made from the latest image.
Get unmodified output with --raw
By default exec runs the command's output through SSHKit's capture, which strips leading and trailing whitespace — including trailing newlines and NUL bytes — corrupting binary output such as a tar stream. Pass --raw to emit stdout exactly as produced; it also lowers the logging level so only the command's output is written.
kamal app exec --raw 'tar c -C /rails/storage .' > storage.tar
--raw can't be combined with --interactive or --detach.
For every exec pattern and option, see references/exec-reference.md.
Auditing What Happened
kamal audit
Shows the latest commands that have been run on each server. Under the hood Kamal tails .kamal/app-audit.log on each host, so you get a per-server timeline:
App Host: server1
[2024-04-05T07:14:23Z] [user] Pushed env files
[2024-04-05T07:14:29Z] [user] Pulled image with version 75bf6fa40b975cbd8aec05abf7164e0982f185ac
[2024-04-05T07:14:45Z] [user] [web] Booted app version 75bf6fa40b975cbd8aec05abf7164e0982f185ac
[2024-04-05T07:14:53Z] [user] Tagging registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac as the latest image
[2024-04-05T07:14:53Z] [user] Pruned containers
[2024-04-05T07:14:53Z] [user] Pruned images
Use it to confirm who deployed what and when, and to see the push/pull/boot/tag/prune sequence each deploy produced.
Inspecting the Resolved Config
kamal config
Displays your config — the values Kamal will use, including the roles, hosts, and primary host; the version, repository, and absolute_image to deploy; the service_with_version; SSH and builder settings; accessories; and logging options:
:roles:
- web
:hosts:
- vm1
- vm2
:primary_host: vm1
:version: 505f4f60089b262c693885596fbd768a6ab663e9
:repository: registry:4443/app
:absolute_image: registry:4443/app:505f4f60089b262c693885596fbd768a6ab663e9
:service_with_version: app-505f4f60089b262c693885596fbd768a6ab663e9
Run it to confirm what a command will target before you run it. See the full example in the official config docs.
Checking Versions
There are two distinct "version" questions, each with its own command:
| Question | Command | What it returns |
|---|
| What app version is running on my servers? | kamal app version | The app version currently running on servers |
| What version of Kamal itself do I have? | kamal version | The version of Kamal installed (e.g. 2.12.0) |
Don't confuse kamal app version (your app's deployed version) with kamal version (the Kamal CLI's version).
Quick Reference
| Goal | Command |
|---|
| See every container on every host | kamal details |
| List app containers / show details | kamal app containers / kamal app details |
| Show app images | kamal app images |
| Show running app version | kamal app version |
| Show recent app logs | kamal app logs |
| Boot / start / stop the app | kamal app boot / kamal app start / kamal app stop |
| Maintenance / live mode | kamal app maintenance / kamal app live |
| Run a command on all servers | kamal app exec 'CMD' |
| Run on the primary only | kamal app exec -p 'CMD' |
| Open an interactive console | kamal app exec -i 'bin/rails console' |
| Review server activity | kamal audit |
| Print the resolved config | kamal config |
| Kamal CLI version | kamal version |
Related Skills
- deploy: For shipping new releases with
kamal deploy and kamal redeploy.
- rollback: For reverting to a previous image with
kamal rollback after a bad deploy.
- logging: For configuring the Docker log driver and options, and shipping deploy/command logs to OpenTelemetry or a file.
- proxy: For managing kamal-proxy — the proxy that returns the
503 during maintenance mode and cuts traffic over on deploy.
