moesh

An SSH, SCP, and FRP replacement over outbound HTTP/1.1 Upgrade.

moesh gives operators an interactive terminal, secure file transfers, and reverse TCP port forwarding on remote machines behind strict NAT, egress-only firewalls, or cloud notebooks (Google Colab, Kaggle, Lambda Labs, RunPod).

The receiver is a blind socket pump — it pairs streams at the transport boundary, carries opaque ciphertext or raw TCP streams, and never holds a byte of plaintext terminal data or cryptographic keys.

1. Why moesh Exists

Standard tools like ssh and scp require the target machine to accept inbound connections. Machines behind strict NAT, ephemeral cloud notebooks, or corporate firewalls cannot open listening ports. Traditional reverse proxies often silently interleave or steal connections when multiple agents dial the same route.

moesh inverts the connection direction and enforces strict slot ownership:

1. Egress-Only Dialout: The remote machine (the agent) dials outbound over standard HTTP port 80 (HTTP/1.1 Upgrade) to a receiver located on the public network.
2. Explicit Lease & Conflict Detection (409 Conflict): Each shell host slot (host-<N>) and each public relay port (26420–26430) is leased exclusively to the active carrier. A second agent dialing an occupied host number or relay port receives HTTP/1.1 409 Conflict with a list of free ports/active hosts and exits cleanly (exit code 3) instead of hijacking existing traffic.
3. Control-Plane Status Probing (/__moesh/status): Any agent can query GET /__moesh/status (or pass --probe) over HTTP port 80 to discover which host slots and relay ports are free, occupied, or unavailable without probing data ports.
4. Single Fleet Master Key (MOESH_TUNNEL_MASTER): A single 32-byte master key deterministically derives both the per-host static keys (host-1, host-2, ...) and the operator static key via HKDF-SHA256. Any agent holding MOESH_TUNNEL_MASTER can expose or connect to any numbered host without manual public-key distribution.
5. Survivable PTY Sessions: Keystrokes, terminal resize events (SIGWINCH), and background processes attach to a persistent pseudo-terminal (PTY). Dropping Wi-Fi or disconnecting leaves the remote processes running; reconnecting re-attaches immediately to the active session.

2. Installation

Install moesh directly from PyPI into your environment or user profile:

# Using pip:
pip install moesh

# Or using uv (recommended for speed and isolation):
uv tool install moesh

# Or using pipx:
pipx install moesh

This installs five CLI tools:

• moesh: Interactive encrypted terminal client (connects to remote hosts).
• moecp: Transactional remote file copy client (scp replacement).
• moesh-tunnel: Remote host daemon exposing an interactive shell session.
• moesh-relay: Outbound reverse TCP port relay (exposes local services onto public receiver ports).
• moesh-bridge: Blind pairing broker (runs on the public receiver server).

You can also import moesh as a Python module:

import moesh
print(moesh.__version__)

3. Quick Start

Step 1: Generate a Fleet Master Key

On your local machine, run:

moesh --new-master

This prints a fresh 64-hex-character master secret. Keep this secret private.

Step 2: Probe the Receiver for Free Slots

Check what host slots and relay ports are available on your public receiver:

moesh-tunnel --probe --receiver receiver.example.com

Step 3: Start the Agent on the Remote Host

On the remote machine (cloud VM, container, or Colab/Kaggle notebook):

export MOESH_TUNNEL_RECEIVER="receiver.example.com"
export MOESH_TUNNEL_MASTER="<YOUR-64-HEX-MASTER-KEY>"
export MOESH_TUNNEL_HOST="auto"   # automatically claims the lowest free host-<N> slot

moesh-tunnel

The agent connects outbound to the receiver, switching protocols to moesh-tunnel-v2, and waits for an operator.

Step 4: Attach Interactive Shell (moesh)

On your local operator laptop:

export MOESH_SHELL_ADDR="receiver.example.com:44441"
export MOESH_TUNNEL_MASTER="<YOUR-64-HEX-MASTER-KEY>"

# Connect to host-1:
moesh -n 1

You get a full PTY shell with line discipline, color support, and signal forwarding. Dropping connection and reconnecting restores your session cleanly.

Step 5: Copy Files Securely (moecp)

Copy files and directory trees with resume capability and SHA-256 verification:

# Upload a file to host-1:
moecp ./weights.safetensors host-1:/models/

# Download a directory recursively preserving timestamps and permissions:
moecp -r -p host-1:/var/log/app ./local-logs/

Step 6: Expose a Local Service Port (moesh-relay)

Expose a local TCP service (e.g., vLLM or web server running on 127.0.0.1:8000) onto a public receiver port:

# Auto-claim the lowest free port in 26420..26430:
moesh-relay --receiver receiver.example.com --remote-port auto --target 127.0.0.1:8000

External clients can now connect directly to http://receiver.example.com:<PORT>.

4. Architecture

Remote Target Host (VM / Container / Notebook)             Public Receiver Bridge                     Operator / Client Host
┌──────────────────────────────────────────────┐          ┌───────────────────────────────────┐      ┌─────────────────────────┐
│  A. Interactive Remote Shell                 │          │  nginx (TCP :80)                  │      │  moesh / moecp          │
│     moesh-tunnel                             │ HTTP/1.1 │    │ /__moesh/tunnel/*            │      │  (moesh -n <N>)         │
│     - Noise_XX Session                       │ Upgrade  │    │ /__relay/*                   │      │                         │
│     - HKDF Identity from MOESH_TUNNEL_MASTER │─────────▶│    ▼                              │      │  receiver:44441         │
│     - Exclusive lease per host-<N>           │Ciphertext│  moesh-bridge (Blind Pump)        │◀─────│  - Noise_XX Mutual Auth │
│     - Persistent PTY Shell Pool              │          │  - 0 plaintext, 0 keys held       │Cipher│  - Auto-reconnect loop  │
├──────────────────────────────────────────────┤          │  - 409 Conflict on duplicate slot │ text └─────────────────────────┘
│  B. Outbound Reverse TCP Relay               │          ├───────────────────────────────────┤      ┌─────────────────────────┐
│     moesh-relay (Zero external deps)         │ HTTP/1.1 │  Public Relay Ports (TCP)         │      │  Any TCP Consumer       │
│     - Dials /__relay/<port|auto|label>       │ Upgrade  │  - :26420 .. :26430               │      │  Connects to receiver   │
│     - Splices directly to local TCP target   │─────────▶│  - Exclusive lease per port/label │◀─────│  on bound relay port    │
│       (e.g. 127.0.0.1:8000)                  │Raw bytes │  - GET /__moesh/status inspection │ Raw  │  (26420..26430)         │
└──────────────────────────────────────────────┘          └───────────────────────────────────┘Bytes └─────────────────────────┘

5. Performance Characteristics (Measured)

6. Complete Documentation

7. License

moesh is open source software licensed under the Apache License, Version 2.0.