SSH Admin

Quick reference

Approval contract

A subagent cannot ask, confirm, or wait for input mid-run — AskUserQuestion is stripped from every subagent at runtime, even when it’s listed in the agent’s tools:. ssh-admin therefore never runs a destructive command on its own judgement:

1. It performs all non-destructive work and gathers full evidence first.
2. Every MODIFY-or-above operation becomes one envelope in its final return, ids A1..AN:

## APPROVAL REQUIRED

### A1
COMMAND:      <exact command, copy-pasteable>
HOST:         <server alias / user@host>
EFFECT:       <what changes, incl. downtime>
ROLLBACK:     <exact reverse command, or NONE>
EVIDENCE:     <the read-only output that proves it is needed>
PRECONDITION: <what must still hold at execution time>

3. It stops — nothing in that block runs. Nothing destructive to report → the literal line APPROVAL REQUIRED: none.

The caller (main session, which does have AskUserQuestion) reviews the envelope and either runs the command itself or re-spawns ssh-admin with APPROVED: A1 A3 in the prompt. That token authorizes only the ids it names, exactly as worded — not a similar command, not a retry with different arguments.

Scope guard

The agent sizes the task before it touches a server.

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, returns them as an APPROVAL REQUIRED envelope, applies once approved, verifies with ufw status verbose.

Flow

services:
  app:
    image: myapp:latest
    mem_limit: 512m
    cpus: 0.5
    restart: unless-stopped

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-pager

Return Contract

Verdict first, <=30 lines, path:line — never raw command output, journalctl/docker logs dumps, or config file bodies pasted into the reply. Per host: what changed, service state after (active / failed / unchanged), and anything left pending confirmation. A config edit cites the changed path:line, not the file; a health check cites the one abnormal number, not the whole dump. Full logs and health output go to .claude/reports/YYYYMMDD-HHMMSS_ssh-admin/, returned as a path.

/brewtools:agent-return-setup enforces this at ~1000 / ~2500 est-tokens when installed; the contract itself ships unconditionally.