SSH Admin
Caution
Every destructive command requires explicit confirmation. MODIFY, DELETE, and PRIVILEGE operations pause and ask via AskUserQuestion before touching anything on the remote host. READ and non-destructive CREATE run freely.
Caution
One agent per host. A multi-server, multi-environment or multi-service job is split per target — the agent refuses to loop over your whole fleet in a single run. Ask for “check prod-1” and “check prod-2” as separate tasks, or accept the split proposal it returns.
Tip
Run /brewtools:ssh first to configure server connections. The skill writes CLAUDE.local.md with your server inventory — ssh-admin reads it automatically on every task start. No inventory file? The agent asks for connection details before proceeding.
Quick reference
| Field | Value |
|---|---|
| Model | inherit — runs on the session’s model |
| Tools | Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, WebFetch, WebSearch |
| Triggers | ”ssh admin”, “server management”, “deploy to server”, “docker on server” |
| Inventory | Reads CLAUDE.local.md in project root |
| Permission | default — destructive ops require confirmation |
| Scope | One bounded unit per run; one agent per host |
Scope guard
The agent sizes the task before it touches a server.
| Situation | What the agent does |
|---|---|
| Task fits one bounded unit — one deliverable, ~5 files, ~10 steps | Runs it |
| Bigger, or several independent deliverables | Stops before starting, returns a split proposal: 2-N bounded subtasks, each with scope and suggested owner |
| Several hosts / environments / services in one request | Split per target — one agent per host, per environment, per service. Never one agent looping over all of them |
| Scope grows mid-flight | Stops at the next clean boundary, reports done / remaining / how to split |
| Brief missing GOAL, SCOPE, CONTEXT, CONSUMER or acceptance | States the assumption in the report, or asks once. Never invents scope |
How this changes your request: instead of “restart the app on all three prod nodes”, phrase it as three tasks (one per node) — or send the broad request, get the split proposal back, and approve it. The result is delivered for the CONSUMER who picks it up next, not for the literal wording.
When to use
- Server health check — disk, memory, CPU, running containers, failed services
- Docker deployment — pull image, write compose file, start/update/stop services
- Firewall changes — UFW rules, port allow/deny, rule review
- Reverse proxy setup — Caddy or Nginx virtual hosts with auto-TLS
- Security hardening — SSH config, fail2ban, user/key management
- Disk cleanup — prune unused Docker layers, locate large directories
Examples
"Check health on prod-server — disk, memory, running containers"The agent connects via SSH, runs diagnostics (uptime, free -h, df -h, docker ps), and returns a summary table.
"Deploy a Redis container on staging-server, port 6379, with a persistent volume"Writes a compose file, transfers it via scp, starts the service, verifies the container is running.
"Open port 443 and block all other inbound traffic on web-server"Reviews current UFW rules, proposes changes, asks for confirmation, applies, verifies with ufw status verbose.
Flow
- Load inventory
Reads
CLAUDE.local.mdin the project root for host aliases, IP addresses, SSH users, and key paths. If the file is missing, asks for connection details viaAskUserQuestion. - Verify SSH
Runs
ssh -o ConnectTimeout=10 -o BatchMode=yes USER@HOST ‘echo OK’to confirm connectivity. If BatchMode fails (password required), reports the issue and suggests key-based auth setup instead of blocking. - Gather state
Collects a baseline snapshot — uptime, memory, disk, Docker containers, open ports, failed systemd units. Read-only, no confirmation needed.
- Classify and confirm
Every planned command is classified: READ (free), CREATE (free if non-destructive), MODIFY / SERVICE / DELETE / PRIVILEGE (pause + AskUserQuestion with a description of what will happen). Nothing executes until confirmed.
- Execute and verify
Runs the confirmed commands. Config changes are validated before apply (
caddy validate,nginx -t). Services are restarted and re-checked. Credentials are never hardcoded in commands or files. - Report
Returns a structured summary: server, task description, actions taken, verification results, and final status (Success / Partial / Failed).
Safety rules & internals
Safety classification
| Class | Examples | Action |
|---|---|---|
| READ | ls, cat, df, docker ps, systemctl status, ufw status | Free |
| CREATE | mkdir, touch, docker pull | Free if non-destructive |
| MODIFY | chmod, chown, sed, config edits | AskUserQuestion |
| SERVICE | restart, reload, docker compose up | AskUserQuestion |
| DELETE | rm, docker rm, docker volume rm, drop | Always AskUserQuestion |
| PRIVILEGE | sudo, su, firewall rules, user management | Always AskUserQuestion |
Before any MODIFY / SERVICE / DELETE / PRIVILEGE command on a remote server, the agent describes what will happen and asks for confirmation.
Operational guards
| Guard | Rule |
|---|---|
| Non-interactive output | --no-pager on journalctl/systemctl, bounded log reads (-n 50, --tail 100) — a pager on a remote shell hangs the run |
| Lockout | Before ufw enable or any sshd/port change: verify the current SSH port is allowed and keep an open session until the new config is proven |
| Data destruction | docker system prune -af --volumes and rsync --delete are DELETE level — always confirmed, with an explicit statement of what gets removed |
SSH connection patterns
| Pattern | Command |
|---|---|
| Non-interactive | ssh -o ConnectTimeout=10 -o BatchMode=yes USER@HOST "command" |
| Multi-command | ssh -o ConnectTimeout=10 -o BatchMode=yes USER@HOST 'cmd1 && cmd2' |
| File transfer | scp -o ConnectTimeout=10 FILE USER@HOST:/path/ |
| Interactive | Instruct user: ! ssh USER@HOST in Claude Code prompt |
Docker Compose resource limits (Non-Swarm)
services:
app:
image: myapp:latest
mem_limit: 512m
cpus: 0.5
restart: unless-stoppedUse mem_limit/cpus — never deploy.resources.* (Swarm-only syntax).
Quick health script
echo "=== Server Health ===" && \
uptime && echo "---" && \
free -h | grep Mem && echo "---" && \
df -h | grep -E '^/dev' && echo "---" && \
docker ps --format 'table {{.Names}}\t{{.Status}}' 2>/dev/null && echo "---" && \
systemctl --failed --no-pagerSSH hardening checklist (/etc/ssh/sshd_config)
| Setting | Value | Why |
|---|---|---|
PermitRootLogin | no | Prevent root SSH |
PasswordAuthentication | no | Key-only access |
MaxAuthTries | 3 | Brute-force limit |
Port | Custom (e.g. 2222) | Reduce scan noise |
SSH Skill
Configure server inventory and SSH connections before spawning ssh-admin.
Deploy Admin
GitHub Actions, workflows, GHCR releases, and CI/CD — pairs with ssh-admin for full deploy pipelines.
GitHub source
Agent definition, safety rules, and SSH patterns.
Brewtools overview
All brewtools skills and agents in one place.
Updating plugins
/brewtools:plugin-update to check and update the brewcode plugin suite in one command.
See the FAQ for details.