starmux 0.11.0 → 0.13.0

package/dist/vendor/desktop-commander/dist/utils/withTimeout.js

@@ -0,0 +1,85 @@
+/**
+ * Executes a promise with a timeout. If the promise doesn't resolve or reject within
+ * the specified timeout, returns the provided default value.
+ *
+ * @param operation The promise to execute
+ * @param timeoutMs Timeout in milliseconds
+ * @param operationName Name of the operation (for logs)
+ * @param defaultValue Value to return if the operation times out
+ * @returns Promise that resolves with the operation result or the default value on timeout
+ */
+export function withTimeout(operation, timeoutMs, operationName, defaultValue) {
+    // Don't sanitize operation name for logs - only telemetry will sanitize if needed
+    return new Promise((resolve, reject) => {
+        let isCompleted = false;
+        // Set up timeout
+        const timeoutId = setTimeout(() => {
+            if (!isCompleted) {
+                isCompleted = true;
+                if (defaultValue !== null) {
+                    resolve(defaultValue);
+                }
+                else {
+                    // Keep the original operation name in the error message
+                    // Telemetry sanitization happens at the capture level
+                    reject(`__ERROR__: ${operationName} timed out after ${timeoutMs / 1000} seconds`);
+                }
+            }
+        }, timeoutMs);
+        // Execute the operation
+        operation
+            .then(result => {
+            if (!isCompleted) {
+                isCompleted = true;
+                clearTimeout(timeoutId);
+                resolve(result);
+            }
+        })
+            .catch(error => {
+            if (!isCompleted) {
+                isCompleted = true;
+                clearTimeout(timeoutId);
+                if (defaultValue !== null) {
+                    resolve(defaultValue);
+                }
+                else {
+                    // Pass the original error unchanged - sanitization for telemetry happens in capture
+                    reject(error);
+                }
+            }
+        });
+    });
+}
+/**
+ * Run an operation under a timeout WITH real cancellation.
+ *
+ * Unlike withTimeout (which only races a timer and leaves the underlying work
+ * running — holding its libuv thread/fd until the OS call returns), this passes
+ * an AbortSignal into the operation and aborts it when the timeout fires, so a
+ * read/stream that honors the signal is cancelled and its resources released.
+ *
+ * Rejects with an Error whose `.code` is 'ETIMEDOUT' on timeout (so existing
+ * ETIMEDOUT handling / permission-error mapping keeps working).
+ *
+ * Caveat: an operation wedged inside a single un-interruptible syscall only
+ * observes the abort once that syscall returns; library reads that ignore the
+ * signal (e.g. Excel/PDF parsers) still get the timeout rejection but keep
+ * running in the background until they finish on their own.
+ */
+export function runWithAbortableTimeout(operation, timeoutMs, operationName) {
+    const controller = new AbortController();
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+            controller.abort();
+            const error = new Error(`${operationName} timed out after ${timeoutMs / 1000} seconds`);
+            error.code = 'ETIMEDOUT';
+            reject(error);
+        }, timeoutMs);
+    });
+    const op = operation(controller.signal);
+    // Swallow the late abort rejection so it can't surface as an unhandled
+    // rejection after the timeout has already settled the race.
+    op.catch(() => { });
+    return Promise.race([op, timeout]).finally(() => clearTimeout(timeoutId));
+}

package/dist/vendor/desktop-commander/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.3.1';

package/dist/vendor/desktop-commander/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@wonderwhy-er/desktop-commander",
+  "version": "0.3.1",
+  "description": "Purified zero-telemetry build of Desktop Commander MCP for Starmux",
+  "license": "MIT",
+  "author": "Eduards Ruzga",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wonderwhy-er/DesktopCommanderMCP.git"
+  },
+  "type": "module",
+  "bin": {
+    "desktop-commander": "dist/index.js"
+  }
+}

package/docs/ACCESS_CONTROL.md

@@ -6,11 +6,11 @@ Authentication decides who can connect. Your instance configuration decides what
 
 | Mode | Use when | Configure |
 | --- | --- | --- |
-| `ingress` | An existing protected ingress controls callers | Protect ingress, then `starmux auth mode ingress` |
-| `api-key` | Your client accepts a Bearer key | `starmux auth key "My client"` |
-| `oauth` | Your client uses browser login and consent | [Configure a provider](OAUTH.md), then `starmux auth mode oauth` |
+| `none` *(default)* | Connecting on the same computer, or your tunnel/reverse proxy already restricts callers | `starmux auth mode none` |
+| `api-key` | Your client accepts a Bearer API key header | `starmux auth key "My AI Client"` |
+| `oauth` | Your client uses browser login and consent (e.g., ChatGPT Web) | [Configure a provider](OAUTH.md), then `starmux auth mode oauth` |
 
-A new local instance uses `ingress`. For remote access in this mode, the ingress must restrict access; HTTPS encrypts traffic but does not authenticate callers. One instance has one active mode. All its authorized clients use the same approved tool permissions.
+A new local instance defaults to `none` (also accepted as `ingress`). For remote access in this mode, your tunnel or reverse proxy must restrict access; HTTPS encrypts traffic but does not authenticate callers. Each instance has one active authentication mode at a time, and all authorized clients share the instance's approved workspace permissions.
 
 ## API keys
 
@@ -20,7 +20,7 @@ starmux auth
 starmux auth revoke CREDENTIAL_ID
 ```
 
-Creating a key also enables API-key mode. Copy the key when printed; Starmux stores only its digest. New keys begin with `smx_`; migrated `mgw_` keys continue to work. Expiration accepts positive durations (`30m`, `12h`, `30d`, `4w`) or a future ISO timestamp. Omit it for no expiry.
+Creating a key automatically enables `api-key` mode and prints both Form UI fields and a ready-to-paste `mcpServers` JSON snippet. Copy the key when printed; Starmux stores only its digest. New keys begin with `smx_` (migrated `mgw_` keys continue to work). Expiration accepts positive durations (`30m`, `12h`, `30d`, `4w`) or a future ISO timestamp. Omit it for no expiry.
 
 Configure your client with `Authorization: Bearer YOUR_KEY`. See the [complete HTTPS example](REMOTE_SETUP.md#2-https--bearer-api-key).
 

package/docs/CLIENTS.md

@@ -1,30 +1,22 @@
 # AI client compatibility
 
-Choose a client you already use, then check its tested connection below. Transport, authentication and host platform are separate parts of a deployment; success with one combination does not certify the others.
+Choose a client you already use, then check its recommended connection below. Transport, authentication and host platform are configured independently.
 
-**Labels:** Tested means a recorded project workflow; owner-reported means a successful user report without a complete recorded test matrix; pending means a compatibility target, not a completed Gateway test.
-
-
-| Client | Current project validation | Connection guide |
+| Client | Validation status | Connection guide |
 | --- | --- | --- |
-| **ChatGPT web** | Tested: Tunnel + OAuth; coding, session revocation and fresh login | [ChatGPT OAuth](REMOTE_SETUP.md#4-configure-core-and-chatgpt) |
-| **Claude App** | Remote MCP supported by the client; Gateway end-to-end validation pending | [Official custom connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) |
-| **Codex** | Tested: installed Gateway plugin through protected Tunnel | [Tunnel](CONNECT_CHATGPT.md#2-secure-mcp-tunnel--no-inbound-port) · [HTTP API-key example](REMOTE_SETUP.md#configure-workbuddy-or-another-header-capable-client) |
-| **WorkBuddy** | Tested: remote HTTPS + IPv6 + API-key file reads/writes to macOS | [API Key setup](REMOTE_SETUP.md#2-https--bearer-api-key) |
-| **Doubao (豆包)** | Owner-reported successful use; exact connection combination not recorded | [Deployment options](REMOTE_SETUP.md) |
-
-A client listing does not imply every authentication or transport combination has passed. In particular, Claude App is a compatibility target, and ChatGPT direct-HTTPS OAuth remains unverified. [OAuth evidence](OAUTH.md) · [WorkBuddy evidence](VALIDATION_WORKBUDDY.md) · [Protected Tunnel evidence](VALIDATION_TUNNEL.md)
-
-## Use WorkBuddy with a Linux workspace
-
+| **ChatGPT Web** | ✅ Tested: Secure Tunnel + OAuth (coding, session revocation and login) | [ChatGPT OAuth](REMOTE_SETUP.md#4-configure-starmux-and-chatgpt) |
+| **Claude App** | 🎯 Target: Remote MCP Custom Connector | [Official custom connector setup](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) |
+| **Codex** | ✅ Tested: Protected Tunnel | [Tunnel setup](CONNECT_CHATGPT.md#2-secure-mcp-tunnel--no-inbound-port) · [HTTP API-key example](REMOTE_SETUP.md#configure-workbuddy-or-another-header-capable-client) |
+| **WorkBuddy** | ✅ Tested: Direct HTTPS + IPv6 + Bearer API key | [API Key setup](REMOTE_SETUP.md#2-https--bearer-api-key) |
+| **Doubao (豆包)** | ✅ Community verified | [Deployment options](REMOTE_SETUP.md) |
 
-**Your AI app's operating system does not have to be your tools' operating system.** Keep WorkBuddy on your Mac or Windows computer and deploy Gateway Core with Desktop Commander on a Linux machine. Connect to that machine's authenticated HTTPS MCP endpoint to work with its files and development tools.
+See [OAuth setup](OAUTH.md) and [remote setup](REMOTE_SETUP.md) for step-by-step configuration.
 
-For example, ask WorkBuddy to inspect a Linux project's configuration, update an approved file, and run its tests on that Linux host. WorkBuddy itself does not need to be installed there. This is remote MCP tool access, not remote desktop control or automatic file synchronization.
+## Use WorkBuddy or Desktop AI Clients with a Linux / NVIDIA Jetson Host
 
-**Validation:** remote WorkBuddy file reads/writes on a Mac have passed; the Linux Core has independently passed real Desktop Commander file-write and Shell tests. The combined **WorkBuddy → Linux** deployment is an intended use case, with end-to-end acceptance still pending. [WorkBuddy evidence](VALIDATION_WORKBUDDY.md) · [Linux setup and permissions](PLATFORMS.md)
+**Your AI client's operating system does not have to match your target machine's operating system.** Many AI clients (such as WorkBuddy or ChatGPT Desktop) only offer macOS and Windows desktop apps. You can keep your AI client on your Mac or Windows laptop, run `starmux up --code` on a **Linux (`x64` / `ARM64`)** server or **NVIDIA Jetson** device, and connect over HTTPS + Bearer API Key or Tunnel to edit code and run terminal commands on the target machine remotely.
 
-WorkBuddy's [official desktop downloads](https://www.codebuddy.cn/docs/workbuddy/Download-History) currently list macOS and Windows. This deployment separates the client installation from the machine that executes tools.
+See [platform support](PLATFORMS.md) for Linux and cross-platform details.
 
 
 [Choose authentication](ACCESS_CONTROL.md#choose-an-authentication-mode) · [Remote deployment](REMOTE_SETUP.md) · [All documentation](README.md)

package/docs/CONNECT_CHATGPT.md

@@ -19,9 +19,9 @@ This is a guide for **your own private ChatGPT connection**, not a claim that th
 ## Before either connection
 
 1. Install and start Starmux using [Local installation](INSTALL.md).
-2. Run `starmux status` and confirm **Core: RUNNING / Healthy**. Note your **actual local port**. The initial default port is **18893**; use the actual value shown by `status`.
-3. The **local** MCP address is `http://127.0.0.1:<PORT>/mcp`. You don't paste that into ChatGPT: ChatGPT runs in the cloud and cannot dial your Mac's `localhost`.
-4. Start with a **restricted read-only** profile. Remote caller authentication and permission to use a tool are separate from simply discovering that tool.
+2. Run `starmux status` and confirm **`● Starmux is running`**. Note your **actual local port**. The default port is **18893**; use the actual value shown by `status`.
+3. The **local** MCP address is `http://127.0.0.1:<PORT>/mcp`. You don't paste that into ChatGPT Web: ChatGPT runs in the cloud and cannot dial your machine's `localhost` directly.
+4. Start with the default **Read-only** mode (`starmux up`). Switch to **Coding mode** (`starmux up --code`) when you want ChatGPT to edit files or run Shell commands.
 
 ## 1. Direct HTTPS — your domain, your Gateway
 
@@ -118,7 +118,7 @@ tunnel-client doctor --profile <YOUR_PROFILE> --explain
 tunnel-client run --profile <YOUR_PROFILE>
 ```
 
-Keep both Gateway and `tunnel-client` running. **Choosing Tunnel in the Gateway App does not itself create or start this connection.**
+Keep both Starmux and `tunnel-client` running.
 
 ### Step 3 — Choose the Tunnel in ChatGPT
 
@@ -145,6 +145,4 @@ Neither route replaces Desktop Commander or changes your local file permissions.
 - **Tools appear, but write is denied:** This may be correct. Check remote caller authorization and local restricted/developer mode. Don't disable security just to make discovery green.
 - **No “Add custom MCP server” option:** ChatGPT's available custom MCP features depend on plan and workspace permissions. See [OpenAI's current connection instructions](https://help.openai.com/en/articles/12584461-connecting-custom-mcp-servers-in-chatgpt).
 
-**Community release gate:** Neither route is independently accepted as a public one-click workflow yet; ChatGPT OAuth Tunnel coding and revocation tests passed, while direct-HTTPS OAuth and independent onboarding remain open. No public endpoint should be deployed without verified caller identity and revocation.
-
 [Main README](../README.md) · [Local installation](INSTALL.md) · [Security](SECURITY.md)

package/docs/INSTALL.md

@@ -10,6 +10,14 @@ starmux up
 
 The first start creates a private configuration and starts a background process on `127.0.0.1:18893`. The terminal returns when the service is ready.
 
+Read the **Connect an AI client (MCP settings)** section printed by `up` (also available with `status`):
+
+- **None (no token required):** a local client uses Streamable HTTP with authentication set to None. For a web or remote client, connect through a protected HTTPS proxy or tunnel that forwards to `127.0.0.1:18893`.
+- **API key:** configure Bearer token authentication (`Authorization: Bearer <YOUR_API_KEY>`) with the key you saved when creating it. The output shows how many keys are active and the command to create one if needed.
+- **OAuth:** use the configured **URL (Remote)** and complete browser sign-in with an allowed account.
+
+`starmux dashboard` opens the local Web Access Console with its owner login so you can view and copy settings in your browser. `--json` retains structured status for scripts.
+
 ```sh
 starmux verify
 starmux status
@@ -36,11 +44,7 @@ With API-key or OAuth authentication enabled, give `verify` a valid Bearer crede
 
 ## Connect remotely
 
-Continue with [remote setup](REMOTE_SETUP.md): HTTPS + API key, ChatGPT OAuth, or an existing protected ingress. A local verification pass confirms the local service; the last step of each remote route is a real tool call from your client.
-
-## Existing installations
-
-Use [migration](MIGRATION.md) to retain your existing workspaces and credentials. New installations store state in `~/.config/starmux` on all platforms.
+Continue with [remote setup](REMOTE_SETUP.md): HTTPS + API key, ChatGPT OAuth, or an existing protected tunnel. A local verification pass confirms the local service; the last step of each remote route is a real tool call from your client.
 
 ## Install from a checkout
 

package/docs/INSTANCES.md

@@ -9,6 +9,7 @@ starmux ls
 starmux status -i work
 starmux logs -f -i blog
 starmux down -i work
+starmux rm blog
 ```
 
 Names such as `work` and `blog` are arbitrary labels. Names and stable IDs both work with `-i` / `--instance`, before or after the command. Instances share the OS account; coding mode uses that account's permissions.
@@ -37,7 +38,7 @@ Set `VISUAL` or `EDITOR` to your editor executable for `config edit`. JSONC supp
     snapshots/
 ```
 
-Configuration holds workspace, port, permissions and optional upstream settings. Credentials and secrets live in private state. `config validate` and `config schema` provide diagnostics and the full schema.
+Configuration holds workspace, port, permissions and optional upstream settings. Credentials and secrets live in private state. `config validate` and `config schema` provide diagnostics and the full schema. `starmux config schema` also works before creating an instance.
 
 ## Import, bind and export
 
@@ -57,13 +58,15 @@ Import makes a private copy. `--link` keeps the external file authoritative. `ma
 starmux config copy experiment -i work
 starmux config rename development -i work
 starmux config default development
-starmux config archive -i experiment
+starmux rm experiment              # Alias for: starmux config archive -i experiment
 starmux ls --archived
 starmux config restore -i experiment
 ```
 
 Copies receive a new identity and port, without credentials or private secrets. An authenticated copy needs its authentication configured before startup. Archive stops the instance and retains recoverable data. The first created instance is the CLI default; `config default` changes it explicitly.
 
+With no instances, `starmux ls` points to `starmux up` to get started. If all instances are archived, use `starmux ls --archived` and restore one with `starmux config restore -i NAME`. Instance operations reject missing or extra arguments; use `-i NAME` to select the instance to archive or restore.
+
 ## Snapshots, secrets and automation
 
 Concurrent edits return `CONFIG_CONFLICT`; reload before saving again. A failed apply attempts to restore the last successful worker configuration. Credential revocations are never rolled back. `config recover` repairs a missing source from the last successful snapshot without replacing an existing file.

package/docs/OAUTH.md

@@ -1,18 +1,14 @@
 # OAuth for ChatGPT and other MCP clients
 
-Gateway is the OAuth **resource server**. A separate authorization server owns user login, consent, PKCE authorization codes, token issuance and refresh. The Core remains loopback-only; HTTPS/Tunnel transport is independent of authorization. Existing ingress and API-key installations remain unchanged until the owner explicitly selects OAuth.
+Starmux acts as the OAuth **resource server**. A separate authorization server (such as Keycloak) owns user login, consent, PKCE authorization codes, token issuance and refresh. Starmux remains loopback-only (`127.0.0.1`); HTTPS or Tunnel transport is configured independently of authorization.
 
 **Start here:** [step-by-step remote installation](REMOTE_SETUP.md) covers Keycloak, HTTPS proxy, CLI configuration, ChatGPT fields and the tested Tunnel layout. This document covers provider setup and the OAuth reference contract.
 
-**Current result:** ChatGPT web OAuth through the official Tunnel passed real coding, session revocation and fresh-login recovery. The owner additionally confirmed a real read-only disk scan. Direct-HTTPS OAuth and native Linux/Windows OAuth acceptance remain open.
+## Implementation overview
 
-## Current implementation and acceptance boundaries
-
-- Implemented: protected-resource discovery, Bearer challenges, JWT validation, owner subject/client allowlists, tool security metadata, live local session revocation, CLI and Dashboard management.
-- The first provider contract uses JWT access tokens with `sub`, `azp` (OAuth client ID), `sid` (stable authorization-server session ID), `iat`, `exp`, audience and scope. Opaque tokens/introspection and providers without this contract are not supported.
-- Resource metadata is available without a token only in OAuth mode at `/.well-known/oauth-protected-resource` and the resource-path-specific location. MCP initialization, listing, tools and resources all require authentication. Mixed anonymous/OAuth tools are not enabled.
-- Local signed-token tests do not establish real ChatGPT compatibility. HTTPS and Tunnel end-to-end acceptance must be recorded separately.
-- A reference Keycloak realm generator is provided. Keycloak's resource-indicator and CIMD features are experimental; do not claim full provider compatibility based only on successful discovery.
+- **Supported features:** protected-resource discovery (`/.well-known/oauth-protected-resource`), Bearer challenges, JWT validation, owner subject/client allowlists, tool security metadata, live local session revocation, and CLI / Web Dashboard management.
+- **Token contract:** JWT access tokens with `sub`, `azp` (OAuth client ID), `sid` (stable authorization-server session ID), `iat`, `exp`, audience and scope. Opaque tokens/introspection are not supported.
+- **Discovery:** Resource metadata is available without a token in OAuth mode at `/.well-known/oauth-protected-resource` and the resource-path-specific location. MCP initialization, tool listing, tool calls and resources all require a valid OAuth token.
 
 ## Configure an existing authorization server
 
@@ -99,11 +95,7 @@ A maximum of 512 remembered OAuth sessions is enforced without evicting revocati
 
 JWT verification checks signatures, issuer, audience, expiry/not-before, issued-at, client, owner subject, session and scope. A wrong scope/owner is denied before MCP dispatch. The Core does not retry tools when authentication fails. Locally trusted Shell tools remain capable of accessing owner files; OAuth admission does not isolate them from the owner account.
 
-Existing Tunnel coding acceptance in ingress mode is recorded separately in [the Tunnel validation report](VALIDATION_TUNNEL.md); it is not OAuth acceptance.
-
-## Validation history
-
-See [client compatibility](CLIENTS.md) and the [OAuth validation archive](VALIDATION_OAUTH.md).
+See [client compatibility](CLIENTS.md) and [remote setup](REMOTE_SETUP.md) for deployment details.
 
 ## Reproduce the local provider test
 

package/docs/PLATFORMS.md

@@ -20,10 +20,10 @@ starmux down
 - State is stored under `~/.config/starmux`; on Windows, `~` is the user profile. Private files use owner-only POSIX permissions or Windows ACLs.
 - Windows runtime control uses authenticated named pipes; Unix hosts use private sockets. Gateway-generated commands use host-appropriate quoting and shells.
 
-## Validation status
+## Supported hosts
 
-The Starmux 0.10.0 CLI is a preview. Its new command workflow is validated on the development macOS host. Earlier Core tests passed on Ubuntu 24.04 arm64 / Node 22.12, including real file writes and Shell. Windows native execution remains pending; earlier implementation or CI configuration does not establish that the new release has passed there.
+Starmux runs on **macOS** (`Apple Silicon` and `Intel`), **Linux** (`x64`, `ARM64`, and edge devices such as **NVIDIA Jetson**), and **Windows**.
 
-The native macOS App is a development build. Public signing, notarization and independent clean-Mac installation are separate release steps.
+The native macOS menu bar App is provided as a development build in [`app/`](../app/README.md).
 
-`npm test` uses isolated home directories and ports. Portable tests cover process lifecycle, permissions, authentication, configuration and the new CLI. macOS also runs the historical lifecycle regression tests needed by migration.
+`npm test` uses isolated home directories and ports to verify process lifecycle, workspace permissions, authentication, configuration, and the CLI.

package/docs/README.md

@@ -9,17 +9,8 @@ Start locally, connect your client, then explore advanced configuration as neede
 ## Go further
 
 - [OAuth and ChatGPT](OAUTH.md)
+- [Connect ChatGPT (HTTPS & Tunnel)](CONNECT_CHATGPT.md)
 - [Instances and JSONC configuration](INSTANCES.md)
-- [Migration from Mac MCP Gateway](MIGRATION.md)
 - [Permissions and security](SECURITY.md)
 - [Client compatibility](CLIENTS.md) and [platform support](PLATFORMS.md)
-- [Release status](RELEASE_STATUS.md)
-- [Architecture](ARCHITECTURE.md) and [contributing](../CONTRIBUTING.md)
-
-## Validation archives
-
-These records describe specific tested deployments, not installation instructions:
-
-- [WorkBuddy](VALIDATION_WORKBUDDY.md)
-- [Tunnel](VALIDATION_TUNNEL.md)
-- [OAuth](VALIDATION_OAUTH.md)
+- [Contributing](../CONTRIBUTING.md)

package/docs/REMOTE_SETUP.md

@@ -6,15 +6,13 @@ For help choosing between the three authentication modes, read [the access-contr
 
 ## Choose authentication independently of transport
 
-| Authentication | Choose it when | Validated path |
+| Authentication | Choose it when | CLI Command |
 | --- | --- | --- |
-| Ingress-managed | Your existing ingress restricts access and you do not need a Gateway credential | Codex plugin through a protected OpenAI Tunnel |
-| Bearer API key | Your client accepts an `Authorization` header | WorkBuddy over public HTTPS + IPv6, including remote reads and writes |
-| OAuth | Your client presents a login/consent flow | ChatGPT web through OpenAI Tunnel + Keycloak, including coding and revocation |
+| **None** (`none` / `ingress`) | Connecting locally, or your tunnel already restricts callers | `starmux auth mode none` |
+| **Bearer API key** | Your client accepts an `Authorization: Bearer <key>` header (e.g., WorkBuddy, Cursor) | `starmux auth key "My AI Client"` |
+| **OAuth 2.0** | Your client requires a browser login/consent flow (e.g., ChatGPT Web) | `starmux auth oauth setup ...` |
 
-HTTPS and Tunnel are transport choices; API key and OAuth are authentication choices. OAuth does not require Tunnel, and HTTPS alone does not authenticate callers. ChatGPT direct-HTTPS OAuth has not received the same end-to-end acceptance as the Tunnel deployment. Doubao compatibility is owner-reported; its precise transport/authentication combination has not been recorded. See the [client matrix](CLIENTS.md).
-
-A Core has one active authentication mode. Switching to OAuth makes existing API keys unusable on that Core, and vice versa. This guide configures one Core at a time, not simultaneous API-key/OAuth listeners. The separate acceptance instances used during development are not a prerequisite for ordinary installation.
+HTTPS reverse proxy and Tunnel are network transport choices; API key and OAuth are authentication choices. Each Starmux instance has one active authentication mode at a time. Switching to OAuth disables API keys on that instance (and vice versa). See the [client matrix](CLIENTS.md).
 
 ## 1. Start locally
 
@@ -81,10 +79,12 @@ For WorkBuddy, merge this entry into `~/.workbuddy/mcp.json` without replacing u
 ```json
 {
   "mcpServers": {
-    "my-gateway": {
+    "starmux": {
       "type": "streamable-http",
       "url": "https://mcp.example.com/mcp",
-      "headers": { "Authorization": "Bearer REPLACE_WITH_YOUR_GATEWAY_KEY" }
+      "headers": {
+        "Authorization": "Bearer smx_REPLACE_WITH_YOUR_API_KEY"
+      }
     }
   }
 }
@@ -110,7 +110,7 @@ Set that variable securely in the environment of the actual Codex process; setti
 4. The next MCP request with that key must fail with HTTP 401. A missing/wrong key must also fail. Already-running tools are not canceled.
 5. Create a new key to restore access; update the client's private configuration.
 
-Local `starmux verify` in API-key mode reads `STARMUX_TOKEN` from its environment. Local PASS is not external acceptance. [WorkBuddy evidence and limits](VALIDATION_WORKBUDDY.md).
+Local `starmux verify` in API-key mode reads `STARMUX_TOKEN` from its environment. Local PASS confirms the local endpoint; verify remote access with a real tool call from your client.
 
 ## 3. OAuth: deploy the authorization server
 
@@ -199,7 +199,7 @@ Validate and run Caddy as in the API-key section. This allowlist is for the **pr
 
 Before enabling public MCP access, configure Core authentication as below. If the proxy is already running while Core still uses ingress mode, keep the `/mcp` route disabled until OAuth mode is set. Issuer metadata can be exposed first for configuration.
 
-## 4. Configure Core and ChatGPT
+## 4. Configure Starmux and ChatGPT
 
 ```sh
 starmux auth oauth setup \
@@ -263,8 +263,8 @@ Manage keys/sessions in the local **Dashboard → Access control**. The macOS Ap
 | HTTP 401 after revoke or idle expiry | Do not retry tools indefinitely; inspect local revocation state, then use a fresh authorized login if appropriate |
 | HTTP 403 | Allowed owner/client and `gateway:access`; do not expand permissions just to hide a failure |
 | OAuth works but a write is denied | Existing workspace/OS/upstream policy still applies |
-| Web answer/app fails to render | Correlate actual tool/audit results before deciding whether execution failed; never automatically repeat a side-effecting call |
-| CLI changes do not affect the server | Check `MAC_MCP_ACCESS_FILE`, launch environment and startup identity panel |
+| Web answer/app fails to render | Correlate actual tool/audit results (`starmux logs -f`) before deciding whether execution failed; never automatically repeat a side-effecting call |
+| CLI changes do not affect the server | Check `starmux ls` and `starmux status` to ensure you are targeting the intended instance (`-i <name>`) |
 
 The local App, Core, proxy, database, provider and Tunnel have separate process lifecycles. Stopping Core stops new tool service; it does not automatically shut down the others. Persist private configuration and PostgreSQL/Caddy data, configure service startup deliberately, and repeat acceptance after reboot or deployment changes.
 

package/docs/SECURITY.md

@@ -3,13 +3,13 @@
 Starmux is a self-hosted connection and routing layer around real upstream MCP tools. Treat exposure to remote clients as a powerful privilege.
 
 - The default **restricted read-only** role enforces project-scoped access and disables arbitrary Shell/write operations.
-- The **trusted developer** role can run commands using your Mac account. In the owner-tested configuration, new `--code` / `--write` configurations use full OS-account permissions. Migrated Home-only configurations keep their previous sandbox until explicitly changed.
-- HTTP MCP listens on loopback by default. **Never expose the raw loopback port publicly.** Direct HTTPS requires a publicly reachable TLS endpoint **and real caller authentication, authorization and revocation**. DNS/TLS alone are insufficient.
-- OpenAI Tunnel is outbound and uses OpenAI's forwarding infrastructure. Tunnel readiness is **not** proof of independent caller authorization.
+- The **trusted coding** role (`starmux up --code`) can edit files and run commands using your OS account permissions. Migrated macOS Home-only configurations keep their previous sandbox until explicitly changed.
+- HTTP MCP listens on loopback (`127.0.0.1`) by default. **Never expose the raw loopback port publicly.** Direct HTTPS requires a publicly reachable TLS endpoint **and caller authentication**. DNS/TLS alone are insufficient.
+- OpenAI Tunnel is outbound and uses OpenAI's forwarding infrastructure. Tunnel readiness alone is **not** caller authorization unless paired with tunnel access controls or Starmux authentication.
 - **OAuth** mode validates tokens and allowed accounts/clients, and supports local session revocation, including refreshed tokens in that session. A fresh authorized session can restore access; session revocation is not an account ban.
-- Optional **Gateway API key** mode authenticates a client credential on every MCP request and supports independent revocation. The default **managed by ingress** mode does not authenticate callers in Core. See [access control](ACCESS_CONTROL.md). Keys inherit owner permissions and do not isolate trusted tools from owner-readable configuration.
+- **Bearer API key** mode authenticates a client credential on every MCP request and supports instant revocation. The default **`none` (`ingress`)** mode does not verify a token in Starmux. See [access control](ACCESS_CONTROL.md). Keys inherit your instance's workspace permissions.
 - Filesystem permissions, macOS TCC/FDA and permissions in the actual upstream Desktop Commander remain relevant.
 - Do not commit API keys, tunnel runtime profiles, passwords or protected files; use personal private configuration and report vulnerabilities privately.
 - Multi-user/multi-host orchestration and user-defined policy scripts are **not shipped** in this preview.
 
-See [connection steps](CONNECT_CHATGPT.md) and [release status](RELEASE_STATUS.md).
+See [connection steps](CONNECT_CHATGPT.md) and [platform support](PLATFORMS.md).