OctSSH

中文 README

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.

<img src="logo.png" width="200" />

OctSSH is an MCP server that gives LLMs safe, controllable, and stateful access to shell environments.

Note

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?

Async Support

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 machine parameter is omitted.

Security Design

OctSSH features a Virtual Mode and Confirm Code verification flow:

🔒 Safety Mechanism: Virtual Mode

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 -rf and similar "delete everything" commands.
• 🔍 Regex Blocklist: Custom sensitive patterns defined in config.

Execution Flow Example:

1. AI calls exec("web", "rm -rf /var/www/html")
2. 🛑 OctSSH intercepts: Recursive delete detected -> Returns confirm_code: a1b2c3 + file impact preview.
3. 👤 User reviews and tells AI: "Confirm execution".
4. ✅ AI calls exec("web", "rm -rf /var/www/html", "a1b2c3") -> Actually executes.

Quick Start

Installation

npm install -g @aliyahzombie/octssh
octssh init

Usage Modes

1. Default Client Mode (stdio)

Runs locally and controls remote machines via SSH (reads ~/.ssh/config):

octssh

2. Streamable HTTP Server Mode (Local Control)

Install 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 via OCTSSH_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"
• Tool Changes: Tools run on this machine. machine parameter is omitted. SSH transfer tools (upload/download) are disabled.

Windows notes (serve mode)

On Windows, OctSSH serve will auto-select a local shell in this order:

1. sh (if available, e.g. Git-Bash/MSYS)
2. pwsh
3. powershell
4. cmd

Override with:

set OCTSSH_SHELL=powershell

Tool Prefix (optional)

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 (async interactive input)

write-stdin lets you send input to a running exec-async session.

Typical flow:

1. Start a long-running command that reads stdin (via exec-async)
2. Send data with write-stdin(session_id, data)
3. Poll output with get-result(session_id)

Notes:

• Default append_newline is true.
• 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).

MCP Client Configuration

General (stdio)

Add to your MCP client config:

{
  "mcpServers": {
    "octssh": {
      "command": "octssh",
      "args": []
    }
  }
}

Claude Code CLI

claude mcp add octssh -- octssh

OpenCode CLI

{
  "mcp": {
    "octssh": {
      "type": "local",
      "command": "octssh",
      "args": [],
      "enabled": true
    }
  }
}

Or:

opencode mcp add octssh --command octssh

[!CAUTION] 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.