@aerostack/gateway

Connect Aerostack to your local AI runtime: pair from your phone, approve risky tool calls with a tap, and let your agent reach hundreds of MCP servers through one URL — no per-tool config, no token-paste dance.

What it does

Aerostack is the control plane for your AI agents. This package is the machine-side bridge that connects your local agent runtime (OpenClaw, Claude Code, Claude Desktop, Cursor, Cline, Goose, Windsurf, and any other MCP client) to an Aerostack Workspace.

Once paired, your agent gets:

• Mobile approval gates — tap to approve risky tool calls from the Aerostack mobile app
• Local Guardian — approval gates for local operations the agent runs on your machine: rm -rf, git push, deploys, file deletions, etc.
• All tools in one place — composed from many MCP servers, addressed through a single workspace
• Centralized OAuth — 27+ providers managed by Aerostack, never embedded in your agent
• Per-tool permissions — workspace tokens scope exactly which tools are reachable
• Usage tracking & audit — every tool call logged and metered

Quick Start

There are two ways to use this package. Pick the one that matches your setup.

Path A — OpenClaw + Aerostack Mobile (recommended)

If you run OpenClaw on your machine and want full mobile-driven approvals + chat:

# 1. Install once, globally
npm install -g @aerostack/gateway

# 2. Pair this machine — opens an interactive QR/code flow
aerostack-gateway init

init will:

1. Print a 6-digit pairing code (and a QR if your terminal supports it).
2. Open the Aerostack mobile app (iOS / Android) → Spaces → "+ connect another machine" → scan/enter the code.
3. Auto-write your workspace credentials, install the always-on LaunchAgent (macOS) / systemd unit (Linux), and add the Aerostack MCP entry to ~/.openclaw/openclaw.json.

Done. Your agent's risky tool calls now appear on your phone for approval.

To verify:

aerostack-gateway status

Path B — Plain MCP client (Claude Code / Desktop / Cline / etc.)

If you don't run OpenClaw and just want to connect an MCP client to a workspace:

npm install -g @aerostack/gateway

Get your workspace URL and token from the Aerostack Admin Dashboard → your workspace → Connect. The URL looks like:

https://api.aerostack.dev/api/gateway/ws/<workspace-slug>

Claude Code:

claude mcp add aerostack -- aerostack-gateway \
  --env AEROSTACK_WORKSPACE_URL=https://api.aerostack.dev/api/gateway/ws/your-slug \
  --env AEROSTACK_TOKEN=mwt_your_token_here

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aerostack": {
      "command": "aerostack-gateway",
      "env": {
        "AEROSTACK_WORKSPACE_URL": "https://api.aerostack.dev/api/gateway/ws/your-slug",
        "AEROSTACK_TOKEN": "mwt_your_token_here"
      }
    }
  }
}

Cline (VS Code) — settings under cline.mcpServers:

{
  "aerostack": {
    "command": "aerostack-gateway",
    "env": {
      "AEROSTACK_WORKSPACE_URL": "https://api.aerostack.dev/api/gateway/ws/your-slug",
      "AEROSTACK_TOKEN": "mwt_your_token_here"
    }
  }
}

Cursor / Goose / any HTTP-native MCP client — point at the workspace URL directly with Authorization: Bearer mwt_.... The bridge isn't needed.

To verify connection:

AEROSTACK_WORKSPACE_URL="..." AEROSTACK_TOKEN="..." aerostack-gateway --check

CLI Reference

| Command | What it does | |---|---| | aerostack-gateway init | Interactive pair flow. Writes token + LaunchAgent + MCP entry. | | aerostack-gateway status | Paired? Connected? Versions? Service state? | | aerostack-gateway doctor | Run preflight checks and offer fixes. | | aerostack-gateway logs [--follow] | Tail connector + exec-daemon logs. | | aerostack-gateway unpair | Stop services, wipe pairing state, restart OpenClaw gateway. | | aerostack-gateway --check | Legacy MCP-bridge connection check (Path B). | | aerostack-gateway --version | Print version and exit. |

How It Works

When paired (Path A), three processes run on your machine — all managed by your OS service manager (launchd on macOS, systemd on Linux):

┌──────────────────────────────── your machine ───────────────────────────────┐
│                                                                             │
│  dev.aerostack.connector       persistent gateway-WS ↔ chat-relay-WS bridge │
│  dev.aerostack.exec-daemon     owns the exec-approvals socket               │
│  dev.aerostack.watchdog        keeps the other two healthy                  │
│                                                                             │
│  Plus: an MCP child spawned by OpenClaw from ~/.openclaw/openclaw.json      │
│                                                                             │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │ HTTPS + WSS
                                   ▼
                         ┌──────────────────────┐
                         │  Aerostack Worker    │
                         └──────────┬───────────┘
                                    │
                         ┌──────────▼───────────┐
                         │  Aerostack Mobile    │
                         │  (iOS / Android)     │
                         └──────────────────────┘

When unpaired (Path B), the bridge runs as a stdio MCP server child of your AI tool — no LaunchAgents, no always-on processes. Same package, two modes.

Local Guardian

Approval gates for local operations — file deletion, destructive shell commands, git push, deploys. The agent calls aerostack__local_guardian before acting on your machine; you get a push notification on your phone and approve or reject in seconds.

| Category | Examples | |---|---| | file_delete | Deleting or overwriting files | | shell_destructive | rm -rf, DROP TABLE, etc. | | git_push | git push, force push, git reset --hard | | config_modify | .env, credentials, production configs | | deploy | Deploy, publish, release to any environment | | database | Direct database mutations outside migrations |

Disconnect / Unpair

You can disconnect from the mobile app (Spaces → agent → "disconnect agent") or from the CLI (aerostack-gateway unpair). Both paths cleanly tear down the local connector and revoke the workspace token server-side. From mobile, the connector sees a workspace_unpaired WebSocket frame and tears down within ~25 ms — it doesn't sit polling a revoked token.

Configuration

Path A doesn't need any of these — init writes them for you. Path B uses them as env vars on the MCP child:

| Variable | Required | Description | |---|---|---| | AEROSTACK_WORKSPACE_URL | Path B | https://api.aerostack.dev/api/gateway/ws/<slug> | | AEROSTACK_TOKEN | Path B | Workspace token (mwt_…) — get from dashboard | | AEROSTACK_LOG_LEVEL | No | debug / info (default) / warn / error |

Troubleshooting

aerostack-gateway status     # is everything paired and connected?
aerostack-gateway doctor     # automated preflight + suggested fixes
aerostack-gateway logs -f    # tail the connector + exec-daemon

Common issues:

| Problem | Fix | |---|---| | aerostack-gateway: command not found | npm install -g @aerostack/gateway | | Path B: AEROSTACK_WORKSPACE_URL is required | The MCP client isn't passing env vars. Check your client's env config block. | | Token shows 401 in status | Pairing was revoked. Re-pair: aerostack-gateway init. | | Mobile shows daemon offline but status shows running | Likely a transient WS reconnect. Wait 30 s; if it persists, run doctor. | | OpenClaw: tools not showing | Send any message via Telegram or another channel to initialize the session. |

Supported MCP Methods

tools/list, tools/call (with approval gates), resources/list, resources/read, prompts/list, prompts/get.

Requirements

• Node.js 22+
• macOS or Linux (Windows support is best-effort — file an issue)
• An Aerostack account (sign up)

Links

• Aerostack Docs
• Aerostack Admin
• Aerostack Mobile
• MCP Specification

License

MIT