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](https://github.com/wonderwhy-er/DesktopCommanderMCP) 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 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)*

Starmux defaults to 127.0.0.1:18893. Choose direct LAN access or a proxy/tunnel according to your network.

A1 — Direct LAN / virtual-network access:

starmux up --allow-lan  # Listen on 0.0.0.0; no Caddy or tunnel needed

starmux status # Show detected LAN / Tailscale IPv4 MCP URLs starmux up --local # Return to loopback only (alias: --no-allow-lan)

The network mode is saved per instance; a later starmux up keeps it. Switching modes on a running instance restarts its Worker. --allow-lan listens on all IPv4 interfaces, so limit network reachability to your intended clients. Authentication settings stay unchanged; use starmux auth key "My AI Client" for per-client credentials. /access, /dashboard, and all other management routes remain local to 127.0.0.1: or localhost: .

A2 — Public domain / HTTPS:

starmux up --local

caddy reverse-proxy --from mcp.example.com --to 127.0.0.1:18893

Caddy and Tailscale Serve/Funnel can forward the original domain Host without rewriting it. Enable API key, OAuth, or authenticated ingress for public access. Keep the original public Host so forwarded requests cannot reach local management pages.

B — Outbound tunnel behind NAT:

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

No Host rewrite option is needed. Other tunnels such as ngrok, frp, and SSH remote forwarding can also preserve the original Host on /mcp, /healthz, and OAuth resource discovery routes. For OpenAI Secure MCP Tunnel and other networking setups, see Installation & Networking.

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 --allow-lan, 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):**