@stage-labs/metro 0.1.0-beta.32 → 0.1.0-beta.33

package/dist/cli.js

@@ -16,9 +16,11 @@ const USAGE = `metro — the command line for your MCP connectors
 
   metro start <agent-id> [--detach]
                   run that agent's stations on this machine
-  metro serve [--port <n>]
+  metro serve [--port <n>] [--tunnel]
                   run a daemon of your own: its agents and stations live in ~/.metro/agents
-                  here, and metro.box manages it through the link it prints
+                  here, and metro.box manages it through the link it prints; --tunnel adds
+                  a public https address through a Cloudflare quick tunnel (needs
+                  cloudflared, no account) so the link works from anywhere
   metro stop [agent-id]
                   stop every metro daemon on this machine, however it was started
   metro status <agent-id>

package/dist/serve.js

@@ -1,9 +1,10 @@
+import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { findBun, localPort, runtimeDir, SERVER_ENTRY, spawnPlan, } from './runtime.js';
 const SCRUBBED = new Set(['METRO_RUN_TOKEN', 'METRO_AGENT', 'DATABASE_URL']);
 const PORT_FLAG = /^--port=(.*)$/;
-const USAGE = 'usage: metro serve [--port <n>]';
+const USAGE = 'usage: metro serve [--port <n>] [--tunnel]';
 function portOf(raw) {
     const n = Number(raw);
     if (raw === undefined || raw === '' || !Number.isInteger(n) || n < 1 || n > 65535)
@@ -12,8 +13,13 @@ function portOf(raw) {
 }
 export function parseServeArgs(argv) {
     let port = localPort();
+    let tunnel = false;
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] ?? '';
+        if (arg === '--tunnel') {
+            tunnel = true;
+            continue;
+        }
         const inline = PORT_FLAG.exec(arg);
         if (inline) {
             port = portOf(inline[1]);
@@ -26,7 +32,14 @@ export function parseServeArgs(argv) {
         }
         throw new Error(`unknown argument '${arg}' — ${USAGE}`);
     }
-    return { port };
+    return { port, tunnel };
+}
+export function findCloudflared() {
+    const found = spawnSync('cloudflared', ['--version'], { stdio: 'ignore' });
+    if (found.error !== undefined || found.status !== 0)
+        throw new Error('metro serve --tunnel needs cloudflared, which is not on PATH.\n' +
+            'Install it with:  brew install cloudflared  (macOS), or from\n' +
+            'https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/downloads/');
 }
 export function serveStateDir() {
     const xdg = process.env.XDG_CACHE_HOME?.trim();
@@ -46,12 +59,15 @@ export function servePlan(opts) {
             METRO_HTTP_HOST: process.env.METRO_HTTP_HOST ?? '127.0.0.1',
             METRO_TRAINS_DIR: join(opts.dir, 'trains'),
             METRO_STATE_DIR: process.env.METRO_STATE_DIR ?? serveStateDir(),
+            ...(opts.tunnel ? { METRO_TUNNEL: 'quick' } : {}),
         },
     };
 }
 export function serve(argv) {
-    const { port } = parseServeArgs(argv);
-    const plan = servePlan({ dir: runtimeDir(), port });
+    const { port, tunnel } = parseServeArgs(argv);
+    if (tunnel)
+        findCloudflared();
+    const plan = servePlan({ dir: runtimeDir(), port, tunnel });
     process.stderr.write(`Starting a metro daemon of your own on http://127.0.0.1:${String(port)}\n`);
     return spawnPlan(plan);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.32",
+  "version": "0.1.0-beta.33",
   "description": "The metro command line. Sign in once per machine, then hand your MCP connector list to Claude Code without the credentials touching disk, argv or shell history.",
   "license": "MIT",
   "repository": {

package/runtime/node_modules/@metro-labs/mcp/src/daemon/attach-serve.ts

@@ -14,7 +14,7 @@ import {
 import { attachmentOwner, recordAttachmentOwner } from './attach-owner.js';
 import { grantAllows, issueAttachmentGrant } from './attach-grant.js';
 import { errMsg, log } from './log.js';
-import { loadTunnelConfig, webhookPort } from './tunnel.js';
+import { configuredTunnelHost, currentTunnelUrl, webhookPort } from './tunnel.js';
 import { isLocalMode } from './paths.js';
 
 function authorized(req: IncomingMessage, name: string): boolean {
@@ -31,7 +31,9 @@ const DEFAULT_PUBLIC_BASE = 'https://mcp.metro.box';
 export function publicBaseUrl(): string | null {
   const env = process.env.METRO_PUBLIC_URL?.trim();
   if (env) return env.replace(/\/+$/, '');
-  const host = loadTunnelConfig()?.hostname;
+  const live = currentTunnelUrl();
+  if (live !== null) return live;
+  const host = configuredTunnelHost();
   return host ? `https://${host}` : null;
 }
 

package/runtime/node_modules/@metro-labs/mcp/src/daemon/boot.ts

@@ -15,9 +15,15 @@ import { installCrashGuard, markDaemonReady } from './crash-guard.js';
 import {
   loadTunnelConfig,
   Tunnel,
+  tunnelConfigFromEnv,
   warnOnLegacyWebhooks,
   webhookPort,
 } from './tunnel.js';
+import {
+  localConnectHint,
+  publicConnectHint,
+  tunnelPendingHint,
+} from './connect-hint.js';
 import { TrainSupervisor } from './supervisor.js';
 import {
   makeEmit,
@@ -39,7 +45,7 @@ import {
 import { loadAgentForRuntime, localAgentKey } from '../db/materialize.js';
 import { fileSource } from '../db/file-source.js';
 import { ensureLocalSessionSecret } from './local-secret.js';
-import { localConnectHint, localSessionApis } from './local-mode.js';
+import { localSessionApis } from './local-mode.js';
 import type { ModeInfo } from './mode-api.js';
 import type { SessionApis } from './session-apis.js';
 import {
@@ -128,8 +134,12 @@ supervisor.onTrainEvent((env, train) => {
 });
 
 let webhookServer: Server | null = null;
-const tunnelCfg = loadTunnelConfig();
-const tunnel = tunnelCfg ? new Tunnel(tunnelCfg, webhookPort()) : null;
+const tunnelCfg = loadTunnelConfig() ?? tunnelConfigFromEnv();
+const tunnel = tunnelCfg ? new Tunnel(tunnelCfg, webhookPort(), announcePublic) : null;
+
+function announcePublic(url: string): void {
+  process.stderr.write(`\n${publicConnectHint(url)}`);
+}
 
 setTrainCallBackend((train, action, args) =>
   supervisor.call(train, action, args),
@@ -140,7 +150,10 @@ const linkedSource = runtime === null ? null : httpSource(runtime);
 const localSource = linkedSource ?? (isLocalMode() ? fileSource : null);
 
 function announceLocalEndpoint(): void {
-  if (isLocalMode()) process.stderr.write(`\n${localConnectHint(webhookPort())}`);
+  if (isLocalMode())
+    process.stderr.write(
+      `\n${tunnel === null ? localConnectHint(webhookPort()) : tunnelPendingHint()}`,
+    );
   const key = localAgentKey();
   if (key === null) {
     if (isLocalMode()) log.info('no agent on this machine yet');

package/runtime/node_modules/@metro-labs/mcp/src/daemon/connect-hint.ts

@@ -0,0 +1,33 @@
+import { hostname } from 'node:os';
+
+const uiBase = (): string => process.env.METRO_UI_URL ?? 'https://metro.box';
+
+export const connectLink = (base: string): string =>
+  `${uiBase()}/#/connect/${encodeURIComponent(base)}`;
+
+export function localConnectHint(port: number): string {
+  const here = `http://127.0.0.1:${String(port)}`;
+  const forward = `ssh -L ${String(port)}:127.0.0.1:${String(port)} ${hostname()}`;
+  return [
+    'Manage this machine from the web UI:',
+    '',
+    `  ${connectLink(here)}`,
+    '',
+    `From another computer, forward the port first:  ${forward}`,
+    '',
+  ].join('\n');
+}
+
+export function publicConnectHint(url: string): string {
+  return [
+    'Manage this machine from the web UI, from anywhere:',
+    '',
+    `  ${connectLink(url)}`,
+    '',
+    'Sign in right away: the first wallet to sign in owns this machine.',
+    '',
+  ].join('\n');
+}
+
+export const tunnelPendingHint = (): string =>
+  'Bringing up a public address through a Cloudflare quick tunnel…\n';

package/runtime/node_modules/@metro-labs/mcp/src/daemon/local-mode.ts

@@ -129,20 +129,6 @@ const agentConnectorApi: AgentConnectorApiDeps = {
     Promise.reject(new ApiError('a local daemon has no pairing codes', 400)),
 };
 
-export function localConnectHint(port: number): string {
-  const ui = process.env.METRO_UI_URL ?? 'https://metro.box';
-  const here = `http://127.0.0.1:${String(port)}`;
-  const forward = `ssh -L ${String(port)}:127.0.0.1:${String(port)} ${hostname()}`;
-  return [
-    'Manage this machine from the web UI:',
-    '',
-    `  ${ui}/#/connect/${encodeURIComponent(here)}`,
-    '',
-    `From another computer, forward the port first:  ${forward}`,
-    '',
-  ].join('\n');
-}
-
 export function localModeInfo(): ModeInfo {
   return { mode: 'local', owner: localOwner(), project: LOCAL_PROJECT_ID };
 }

package/runtime/node_modules/@metro-labs/mcp/src/daemon/tunnel.ts

@@ -1,5 +1,6 @@
 import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { timingSafeEqual } from 'node:crypto';
+import { Resolver } from 'node:dns/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { STATE_DIR } from './paths.js';
@@ -10,11 +11,61 @@ const FILE = join(STATE_DIR, 'tunnel.json');
 const LEGACY_WEBHOOKS_FILE = join(STATE_DIR, 'webhooks.json');
 const RESTART_DELAY_MS = 2_000;
 
-interface TunnelConfig {
+interface NamedTunnel {
   name: string;
   hostname: string;
 }
 
+interface QuickTunnel {
+  quick: true;
+}
+
+export type TunnelConfig = NamedTunnel | QuickTunnel;
+
+const isQuick = (cfg: TunnelConfig): cfg is QuickTunnel => 'quick' in cfg;
+
+export const tunnelConfigFromEnv = (): TunnelConfig | null =>
+  process.env.METRO_TUNNEL?.trim() === 'quick' ? { quick: true } : null;
+
+const QUICK_URL_RE = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
+
+export const quickTunnelUrlIn = (text: string): string | null =>
+  QUICK_URL_RE.exec(text)?.[0] ?? null;
+
+let liveUrl: string | null = null;
+
+export const currentTunnelUrl = (): string | null => liveUrl;
+
+export type Resolves = (host: string) => Promise<boolean>;
+
+const PUBLIC_RESOLVERS = ['1.1.1.1', '1.0.0.1'];
+const RESOLVE_EVERY_MS = 3_000;
+const RESOLVE_GIVE_UP_MS = 180_000;
+
+export async function resolvesAtCloudflare(host: string): Promise<boolean> {
+  const resolver = new Resolver();
+  resolver.setServers(PUBLIC_RESOLVERS);
+  try {
+    return (await resolver.resolve4(host)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function untilResolvable(host: string, resolves: Resolves): Promise<boolean> {
+  const deadline = Date.now() + RESOLVE_GIVE_UP_MS;
+  while (Date.now() < deadline) {
+    if (await resolves(host)) return true;
+    await new Promise((r) => setTimeout(r, RESOLVE_EVERY_MS));
+  }
+  return false;
+}
+
+export function configuredTunnelHost(): string | null {
+  const cfg = loadTunnelConfig();
+  return cfg !== null && !isQuick(cfg) ? cfg.hostname : null;
+}
+
 export interface Endpoint {
   id: string;
   webhookId?: string;
@@ -98,6 +149,12 @@ function fetchTunnelToken(name: string): string | null {
   return token.length > 0 ? token : null;
 }
 
+interface Plan {
+  args: string[];
+  env: NodeJS.ProcessEnv;
+  mode: string;
+}
+
 export class Tunnel {
   private child: ChildProcess | null = null;
   private closed = false;
@@ -106,57 +163,88 @@ export class Tunnel {
   constructor(
     private cfg: TunnelConfig,
     private port: number,
+    private onUrl: (url: string) => void = () => undefined,
+    private resolves: Resolves = resolvesAtCloudflare,
   ) {}
 
   get hostname(): string {
-    return this.cfg.hostname;
+    if (!isQuick(this.cfg)) return this.cfg.hostname;
+    return liveUrl === null ? '' : new URL(liveUrl).host;
+  }
+
+  private origin(): string {
+    return `http://127.0.0.1:${String(this.port)}`;
+  }
+
+  private plan(): Plan {
+    if (isQuick(this.cfg))
+      return {
+        args: ['--no-autoupdate', 'tunnel', '--url', this.origin()],
+        env: process.env,
+        mode: 'quick',
+      };
+    if (this.token === undefined) this.token = fetchTunnelToken(this.cfg.name);
+    const args = ['--no-autoupdate', 'tunnel', 'run', '--url', this.origin()];
+    if (!this.token) args.push(this.cfg.name);
+    return {
+      args,
+      env: this.token ? { ...process.env, TUNNEL_TOKEN: this.token } : process.env,
+      mode: this.token ? 'token' : 'named',
+    };
+  }
+
+  private noticeUrl(text: string): void {
+    if (!isQuick(this.cfg)) return;
+    const url = quickTunnelUrlIn(text);
+    if (url === null || url === liveUrl) return;
+    liveUrl = url;
+    log.info({ url }, 'quick tunnel up; waiting for its name to resolve');
+    this.announceWhenResolvable(url).catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'quick tunnel: announce failed');
+    });
+  }
+
+  private async announceWhenResolvable(url: string): Promise<void> {
+    const resolved = await untilResolvable(new URL(url).host, this.resolves);
+    if (liveUrl !== url) return;
+    if (!resolved) log.warn({ url }, 'quick tunnel name still not resolving; announcing anyway');
+    this.onUrl(url);
   }
 
   start(): void {
     if (this.closed) return;
-    if (this.token === undefined) this.token = fetchTunnelToken(this.cfg.name);
-    const mode = this.token ? 'token' : 'named';
+    const plan = this.plan();
     log.info(
-      {
-        name: this.cfg.name,
-        hostname: this.cfg.hostname,
-        port: this.port,
-        mode,
-      },
+      { tunnel: isQuick(this.cfg) ? 'quick' : this.cfg.name, port: this.port, mode: plan.mode },
       'cloudflared tunnel starting',
     );
-    const args = [
-      '--no-autoupdate',
-      'tunnel',
-      'run',
-      '--url',
-      `http://127.0.0.1:${this.port}`,
-    ];
-    if (!this.token) args.push(this.cfg.name);
-    const env = this.token
-      ? { ...process.env, TUNNEL_TOKEN: this.token }
-      : process.env;
-    this.child = spawn('cloudflared', args, {
+    const child = spawn('cloudflared', plan.args, {
       stdio: ['ignore', 'pipe', 'pipe'],
-      env,
+      env: plan.env,
     });
-    this.child.stderr?.on('data', (d: Buffer | string) => {
-      log.debug(
-        {
-          cloudflared: (typeof d === 'string' ? d : d.toString('utf8')).trim(),
-        },
-        'cloudflared',
-      );
+    this.child = child;
+    child.stderr?.on('data', (d: Buffer | string) => {
+      const text = (typeof d === 'string' ? d : d.toString('utf8')).trim();
+      log.debug({ cloudflared: text }, 'cloudflared');
+      this.noticeUrl(text);
     });
-    this.child.on('exit', (code) => {
+    child.on('exit', (code) => {
       this.child = null;
+      liveUrl = null;
       if (this.closed) return;
       log.warn({ code }, 'cloudflared exited; restarting');
       setTimeout(() => {
         this.start();
       }, RESTART_DELAY_MS);
     });
-    this.child.on('error', (err) => {
+    child.on('error', (err) => {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        this.closed = true;
+        log.error(
+          'cloudflared is not installed, so there is no public address; install it and restart',
+        );
+        return;
+      }
       log.warn({ err: errMsg(err) }, 'cloudflared spawn error');
     });
   }

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.32"
+  "version": "0.1.0-beta.33"
 }