Starmux — All-in-One Self-Hosted Remote MCP Server & Gateway

Starmux — All-in-One Self-Hosted Remote MCP Server & Gateway

One turnkey daemon for remote filesystem, terminal, background processes, auth, and stdio MCP multiplexing—no manual component assembly required.

All-in-One Remote MCP Server · Streamable HTTP Gateway · Built-in Filesystem, Terminal, Process & Git Tools · stdio Multiplexer · MIT

Why Starmux? · All-in-One vs. DIY Stacks · Quick Start · Auth & Multi-Instance Permissions · Use Cases · macOS App · Documentation

Why Starmux?

Cloud AI assistants (like ChatGPT Web, Claude, or Doubao) are isolated in the browser, and many desktop coding agents (like WorkBuddy, Cursor, Claude Code, Codex, Antigravity, DSH-Harness, Kimi Code, Minimax Code, or ZCode) lack native apps for headless Linux servers or ARM64 edge boards.

Normally, solving this requires manually assembling 3–4 separate open-source tools: a local tool server (DesktopCommanderMCP or filesystem-mcp), a stdio-to-HTTP transport adapter (supergateway or mcp-proxy), an authentication/aggregation gateway (MCPHub or ContextForge), and a process supervisor.

Starmux (Star topology + Multiplexer) replaces that entire fragmented chain with a single, turnkey self-hosted daemon (starmux up):

Traditional DIY Stack:  [Filesystem/Terminal MCP] + [supergateway / mcp-proxy] + [Auth/Aggregator Gateway] + [Supervisor]
Starmux (All-in-One):   [                   Single 'starmux up' Daemon (127.0.0.1:18893/mcp)                   ]

• Turnkey Filesystem, Diff File Editing, Terminal & Process Management (Desktop Commander Engine): Out of the box—with zero external MCP servers to install—AI clients can read/write local files (read_file, write_file, list_directory), run ripgrep code searches (start_search), perform surgical diff edits (edit_block), control interactive PTY/Shell terminal sessions (start_process, interact_with_process, read_process_output), manage background processes (list_processes, kill_process, force_terminate), and run Git workflows.
• Operate Headless Linux, NVIDIA Jetson (ARM64), macOS & Windows Remotely: Desktop AI clients like WorkBuddy or ChatGPT have no native Linux or ARM64 desktop app. Run Starmux on your target Linux workstation, NVIDIA Jetson Orin, or server, and drive its filesystem and terminal remotely from your Mac/PC or browser.
• Built-in stdio-to-Streamable HTTP Bridge & Multi-Server Aggregator: Exposes a native Streamable HTTP (/mcp) endpoint directly and can multiplex your own extra local stdio MCP servers (upstreams) behind the same port—no separate supergateway or mcp-proxy wrapper needed.
• Integrated Read-Only Safety Gate, Revocable API Keys, OAuth 2.0 & Local Admin UI: Starts in Global Read-Only mode (readOnly) by default so AI can safely inspect files and directories without running shell commands or modifying disk. Switch to Coding mode (--code) when needed, lock down remote access with per-client revocable Bearer API keys or OAuth 2.0 + PKCE, and manage everything from the CLI or private local Admin UI / Web Dashboard.

All-in-One vs. Fragmented DIY Stacks

Instead of wiring together separate tool backends, transport bridges, and auth proxies—or deploying heavy control planes that still lack host tools—Starmux provides a unified end-to-end runtime:

Quick Start

1. Install

Requires Node.js 22.12+ on macOS, Linux (x64 / ARM64 / NVIDIA Jetson), or Windows.

npm install -g starmux

(Upgrading? Run starmux down before installing the new version—see the Upgrade Guide.)

2. Start in your project directory

cd /path/to/your/project

# Option 1: Read-only mode (default — safely inspect files, folders & code)
starmux up

# or, Option 2: Coding mode (enable file edits, interactive terminal, process management & Git)
starmux up --code

Starmux starts in the background on http://127.0.0.1:18893/mcp with Authentication: None by default for immediate local connection:

● Starmux is running  (instance: default)
  Instance        <instance UUID>
  Listen          http://127.0.0.1:18893/mcp  (this computer only)
  Project         /path/to/your/project
  Mode            Read-only (global · OS account)  (run 'starmux up --code' to enable edits & shell)
  Auth            None (no token required)

(Switch between Read-only and Coding permissions anytime with starmux up --code and starmux up --read.)

3. Expose for Remote / Cloud AI (Skip if your AI client runs on this same computer)

Because Starmux binds strictly to 127.0.0.1:18893 for local security, choose the forwarding method that matches your network when connecting from a cloud AI client (ChatGPT Web) or another computer (WorkBuddy / Cursor on Mac $\rightarrow$ Linux / Jetson):

Copy-paste commands for Option A1 (Caddy Reverse Proxy) & Option B (Outbound Tunnels)

• Option A1: Reachable IP (LAN or Public Domain) with Caddy: Replace mcp.example.com with your public domain (or http://YOUR_LAN_IP on a trusted private LAN):

  caddy run --adapter caddyfile --config - << 'EOF'
  mcp.example.com {
      handle /mcp {
          reverse_proxy 127.0.0.1:18893 {
              header_up Host 127.0.0.1:18893
          }
      }
  }
  EOF

• Option B: Behind NAT / CGNAT — Outbound Tunnel (No inbound port forwarding required):
  • OpenAI Secure MCP Tunnel (for ChatGPT Web / Codex):

    tunnel-client run \
      --control-plane.tunnel-id "tunnel_YOUR_TUNNEL_ID" \
      --control-plane.api-key "env:MAC_MCP_TUNNEL_KEY" \
      --mcp.server-url "http://127.0.0.1:18893/mcp" \
      --health.listen-addr "127.0.0.1:18891" \
      --log.level info

  • or, Cloudflare Quick Tunnel:

    cloudflared tunnel --url http://127.0.0.1:18893 --http-host-header 127.0.0.1:18893

(See Installation & Networking for Tailscale, frp, rathole, ngrok, and IPv6 TLS setups.)

4. Connect your AI client

With default settings (Auth: None), connect your AI client using any of the 3 options below:

Option 1 — Ask your AI coding agent to add it for you (Zero manual config)

For agentic coding clients (Claude Code, Antigravity, Codex, Cursor, WorkBuddy, DSH-Harness, Kimi Code, Minimax Code, ZCode), send this prompt in the AI chat (replace the URL with your LAN IP, domain, or http://127.0.0.1:18893/mcp):

Create this MCP Server connector:
"starmux": {
  "type": "streamable-http",
  "url": "http://192.168.50.114/mcp"
}

or, Option 2 — AI clients with a Form UI (e.g., ChatGPT Web, Claude, Doubao)

or, Option 3 — Manually paste into mcp.json

• Same-computer connection (or when using local ssh -L port forwarding):

  {
    "mcpServers": {
      "starmux": {
        "type": "streamable-http",
        "url": "http://127.0.0.1:18893/mcp"
      }
    }
  }

• Remote / LAN connection (via Direct Proxy or Tunnel — do NOT use 127.0.0.1 across separate machines):

  {
    "mcpServers": {
      "starmux": {
        "type": "streamable-http",
        "url": "https://mcp.example.com/mcp"
      }
    }
  }

Securing Remote Access: Auth & Multi-Instance Permissions

When exposing Starmux beyond 127.0.0.1, lock down your endpoint with per-client credentials and permission controls:

1. Per-Client Bearer API Keys & OAuth 2.0

1. Per-Client Bearer API Keys (with instant revocation & private Admin UI): Create a named credential for each AI client so you can audit or revoke them independently without exposing the local admin interface:

    starmux auth key "My AI Client"
    starmux auth                    # List active API keys, OAuth sessions, and auth status
    starmux dashboard               # Open the private local Admin UI / Web Access Console (127.0.0.1 only)

   Then add the Authorization header to your client's mcp.json:

    {
      "mcpServers": {
        "starmux": {
          "type": "streamable-http",
          "url": "https://mcp.example.com/mcp",
          "headers": {
            "Authorization": "Bearer smx_YOUR_GENERATED_API_KEY"
          }
        }
      }
    }

2. OAuth 2.0 + PKCE Browser Login (for ChatGPT Web): Acts as a standard OAuth 2.0 protected resource server with PKCE and session revocation (via self-hosted Keycloak). See Security & Authentication — OAuth 2.0.

2. Advanced: Multiple Instances, Separate Project Folders & stdio Multiplexing (-i)

(Optional) By default, Starmux runs a single default instance. If you want separate remote MCP endpoints on one computer—each with its own port, project directory / folder context, credentials, mounted stdio MCP servers, and Read-Only vs. Coding permission mode—pass -i <name>:

# Instance 1: Coding mode on port 18893 for repo-a
starmux up ~/work/repo-a -i work --code

# Instance 2: Strict Read-Only mode on an auto-assigned port for docs/blog folder
starmux up ~/personal/blog -i blog --read

starmux ls                      # List all instances with status, mode, port, and project folder
starmux config edit -i work     # Mount extra local stdio MCP servers (upstreams) or customize settings
starmux config apply -i work    # Hot-reload configuration changes
starmux down -i work            # Stop a specific instance

Security & Trust Boundary Note: Starmux's default Read-Only mode (--read) blocks write tools, shell execution, and Git mutations across the instance. In Coding mode (--code), terminal and file tools run with your OS account's permissions (the configured project directory sets the working context, not an OS chroot sandbox; an optional home-directory write sandbox is available on macOS). See Instances & Upstream Multiplexing and Security Model.

Everyday CLI Commands

starmux status          # Check health, endpoints, active permission mode, and recent tool activity
starmux up .            # Switch active project folder context to current directory
starmux auth            # View auth mode, create/revoke per-client API keys, and inspect OAuth sessions
starmux verify          # Run an end-to-end local MCP handshake, tool discovery, and read probe
starmux doctor          # Run environment, port lease, and configuration diagnostics
starmux dashboard       # Open the local Web Admin UI / Access Console to manage access & tool deny rules
starmux logs -f         # Stream live MCP gateway and tool invocation logs
starmux down            # Stop the gateway (alias: stop)

Tested AI Client Matrix

Common Use Cases & FAQ

• How can ChatGPT access files and terminal tools on my local computer? Run starmux up locally and expose 127.0.0.1:18893/mcp via OpenAI Secure MCP Tunnel or Direct HTTPS so ChatGPT Web can inspect folders or run tools without manual file uploads.
• How can WorkBuddy on Mac/Windows operate a headless Linux server or NVIDIA Jetson remotely? Install Starmux on the Linux x64/ARM64 or NVIDIA Jetson Orin host, expose /mcp over LAN or HTTPS with Caddy, and add "type": "streamable-http" in WorkBuddy—no Linux desktop app required.
• Is there a self-hosted, open-source alternative to the hosted Remote Desktop Commander service? Yes. Starmux bundles the open-source Desktop Commander tool engine with a built-in Streamable HTTP server, read-only controls, and self-hosted auth so your tools execute without a third-party cloud relay.
• How do I aggregate multiple local stdio MCP servers behind one Streamable HTTP endpoint? Configure upstreams in your Starmux instance (starmux config edit) to multiplex extra stdio MCP servers alongside built-in filesystem/terminal tools on a single port.
• How do I connect a cloud AI client to an MCP server behind NAT / CGNAT? Compare outbound tunnels (OpenAI Tunnel, Cloudflare Tunnel, frp, rathole), Direct IPv6/IPv4 HTTPS with Caddy, and SSH port forwarding.
• How can I secure a self-hosted remote MCP server with OAuth 2.0 or revocable API keys? Use starmux auth key for per-client Bearer tokens or configure Keycloak OAuth 2.0 + PKCE for browser-based AI connectors.

中文场景速览（一站式自托管远程 MCP 服务与网关）： Starmux 将 Desktop Commander 风格的文件读写、代码搜索、Diff 编辑、交互式终端、进程管理与 Git 工具、stdio 转 Streamable HTTP 网关、多本地 stdio MCP 服务聚合、只读（Read-Only）与 Coding 权限切换、以及 API Key / OAuth 2.0 鉴权 一体化内置于单个守护进程中。无需手工拼装 DesktopCommanderMCP + supergateway，即可让网页版 ChatGPT、Claude、豆包 或桌面端 WorkBuddy、Cursor、Codex、Antigravity 通过局域网 Caddy、Direct HTTPS（支持公网 IPv4/IPv6）、SSH 转发或内网穿透（NAT/CGNAT Tunnel）安全操作 Linux (x64/ARM64)、NVIDIA Jetson、macOS 与 Windows 上的本地文件与终端。

Native macOS App

Prefer a visual interface? The native SwiftUI menu bar App puts service health, Read-Only vs. Coding mode toggles, live MCP connection topology, and recent tool calls in one compact panel.

Native macOS Menu Bar App (English & Chinese) · Controls the same instances as the CLI

The App and CLI manage the same underlying instances. Quitting the App stops only instances started by the App; background instances started via CLI keep running.

Documentation & Architecture Guides

Explore the Documentation Index by topic:

• 📦 Installation, Platforms & Network Forwarding — Supported hosts (macOS, Linux, NVIDIA Jetson, Windows), everyday CLI commands, upgrades, source builds, and Caddy / Tunnel / SSH forwarding.
• 🔒 Security, Access Control & Authentication — Global Read-Only vs. Coding permissions, trust boundaries, per-client Bearer API keys (starmux auth key), private local Admin UI, and self-hosted Keycloak OAuth 2.0 + PKCE.
• 🤖 AI Client Configuration Guides — End-to-end setup (including 1-step Prompt Auto-Setup) for ChatGPT Web, Claude App / Code, WorkBuddy, Antigravity, Codex, Cursor, DSH-Harness, Kimi Code, Minimax Code, ZCode, and Doubao (豆包).
• ⚙️ Multi-Instance & JSONC Configuration — Running multiple isolated instances (-i NAME), hot-reloading config.jsonc, mounting extra local stdio MCP servers (upstreams), and managing secrets.

License

Starmux original code is MIT Licensed. Desktop Commander is bundled as a pinned dependency and retains its own license and notices. Starmux is an independent open-source project and is not endorsed by Desktop Commander or AI client vendors.