npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ssh-fleet-mcp-server

v0.2.2

Published

MCP server that manages a fleet of SSH hosts: pooled connections and host-routed exec/tmux tools.

Readme

ssh-fleet-mcp-server

License NPM Version

ssh-fleet-mcp-server is a Model Context Protocol (MCP) server that manages a fleet of SSH hosts behind a pooled connection layer. LLMs and MCP clients get a single server that can route exec and tmux_* commands to any configured host by name — no separate server process per host required.

Built on somamcp and the shared @ssh-mcp/core package (pool, tmux builders, auth resolution).

Contents

Quick Start

  1. Add the server to your MCP client with no --config — see Client Setup.
  2. Ask your LLM to call fleet_setup. On first start the server wrote a commented starter config; fleet_setup says where.
  3. Uncomment an example host in that file, restart the server, and ask your LLM to list hosts or run commands.

First Run

When no --config flag or SSH_FLEET_CONFIG is given and ~/.config/ssh-fleet/fleet.toml doesn't exist, the server writes a starter config there (mode 0600, folder 0700) and starts with zero hosts. The file is all comments, with example blocks for a password host, a key host, a read-only policy and a CA; remove the leading # from a block's lines to use it. Edits take effect on restart (in Claude Code, /mcp and reconnect).

  • Only the default path is created. A --config or SSH_FLEET_CONFIG path that doesn't exist fails startup, so a typo can't give you a healthy-looking server with no hosts.
  • fleet_setup says what's missing: an unset password_env variable, a host's last connection error, or a new CA's line to add on hosts.
  • A misconfigured host doesn't stop the server. A key file that can't be read, an unset key_env, or agent = true without SSH_AUTH_SOCK (Claude Desktop doesn't pass it) fails that host's calls with the reason, and fleet_setup shows it from the first start.
  • A CA key_file that doesn't exist is created (ssh-keygen, ed25519, 0600). This keeps the key on disk; use key_cmd or key_env to keep it off disk instead. A typo in key_file creates a new CA that no host trusts, so check fleet_setup after any CA change.
  • One client per config in CA mode. A second server on the same config fails on the runtime_dir lock before it can explain itself, and Claude Desktop hides stderr. Give each client its own config with its own runtime_dir.
  • Don't list the hub machine as a fleet host when its CA is a key_file. An agent with exec there could read the key or use the server's private agent and sign its own certificates.
  • Two clients starting at once can race to create the same CA key; the loser fails to load it, and a restart fixes it.

Config Discovery

The server looks for its fleet configuration in this order:

  1. --config=<path> CLI flag — explicit path wins.
  2. SSH_FLEET_CONFIG environment variable — useful in Docker / systemd.
  3. Default location: ~/.config/ssh-fleet/fleet.toml.

If the default config is missing, the server creates it (see First Run). If any other config file cannot be read, or a config contains validation errors, the server logs the problem and exits immediately (fail-fast). No host is connected until an MCP tool call is received (lazy connect via the pool).

Fleet Config Schema

The fleet config is a TOML file with four top-level sections.

[defaults] (optional)

Default values applied to every host that does not override them.

| Key | Type | Default | Description | | -------------- | ------ | --------- | --------------------------------------------------- | | port | int | 22 | SSH port. | | user | string | OS user | SSH username. Falls back to the OS user if omitted. | | tmux_session | string | "agent" | Default tmux session name for tmux_* tools. |

[pool] (optional)

Controls the shared per-host connection pool. Each key below that is set must be a whole number from 1 to 2147483647, or startup fails; for the _ms keys that limit is about 24.8 days. There is no value that turns a timeout off.

| Key | Type | Default | Description | | --------------------- | ---- | --------- | --------------------------------------------------------------------------------------------------- | | max_per_host | int | 2 | Maximum concurrent SSH connections per host. | | idle_timeout_ms | int | 60000 | Idle connection eviction interval (ms). | | acquire_timeout_ms | int | 30000 | How long to wait for a pool slot before failing a tool call (ms). | | exec_timeout_ms | int | 600000 | How long exec and the tmux_* tools wait for a command when the call gives no timeout_ms (ms). | | max_exec_timeout_ms | int | 3600000 | The most an exec call's timeout_ms may ask for; a larger value is lowered to it (ms). |

[audit] (optional)

Where the audit log is written. See Audit Log.

| Key | Type | Default | Description | | ------ | ------ | -------------------------------------- | ------------------------------------------------------------------- | | path | string | ~/.local/state/ssh-fleet/audit.jsonl | Audit log file (supports ~ and $VAR). Created with mode 0600. |

[defaults.policy] / [hosts.policy] (optional)

Per-host rules checked before every tool call. See Policy. A key in a host's [hosts.policy] replaces the same key from [defaults.policy]; lists are replaced, not merged.

| Key | Type | Built-in default | Description | | ---------------- | -------- | ---------------- | ----------------------------------------------------------------------------------------- | | mode | string | "readwrite" | "readonly", "readwrite" or "deny". | | tmux | string | "open" | "approve" or "open"; gates tmux_send / tmux_keys on a readwrite host. | | allow | string[] | — | readonly only: regexes a whole exec command must match. | | needs_approval | string[] | — | readwrite only: regexes that, matching anywhere in an exec command, require approval. | | agents | string[] | — | Agents allowed on this host. claude matches claude and every claude@<instance>. |

An empty list means "not set": allow = [] is how a host drops an allow list it would otherwise inherit. With no policy anywhere, every call is allowed, as before policy existed.

[[hosts]] (zero or more)

With none, the server starts and fleet_setup says what to add.

Each [[hosts]] entry defines a remote machine. Host names must be unique and may contain only letters, digits, hyphens, and underscores.

| Key | Type | Required | Description | | -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------ | | name | string | yes | Logical name used as the host param in tool calls. | | host | string | yes | Hostname or IP address. | | port | int | no | Overrides [defaults].port. | | user | string | no | Overrides [defaults].user. | | tmux_session | string | no | Overrides [defaults].tmux_session. | | log_output | bool | no | Add a 1024-character excerpt of exec output to the audit log. Off by default because output can contain secrets. | | key | string | no* | Path to private SSH key (supports ~ and $VAR). | | key_env | string | no* | Name of env var holding the private key PEM. | | agent | bool | no* | true to use SSH_AUTH_SOCK (ssh-agent / 1Password / Bitwarden). | | password_env | string | no* | Name of env var holding the SSH password. |

*Exactly one auth field is required per host. See Auth Modes.

Auth Modes

Each host must specify exactly one authentication method:

| Mode | Field | How it works | | ------------ | -------------- | ---------------------------------------------------------------------------------------- | | Key file | key | Path to a PEM private key; ~ and $VAR are expanded at startup. | | Key from env | key_env | Name of an env var holding the PEM (injected by envpkt, Vault, Doppler). | | SSH agent | agent = true | Delegates to SSH_AUTH_SOCK — the server never sees the private key. | | Password env | password_env | Name of an env var holding the password; read once at startup. | | CA | ca | Names a [[cas]] entry; connects with a 10-minute certificate. See CA Mode. |

Secrets-by-Reference Rule

Inline password and private_key fields are rejected at parse time. The parser will refuse to start if you write:

# WRONG — fails validation
[[hosts]]
name = "bad"
host = "example.com"
password = "hunter2"

Use password_env pointing at an environment variable instead. This keeps secrets out of the config file and out of source control.

Tools

All tools except hosts_list and fleet_setup require a host parameter — the logical name of a configured fleet host (from [[hosts]].name). An unknown name raises an error immediately, before any SSH attempt.

A failed call is an error result the model can read, labelled with an errorCategory and, where they help, suggestions:

| errorCategory | When | Hint | | --------------- | --------------------------------------------------------- | ------------------------------------------------ | | auth | The host's policy denied the call. | Use what the policy allows, or ask the operator. | | not_found | No host by that name. | Call hosts_list. | | timeout | Every pooled connection to the host is busy. | Try again, or raise [pool].max_per_host. | | timeout | exec ran past its timeout (message: timed out after). | Run it in tmux, or pass a larger timeout_ms. | | timeout | A tmux_* command ran past [pool].exec_timeout_ms. | Try again, or raise it. | | execution | The connection failed (message starts [<host>]). | Call fleet_setup. | | execution | The command exited non-zero, or tmux reported an error. | None: the message carries the output. | | validation | A bad tmux argument: session name, key, or empty keys. | None: the message names the argument. | | internal | The audit log can't be written, so every call is refused. | Check [audit].path. | | internal | A bug in the server (a TypeError or RangeError). | None: report it. |

The server also has somamcp's info tool. It reports the name, version and build: the short commit it was built from (with -dirty when the tree had uncommitted changes), the branch and the build date. Use it to tell which build a hub runs.

hosts_list

List configured fleet hosts and their live connection-pool status.

Parameters: none.

Returns a JSON array of { name, state, inFlight } objects, where inFlight is the count of currently active connections to that host. state is one of:

  • "connected": a pooled connection is open and running a command.
  • "idle": a pooled connection is open and waiting.
  • "disconnected": no open connection. This is normal: hosts connect on their first call and close after idle_timeout_ms.
  • "error": no open connection, and the last call failed for a connection reason: refused, auth, or a busy pool's acquire_timeout_ms. The row adds last_error: { message, at }, and stays error until the host's next successful call.

A CA host shows one row under its own name until its first call, then one row per agent, named <host> (<agent>). If a host you added to the config is missing, the server started before the edit; fleet_setup says so.

fleet_setup

Show setup state and what to do next. Read-only: it never writes config or keys. Audited like hosts_list.

Parameters: none.

Returns JSON:

  • config: { path, created_this_start, changed_since_start }. The server reads fleet.toml once, at start. When the file on disk differs, config adds hosts_on_disk (or errors_on_disk, if the new file doesn't parse), and the first next step says to reconnect the server.
  • next_steps: what to do, in order: reconnect after a config edit (or fix the edited file's errors), add a host, set a missing password_env variable, add a new CA's line on hosts, and each host's last connection error.
  • hosts: per host, name, address (user@host:port), auth (password_env, key, key_env, agent or ca), connections (the hosts_list rows for it), and when they apply password_env with env_set (never the value), ca, principal, last_error { message, at }, and enroll_line.
  • cas: per CA, name, key_source (key_cmd, key_env or key_file; a key_cmd string is never shown), key_file, created_this_start, public_key and enroll_line (cert-authority,principals="…" <public key>).
  • audit_log, and in CA mode runtime_dir and known_hosts.

exec

Run a one-shot shell command on a fleet host over SSH.

| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------------------------------------------------------------------- | | host | string | yes | Configured host name. | | command | string | yes | Shell command to execute. | | timeout_ms | int | no | How long to wait (ms). Defaults to [pool].exec_timeout_ms, capped at [pool].max_exec_timeout_ms. |

Returns stdout. If the command also wrote to stderr, the stderr text follows under a [stderr] line, so warnings stay visible. A non-zero exit raises a UserError with the host name, exit code, and stderr, then stdout under a [stdout] line (either one alone when the other is empty). Exit code 0 always succeeds, even with stderr: many tools, such as systemctl, warn on stderr and exit 0. A command a signal ended (an OOM kill, kill -9) fails as 128 plus the signal number, with the name: exit 137 (signal KILL); the audit result line records signal beside code. On a ca host, OpenSSH's ssh reports a signal as plain exit 255, with no name. If the connection drops before the command finishes, the call fails with exit 255 (no exit status: channel closed) and the audit line records no_exit_status.

When the timeout runs out, the call fails with label timeout and the output so far: [<host>] timed out after 5000 ms: then stderr and stdout as above. The server stops waiting, sends the command KILL, and closes the channel. OpenSSH 7.9 and later deliver the signal; an older server ignores it, and the command keeps running until it next writes output. On a ca host, the server kills its local ssh client instead. That closes the channel but sends no signal, so the command stops only when it next writes output, as on an older server. The audit result line records timed_out_ms. The tmux_* tools wait [pool].exec_timeout_ms too.

Long jobs

A package upgrade, an image pull, or a backup can outlive one call, and an upgrade of the network layer under the connection (a VPN daemon, tailscaled) can drop the SSH session partway. Don't hold the call open. Start the job somewhere that survives the session, then check on it:

  1. tmux (preferred). tmux_send starts the job in a session on the host, and tmux_read shows its progress. The tmux server outlives the SSH session, so a dropped connection doesn't stop the job, and every send and read goes through policy and the audit log. It needs tmux on the host and a readwrite host whose policy leaves tmux at its default, "open": a readonly host refuses tmux input, and tmux = "approve" refuses it until approval exists.
  2. A detached process. On Linux, systemd-run --user --unit=upgrade-1 <command>, then systemctl --user status upgrade-1 or journalctl --user -u upgrade-1. On macOS, nohup <command> > /tmp/job.log 2>&1 & echo $! > /tmp/job.pid, then tail /tmp/job.log and kill -0 $(cat /tmp/job.pid). Start it with exec; check it with exec. Both use > or &, which a readonly policy rejects, so they need a readwrite host.

tmux_list

List tmux sessions on a fleet host. Returns a JSON array of session names, empty when no tmux server is running.

The tmux_* tools find tmux on the host's PATH, then in /opt/homebrew/bin and /usr/local/bin. That covers Homebrew on macOS, where a command sent over SSH gets only /usr/bin:/bin:/usr/sbin:/sbin. exec gets no such help: to run other Homebrew tools through it, load Homebrew's PATH in the host's ~/.zshenv.

They need a POSIX login shell, such as sh, bash or zsh, for the SSH account: sshd runs each command with it, and csh, tcsh and fish can't parse the commands. On such an account the tools fail and say so; exec is unaffected.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | --------------------- | | host | string | yes | Configured host name. |

tmux_send

Type text into a persistent tmux session on a fleet host. Creates the session if it does not exist.

| Parameter | Type | Required | Description | | --------- | ------- | -------- | ---------------------------------------------------------- | | host | string | yes | Configured host name. | | session | string | no | tmux session name (defaults to the host's tmux_session). | | input | string | yes | Text to type. | | submit | boolean | no | Press Enter after the text (default true). |

tmux_read

Capture the recent pane transcript of a tmux session on a fleet host.

| Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------------------- | | host | string | yes | Configured host name. | | session | string | no | tmux session name (defaults to the host's tmux_session). | | lines | int | no | Lines of scrollback (default 200; capped at 2000). |

tmux_keys

Send control/special keys (e.g. C-c) to a tmux session on a fleet host.

| Parameter | Type | Required | Description | | --------- | -------- | -------- | ---------------------------------------------------------- | | host | string | yes | Configured host name. | | session | string | no | tmux session name (defaults to the host's tmux_session). | | keys | string[] | yes | tmux key names, e.g. ["C-c"]. |

Policy

Each host-routed call is checked against its host's policy before it runs. hosts_list is never gated. The first matching rule decides:

  1. mode = "deny" — every tool on the host is denied.
  2. agents — if set and the calling agent isn't listed, the call is denied.
  3. tmux_list / tmux_read — allowed.
  4. tmux_send / tmux_keys — denied on a readonly host. On a readwrite host, tmux = "approve" requires approval and tmux = "open" allows. (allow and needs_approval can't gate tmux input: it can be split across calls.)
  5. exec on a readonly host — denied if the command contains a newline, carriage return, NUL or any of ; & | $ ` ( ) < > { } \ ' " * ? [ ~. Otherwise it must match some allow pattern as a whole (each pattern is wrapped as ^(?:…)$, no regex flags).
  6. exec on a readwrite host — requires approval if any needs_approval pattern matches anywhere in the command; otherwise allowed.

A denied call returns [<host>] denied by rule <rule>: <reason> to the agent and is logged with decision: "deny", rule and reason (see Audit Log).

Read before relying on it:

  • readonly is an allowlist, on purpose. There is no deny-list mode: deny-lists over shell text are trivially bypassed (r''m, $(…), sh -c). Spell out the characters a pattern allows, as in systemctl status [\[email protected]]+. Never use ., .* or \S in an allow pattern.
  • Write patterns as TOML literal strings. In a TOML double-quoted string \w is an invalid escape and fails startup. Use single quotes, 'systemctl status [\[email protected]]+', or double each backslash, "systemctl status [\\[email protected]]+". Patterns have no regex flags, so group an emoji or other astral character before repeating it: (?:😀)+.
  • Avoid nested quantifiers such as (\w+ ?)+ in allow and needs_approval. Patterns run synchronously, and one that backtracks badly can stall the whole server, not just one host. As a backstop, a command longer than 4096 characters is denied whenever policy patterns would be matched against it (any readonly host, or a readwrite host with needs_approval).
  • needs_approval is a tripwire, not a boundary. It catches honest mistakes; an agent trying to get around it can.
  • Approval isn't available yet, so anything that requires approval is denied. tmux = "approve" is the recommended setting once approval ships; the built-in default is "open".
  • Agent identity isn't available yet — every agent is "unknown" — so a host with agents set denies every call. The server prints a warning naming each such host at startup.
  • Over stdio, nothing is governed. A stdio server runs as the agent's own OS user, so the agent can bypass every rule here with its own shell and credentials. Governance needs the hub to run as a separate user that alone holds the SSH credentials.
  • The real boundary is the remote account the host entry logs in as, and its sudoers.

Sample restricted account

On a readonly host, log in as a dedicated account that can only read. For example, a fleet-ro user with no sudo except this /etc/sudoers.d/fleet-ro:

fleet-ro ALL=(root) NOPASSWD: /usr/bin/systemctl status *, /usr/bin/journalctl -u *
  • In sudoers, * matches any trailing arguments, so these entries allow systemctl status and journalctl -u with anything after them. Keep the list to commands that are harmless with any arguments.
  • The allow patterns must then include the sudo prefix, for example sudo systemctl status [\[email protected]]+ and sudo journalctl -u [\[email protected]]+ -n \d+.

Audit Log

Every tool call that runs writes two JSON lines to the audit log (see [audit]): a decision line before the call runs and a result line after it, sharing id. A call that hangs or crashes the server is still on record. A call denied by policy never runs, so it writes only its decision line.

{"ts":"2026-10-17T14:02:11.000Z","id":"5f0c…","event":"decision","agent":"unknown","tool":"exec","host":"box-a","command":"systemctl status cups","decision":"allow","rule":"box-a:readonly"}
{"ts":"2026-10-17T14:02:11.412Z","id":"5f0c…","event":"result","agent":"unknown","tool":"exec","host":"box-a","status":"ok","ms":412,"code":0,"stdout_bytes":1830,"stderr_bytes":0}

What each tool records:

| Tool | Decision line | Result line | | ------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | hosts_list | (no host) | — | | exec | command, timeout_ms if set | code, stdout_bytes, stderr_bytes; signal, timed_out_ms or no_exit_status when they apply; plus excerpts when the host sets log_output | | tmux_list | — | — | | tmux_send | session, input, submit | — | | tmux_read | session, lines | stdout_bytes (never the transcript) | | tmux_keys | session, keys | — |

  • Sizes, not contents. Output can contain secrets, so only byte counts are logged. A host with log_output = true also gets stdout_excerpt / stderr_excerpt (first 1024 characters) on exec.
  • status says whether the call finished, not whether the command succeeded.
    • It is "ok" when the call finished. That includes an exec whose command exited non-zero or was ended by a signal, so grep with no match doesn't read as a fault. Check code for those.
    • It is "error" with an error message when the call didn't finish: an unknown host, a command stopped at its timeout (timed_out_ms), or a connection that dropped before the exit status arrived (no_exit_status). A timeout or dropped connection keeps its code and sizes.
    • On a ca host, OpenSSH's ssh reports a dropped connection as plain exit 255, which can't be told apart from a command's own exit. That line reads "ok" with code 255.
  • Finding failures. This filter finds every call that ran and failed, whether the command failed or the call never finished: jq -c 'select(.event == "result" and (.status == "error" or (.code // 0) != 0))' audit.jsonl. A denied call has no result line, so find those with select(.decision == "deny").
  • decision is "allow" or "deny". rule names the policy rule that decided, qualified by host (box-a:readonly); it is absent when no policy applies (hosts_list, an unknown host). A deny line also has a reason.
  • agent is "unknown" until per-agent identity lands.
  • client says which client made the call. It is SSH_FLEET_CLIENT from the server's environment if set (put it in the client's MCP config env block, for example claude-code@mac-mini), else the name/version the client sent in its MCP handshake, for example claude-code/2.1.0. Either way it has control characters removed and is at most 64 characters, and the field is left out when neither exists. It tells clients apart in the log. A client can claim any name, so it isn't a verified identity, and policy's agents never matches it.
  • No unaudited calls. The server refuses to start if the log can't be written, and a call whose audit line can't be written fails.
  • The file is reopened for every line, so a deleted or rotated log is recreated at mode 0600. A symlink at the audit path is refused rather than followed.
  • Append-only is best effort — the server's user can truncate its own file. For stronger integrity, set the OS append-only flag from an administrator account: sudo chattr +a <file> (Linux) or sudo chflags uappend <file> (macOS). Rotation is out of scope.

CA Mode

With ca = "<name>", a host trusts one SSH certificate authority instead of a per-host key. The server holds the CA in a private ssh-agent, signs a 10-minute certificate for each connection, and connects with the system ssh binary (OpenSSH: ssh, ssh-keygen, ssh-agent, ssh-add). Agents never hold an SSH credential.

runtime_dir = "/run/ssh-fleet"                 # optional; sockets and ephemeral keys
known_hosts = "~/.local/state/ssh-fleet/known_hosts"  # optional; the hub's own

[[cas]]
name = "home"
key_cmd = "security find-generic-password -s ssh-fleet-ca -w"   # or key_env / key_file
principal = "fleet"                  # default
source_address = "100.64.0.1/32"     # optional: certificates only work from here

[[hosts]]
name = "box-a"
host = "10.0.0.11"
user = "fleet-ro"
ca = "home"

| [[cas]] key | Description | | ---------------- | ----------------------------------------------------------------------------------------------------------- | | name | Letters, digits, hyphen, underscore, checked when the config loads. Hosts refer to it with ca = "<name>". | | key_cmd | A shell command whose output is the CA private key (a keychain or password-manager read). | | key_env | An env var holding the CA private key; removed from the environment once read. | | key_file | A key file: a regular file (not a symlink), mode 0600 or stricter, owned by the hub user. | | principal | The principal certificates name (default "fleet"). A host may override it with its own principal. | | source_address | An IPv4 or IPv6 CIDR; certificates are only accepted from those addresses. |

Exactly one of key_cmd, key_env or key_file. Inline keys are rejected.

runtime_dir (default $XDG_RUNTIME_DIR/ssh-fleet, else ~/.local/state/ssh-fleet/run) must be a directory of its own: startup refuses one that holds files the server didn't create, and shutdown deletes only the server's own files. One server per runtime_dir: a second server started on the same one (say Claude Desktop and Claude Code with the same fleet config) fails startup with runtime_dir … is in use by pid N and leaves the first running. Give each its own config with its own runtime_dir.

Enrolling a host

Add one line to a root-owned authorized-keys file for the account the host entry logs in as:

cert-authority,principals="fleet" ssh-ed25519 AAAA… ssh-fleet-ca

Use AuthorizedKeysFile /etc/ssh/authorized_keys/%u in sshd_config, or TrustedUserCAKeys plus AuthorizedPrincipalsFile. A user-writable ~/.ssh/authorized_keys defeats the point: any agent with write access could append its own key and bypass the hub for good. The principal is just a label the certificate must carry; what limits access is which account's file holds the CA line, and that account's rights.

The CA key at boot

The server loads the CA at startup with no interactive unlock, so it restarts unattended. Keep the canonical copy in your password manager, and give the server a working copy only it can read:

  • macOS: key_cmd reading the hub user's keychain (security find-generic-password -s ssh-fleet-ca -w).
  • Linux: a 0600 key_file owned by the hub user. If the file doesn't exist, the server creates it on first start, and fleet_setup shows the line to add on hosts.
  • Either: key_cmd against a non-interactive secrets service (op read …, Bitwarden Secrets Manager, Infisical), or key_env.

The key reaches ssh-add on stdin; the server never writes it to disk except when it creates a missing key_file. A key_cmd must finish within 30 seconds and runs without a terminal, so a command that would prompt fails startup, naming the CA, instead of hanging.

What a certificate allows

  • 10 minutes, key ID = the agent's name, the configured principal, and an increasing serial.
  • No port forwarding, agent forwarding, X11 forwarding or ~/.ssh/rc; optional source_address.
  • Each (agent, host) pair gets its own master connection and its own certificate, so one agent never rides another's session, and the host's sshd log names the agent (Accepted certificate ID "claude").
  • A master is retired when its certificate expires; calls in flight finish, and the next call gets a fresh certificate.
  • Host keys are trusted on first use, recorded in the hub's own known_hosts.
  • ~/.ssh/config is ignored (-F /dev/null), so nothing in it can add an identity. ProxyJump isn't supported yet.
  • At startup the server mints and discards one certificate per CA, so a CA it can't sign with, or a certificate option ssh-keygen rejects, stops startup instead of failing every call.
  • A master to a host that stops answering drops within about 45 seconds (SSH keepalives).
  • After a crash, the next start stops the old agent and any masters it left running, and clears stale sockets and keys from runtime_dir. It stops a process only if ps shows it is ssh-agent or ssh on a socket in that runtime_dir, so a reused process ID never takes down anything else.

Revoking access

  • Stop the server: no new certificates; outstanding ones expire within 10 minutes and their masters are retired.
  • Cut access now: remove the CA line from the host.
  • Separate trust domains (fleets run by different parties): use separate [[cas]] entries, so each can be revoked alone.

Enforcement

CA mode governs access only if the server is the only path. Run it as its own OS user (a launchd or systemd service), so agent processes running as you can't read the CA key, the certificates or the audit log, and don't give your interactive user unrestricted sudo. Over stdio, as the same user as the agent, nothing is governed.

Example Config

[defaults]
port = 22
user = "agent"
tmux_session = "agent"

[pool]
max_per_host = 2
idle_timeout_ms = 60000

[[hosts]]
name = "box-a"
host = "10.0.0.11"
user = "fleet-ro"
key = "~/.ssh/id_ed25519"
  [hosts.policy]
  mode = "readonly"
  allow = ['sudo systemctl status [\[email protected]]+', 'sudo journalctl -u [\[email protected]]+ -n \d+', 'df -h', 'uptime']

[[hosts]]
name = "box-b"
host = "build.example.com"
agent = true

[[hosts]]
name = "box-c"
host = "192.168.1.50"
password_env = "BOXC_SSH_PASSWORD"   # value read from the env var, never inline

Client Setup

.mcp.json / claude_desktop_config.json

With no --config, the server uses ~/.config/ssh-fleet/fleet.toml and creates it on first start (see First Run). Put each host's password_env / key_env variables in the env block:

{
  "mcpServers": {
    "ssh-fleet": {
      "command": "node",
      "args": ["packages/orchestrator/dist/index.js"],
      "env": { "MINI_SSH_PASSWORD": "…" }
    }
  }
}

Or via npx, with an explicit config (which must already exist). Pin the version in the arguments, for the reason under Installing on a hub:

{
  "mcpServers": {
    "ssh-fleet": {
      "command": "npx",
      "args": ["-y", "ssh-fleet-mcp-server@<version>", "--config=/path/to/fleet.toml"]
    }
  }
}

Set SSH_FLEET_CONFIG in your environment (or the MCP client's env block) if you prefer the env-var discovery path over an explicit --config flag. In CA mode, give each client its own config and runtime_dir.

These examples run from a clone of this repo. For an installed server on another machine, see Running on Several Machines.

Running on Several Machines

A machine that runs this server and logs in to fleet hosts is a hub. Each hub keeps its own config (~/.config/ssh-fleet/fleet.toml), its own audit log, and its own credentials.

Where to register the server

Register it in the MCP config of a folder you start admin sessions from (for example ~/admin/.mcp.json), not in your user-wide config. Only sessions started there get fleet access. Claude Code asks you to approve a folder's servers the first time; until then claude mcp list shows them as pending approval.

In CA mode, two Claude Code sessions started in that folder load the same config, so the second session's server fails on the runtime_dir lock. Start the second one from another folder, or with claude --strict-mcp-config --mcp-config <file>, where <file> starts the server with a --config that has its own runtime_dir. Without --strict-mcp-config, the folder's .mcp.json still loads and its server still collides.

Use full paths. An MCP client launched from a GUI may not have Homebrew's PATH, and the package's #!/usr/bin/env node needs node on it. On an Apple silicon Mac with Homebrew (/usr/local/bin on Intel):

{
  "mcpServers": {
    "ssh-fleet": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/opt/homebrew/bin/ssh-fleet-mcp-server"]
    }
  }
}

Installing on a hub

Pin a version, and update on purpose: this server holds SSH credentials, so a new version shouldn't arrive on its own at the next restart. In a terminal on the hub (not ssh <hub> npm …, which gets the bare PATH described under macOS hosts and won't find Homebrew's or nvm's npm):

npm install -g ssh-fleet-mcp-server@<version>

npm uninstall -g ssh-fleet-mcp-server removes it.

To try a build that isn't released yet, pack it on a machine with this repo, copy the tarball to the hub, and install that the same way:

cd packages/orchestrator && pnpm build && pnpm pack          # → ssh-fleet-mcp-server-<version>.tgz
scp ssh-fleet-mcp-server-<version>.tgz <hub>:/tmp/
npm install -g /tmp/ssh-fleet-mcp-server-<version>.tgz       # on the hub

Credentials: one key per hub and host

Start with a separate key for each hub and host it logs in to. Leave it without a passphrase (-N ""): the server can't unlock one.

ssh-keygen -t ed25519 -N "" -C ssh-fleet@<hub> -f ~/.ssh/fleet_<host>   # on the hub

On the host, add the public key to the fleet account's ~/.ssh/authorized_keys, limited to the hub's address (a CIDR such as 10.0.0.0/24 if it changes) and with forwarding and terminals turned off. The server runs every tool on a plain exec channel, so it needs none of them:

from="<hub address>",no-port-forwarding,no-agent-forwarding,no-X11-forwarding,no-pty ssh-ed25519 AAAA… ssh-fleet@<hub>

In CA mode the certificate carries the same limits, so hosts need no such options.

Then key = "~/.ssh/fleet_<host>" in the hub's config, and ssh-fleet-mcp-server check on the hub. To cut off one hub, delete its line on each host; the other hubs keep working. The cost grows with the fleet: three hubs and five hosts is fifteen lines to add and remove.

Why not one key in a password manager

A password manager's SSH agent (1Password, Bitwarden) can serve one key to every hub through agent = true, but it fits a fleet server badly:

  • It needs the app running and unlocked, and it may ask you to approve each use. On a hub that restarts unattended, nobody is there to approve.
  • Claude Desktop doesn't pass SSH_AUTH_SOCK. An agent = true host there fails every call, and fleet_setup says why, unless you set SSH_AUTH_SOCK in the server's env block.
  • One shared key widens the damage. A compromised hub exposes every host, and revoking the key cuts off every hub.

Centralizing: CA mode

To manage access in one place, use CA Mode instead:

  • One CA key; each host trusts it once, with one cert-authority line in a root-owned authorized-keys file. Each hub signs itself a 10-minute certificate per connection.
  • Adding a hub doesn't touch the hosts. The new hub gets a working copy of the CA key.
  • Keep the canonical copy in your password manager, and give each hub its working copy once (see The CA key at boot). No hub needs the password manager unlocked at runtime.
  • The config can be shared. When every host uses ca, fleet.toml holds no secrets. A dotfiles manager can sync one copy to every hub if every hub reads the CA key the same way: key_env, or a key_file at the same path under ~. Two traps:
    • Place the hub's working CA copy before the config arrives. Otherwise the server finds no key_file, creates a new CA that no host trusts, and every connection fails.
    • Widen source_address to cover every hub, or certificates signed on the other hubs are refused.

Two limits: enrolling a host needs root once, and only one server can run per runtime_dir, so two sessions on one hub need separate configs.

macOS hosts

  • Turn on Remote Login (System Settings → General → Sharing).
  • tmux_* tools find Homebrew's tmux without setup (see tmux_list).
  • exec gets a bare PATH (/usr/bin:/bin:/usr/sbin:/sbin): a command sent over SSH runs in a non-login shell, and zsh, the macOS default, doesn't read ~/.zprofile then. For Homebrew tools through exec, add eval "$(/opt/homebrew/bin/brew shellenv)" (/usr/local/bin/brew on Intel) to the fleet account's ~/.zshenv.

Command Line

check

ssh-fleet-mcp-server check [--config=<path>]

Connects to every host from a terminal and runs true, printing one line per host as it finishes, then a line per CA, even when there are no hosts yet: its enrollment line, or the hint that its key_file is missing. Exits 0 when every host passes (or there are none), 1 otherwise. Each line names the account it connects as: the host's user, else the hub's $USER, else root.

ok    mini [email protected]:22   password_env 212 ms
FAIL  nas  [email protected]:22 ca           Permission denied (publickey).
CA home: cert-authority,principals="fleet" ssh-ed25519 AAAA… ssh-fleet-ca-home
  • It never creates a config or key. A CA whose key_file is missing fails its hosts with a hint, without connecting.
  • It skips policy, so it can run true even on a readonly or deny host. Each probe is audited with tool: "check", agent: "operator", bypass: "policy". It isn't reachable over MCP.
  • It uses its own runtime dir (<runtime_dir>-check), so it works while the server is running. Once the check has started probing hosts, Ctrl-C or SIGTERM (as from timeout 30 ssh-fleet-mcp-server check) stops its CA agent before it exits.
  • A ForceCommand account that doesn't allow true fails the check.
  • Run it with the same environment the MCP client gives the server, so password_env and key_env variables are set.

Development

All tooling is delegated to ts-builds. Run from the repo root:

pnpm -r validate      # validate all packages (core, connector, orchestrator)

Or from this package directory:

pnpm validate         # format → lint → typecheck → test → build
pnpm test             # vitest run
pnpm test:watch       # vitest watch mode
pnpm build            # production build to dist/

Integration tests (requiring a live SSH server on localhost) are automatically skipped when the host is not reachable — CI remains green in environments without SSH available.