Rackhand
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Rackhand — SSH MCP server for AI agents
Rackhand is a self-hosted, remote MCP server. It gives Claude, ChatGPT, Cursor or any AI agent a real shell, real files and background jobs on your own VPS, and on every machine that VPS can reach over SSH. Machines it cannot reach, behind NAT or a firewall, open a tunnel to it instead.
AI client (Claude, ChatGPT, Kimi, Cursor, your own agent)
│ HTTPS, one secret URL
▼
Rackhand on your VPS ──SSH/SFTP──▶ any host in hosts.jsonRead this first. The connector URL contains a secret, and that secret is the only authentication. Whoever has the URL has a root shell on the machine, and on every host listed in
hosts.json. Treat it like a root password: do not paste it into chats, issues, screenshots or logs. On AWS EC2, anyone with the URL can also use the instance's IAM role - check what that role allows before you install (see Security).
18 tools, one install command, no account, no database. Version 1.9.0.
Formerly ssh-mcp. The service, paths and settings keep that name, so existing installs upgrade in place.
Quick start
On a fresh Linux VPS (x86-64 or arm64, systemd, public IP, ports 80 and 443 open), as root:
curl -fsSL https://raw.githubusercontent.com/Matrixx0070/rackhand/main/install.sh | sudo bashThe installer:
installs Node.js 22 if Node 20+ is missing,
puts the server in
/opt/ssh-mcp,writes a random secret to
/etc/ssh-mcp.env,starts the systemd service
ssh-mcp(it listens on127.0.0.1only),puts Caddy in front of it with an automatic HTTPS certificate for
https://<your-ip-with-dashes>.sslip.io(no domain needed),checks that the server answers and prints your connector URL:
https://203-0-113-10.sslip.io/mcp/<64 hex characters>Options (environment variables in front of bash): DOMAIN=mcp.example.com to use your own domain,
NO_CADDY=1 if you already run a reverse proxy, PUBLIC_IP=... to skip the IP lookup. The top of
install.sh lists all of them. If something already listens on port 443, the installer leaves it
alone and tells you which proxy rule to add.
Run the same command again to upgrade: hosts.json and the secret are kept, the old server.ts is backed up,
and it is put back automatically if the new one does not answer.
Related MCP server: ssh-mcp
Connect your AI client
The server speaks standard MCP over Streamable HTTP, so any client that supports remote MCP servers works. Menus move around; the names below are the ones in use when this was written.
Client | How |
Claude (web, desktop, mobile) | Settings → Connectors → Add custom connector → paste the URL |
Claude Code |
|
ChatGPT | Settings → Apps & Connectors → Advanced → turn on Developer mode, add a connector with the URL, authentication: No authentication. Which plans may use write-capable custom connectors is decided by OpenAI and has changed over time. |
Kimi Code CLI |
|
Cursor, VS Code, Gemini CLI, others | a remote/HTTP MCP server entry, e.g. |
Your own agent | any MCP SDK: Streamable HTTP client pointed at the URL |
Then ask the assistant something like "run uname -a on my VPS".
Tools
Every tool takes host: a name from list_hosts. local is the VPS the server runs on; every other host is
reached over SSH and behaves the same way.
Fewer round trips
Every tool call from a model costs seconds (round trip + thinking); the work on the host takes milliseconds. So the fastest way to work is to put more into one call.
Tool | Input | What it does |
|
| Runs several steps in ONE call, in order. Each op is exactly one of |
{"host": "local", "cwd": "/app", "ops": [
{"write": {"file_path": "/app/a.ts", "content": "..."}},
{"edit": {"file_path": "/app/b.ts", "old_string": "x", "new_string": "y"}},
{"bash": {"command": "npm test", "quiet": true}},
{"read": {"file_path": "/app/out.log", "limit": 50}}
]}=== [1/4] write /app/a.ts | ok | 0.00s ===
Wrote 12 bytes to local:/app/a.ts
=== [2/4] edit /app/b.ts | ok | 0.00s ===
...
=== [3/4] bash npm test | FAILED | 4.20s ===
...
[exit code: 1]
=== [4/4] read /app/out.log | skipped ===
=== batch: 2 ok, 1 failed, 1 skipped | 4.21s ===The server also sends short instructions at initialize (the INSTRUCTIONS constant in server.ts) that point
any model at batch, the files / edits arrays, ssh_exec_many, quiet and background jobs.
Shell and files
Same parameter names as the Bash / Read / Write / Edit tools many coding agents already know.
Tool | Input | What it does |
|
| Runs a command. stdout+stderr merged in order; a failure adds |
|
| Text as numbered lines ( |
|
| Creates or overwrites files, in parallel, over one connection. Parent directories are created. |
|
| Exact text replacement; |
Commands, jobs, code
Tool | Input | What it does |
|
| Runs a command; returns |
|
| Runs them concurrently; one block per id with exit code, stdout, stderr, duration. |
|
| Starts the command in the background and returns a |
|
| Job state, end of the log, block until exit, or stop it. |
|
| Lists jobs newest first: |
|
| Writes the code to a temp file, runs it, returns exit, stdout, stderr. |
| - | Lists the hosts in |
|
| Connects another server: tests the login, pins its host key, saves it (More hosts). |
|
| Plain file read (utf8/base64), write and directory listing. |
|
| Returns a time-limited URL and a one-line installer for the |
|
| Shows the audit log (below): what was run on the hosts, from any chat or client. |
Which one to use: batch for anything with more than one step; bash / read / write / edit for single steps;
ssh_exec_many for several independent commands; run_in_background + ssh_job for anything long; the bridge for
big, binary or many files.
The tripwire
A model can make the kind of mistake that has no undo. So a short list of commands is refused unless the call says
confirm: true (box exec -y on the bridge):
Refused without | Examples |
Recursive delete of |
|
Recursive |
|
Formatting or overwriting a disk |
|
Powering off or restarting the machine |
|
A fork bomb |
|
Error: Refused by the tripwire: recursive delete of "/etc". Nothing was run. This is on the short list of commands
that are rarely meant and hard to undo; if the user really wants it, send it again with confirm: true.Everything else runs without a question: rm -rf /opt/app/releases/old, rm -rf /var/lib/apt/lists/*,
find /var/log -name '*.gz' -delete, mkfs.ext4 disk.img, dd if=/dev/sda of=backup.img and echo "rm -rf /" are
none of its business. It looks inside sudo, bash -c '...', ssh host '...', $(...) and scripts fed to a shell as
a here-document, on every host and through every tool that runs a command.
It is a seat belt, not a lock. It reads the command text and never runs anything to find out, so it is easy to get
around on purpose (echo reboot | bash, a script file, a variable that expands to /). It does not make the
connector safe to hand to someone you do not trust, and it is not a substitute for backups. Refusals and confirmed
commands are in the audit log (tripwire / confirmed). TRIPWIRE=off in /etc/ssh-mcp.env turns it off.
More hosts
Ask the assistant: "add my server 203.0.113.10 as web-1, user deploy". That is the add_host tool:
The first call creates the connector's own SSH key (once, in
/var/lib/ssh-mcp/keys), tries to log in, and when the server does not know the key yet, answers with the one line to add to~/.ssh/authorized_keyson that server, and with the fingerprint of the host key the server presented.You add the line on the server (that is the only manual step) and check the fingerprint there:
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub.The second call logs in, runs a test command, pins the host key and saves the host. It works at once as
host: "web-1"in every tool.
Added host "web-1": deploy@203.0.113.10:22
Host key pinned: SHA256:... (ssh-ed25519)
Key exchange: mlkem768x25519-sha256 (post-quantum) - the connection is made by this machine's OpenSSH client, everything else runs inside it
Test: logged in as deploy on web-1A pinned host is only ever talked to if it presents that same key. add_host has no password option on purpose:
a password would have to pass through the model and the chat. It never overwrites an existing name unless told
replace: true, and keeps the previous file as hosts.json.bak.
By hand it is the same thing: /opt/ssh-mcp/hosts.json (see hosts.example.json) lists what the
server may reach. It is read on every call, so no restart is needed.
ssh-keygen -t ed25519 -N '' -f /root/.ssh/id_ed25519 # a key (once)
ssh-copy-id -i /root/.ssh/id_ed25519.pub deploy@203.0.113.10 # per target host
ssh-keyscan -t ed25519 203.0.113.10 2>/dev/null | ssh-keygen -lf - # -> SHA256:... for hostFingerprint{
"local": { "local": true },
"web-1": { "host": "203.0.113.10", "username": "deploy", "privateKeyPath": "/root/.ssh/id_ed25519",
"hostFingerprint": "SHA256:..." }
}Use keys. If a key has a passphrase, put it in an environment variable in /etc/ssh-mcp.env and name that variable
in passphraseEnv; never put a secret in hosts.json itself.
Post-quantum key exchange
Traffic that is recorded today can be decrypted later by whoever gets a large enough quantum computer, unless the key exchange that protected it was a post-quantum one. For the hosts it reaches over SSH, Rackhand uses one wherever the server has it:
add_hostfirst tries a connection made by this machine's OpenSSH client, restricted to the post-quantum key exchanges (mlkem768x25519-sha256from OpenSSH 9.9,sntrup761x25519-sha512from 9.0) and to the pinned host key. That connection only carries bytes to the server's own SSH port; the connector's commands, files and jobs run inside it. So no login and no data crosses the network under a classical key exchange, not even the first login. (The one thing that does is the first look at the server's host key, which is public.)The result says which it is, and the host is saved with
"pq": true.list_hostsshows(post-quantum key exchange), and the audit log marks each such call with(pq)and records the algorithm (kex).No silent downgrade. A host added this way never falls back to a classical connection by itself. If the server later stops offering post-quantum key exchange, or forwarding is switched off, calls fail and say why, until you decide:
"pq": falsefor that host inhosts.json, oradd_hostagain withreplace: true.When post-quantum is not possible,
add_hostsays why and adds the host as a classical one ("pq": false): the server's SSH is older than OpenSSH 9.0, it does not allow TCP forwarding for that login (AllowTcpForwarding, orno-port-forwardingon the key), or this machine has no OpenSSH client that can do it.For a host you wrote into
hosts.jsonyourself, add"pq": true. It needshostFingerprintand aprivateKeyPathwithout a passphrase. Hosts without the setting are connected to as before.Behind a port mapping (a container, a router), or when the server's SSH listens on one address only,
add_hostasks the server where its own SSH is and saves that aspqVia.PQ_SSH=requirein/etc/ssh-mcp.envrefuses every remote host that is not post-quantum, andadd_hostthen adds nothing else.PQ_SSH=offturns the feature off.
What it costs: making the connection takes two SSH handshakes instead of one (about 0.3 s with OpenSSH 9.6 on one
machine). It is then kept and shared: an unused connection stays open for 60 seconds, and up to four calls run
on one at the same time, so the calls that follow need no handshake at all. Measured that way, a call to a
post-quantum host took 48 ms, against 80 ms for a classical host, which connects anew every time. PQ_SSH_KEEP in
/etc/ssh-mcp.env sets the seconds; 0 makes a connection per call. A connection that died while it was not
used is replaced without the call failing, and a server that allows only one session per connection
(MaxSessions 1) gets a connection per overlapping call.
What it does not cover:
The other leg. Between your AI client and this server the protection is TLS. Caddy offers a post-quantum key exchange there (X25519MLKEM768) and uses it when the client asks for it; whether the client asks is the client's choice, and this server cannot force it.
Someone in the path while a host is added can make a server look as if it had no post-quantum key exchange. The host is then added as a classical one, and the result says so;
PQ_SSH=requirerefuses instead.Only the key exchange is post-quantum. Host keys and login keys are the usual ones: breaking those lets an attacker impersonate a server in the future, not read what was recorded in the past.
Machines the connector cannot reach: tunnels
A machine behind NAT or a firewall - a PC at home, a laptop, a server in a private network - can be a host too. It
is not connected to; it connects. Ask the assistant: "add my home PC as home-pc, user frank, it is behind NAT", which
is add_host with tunnel: true (and no host). The answer is one command to run on that machine, as root:
curl -fsSL https://<your-connector>/t/<link> | sudo bashThe link works once, within 30 minutes (curl -fsSL <link> shows the script without running it). The script
checks for an OpenSSH client with a post-quantum key exchange (OpenSSH 9.0 or newer), OpenSSL 1.1.1 or newer, curl, and an SSH server on the port given to
add_host(22 unless told otherwise),adds the connector's key to that user's
~/.ssh/authorized_keys,makes a key for the tunnel in
/etc/ssh-mcp-tunnel, and sends the connector that key and the machine's SSH host keys,installs the systemd service
ssh-mcp-tunnel, which keeps an SSH connection open to the connector over HTTPS (port 443) and opens it again when it drops,waits until the connector has logged in through it, and prints
connected: ....
From then on the machine is 127.0.0.1:<port> on the connector, with its host key pinned, and every tool works
with it. list_hosts tells whether its tunnel is open:
home-pc: frank@127.0.0.1:20200 (reverse tunnel: open, post-quantum key exchange mlkem768x25519-sha256)and a call while it is not open says so, instead of a bare "connection refused".
How it is locked down:
Nothing new has to be reachable, on either side. The tunnel comes in through the connector's HTTPS port (Caddy passes the HTTP upgrade on to the connector), and the machine only makes outgoing connections.
At the connector, a tunnel can do one thing. Each tunnel gets an
sshd -iof its own, with a configuration (/var/lib/ssh-mcp-tunnel/sshd_config) that allows a remote forward to the one port that tunnel's key is bound to (permitlisten) and nothing else: no shell and no command (MaxSessions 0), no forwarding into the connector's machine (AllowTcpForwarding remote,PermitOpen none), post-quantum key exchange only. It logs in as the accountsshmcp-tunnel, which is created on first use, without a password or a shell.Both ends are pinned. The connector's tunnel host key is written into the script (fetched over HTTPS) and pinned on the machine; the machine's SSH host key must be one of those it reported, and is pinned on the connector.
The tunnel's address on the connector is a secret of its own. An unknown address, a used-up link, another key, another port: nothing.
A machine that comes back on a new connection (after a reboot, or when its network changed) replaces the one it left open at once, instead of waiting until that one times out.
add_hostwithreplace: truehands the name to another machine; the old one keeps working until the new one is in, then its key and address stop working.
To undo it on the machine: systemctl disable --now ssh-mcp-tunnel; rm -r /etc/ssh-mcp-tunnel /etc/systemd/system/ssh-mcp-tunnel.service, and remove the connector's line from authorized_keys. On the
connector, remove the host from hosts.json: its key goes from the tunnel's authorized_keys at the next start or
add_host. Without root or systemd, SSHMCP_TUNNEL_FOREGROUND=1 keeps the tunnel in the foreground instead of a
service (SSHMCP_TUNNEL_DIR and SSHMCP_AUTHORIZED_KEYS say where its files and the connector's key go).
Settings, in /etc/ssh-mcp.env: TUNNEL=off turns tunnels off; TUNNEL_PORTS (20200-20999) are the ports they
get; TUNNEL_USER is the account they log in as; TUNNEL_DIR is where their sshd keeps its files.
The bridge and the box command
For an assistant that has its own sandbox shell: bridge returns https://<host>/b/<token>, and from that shell
curl -fsS '<url>/cli' -o /tmp/box && bash /tmp/box install
box exec [-t SEC] [-C DIR] [-y] [HOST] -- 'command' # merged output of any size, same exit code; "-" reads a script from stdin
box put ./file [HOST:]/remote/path [MODE] # one file, any size, binary-safe, all-or-nothing
box get [HOST:]/remote/path [./file|-]
box push ./dir [HOST:]/remote/dir [-x PATTERN] # whole tree as one tar.gz stream
box pull [HOST:]/remote/dir ./dir [-x PATTERN]
box call TOOL '{json}' # any of the 18 tools
box toolsEach command is one HTTPS request that does not pass through the model, so a script can do dozens of operations
in one tool call and run several at once with & or xargs -P. For scale, on one small cloud VM: 50 MB up in
about 8 s, a 4,300-file tree in under 4 s, one command in about 0.6 s.
An upload is renamed over its target only when every byte arrived; an existing file keeps its mode and owner.
A dropped connection stops the transfer on the host.
The token is
<expiry>.<HMAC of expiry with MCP_SECRET>: no state, valid until it expires, and it cannot mint another one. It grants the same access as the connector URL. The only way to revoke one early is a new secret.
Audit log
Every tool call and every bridge request is written to /var/lib/ssh-mcp/audit/audit.jsonl, readable only by the
user the service runs as. Ask the assistant "show me the audit log" (the audit tool), or read the file:
$ tail -f /var/lib/ssh-mcp/audit/audit.jsonl | jq -c .
{"t":"2026-11-18T15:30:01.120Z","id":"9f2c41aa","via":"mcp","ip":"203.0.113.5","ua":"Claude-User","tool":"bash","host":"local","what":"npm test","cwd":"/app"}
{"t":"2026-11-18T15:30:05.320Z","id":"9f2c41aa","ok":false,"exit":1,"ms":4200}Two lines per call. The first is written before the call runs, so a command that takes the server down with it is still on record; the second carries the result (
ok,exit,err,ms). They share anid.Who:
ipis the address your reverse proxy saw,uathe client's user agent,viaismcp(the connector URL) orbridge;tokties a bridge request to thebridgecall that created its URL.What: for commands the command itself; for file tools the paths and sizes. File contents are never logged. Each step of a
batchhas its own entry (batch: "<id>#2/4"). A call that reached its host over a post-quantum key exchange haskexin its result line.Masking: values that look like credentials (
password=...,--token ...,Authorization: Bearer ..., private keys, the connector's own secret and bridge tokens) are replaced with***before anything is written, and long commands are cut to 2000 characters. This is best effort: do not rely on it to keep secrets out of the log.Server events: every start of the server is logged, and if the file is removed, emptied or replaced, the next entry says so (
"event":"reset").Rotation: at 20 MB the file moves to
audit.jsonl.1(up to.5), so the log is bounded at about 120 MB.
Settings (in /etc/ssh-mcp.env, then restart): AUDIT_MAX_MB (20), AUDIT_KEEP (5), AUDIT_DIR, and
AUDIT_LOG=off to turn it off.
What it is not: requests with a wrong secret are not logged (use your proxy's access log for that), and the log lives on the machine it describes - whoever has the connector URL can also delete it. If it has to survive that, ship it elsewhere (any log forwarder can follow the file).
Operating it
Logs |
|
Restart |
|
New secret |
|
Upgrade | run the installer again |
Uninstall |
|
The service runs with KillMode=process and OOMPolicy=continue: restarting, crashing or an out-of-memory kill of
the connector does not take down the programs that were started through it.
State on the host: /var/lib/ssh-mcp/jobs (background job logs, not pruned), /var/lib/ssh-mcp/sessions (one
remembered working directory per bash session), /var/lib/ssh-mcp/out (full copies of oversized output, deleted
after 3 days), /var/lib/ssh-mcp/audit (the audit log), /var/lib/ssh-mcp/keys (the SSH key add_host uses).
For a careful upgrade of a busy server there is upgrade/deploy.sh: it swaps in
/opt/ssh-mcp/server.new.ts, checks the tool list, the audit log, the tripwire, a real batch call and the bridge, and rolls
back by itself.
upgrade/rehearse.sh rehearses that on a throwaway copy of the service first.
Security
The URL is the key. There is no login, no per-user permission and no allow-list of commands. Anything that can call the URL can run anything as the user the service runs as, which is root by default.
The server binds to
127.0.0.1; the reverse proxy is the only public entry, and only over HTTPS.Every host in
hosts.jsonis fully reachable by anything that can call the connector. Keep the list short and prefer a non-rootusernameon the targets.Connections to those hosts use post-quantum key exchange where the server has it, and a host added that way does not fall back. The leg from the AI client to this server is TLS, and how strong that is against a future quantum computer depends on the client.
Tunnels come in through the HTTPS port and can only pass the connector's connections on to the machine's own SSH server; their key exchange is post-quantum only.
Cloud credentials on the machine are in reach too. On AWS EC2 the instance's IAM role can be used by anyone with a shell, so anyone with the URL has that role's permissions. The installer prints a warning when it finds a role. Give the instance no role, or one with only the permissions the machine itself needs.
An AI model decides which commands to run. Review what it does, keep backups, and do not point it at a machine whose loss you cannot afford. The tripwire catches a few well-known accidents; it is not a permission system.
Optional hardening: restrict the proxy to your AI provider's published outbound IP ranges, use your own domain, rotate the secret, run the service as a less privileged user.
Found a security problem? Please report it privately (GitHub: Security → Report a vulnerability) rather than in a public issue.
Development
npm ci
npm run typecheck
npm test # 174 black-box tests over the HTTP endpoint, against "local", an in-process SSH server and a real sshdThe whole server is one file, server.ts, run with tsx; box.sh is the bridge client the
server hands out. Configuration is by environment variable: MCP_SECRET (required, 32+ characters), PORT (8787),
HOSTS_FILE (./hosts.json), JOBS_DIR (/var/lib/ssh-mcp/jobs), PUBLIC_URL (only if the proxy does not send
X-Forwarded-Host), the AUDIT_* settings above, TRIPWIRE=off, PQ_SSH (off or require), PQ_SSH_KEEP, and
TUNNEL, TUNNEL_PORTS, TUNNEL_USER and TUNNEL_DIR.
The fifteen post-quantum tests and the eight tunnel tests start a private sshd on a loopback port and read its
log, so they need the OpenSSH server and a client with a post-quantum key exchange (apt-get install openssh-server openssh-client), and the tunnel tests openssl and curl as well; without them they are skipped and say so.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants full SSH/SFTP remote operations — session management, command execution, interactive shells, file transfers, port forwarding, and system diagnostics.2MIT
- AlicenseAqualityCmaintenanceAn MCP server that gives AI agents SSH access to remote machines through your local OpenSSH client, enabling remote command execution, file transfer, persistent shell sessions, and port forwarding.17432 PyPI42MIT
- AlicenseAqualityBmaintenanceAn open MCP server that gives any AI agent SSH access to remote Linux/Unix machines — shell commands, file read/write, and SFTP transfers.1116 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceA self-hosted MCP server that gives AI agents controlled access to a machine: filesystem, shell, background processes, git, web fetching and persistent key-value memory.GPL 3.0