English | 中文

A lightweight, zero-dependency shell execution server with SSE streaming and end-to-end encryption. Expose a shell on any device — Linux server, Termux (Android), Windows — and control it securely over the network. Ships with a companion MCP binary for Claude Desktop integration.

• End-to-end encryption — X25519 ECDH key exchange + AES-256-GCM, authenticated by a pre-shared API key
• HMAC request signing — proves API key possession without transmitting it
• Anti-replay protection — time-bucketed nonce tracking with ±5 min clock skew tolerance
• SSE streaming — stdout and stderr delivered line-by-line
• Rate limiting — per-IP token bucket (20 req/s sustained, burst 40)
• Single binary — zero dependencies, statically linked, ~8 MiB
• Cross-platform — Linux (arm64/amd64), Windows (amd64), Termux on Android
• System service — installs as systemd (Linux), runit (Termux), or nssm (Windows)
• MCP support — separate conch-mcp binary bridges Claude Desktop (stdio/JSON-RPC) to a remote Conch server

Linux / Termux:

curl -fsSL https://raw.githubusercontent.com/newo-ether/conch/main/scripts/install.sh | sudo bash

Windows (PowerShell as Administrator):

Set-ExecutionPolicy Bypass -Scope Process -Force; irm https://raw.githubusercontent.com/newo-ether/conch/main/scripts/install.ps1 | iex

The script auto-detects your platform, downloads the pre-built binary from GitHub Releases, generates an API key, and registers a system service.

Custom options:

# Linux: custom port and key
sudo ./scripts/install.sh --port 14216 --api-key "your-key"

# Termux (no root needed)
./scripts/install.sh --port 8080

# Windows: custom port and key
.\scripts\install.ps1 -Port 14216 -ApiKey "your-key"

git clone git@github.com:newo-ether/conch.git
cd conch

# Server
go build -o conch .
./conch  # CONCH_API_KEY=... required

# MCP binary
go build -o conch-mcp ./cmd/mcp/

make all              # server: linux-arm64, linux-amd64, windows-amd64
make mcp-all          # MCP:    linux-arm64, linux-amd64, windows-amd64

Binaries land in build/.

export CONCH_API_KEY="your-secret-key"
./conch

# Or with the installer
sudo ./scripts/install.sh --api-key "your-secret-key"

Test:

curl -s http://localhost:14216/health
# {"status":"ok"}

On Termux, commands run in /data/data/com.termux/files/home. On Windows, workdir defaults to %USERPROFILE%.

No auth. Returns {"status":"ok"}.

Returns the server's persistent X25519 public key, signed with HMAC-SHA256(key, nonce|public_key) to prevent MITM substitution:

{
  "public_key": "<base64url 32B>",
  "nonce": "<base64url 12B>",
  "signature": "<64 hex chars>"
}

Clients verify this signature before trusting the key.

Execute a shell command. Every request carries an HMAC signature that proves API key possession.

Headers:

Request body: Encrypted with AES-256-GCM using a key derived via ECDH(client_ephemeral_priv, server_pub) → HKDF-SHA256.

After decryption, the body is JSON:

{
  "command": "ls -la /tmp",
  "timeout_ms": 10000,
  "workdir": "/tmp"
}

Response: text/event-stream with encrypted data payloads (each data: line is base64url-encoded AES-256-GCM ciphertext):

event: line
data: <base64url ciphertext>

event: result
data: <base64url ciphertext>

Error responses: 401 for all auth failures (signature mismatch, clock skew, replayed nonce, missing headers). 400 for decryption errors. 405 for wrong method.

Client                           Server
  |                                 |
  |---- GET /public-key ----------->|  (verify HMAC signature)
  |<--- {pubKey, nonce, sig} ------|
  |                                 |
  |  ECDH(eph_priv, server_pub) -> AES key
  |  Encrypt command JSON
  |  HMAC sign all request fields
  |                                 |
  |---- POST /execute ------------->|  (verify HMAC, check nonce, decrypt)
  |<--- SSE stream (encrypted) ----|

The conch-mcp binary exposes a shell_execute tool to Claude Desktop via the Model Context Protocol.

{
  "mcpServers": {
    "conch": {
      "command": "/path/to/conch-mcp-windows-amd64.exe",
      "env": {
        "CONCH_DEVICES": "{\"pi\":{\"url\":\"http://192.168.1.100:14216\",\"key\":\"xxx\",\"description\":\"Raspberry Pi 4\"},\"laptop\":{\"url\":\"http://192.168.1.200:14216\",\"key\":\"yyy\",\"description\":\"Windows laptop\"}}"
      }
    }
  }
}

{
  "mcpServers": {
    "conch": {
      "command": "/path/to/conch-mcp-windows-amd64.exe",
      "env": {
        "CONCH_SERVER_URL": "http://<host>:14216",
        "CONCH_API_KEY": "<your-api-key>"
      }
    }
  }
}

shell_execute — Execute a command on the remote Conch server.

MIT — see LICENSE.