Kamal strips the bloat out of deploying containers to bare metal and VPS hosts. Day-two visibility, however, still means juggling SSH tabs to run docker ps, docker stats, and docker logs -f box by box—or maintaining a Prometheus and Grafana stack heavier than the apps it watches. Kamal Watch fixes that with a single Go binary and zero host agents. Give it SSH key access to your Kamal servers, and it discovers every service (web, job workers, and accessories like Postgres or Redis), maps live kamal-proxy routes and TLS status, reads deployment audit logs, and streams container logs in real time.
Inspired by htop, the interface favors dense, monospaced terminal telemetry over sprawling charts. Each server card displays live CPU, core count, memory, swap, and root disk gauges above collapsible service rows that update automatically every few seconds. Nothing extra gets installed on your application servers: if Kamal can SSH into a host, Kamal Watch can observe it immediately.
Warning
Early Alpha — Private Networks Only (localhost, Private LAN/VPC, or VPN)
Do not expose Kamal Watch to the public internet. This early alpha release is built strictly for trusted private networks:
- No HTTP authentication: Anyone who can reach the web port can view server topology, deployment history,
/api/inventoryJSON, and live Docker logs for every container on your monitored hosts. - Direct SSH access: Kamal Watch connects to your servers with an SSH private key and verifies server host keys against
~/.ssh/known_hosts(or a configuredknown_hosts_path) by default. - Required posture: Run it bound to
127.0.0.1on your workstation, or deploy it inside an isolated LAN, private VPC, or mesh VPN (such as Tailscale or WireGuard) unreachable from the open internet.
- Go 1.26+ (to build from source) or Docker.
- SSH access to your Kamal hosts as a user that can run
dockercommands withoutsudo(rootor a user in thedockergroup—the same user Kamal uses). - An unencrypted (passphraseless) SSH private key authorized on each monitored host so
kamal-watchcan connect non-interactively. Generate a dedicated key if needed:ssh-keygen -t ed25519 -f ~/.ssh/kamal_watch -N "" -C "kamal-watch" ssh-copy-id -i ~/.ssh/kamal_watch.pub deploy@10.0.1.10
Clone the repository and build the static binary:
git clone https://github.com/jefflunt/kamal-watch.git
cd kamal-watch
./cmd/buildThis writes the compiled binary to ./bin/kamal-watch. You can also install directly with Go:
go install github.com/jefflunt/kamal-watch/cmd/kamal-watch@latestCopy the example config and list the servers you want to monitor:
cp kamal-watch.example.yml kamal-watch.ymlEdit kamal-watch.yml:
# Use "127.0.0.1:8080" locally; use ":8080" inside a container on a private network
listen_addr: "127.0.0.1:8080"
poll_interval: 4s
servers:
- name: app-server-01
host: 10.0.1.10 # Private LAN, VPC, or Tailscale IP/hostname
port: 22
user: deploy # Must have Docker access and ~/.kamal/*-audit.log
key_path: ~/.ssh/kamal_watch # Unencrypted private key path./bin/kamal-watch -config kamal-watch.ymlOpen http://127.0.0.1:8080 in your browser. Override the listen address anytime with -addr (for example, ./bin/kamal-watch -addr 127.0.0.1:9090).
Inside the provided Dockerfile, kamal-watch listens on port 8080 and reads /app/config/kamal-watch.yml by default. Mount your configuration directory and SSH key from the host as read-only volumes.
On the private/VPN server that will run kamal-watch:
sudo mkdir -p /etc/kamal-watch
sudo cp ~/.ssh/kamal_watch /etc/kamal-watch/id_ed25519
sudo chmod 600 /etc/kamal-watch/id_ed25519Create /etc/kamal-watch/kamal-watch.yml on that host (note listen_addr: ":8080" and the in-container key_path):
listen_addr: ":8080"
poll_interval: 4s
servers:
- name: app-server-01
host: 10.0.1.10
port: 22
user: deploy
key_path: /app/ssh/id_ed25519Bind port 8080 strictly to localhost or a private LAN/Tailscale interface IP (for example, 100.64.0.10):
docker build -t kamal-watch .
docker run -d --name kamal-watch --restart unless-stopped \
-p 100.64.0.10:8080:8080 \
-v /etc/kamal-watch:/app/config:ro \
-v /etc/kamal-watch/id_ed25519:/app/ssh/id_ed25519:ro \
kamal-watchTo deploy kamal-watch alongside your apps using Kamal on a private network or VPN, create config/deploy.yml (gitignored by default):
service: kamal-watch
image: your-registry/kamal-watch
servers:
web:
- 100.64.0.10 # Private VPC, LAN, or Tailscale IP ONLY
proxy:
host: watch.internal # Private DNS / split-horizon host — do NOT expose publicly
app_port: 8080
healthcheck:
path: /up
interval: 5
timeout: 10
registry:
server: ghcr.io
username: your-github-user
password:
- KAMAL_REGISTRY_PASSWORD
builder:
arch: amd64
volumes:
- "/etc/kamal-watch:/app/config:ro"
- "/etc/kamal-watch/id_ed25519:/app/ssh/id_ed25519:ro"Then deploy:
kamal setupEvery poll_interval, kamal-watch runs a single batched, read-only SSH command per server to collect:
- Host gauges:
uptime,nproc,top -bn1,df -h /, andfree -h - Container state & telemetry:
docker ps -a --format '{{json .}}'anddocker stats --no-stream --format '{{json .}}' - Proxy routes:
docker exec kamal-proxy kamal-proxy list - Audit logs:
head -n 30 "$HOME"/.kamal/*-audit.log - Live log streams (on demand):
docker logs --tail 150 -f <container>streamed to the browser over Server-Sent Events (SSE)
| Method & Path | Purpose |
|---|---|
GET / |
Main htop-style multi-server dashboard and interactive SSE log drawer |
GET /up |
Lightweight unauthenticated healthcheck endpoint for kamal-proxy / Docker |
GET /server/{name} |
Full Docker container table for a single server |
GET /server/{name}/app/{app} |
Service role breakdown, aggregate CPU/RAM, and Kamal audit log history |
GET /api/inventory |
JSON snapshot of all servers and apps (also used for Kamal healthchecks) |
GET /events |
SSE stream pushing live cluster inventory updates |
GET /logs/stream |
SSE Docker log stream (?server=<name>&container=<id-or-name>&tail=150&follow=true) |
Released under the MIT License.