ssh — manage servers

opus brewtools

Caution

Every destructive command requires explicit confirmation. DELETE and PRIVILEGE operations always gate on user approval — even when chained with safe commands. The skill breaks compound requests into individually classified steps before executing anything.

Tip

No server configured yet? Run /brewtools:ssh setup — the skill walks you through key auth, writes ~/.ssh/config, and generates the ssh-admin agent with full server context baked in. For complex multi-step operations (deploy, rollback, migration) the skill delegates to that agent automatically.

Quick reference

FieldValue
Command/brewtools:ssh
Arguments<task description> or setup / connect / configure / update-agent
Modelopus
Agentssh-admin — auto-delegated for complex ops
Config storageCLAUDE.local.md (gitignored, never committed)

When to use

  • First-time setup — add a new server: /brewtools:ssh setup
  • System admin — disk usage, memory, logs, pending updates: /brewtools:ssh check disk space on vps-main
  • Docker ops — containers, images, compose lifecycle: /brewtools:ssh show running containers
  • Deploy — pull image, restart service, health check: /brewtools:ssh pull latest and restart brewcode-docs
  • Security audit — firewall rules, fail2ban, sshd config: /brewtools:ssh check ufw and fail2ban status
  • Agent refresh — after server changes: /brewtools:ssh update-agent

Examples

# First time — set up a new server
/brewtools:ssh setup

# Execute tasks (default mode when servers are configured)
/brewtools:ssh check disk space and docker status on vps-main

# Deploy: pull + restart
/brewtools:ssh pull ghcr.io/org/app:latest and restart on vps-main
# Connect explicitly, then describe the task
/brewtools:ssh connect to staging

# Refresh the ssh-admin agent after infrastructure changes
/brewtools:ssh update-agent

Flow

  1. Mode detection

    Auto-parses your intent: setup, connect, configure, update-agent, or execute (default). Empty args with no servers configured → setup automatically.

  2. Environment check

    Scans for SSH keys, running ssh-agent, existing ~/.ssh/config entries, and server inventory in CLAUDE.local.md. Fails fast with a clear error if SSH environment is broken.

  3. Connection setup (setup mode)

    Asks for host, user, port, alias. Tries available keys (ed25519 → rsa → ecdsa). On failure offers password login + key install flow. Writes a Host block to ~/.ssh/config.

  4. Server discovery

    Runs read-only commands over SSH: OS, kernel, Docker version and containers, disk mounts, listening ports, active services. Max 30 s timeout — partial results reported if it times out.

  5. Persist config

    Saves server inventory to CLAUDE.local.md. Adds CLAUDE.local.md to .gitignore. Generates (or regenerates) .claude/agents/ssh-admin.md with discovered server data baked in.

  6. Classify and confirm

    Each command is assigned a safety level. READ and CREATE run freely. MODIFY and SERVICE ask for confirmation. DELETE and PRIVILEGE show a destructive-action warning and always require explicit approval.

  7. Execute and report

    Simple ops run inline (max 5 SSH calls per invocation). Complex multi-step tasks delegate to the ssh-admin agent via Task tool. Session ends with a summary: server, mode, actions taken, changes made, status.

Safety classification matrix & internals

Safety levels — what needs confirmation:

LevelExample commandsConfirmation
READls, cat, df, docker ps, systemctl statusNone — runs freely
CREATEmkdir, docker pull, touchNone if non-destructive
MODIFYchmod, sed, config editsRequired
SERVICErestart, reload, docker compose upRequired
DELETErm, docker rm, pruneAlways required
PRIVILEGEsudo, firewall changes, user managementAlways required

Loop and timeout limits:

RuleLimit
SSH connection timeout10 s (ConnectTimeout=10 BatchMode=yes)
Server discovery script30 s total
Single SSH command60 s — killed and reported on timeout
Total SSH calls per invocation15 max, then stop and report
Key auth attempts (setup)3, then ask user
AskUserQuestion per phase3 max, combined into one if more needed

Server discovery collects:

  • OS distribution, version, kernel, architecture
  • Docker version, running containers, compose projects
  • Disk mounts, filesystem types, usage percentages
  • Listening ports, active systemd services

Config files:

FilePurpose
CLAUDE.local.mdServer inventory table — alias, host, user, key, OS, Docker
&#126;/.ssh/configHost blocks — skill reads but does not overwrite existing blocks
.claude/agents/ssh-admin.mdGenerated agent with server context; use update-agent to refresh

Fallback strategy: if a helper script fails, the skill attempts the same operation inline (individual Bash calls). If both fail, it reports SCRIPT_ERROR / EXIT_CODE / STDERR / PHASE and stops — no silent swallowing.

Interactive terminal commands (e.g., sudo with password prompt): use the Claude Code escape hatch ! ssh deploy@your-server to open a direct terminal session.

🤖

ssh-admin agent

The agent generated by this skill — handles complex multi-step server operations with full inventory context.

🚀

Deploy skill

GitHub Actions deployment — workflows, releases, GHCR, CI/CD automation.

🔗

GitHub source

Source code, helper scripts, and agent template.

📄

Brewtools overview

All brewtools skills — text, secrets, deploy, provider switching, plugin management.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.