I was just VibeCoding and suddenly thought: Why can't I just let my agent deploy code to the server for me?
So, I built OctSSH.
OctSSH is an MCP server that gives LLMs safe, controllable, and stateful access to shell environments.
By default (stdio mode), OctSSH only connects to machines already configured in your local ssh_config for passwordless login.
Tip
So... what makes OctSSH special?
OctSSH provides a complete set of async tools to prevent LLMs from timing out on long-running tasks:
| Tool | Description |
|---|---|
exec(machine, command, confirm_code?) |
Run short commands synchronously |
sudo-exec(machine, command, confirm_code?) |
Run synchronously as root (sudo -n) |
exec-async(machine, command, confirm_code?) |
Run long tasks in background (screen) |
exec-async-sudo(...) |
Run background tasks as root |
write-stdin(session_id, data, append_newline?) |
Write to stdin of a running async task |
get-result(session_id, lines?) |
Inspect async task output |
grep-result(session_id, pattern, ...) |
Search task logs |
cancel(session_id) |
Terminate a task |
sleep(time) |
Pause (useful for polling) |
Note: In HTTP Serve mode, these tools operate directly on the local machine, and the
machineparameter is omitted.
OctSSH features a Virtual Mode and Confirm Code verification flow:
We don't want AI to become a world-ending terminator, so we designed Virtual Mode.
When the AI attempts the following, OctSSH will not execute immediately, but instead returns a confirm_code:
- 📁 File Overwrite: Uploading to a path that already exists.
- 💀 High-Risk Commands:
rm -rfand similar "delete everything" commands. - 🔍 Regex Blocklist: Custom sensitive patterns defined in config.
Execution Flow Example:
- AI calls
exec("web", "rm -rf /var/www/html") - 🛑 OctSSH intercepts: Recursive delete detected -> Returns
confirm_code: a1b2c3+ file impact preview. - 👤 User reviews and tells AI: "Confirm execution".
- ✅ AI calls
exec("web", "rm -rf /var/www/html", "a1b2c3")-> Actually executes.
npm install -g @aliyahzombie/octssh
octssh initRuns locally and controls remote machines via SSH (reads ~/.ssh/config):
octsshInstall this on the target server. It exposes the server to LLMs via a secure HTTP interface. In this mode, OctSSH controls the local machine directly (no outbound SSH).
octssh serve- Default Listen:
127.0.0.1:8787(Override viaOCTSSH_SERVE_HOST/OCTSSH_SERVE_PORT) - Auth: Prints a random key on startup. Clients must send header
X-OctSSH-Key: <key>.- Set fixed key:
export OCTSSH_SERVE_KEY="my-secret"
- Set fixed key:
- Tool Changes: Tools run on this machine.
machineparameter is omitted. SSH transfer tools (upload/download) are disabled.
To avoid tool name collisions when you run multiple OctSSH instances, you can prefix all exposed tools:
export OCTSSH_TOOL_PREFIX="us1_"Example: list becomes us1_list.
write-stdin lets you send input to a running exec-async session.
Typical flow:
- Start a long-running command that reads stdin (via
exec-async) - Send data with
write-stdin(session_id, data) - Poll output with
get-result(session_id)
Notes:
- Default
append_newlineistrue. - Max payload is 64KiB per call.
- This is a streaming stdin: EOF is not sent. If the program exits on EOF, cancel the session instead.
- If you set
OCTSSH_TOOL_PREFIX, tool names are prefixed too (e.g.us1_write-stdin).
Add to your MCP client config:
{
"mcpServers": {
"octssh": {
"command": "octssh",
"args": []
}
}
}claude mcp add octssh -- octssh{
"mcp": {
"octssh": {
"type": "local",
"command": "octssh",
"args": [],
"enabled": true
}
}
}Or:
opencode mcp add octssh --command octsshCaution
This project connects to real servers (or executes on the local machine). Please carefully review LLM operations. Using this project means you agree that the developer is not responsible for any accidental damage.