Architectural Bridge for Local Agent Gateways

Modern browser-based agent UIs face a common networking hurdle: connecting a public-facing Next.js frontend to a local, private agent gateway (like OpenClaw) without exposing your backend to the public internet or hitting frustrating Cloudflare WebSocket timeouts.

This skill implements the Two-Hop WebSocket Proxy architecture. It provides a robust communication layer that sits between your Next.js App Router and your local agent services. By mediating the connection through a Node.js shim, it enables real-time service status, log streaming, and action whitelisting while ensuring your Gateway remains securely on your private network.

What it does

• Two-Hop WebSocket Proxy: Proxies real-time messages from Browser to Next.js Server to Local Gateway, surviving restarts and timeouts.
• Secure Action Whitelisting: Provides API routes with hardcoded agent/action whitelists to prevent unauthorized command execution.
• Resilient Client Hook: Includes a React useBridge hook with automated exponential backoff and connection state management.
• Unified Agent API: Standardized routes for service status, log tailing, and Telegram bot passthrough with signed timeouts.

Why use this skill?

While you could try to prompt an AI to "proxy a websocket," this skill delivers a production-hardened pattern used in real agent-orchestration stacks. It handles the edge cases developers often miss: graceful degradation when the bridge is offline, explicit timeout signaling to prevent hung fetches, and a "fail-closed" security model that avoids environment variable leakage.