Architecture

Overview

┌──────────────┐     outbound WSS     ┌──────────┐     MCP/SSH     ┌──────────┐
│  Your Machine│ ──────────────────▶  │  Relay   │ ◀──────────────  │ AI Agent │
│  (flexx)     │                      │          │                  │          │
└──────────────┘                      └──────────┘                  └──────────┘
                                           │
                                           │ internal API
                                           ▼
                                      ┌──────────┐
                                      │   BFF    │
                                      │ (API GW) │
                                      └──────────┘
                                           │
                                     ┌─────┴─────┐
                                     ▼           ▼
                                 PostgreSQL    Redis

Components

flexx (daemon)

The Go binary running on your machine. It:

• Connects outbound to the relay via WebSocket
• Registers its capabilities (available tools, system info)
• Executes MCP tool calls received from the relay
• Runs an embedded SSH server for remote shell access
• Auto-discovers installed tools (ripgrep, Chrome, Docker, etc.)

Relay

A Bun/Hono server that acts as the hub. It:

• Accepts WebSocket connections from daemons (remotes)
• Accepts MCP requests from AI agents via HTTP + SSE
• Routes MCP tool calls to the correct remote
• Proxies SSH connections between agents and remotes
• Validates authentication tokens with the BFF
• Serves OAuth protected resource metadata

BFF (API Gateway)

A Bun/Hono server that handles:

• User authentication (Better Auth for sessions, API keys for CLI)
• OAuth 2.1 authorization server (PKCE, consent, token management)
• Remote registration and management
• Billing and usage tracking
• Internal token validation for relay

Dashboard

A Next.js web application for:

• Onboarding new users with step-by-step CLI setup
• Managing remotes, API keys, and settings
• MCP configuration snippets for Cursor, Claude, ChatGPT, etc.
• OAuth consent flow for AI agent authorization
• Billing management

Authentication

OAuth 2.1 (MCP clients)

AI agents authenticate via OAuth 2.1 with PKCE:

1. AI agent discovers OAuth metadata at /.well-known/oauth-authorization-server
2. Agent redirects user to consent page on the dashboard
3. User approves access and selects which remote to connect
4. Agent receives an authorization code and exchanges it for tokens
5. Agent uses the access token for MCP requests

Scopes: remotes:read, remotes:write, tools:execute, profile:read

API keys (CLI)

MCP request flow

1. AI agent sends MCP request to relay with OAuth bearer token
2. Relay validates the token with BFF's internal API
3. BFF returns the user, org, remote ID, and scopes
4. Relay finds the connected daemon for that remote
5. Relay forwards the tool call to the daemon via WebSocket
6. Daemon executes the tool and returns the result
7. Relay forwards the result back to the AI agent

Security model

• Outbound only — your machine never listens on any port
• End-to-end TLS — all WebSocket and HTTP connections are encrypted
• OAuth 2.1 with PKCE — prevents token interception attacks
• Workspace scoping — file operations are restricted to configured paths
• Command filtering — dangerous commands are blocked by default
• Token revocation — access can be revoked from the dashboard at any time