@aerostack/gateway 0.17.2 → 0.17.4

package/README.md

@@ -116,12 +116,22 @@ Token: mwt_your_token_here  (Authorization: Bearer header)
 
 ### 3. Verify your connection
 
-Run the built-in diagnostic check to make sure everything is working:
+Run the built-in diagnostic to verify everything works end-to-end:
 
 ```bash
+# Option A: if npx works on your system
 AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace" \
 AEROSTACK_TOKEN="mwt_your_token_here" \
-npx @aerostack/gateway --check
+npx -y @aerostack/gateway --check
+```
+
+```bash
+# Option B: install globally first (recommended for servers/VMs)
+npm install -g @aerostack/gateway
+
+export AEROSTACK_WORKSPACE_URL="https://mcp.aerostack.dev/ws/your-workspace"
+export AEROSTACK_TOKEN="mwt_your_token_here"
+aerostack-gateway --check
 ```
 
 You should see:
@@ -141,6 +151,8 @@ You should see:
 
 If any step fails, the output tells you exactly what to fix.
 
+> **Tip:** After global install, you can simplify your MCP config to use `"command": "aerostack-gateway"` instead of `"command": "npx"` — faster startup, no network fetch.
+
 ### 4. Use it
 
 ```
@@ -152,14 +164,38 @@ Tools are namespaced as `{server}__{tool}` (e.g., `github__create_issue`, `slack
 
 ## Troubleshooting
 
+**Step-by-step debug:**
+
+```bash
+# 1. Can the gateway reach your workspace?
+aerostack-gateway --check
+
+# 2. If using OpenClaw, is the gateway running?
+openclaw gateway status
+
+# 3. Is the MCP server configured?
+openclaw mcp show aerostack
+
+# 4. Start the gateway if not running
+openclaw gateway start
+
+# 5. Run OpenClaw's built-in diagnostics
+openclaw doctor
+```
+
+**Common issues:**
+
 | Problem | Solution |
 |---------|----------|
-| `npx` hangs or fails | Run `npm install -g @aerostack/gateway` instead, then use `"command": "aerostack-gateway"` |
+| `npx` hangs or fails | Run `npm install -g @aerostack/gateway` instead, then use `"command": "aerostack-gateway"` in your MCP config |
+| `AEROSTACK_WORKSPACE_URL is required` | The env vars aren't being passed. Use `export` before running `--check`, or verify your MCP config has the `env` block |
+| `npx` error: "could not determine executable" | Install globally: `npm install -g @aerostack/gateway`, then run `aerostack-gateway --check` |
 | "Token invalid" in `--check` | Regenerate token at dashboard → Workspace → Tokens |
-| "0 tools found" | Add MCP servers to your workspace in the dashboard first |
+| "0 workspace tools" | Built-in tools (Local Guardian, Chat) are always available. Add MCP servers to your workspace for more tools |
 | OpenClaw: tools not showing | Send a message via Telegram or another channel to initialize the session |
 | Dashboard shows "No agents" | Run `--check` to verify, or wait 2 minutes for the heartbeat to register |
 | "Workspace unreachable" | Check the URL format: `https://mcp.aerostack.dev/ws/your-workspace` |
+| Multiple phantom agents in dashboard | Update to latest version (`npm install -g @aerostack/gateway@latest`) — fixed in 0.17.2 |
 
 ## How It Works
 

package/dist/index.js

@@ -51,9 +51,9 @@ ${V}`:V}}}const x=new we({name:"aerostack-gateway",version:"0.15.29"},{capabilit
   Fix: Regenerate token at your dashboard \u2192 Workspace \u2192 Tokens
 `),process.exit(1)),e(`  \u274C Workspace unreachable      (HTTP ${t.status})`),e(`
   Fix: Check AEROSTACK_WORKSPACE_URL is correct
-`),process.exit(1));const n=await t.json();e(`  \u2705 Workspace URL reachable    (${m})`),e(`  \u2705 Token valid                (${n.token_name}, role: ${n.token_role})`),e(`  \u2705 Workspace connected        ("${n.workspace}")`),e(`  \u2705 Tools available             (${n.mcp_servers} tools)`);try{const s=await fetch(`${m}/chat/heartbeat`,{method:"POST",headers:{Authorization:`Bearer ${h}`,"Content-Type":"application/json"},body:JSON.stringify({agent_type:"check",user_agent:"aerostack-gateway/check",bridge_id:"check"}),signal:AbortSignal.timeout(1e4)});e(s.ok?"  \u2705 Dashboard registration     (bridge visible in admin)":`  \u26A0\uFE0F  Dashboard registration     (returned ${s.status})`)}catch{e("  \u26A0\uFE0F  Dashboard registration     (heartbeat failed \u2014 non-fatal)")}e(`
+`),process.exit(1));const n=await t.json();e(`  \u2705 Workspace URL reachable    (${m})`),e(`  \u2705 Token valid                (${n.token_name}, role: ${n.token_role})`),e(`  \u2705 Workspace connected        ("${n.workspace}")`);const s=4,o=(n.mcp_servers??0)+s;e(`  \u2705 Tools available             (${o} tools: ${n.mcp_servers} workspace + ${s} built-in)`);try{const a=await fetch(`${m}/chat/heartbeat`,{method:"POST",headers:{Authorization:`Bearer ${h}`,"Content-Type":"application/json"},body:JSON.stringify({agent_type:"check",user_agent:"aerostack-gateway/check",bridge_id:"check"}),signal:AbortSignal.timeout(1e4)});e(a.ok?"  \u2705 Dashboard registration     (bridge visible in admin)":`  \u26A0\uFE0F  Dashboard registration     (returned ${a.status})`)}catch{e("  \u26A0\uFE0F  Dashboard registration     (heartbeat failed \u2014 non-fatal)")}e(`
   All checks passed. Your agent is connected.`),e(`  Dashboard: ${n.dashboard_url||"https://app.aerostack.dev"}
-`),n.mcp_servers===0&&e(`  Note: 0 tools found. Add MCP servers or functions to your workspace first.
+`),n.mcp_servers===0&&e(`  Tip: Add MCP servers to your workspace for more tools. Built-in tools (Local Guardian, Chat) are ready.
 `),process.exit(0)}catch(t){t?.name==="TimeoutError"||t?.name==="AbortError"?(e("  \u274C Workspace unreachable      (timeout after 10s)"),e(`
   Fix: Check AEROSTACK_WORKSPACE_URL and your network connection
 `)):(e(`  \u274C Connection failed          (${t?.message??"unknown error"})`),e(`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aerostack/gateway",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "stdio-to-HTTP bridge connecting any MCP client to Aerostack Workspaces",
   "author": "Aerostack",
   "license": "MIT",