SSH

new opus

Remote server management skill. Connect, configure, and deploy on remote servers through a conversational interface with automatic safety classification for every operation.

🔗

CONNECT

Set up SSH connections to new or existing servers with auto-discovery of OS, Docker, disks, and services.

📟

EXECUTE

Run commands and tasks on remote servers through a conversational interface — describe what you need in plain language.

🔧

MANAGE

Docker, services, deployments, disk management with safety classification — destructive ops always require confirmation.

Quick Reference

Field	Value
Command	`/brewtools:ssh`
Arguments	`<task description>` or `setup/connect/configure/update-agent`
Modes	setup, connect, configure, execute (default), update-agent
Agent	ssh-admin (auto-delegated for complex ops)
Config storage	`CLAUDE.local.md` (gitignored)
Model	opus

Quick Start

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

# Connect to a configured server
/brewtools:ssh connect to vps-main

# Execute tasks (default mode)
/brewtools:ssh check disk space and docker status

# Deploy operations
/brewtools:ssh pull latest image and restart brewcode-docs

# Update server inventory
/brewtools:ssh update agent

Connection Flow

Phase 0 — Mode detection
Auto-parses your intent from the argument: setup, connect, configure, update-agent, or falls back to execute (default).
Phase 1 — Environment check
Scans for SSH keys, running ssh-agent, existing ~/.ssh/config entries, and previously stored server inventory in CLAUDE.local.md.
Phase 2 — Connection setup
Configures host, user, key-based authentication, and known_hosts verification. Supports jump hosts and custom ports.
Phase 3 — Server discovery
Runs non-destructive read commands to catalog: OS version, kernel, Docker containers, disk usage, listening ports, and active services.
Phase 4 — Persist config
Saves server inventory to CLAUDE.local.md and generates or updates the ssh-admin agent with discovered server data.
Phase 5 — Execute user request
Classifies each command by safety level (READ/CREATE/MODIFY/SERVICE/DELETE/PRIVILEGE), asks confirmation when required, then executes.
Phase 6 — Session report
Summarizes all commands executed, their outputs, and any changes made to the remote server.

Safety Classification

Every command is classified before execution. READ and CREATE run freely; MODIFY and above require confirmation.

🔍

READ

ls, cat, df, docker ps, systemctl status — free, no confirmation needed.

➕

CREATE

mkdir, docker pull, touch — free if non-destructive.

✏️

MODIFY

chmod, sed, config edits — asks for confirmation before executing.

🔄

SERVICE

restart, reload, docker compose up — asks for confirmation before executing.

⚠️

DELETE

rm, docker rm, prune — ALWAYS asks for confirmation.

🛡️

PRIVILEGE

sudo, firewall changes, user management — ALWAYS asks for confirmation.

Caution

Destructive operations (DELETE, PRIVILEGE) always require explicit confirmation, even when chained with safe commands. The skill will break compound commands into individual safety-classified steps.

Server Discovery

On first connection, the skill auto-detects the following information and stores it in your server inventory.

📄

OS and Kernel

Distribution name, version, kernel version, architecture. Used to select correct package manager and service commands.

⭐

Docker and Containers

Docker version, running containers, images, compose projects. Enables container-aware deploy operations.

✅

Disks and Storage

Mount points, filesystem types, usage percentages, available space. Alerts on low-disk conditions.

🔧

Services and Ports

Listening ports, active systemd services, open firewall rules. Provides context for deploy and troubleshooting tasks.

Configuration

CLAUDE.local.md

Server inventory is stored in CLAUDE.local.md at the project root. This file is gitignored and never committed.

## SSH Servers

| Alias | Host | User | Key | OS | Docker |
|-------|------|------|-----|----|--------|
| vps-main | your-server.example.com | deploy | ~/.ssh/id_ed25519 | Ubuntu 24.04 | 27.1.1 |
| staging | staging.example.com | deploy | ~/.ssh/staging_key | Debian 12 | 26.1.4 |

The skill reads this table on every invocation to resolve server aliases and inject context into the ssh-admin agent.

~/.ssh/config

Standard SSH config for connection defaults. The skill reads this but does not modify it.

Host vps-main
  HostName your-server.example.com
  User deploy
  Port 22
  IdentityFile ~/.ssh/id_ed25519
  StrictHostKeyChecking accept-new

Host staging
  HostName staging.example.com
  User deploy
  Port 22
  IdentityFile ~/.ssh/staging_key
  ProxyJump bastion.example.com

Best practice: define Host blocks for every server you manage. The skill resolves aliases from both CLAUDE.local.md and ~/.ssh/config.

ssh-admin agent

The skill dynamically generates an ssh-admin agent file with discovered server data baked into its prompt. This agent handles complex multi-step operations (deploy, rollback, migration) with full server context.

The agent receives:

Server inventory from CLAUDE.local.md
OS-specific command mappings (apt vs yum, systemd vs openrc)
Docker container topology
Disk and service state

Use update-agent mode to refresh agent data after server changes.

Usage Examples

System Admin

# Check disk space across all mounts
/brewtools:ssh check disk usage on vps-main

# View memory and CPU load
/brewtools:ssh show memory and cpu on staging

# Tail application logs
/brewtools:ssh show last 100 lines of nginx error log

# Check for pending OS updates
/brewtools:ssh list available security updates on vps-main

Docker

# List running containers
/brewtools:ssh show docker containers on vps-main

# View container logs
/brewtools:ssh show logs for brewcode-docs container

# Compose operations (requires confirmation)
/brewtools:ssh docker compose up -d on staging

# Registry authentication
/brewtools:ssh login to ghcr.io on vps-main

Deploy

# Pull latest image and restart
/brewtools:ssh pull ghcr.io/org/app:latest and restart on vps-main

# Blue-green deploy
/brewtools:ssh deploy new version of docs with zero downtime

# Verify deployment health
/brewtools:ssh check health endpoint after deploy on vps-main

Security

# Check firewall rules
/brewtools:ssh show ufw status on vps-main

# Review fail2ban status
/brewtools:ssh check fail2ban banned IPs

# SSH hardening audit
/brewtools:ssh check sshd config for security issues

# Review active SSH sessions
/brewtools:ssh show who is connected via SSH

Tip

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

Note

CLAUDE.local.md is gitignored by default. Server inventory, credentials references, and connection details are never committed to version control.

Troubleshooting

Issue	Solution
Permission denied	Check key path, run `ssh-add`, verify `authorized_keys` on remote server
Connection timeout	Verify port is open, check firewall rules, confirm host is reachable with `ping`
Host key changed	Remove old entry from `~/.ssh/known_hosts` for the target host
Docker permission denied	User must be in the `docker` group or commands need `sudo` prefix
Server not found in inventory	Run `/brewtools:ssh setup` to add the server or `/brewtools:ssh update-agent` to refresh

🚀

Latest Release

Download, changelog, and installation instructions.

🔗

View on GitHub

Source code, README, and configuration files.

Updating plugins

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