Conch

English · 简体中文

Conch is an SSH client written in Rust. A single r-shell binary manages saved connections, runs remote commands, opens an interactive shell, transfers files over SFTP, and prints a quick system snapshot.

It also ships an optional MCP server, so AI assistants (Cursor, Claude, and other MCP clients) can work on your servers through one persistent SSH session instead of spawning a fresh ssh process on every step.

There's a desktop app too — a Flutter UI on top of the same Rust core — with a tabbed terminal, file browser, and live monitoring.

Screenshots

Related MCP server: Simple SSH MCP Server

Contents

• Screenshots

• Features

• Install

• Quick start

• Commands

• MCP server

• Authentication

• Configuration

• Security

• Development

• Project layout

• License

Features

The same binary runs on macOS, Linux, and Windows. exec, shell, upload, and download work against any POSIX host; ls and stats expect a Linux host (they rely on GNU ls and /proc).

Install

Desktop app

Prebuilt desktop builds are on the releases page. The runtime is bundled, so there's nothing else to install.

The builds aren't code-signed yet. On macOS, right-click Conch.app → Open the first time; on Windows, choose More info → Run anyway if SmartScreen warns.

CLI

On macOS, mount the DMG and copy the binary onto your PATH:

sudo cp /Volumes/Conch/r-shell /usr/local/bin/r-shell
sudo chmod +x /usr/local/bin/r-shell
xattr -dr com.apple.quarantine /usr/local/bin/r-shell   # clear Gatekeeper quarantine
r-shell --version

On Windows, run the installer (it adds r-shell to your PATH) and open a new terminal.

From source

You need Rust and Cargo (rustup.rs). No OpenSSL or libssh is required — Conch uses the pure-Rust russh stack.

git clone https://github.com/MageGojo/conch.git
cd conch
cargo build --release --manifest-path cli/Cargo.toml
sudo install -m 0755 cli/target/release/r-shell /usr/local/bin/r-shell

Or run it straight from Cargo without installing:

cargo run --manifest-path cli/Cargo.toml -- <command> [options]

Quick start

# save a connection
r-shell connections add --name prod --host 203.0.113.10 --username deploy \
  --auth publickey --key-path ~/.ssh/id_ed25519

# use it
r-shell connections list
r-shell exec -c prod -- uptime
r-shell shell -c prod
r-shell upload   -c prod ./app.tar.gz /tmp/app.tar.gz
r-shell download -c prod /tmp/app.tar.gz ./app-copy.tar.gz

Every command that talks to a host takes a target: either a saved connection (-c <id|name>) or inline details. If a password is needed but not given, you're prompted for it (input isn't echoed).

Common target flags (exec, shell, ls, upload, download, stats):

Commands

Run r-shell --help or r-shell <command> --help for the full list of options.

connections

Saved connections live in a local workspace.json (see Configuration).

r-shell connections list [--json]

r-shell connections add \
  --name prod --host 203.0.113.10 --username deploy --port 22 \
  --auth publickey --key-path ~/.ssh/id_ed25519 \
  --folder Work --description "Production web server"

r-shell connections update <id> --port 2222 --folder Staging
r-shell connections remove <id>

Required flags: --name, --host, --username. --auth is password or publickey (default password); --port defaults to 22; --folder defaults to All Connections. update takes a connection id plus any of the same flags.

exec

Runs one command and prints its output. Everything after -- is sent verbatim.

r-shell exec -c prod -- uname -a
r-shell exec -c prod -- "ls -la /var/www && df -h"
r-shell exec --host 203.0.113.10 --user deploy -- systemctl status nginx

shell

A full interactive PTY in raw mode (vim, htop, less, …). Press Ctrl-] to force-quit the local loop if a session hangs.

r-shell shell -c prod

ls

r-shell ls -c prod /var/log
r-shell ls -c prod /var/log --json
r-shell ls -c prod              # defaults to the home directory

Columns: kind (DIR/FILE/LNK), permissions, size, modified time, name. (Linux hosts.)

upload / download

Single-file transfers over SFTP.

r-shell upload   -c prod ./local.tar.gz /tmp/remote.tar.gz
r-shell download -c prod /tmp/remote.log ./local.log

stats

Takes two quick samples and prints a snapshot (Linux hosts; relies on /proc).

r-shell stats -c prod

OS:      Linux 6.1.0
Uptime:  12d 4h 31m
CPU:     7.4%  (8 cores, load 0.42)
Memory:  61.2%  (4.9/7.8 GB)
Disk:    40.0%  (3.8/9.5 GB)
Network: down 1.5 KB/s  up 320 B/s

mcp

Starts the local MCP server (see below).

r-shell mcp
# Conch MCP server listening on http://127.0.0.1:9123/mcp

MCP server

r-shell mcp starts a local Model Context Protocol server over Streamable HTTP, bound to 127.0.0.1 only. Point an MCP client at http://127.0.0.1:9123/mcp:

{
  "mcpServers": {
    "r-shell": {
      "url": "http://127.0.0.1:9123/mcp"
    }
  }
}

For Cursor this goes in ~/.cursor/mcp.json. Claude Desktop and other clients add the same URL as a Streamable HTTP server, then restart.

The server keeps one SSH session alive across calls, so an assistant can run commands and read or write files without reconnecting each time. Sessions live in memory only, for as long as r-shell mcp is running.

Session tools:

Connection tools (operate on workspace.json):

Credentials are never returned — list calls only expose booleans such as has_password. The endpoint requires a loopback Host header (and a loopback Origin, if one is present); cross-origin and DNS-rebound requests get 403.

Authentication

• Password — --auth password with --password, or omit it to be prompted at connect time.

• Public key — --auth publickey with --key-path (and --passphrase for an encrypted key). Paths starting with ~/ are expanded.

Host keys are verified against ~/.ssh/known_hosts on a trust-on-first-use basis. The first connection records the key; later connections must match. A mismatch aborts the connection (a possible man-in-the-middle) until you remove the offending line from known_hosts. --insecure skips the check entirely — use it only for throwaway or local test hosts.

Configuration

Saved connections are stored as JSON:

On Unix the file and its directory are created with owner-only permissions (0600 / 0700).

Security

• Host keys are verified against known_hosts (trust-on-first-use); a changed key aborts the connection unless --insecure is passed.

• Passwords, private keys, and passphrases are never printed or returned by MCP calls — list responses only expose has_password / has_private_key_path.

• Password prompts don't echo input.

• workspace.json is owner-only on Unix.

• The MCP server binds to localhost and rejects non-loopback Host/Origin (defeating DNS rebinding and cross-origin access).

Development

The root package.json is a thin wrapper around Cargo:

pnpm dev      # cargo run -- --help
pnpm check    # cargo check
pnpm test     # cargo test
pnpm build    # cargo build
pnpm fmt      # cargo fmt

Or call Cargo directly with --manifest-path cli/Cargo.toml. Version bumps go through pnpm version:patch|minor|major, which update package.json, cli/Cargo.toml, cli/Cargo.lock, and CHANGELOG.md.

Project layout

conch/
├── cli/         # r-shell: the CLI + MCP server (Rust)
├── core/        # shared SSH / MCP core library
├── desktop/     # desktop app (Flutter UI + Rust core)
├── packaging/   # macOS .dmg and Windows installer scripts
├── scripts/     # version-bump helpers
└── .github/     # CI: tests and release builds

License

MIT — see LICENSE. Maintained by the team at ApiZero. Issues and pull requests are welcome on GitHub.