RMTE — AI Agent Gateway & Model Context Protocol (MCP) Guide

🔄 Architecture & Client Ecosystem

How RMTE connects AI Agents and Headless CLI alongside Web IDE and Terminal TUI viewers.

E2EE Gateway

Claude / Cursor 🤖

Local AI agent issues JSON-RPC tool calls (stdio) to local rmte mcp client.

stdio

JSON-RPC

Encrypted Relay 🌐

Routes sealed frames (my.rmte.biz.id or private). Commands, output and files are end-to-end encrypted.

WSS Outbound

AES-GCM

Target Host (Shell & Files) 💻

Runs --allow-exec. Fully cross-platform (Linux, macOS, and Windows hosts). Executes commands with a live read-only spectator view in tab [AI].

🛡️ Explicit Opt-In Security

The host machine must explicitly pass --allow-exec. Without this flag, all remote execution attempts are strictly rejected.

👁️ Read-Only Spectator Mode

Human viewers in the Web IDE can observe AI commands and outputs in real time, but keystroke injection into the AI PTY is locked to prevent prompt corruption.

🔒 AES-GCM 256-bit E2EE

Every tool invocation, file chunk, and terminal stream is encrypted locally using client-derived keys. The relay cannot snoop on your code or secrets.

⚡ Process Reaping & Safety

Clean process termination via cmd.Wait() and recursive process-tree termination on Windows prevent zombie processes. Commands run non-interactively. Host-level --buffer (default 1 MB) bounds file operations, while 25MB per-message limits protect against oversized JSON-RPC envelope panics.

⚡ 30-Second Quickstart Setup

Step-by-step setup to connect Claude Desktop, Cursor, or Antigravity to your remote workspace.

Instant Setup

Step 1: Start Host Session with Execution Allowed

On the target machine or container you wish to control, start RMTE with --allow-exec:

TERMINAL (TARGET HOST)

# Outbound share to public relay:
./rmte share --allow-exec

# Or run detached in the background with custom session credentials:
./rmte share --id="my-server" --pass="supersecret123" --allow-exec -q

Step 2: Configure Your AI Coding Assistant

RMTE supports credential ingestion via environment variables (RMTE_PASS, RMTE_ID, RMTE_SERVER), secure key files (--pass-file), or direct CLI flags. For maximum process table safety, use the env block or --pass-file:

Option A: Claude Desktop (Anthropic)

Add the RMTE server entry into your claude_desktop_config.json using the secure env block:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "rmte": {
      "command": "rmte",
      "args": ["mcp"],
      "env": {
        "RMTE_SERVER": "wss://my.rmte.biz.id/ws-rmte",
        "RMTE_ID": "my-server",
        "RMTE_PASS": "supersecret123"
      }
    }
  }
}

Option B: Claude Code CLI

Add RMTE directly into Claude Code using session environment variables (avoids argument exposure):

CLAUDE CODE CLI

# Add RMTE with credential in env:
RMTE_PASS="supersecret123" claude mcp add rmte -- rmte mcp --id="my-server"

Option C: Cursor IDE & VS Code (Roo Code / Cline)

In Cursor (Cursor Settings → Features → MCP) or VS Code MCP settings:

CURSOR / VS CODE MCP CONFIG

{
  "mcpServers": {
    "rmte": {
      "command": "rmte",
      "args": [
        "mcp",
        "--server-relay=wss://my.rmte.biz.id/ws-rmte",
        "--id=my-server",
        "--pass=supersecret123"
      ]
    }
  }
}

🛠️ The 7 Built-In MCP Tools

Full capability matrix exposed to AI agents over the Model Context Protocol (v2025-03-26 with Tool Annotations).

Tool Reference

rmte_exec ⚡

Executes a shell command on the host (POSIX PTY on Linux/macOS; native headless pipes with UTF-8 encoding on Windows). In synchronous mode (default), output is captured until completion and returned with duration and exit code. Spectators can watch live in the [AI] tab.

Arguments: cmd (string, req), background (bool, opt), tab_name (string, opt), timeout (int sec, opt)

rmte_read_file 📖

Reads the UTF-8 text content of a remote file. File size is bounded by the host's --buffer limit (default 1 MB, configurable on host via --buffer=<N>) to protect host memory.

Arguments: path (string, req)

rmte_write_file ✍️

Creates or overwrites a text file with new content on the remote host (bounded by host --buffer limit). Automatically registers the file in the Web File Explorer tree.

Arguments: path (string, req), content (string, req)

rmte_upload_file 📤

Uploads a local file from the AI agent's computer to the remote host workspace via encrypted binary frame channel (Tab ID 255, bounded by host --buffer).

Arguments: local_path (string, req), remote_path (string, req)

rmte_download_file 📥

Downloads a file from the remote host workspace directly to the AI agent's local filesystem (bounded by host --buffer).

Arguments: remote_path (string, req), local_path (string, req)

rmte_list_files 📂

Lists directory contents on the remote machine. Returns filenames, file sizes, and directory indicators (name, is_dir, size).

Arguments: path (string, opt - defaults to cwd)

rmte_get_info ℹ️

Retrieves system diagnostics from the remote host: Operating System (Linux, Darwin, Windows), CPU architecture, hostname, current working directory, process PID, and list of active terminal tabs.

Arguments: None (zero-argument probe)

💻 Headless Remote CLI Execution (rmte exec)

Run remote commands from local shell scripts, CI/CD runners, and cron jobs over E2EE.

Scripting Automation

rmte exec connects into an active RMTE host session, issues a command, waits for completion, prints the output cleanly to stdout/stderr, and exits with the exact exit status code returned by the remote process.

SYNCHRONOUS CLI EXECUTION

# Run tests remotely and propagate exit code:
./rmte exec --id="my-server" --pass="supersecret123" -- "go test -v ./..."
echo "Remote test status: $?"

Dedicated Background Services with `--bg` and `--tab-name`

To launch long-running web dev servers (Vite, Next.js, FastAPI) without blocking your local shell, specify --bg:

BACKGROUND TAB EXECUTION

# Spawns a dedicated "ViteDev" terminal tab on the host that runs continuously:
./rmte exec --id="my-server" --pass="supersecret123" --bg --tab-name="ViteDev" -- "npm run dev"

⚙️ Interactive MCP Config Generator

Customize your credentials below to generate ready-to-paste configurations for any AI assistant.

Live Generator

Target Session ID (--id)

Session Password (--pass)

Relay WebSocket URL

GENERATED CLAUDE DESKTOP CONFIG

❓ FAQ & Troubleshooting

Common questions regarding AI execution, sandboxing, and security boundaries.

Security & Tips

🔴 Error: "execution not allowed by host"

The remote host was started without execution permissions. Restart the host session with --allow-exec (or --enable-ai). This safety mechanism prevents viewers from running arbitrary code on unvetted hosts.

👥 Can human viewers in the Web IDE see what the AI is doing?

Yes! An isolated tab named [AI] rmte-exec (or your custom bot name) appears in the Web IDE tab bar. Human spectators can observe terminal outputs and file creations live in read-only spectator mode. Spectator keystrokes are blocked so humans cannot interfere with the AI's execution stream.

🔒 Can the central relay server see my AI prompts or code?

No. Commands, their output and file contents are encrypted and authenticated end to end with AES-GCM 256-bit keys derived locally from the session password, which never reaches the relay. The relay only sees routing IDs, message sizes and timing. (Web Preview traffic is the exception; see SECURITY.md.)

🌐 How do I connect to a self-hosted relay with self-signed TLS?

Pass the --insecure flag in your MCP server arguments or CLI exec command:
rmte mcp --server-relay="wss://my-internal-relay:8048/ws-rmte" --insecure --id="mysession" --pass="secret"

📦 What is the file size limit for read, write, upload, and download?

File operations are bounded by the host's --buffer limit (default: 1 MB). If your project requires editing or transferring larger files, launch the host with a higher buffer limit, for example: ./rmte share --allow-exec --buffer=10 (for 10 MB limits). Note that the 25MB limit is strictly an internal transport envelope safeguard for JSON-RPC messages over stdio to prevent parser crashes.

Connect AI Coding Agents to Remote Machines