Skip to main content
skill CX Codex

ssh-doctor — Claude Code skill: what it does, how to install

ssh-doctor troubleshoots macOS SSH failures, including pre-auth disconnections, stale sshd sessions, and Remote Login misconfigurations.

MIT 239 installs ★ 7,554 updated 2026-10-20

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add steipete/agent-scripts --skill ssh-doctor -a claude-code
Open on GitHub

What ssh-doctor does

This skill runs a systematic diagnostic routine for SSH on macOS. It starts with a loopback check against 127.0.0.1 on port 22 to separate local daemon issues from network filtering. When loopback succeeds but remote access fails, it inspects socket filters via socketfilterfw, packet filters via pfctl, and listening interfaces.

It directly targets pre-authentication drops caused by macOS launchd limits. If launchctl print system/com.openssh.sshd reports a high copy count, launchd refuses new inetd instances with error 67. The skill tracks down stranded sshd-session processes parented by PID 1, inspects open sockets, and terminates them using TERM.

Running these diagnostics requires sudo privileges on the target Mac for tools like systemsetup, launchctl, and sshd -T. The script avoids printing tokens, secrets, or broad environment dumps during execution.

What it helps with

  • fix SSH pre-auth connection closed errors on macOS
  • terminate stranded sshd-session processes blocking connections
  • verify Remote Login status and launchd daemon health
  • inspect sshd_config for restrictive AllowUsers or MaxStartups

Example prompts for the agent

  • Diagnose why SSH connections to this Mac drop before authentication.
  • Check com.openssh.sshd launchd status and kill stranded sshd-session processes.
  • Verify Remote Login settings and firewall rules for port 22.

How to install ssh-doctor

1Skills CLI (Vercel)

npx skills add steipete/agent-scripts --skill ssh-doctor -a claude-code

2Manually: put the files in place

~/.claude/skills/ssh-doctor/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/ssh-doctor/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about ssh-doctor

How to install ssh-doctor in Claude Code?

Run npx skills add steipete/agent-scripts --skill ssh-doctor -a claude-code in your terminal. Alternatively, add the skill directly to ~/.claude/skills/ssh-doctor/SKILL.md.

What does ssh-doctor do?

It diagnoses SSH server issues on macOS. The skill checks loopback reachability, inspects sshd_config parameters, checks firewall state, and clears dead sessions.

How does ssh-doctor resolve launchd inetd process limits?

It checks launchctl print system/com.openssh.sshd for high copy counts and locates lingering sshd-session processes. The skill terminates stranded instances with TERM so launchd can spawn new connections.

Source text

SKILL.md · MIT
---
name: ssh-doctor
description: "SSH triage: Remote Login, launchd sshd, pre-auth closes, stale sessions."
---

# SSH Doctor

Use when SSH connects then closes before auth, Remote Login seems advertised but unusable, or local/remote Mac SSH needs diagnosis.

## Rules

- Do not print secrets, tokens, full env, or broad secret grep output.
- Validate locally first: loopback failure means server-side sshd/launchd/config; loopback success plus remote failure means network/firewall/filter/listen path.
- Report suspicious config lines before changing `/etc/ssh/sshd_config`.
- Prefer non-interactive SSH:

```bash
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'hostname; id -un'
```

## Baseline

```bash
hostname; id -un; sw_vers
ipconfig getifaddr en0
ipconfig getifaddr en1 2>/dev/null || true
ipconfig getifaddr en7 2>/dev/null || true
sudo systemsetup -getremotelogin
sudo systemsetup -setremotelogin on
sudo launchctl print system/com.openssh.sshd 2>&1 | head -80
sudo launchctl kickstart -k system/com.openssh.sshd
sudo lsof -nP -iTCP:22 -sTCP:LISTEN
nc -vz 127.0.0.1 22
ssh -4 -F /dev/null -o RequestTTY=no -o RemoteCommand=none [email protected] 'hostname; id -un'
```

Use `BatchMode=yes` only when password fallback would hang or prompt.

## Config

```bash
sudo sshd -T 2>&1 | egrep -i '^(allowusers|denyusers|allowgroups|denygroups|listenaddress|maxstartups|logingracetime|usepam|passwordauthentication|pubkeyauthentication|authenticationmethods)'
sudo egrep -n '^[[:space:]]*(AllowUsers|DenyUsers|AllowGroups|DenyGroups|Match|MaxStartups|LoginGraceTime|ListenAddress|AuthenticationMethods|UsePAM|PasswordAuthentication|PubkeyAuthentication)\b' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/* 2>/dev/null || true
```

Suspicious:

- `DenyUsers` matching target user
- restrictive `AllowUsers` / `AllowGroups`
- `Match` block accidentally applying
- tiny `MaxStartups`
- tiny `LoginGraceTime`
- `ListenAddress` missing target interface

## Logs

```bash
sudo log show --last 30m --predicate 'process == "sshd" OR process == "launchd"' --style compact | tail -160
```

Important Mac symptom:

- client: `kex_exchange_identification: Connection closed by remote host`
- server log: `Could not create new instance of inetd service: 67: Too many processes`
- `launchctl print system/com.openssh.sshd`: high `copy count`
- many `sshd-session: USER` processes parented by PID 1

This means launchd accepted TCP but refused to spawn more sshd inetd copies.

## Stale sshd-session Fix

Inspect first:

```bash
sudo launchctl print system/com.openssh.sshd 2>&1 | egrep 'active count|copy count|state =|last exit code|runs ='
ps -axo pid,ppid,uid,user,state,lstart,etime,comm,args | awk '/sshd-session:/ && !/awk/ {print}'
sudo lsof -nP -c sshd-session -iTCP 2>/dev/null | head -120
```

If stale sessions are clearly stranded and blocking new SSH, terminate by selected command-line match:

```bash
ps -axo pid=,args= | awk '/sshd-session: / && !/awk/ {print $1}' | xargs sudo kill -TERM
sleep 2
ps -axo pid=,args= | awk '/sshd-session: / && !/awk/ {print}'
```

If `TERM` leaves blockers, re-check ownership and active shells before using `KILL`.

## Firewall

Only after loopback works but remote fails:

```bash
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep -i ssh -A2 -B2 || true
sudo pfctl -sr 2>/dev/null | head -80
sudo pfctl -si 2>/dev/null | head -80
```

Also check listen address and target interface:

```bash
ifconfig | awk '/^[a-z0-9]+:/{iface=$1; sub(":","",iface)} iface ~ /^en[0-9]+$/ && /inet / {print iface, $2}'
sudo lsof -nP -iTCP:22 -sTCP:LISTEN
```

## OP Profile Block

If asked to ensure `~/.profile` has a Codex-managed `OP_SERVICE_ACCOUNT_TOKEN` copied from another host:

- verify exact variable/markers without printing value
- copy only the matching line/block
- redirect through a `chmod 600` temp file
- never echo the token

Presence check:

```bash
awk 'BEGIN{b=0;e=0;x=0} /BEGIN Codex-managed OP_SERVICE_ACCOUNT_TOKEN/ {b=1} /END Codex-managed OP_SERVICE_ACCOUNT_TOKEN/ {e=1} /^[[:space:]]*(export[[:space:]]+)?OP_SERVICE_ACCOUNT_TOKEN=/ {x=1} END{print "marker_begin", b; print "marker_end", e; print "exact_var", x}' ~/.profile
```

Append from remote host:

```bash
tmpfile=$(mktemp /tmp/codex-op-token.XXXXXX)
chmod 600 "$tmpfile"
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'awk '\''/^[[:space:]]*(export[[:space:]]+)?OP_SERVICE_ACCOUNT_TOKEN=/ {print; exit}'\'' ~/.profile' > "$tmpfile"
if [ -s "$tmpfile" ]; then
  {
    printf '\n# BEGIN Codex-managed OP_SERVICE_ACCOUNT_TOKEN\n'
    sed -n '1p' "$tmpfile"
    printf '# END Codex-managed OP_SERVICE_ACCOUNT_TOKEN\n'
  } >> ~/.profile
fi
rm -f "$tmpfile"
```

## Closeout

Report:

- root cause
- exact commands changed
- validation output, redacted as needed
- whether remote should retry

© steipete · MIT · steipete/agent-scripts

Similar skills

All skills for DevOps and infrastructure →

From the same set20

The whole set →
browser-use browser-use — a skill to control your real Chrome profile with saved logins and extensions. Routes through the Codex plugin when available, then OpenClaw extension over mcporter, and falls back to direct DevTools attachment if needed. CX Codex +1 278installs github-deep-review github-deep-review — a skill for in-depth GitHub issue and PR review. Reads code, traces the root cause, proposes the best fix, and identifies what must be verified before merge. CX Codex +1 275installs native-app-performance CLI skill for analyzing native app performance via xctrace and Time Profiler. Records execution traces, extracts samples, symbolicates stack frames, and identifies bottlenecks without opening Instruments. CX Codex +1 251installs instruments-profiling The instruments-profiling skill guides macOS and iOS profiling with Instruments and xctrace, from trace capture to stack export. Use it when a native app has a slow path. CX Codex +1 242installs domain-dns-ops The domain-dns-ops skill guides domain, Cloudflare zone, and redirect work. Use it when setting up a domain and checking DNS or HTTPS behavior. CX Codex +1 192installs discord-clawd discord-clawd — a skill to send questions to a Discord-backed agent via OpenClaw relay. Not for archive search—use it to communicate directly with a live session. CX Codex +1 122installs openclaw-relay openclaw-relay is a Claude Code skill that routes prompts and messages to OpenClaw sessions via local acpx or SSH, resolving targets from named aliases in config/session_aliases.json. CX Codex +1 120installs mac-maintenance mac-maintenance automates macOS maintenance by upgrading Homebrew packages, pulling clean git repositories, and emptying the Trash. CX Codex +1 117installs

Project sponsors

Companies that keep this analytics open