# openai/tunnel-client architecture

> Architecture diagram of the GitHub repository openai/tunnel-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openai/tunnel-client
- Repository: https://github.com/openai/tunnel-client

## Overview

Secure MCP Tunnel is a customer-run Go agent that keeps a private MCP server off the public internet while connecting it to OpenAI-hosted products. Its main workflow is to accept local MCP traffic, dispatch requests through a control-plane tunnel, and return responses; operators can inspect readiness and runtime behavior through a local admin UI. The repository also includes OAuth discovery, Harpoon-mediated HTTP tools, bundled cloudflared supervision, and Codex-managed runtime support. Wiring is grounded in the sampled app modules; some internal request-level handoffs are not shown.

Main entry points: [`adminui/src/App.svelte`](https://github.com/openai/tunnel-client/blob/master/adminui/src/App.svelte) (Admin UI shell), [`adminui/src/lib/api.ts`](https://github.com/openai/tunnel-client/blob/master/adminui/src/lib/api.ts) (UI API client), [`pkg/runtimeapp/app.go`](https://github.com/openai/tunnel-client/blob/master/pkg/runtimeapp/app.go) (Runtime composition), [`pkg/app/app.go`](https://github.com/openai/tunnel-client/blob/master/pkg/app/app.go) (Full-client composition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Tunnel runtime"]
  node_runtime_entry["Runtime composition<br/>[app.go]"]
  node_full_entry["Full-client composition<br/>[app.go]"]
  node_cloudflared_runtime["Cloudflared supervisor<br/>[supervisor.go]"]
end

subgraph group_services["Runtime services"]
  node_controlplane["Control-plane client"]
  node_dispatcher["MCP dispatcher<br/>[processor.go]"]
  node_mcpclient["MCP client transport"]
  node_oauth["OAuth discovery<br/>[discovery.go]"]
  node_harpoon_adapter["Harpoon adapter<br/>[server.go]"]
  node_harpoon_core["Harpoon tools<br/>[server.go]"]
  node_local_proxy["Local proxy<br/>[localproxy.go]"]
end

subgraph group_operations["Operations UI"]
  node_admin_backend["Admin services<br/>[startup.go]"]
  node_web_app["Admin UI shell<br/>[App.svelte]"]
  node_api_client["UI API client<br/>[api.ts]"]
  node_overview["Overview panel"]
  node_metrics["Metrics panel"]
  node_oauth_panel["OAuth panel<br/>[OAuthPanel.svelte]"]
  node_harpoon_panel["Harpoon panel"]
  node_system_panel["System panel<br/>[SystemPanel.svelte]"]
  node_logs_panel["Logs panel<br/>[LogsPanel.svelte]"]
  node_codex_panel["Codex panel<br/>[CodexPanel.svelte]"]
end

subgraph group_codex["Codex management"]
  node_codex_manager["Codex runtime manager<br/>[manager.go]"]
  node_codex_session["Managed runtime session<br/>[session.go]"]
end

node_operator(("Operator"))
node_mcpserver(("Private MCP server"))
node_openai(("OpenAI tunnel service"))

node_mcpserver -.->|"serves MCP"| node_mcpclient
node_mcpclient -.->|"forwards requests"| node_dispatcher
node_dispatcher -.->|"polls tunnel"| node_controlplane
node_controlplane -->|"exchanges tunnel data"| node_openai
node_runtime_entry -->|"wires"| node_controlplane
node_runtime_entry -->|"wires"| node_dispatcher
node_runtime_entry -->|"wires"| node_mcpclient
node_runtime_entry -->|"wires"| node_oauth
node_runtime_entry -->|"wires"| node_harpoon_core
node_full_entry -->|"wires"| node_admin_backend
node_full_entry -->|"wires"| node_harpoon_adapter
node_full_entry -->|"starts supervisor"| node_cloudflared_runtime
node_harpoon_adapter -->|"adapts"| node_harpoon_core
node_operator -->|"opens dashboard"| node_web_app
node_web_app -.->|"requests status"| node_admin_backend
node_web_app -->|"renders"| node_overview
node_web_app -->|"renders"| node_metrics
node_web_app -->|"renders"| node_oauth_panel
node_web_app -->|"renders"| node_harpoon_panel
node_web_app -->|"renders"| node_system_panel
node_web_app -->|"renders"| node_logs_panel
node_web_app -->|"renders"| node_codex_panel
node_overview -->|"fetches status"| node_api_client
node_metrics -->|"fetches metrics"| node_api_client
node_oauth_panel -->|"fetches OAuth"| node_api_client
node_harpoon_panel -->|"fetches targets"| node_api_client
node_system_panel -->|"fetches system data"| node_api_client
node_logs_panel -->|"fetches logs"| node_api_client
node_codex_panel -->|"requests Codex data"| node_api_client
node_codex_panel -.->|"manages runtimes"| node_codex_manager
node_codex_manager -->|"starts sessions"| node_codex_session

click node_runtime_entry "https://github.com/openai/tunnel-client/blob/master/pkg/runtimeapp/app.go"
click node_full_entry "https://github.com/openai/tunnel-client/blob/master/pkg/app/app.go"
click node_cloudflared_runtime "https://github.com/openai/tunnel-client/blob/master/pkg/cloudflared/runtime/supervisor.go"
click node_controlplane "https://github.com/openai/tunnel-client/blob/master/pkg/controlplane/internal/tunnel_service_client.go"
click node_dispatcher "https://github.com/openai/tunnel-client/blob/master/pkg/dispatcher/internal/processor.go"
click node_mcpclient "https://github.com/openai/tunnel-client/blob/master/pkg/mcpclient/serialized_forwarding_transport.go"
click node_oauth "https://github.com/openai/tunnel-client/blob/master/pkg/oauth/discovery.go"
click node_harpoon_adapter "https://github.com/openai/tunnel-client/blob/master/pkg/harpoon/server.go"
click node_harpoon_core "https://github.com/openai/tunnel-client/blob/master/pkg/runtimeharpoon/server.go"
click node_local_proxy "https://github.com/openai/tunnel-client/blob/master/pkg/localproxy/localproxy.go"
click node_admin_backend "https://github.com/openai/tunnel-client/blob/master/pkg/adminui/startup.go"
click node_web_app "https://github.com/openai/tunnel-client/blob/master/adminui/src/App.svelte"
click node_api_client "https://github.com/openai/tunnel-client/blob/master/adminui/src/lib/api.ts"
click node_overview "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/OverviewPanel.svelte"
click node_metrics "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/MetricsPanel.svelte"
click node_oauth_panel "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/OAuthPanel.svelte"
click node_harpoon_panel "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/HarpoonPanel.svelte"
click node_system_panel "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/SystemPanel.svelte"
click node_logs_panel "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/LogsPanel.svelte"
click node_codex_panel "https://github.com/openai/tunnel-client/blob/master/adminui/src/components/CodexPanel.svelte"
click node_codex_manager "https://github.com/openai/tunnel-client/blob/master/pkg/codexplugin/manager.go"
click node_codex_session "https://github.com/openai/tunnel-client/blob/master/pkg/codexplugin/session/session.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runtime_entry,node_full_entry,node_cloudflared_runtime toneBlue
class node_controlplane,node_dispatcher,node_mcpclient,node_oauth,node_harpoon_adapter,node_harpoon_core,node_local_proxy toneAmber
class node_admin_backend,node_web_app,node_api_client,node_overview,node_metrics,node_oauth_panel,node_harpoon_panel,node_system_panel,node_logs_panel,node_codex_panel,node_mcpserver toneMint
class node_codex_manager,node_codex_session toneRose
class node_operator,node_openai toneIndigo
```

## Components

### Tunnel runtime

- [Runtime composition](https://github.com/openai/tunnel-client/blob/master/pkg/runtimeapp/app.go): `pkg/runtimeapp/app.go`
- [Full-client composition](https://github.com/openai/tunnel-client/blob/master/pkg/app/app.go): `pkg/app/app.go`
- [Cloudflared supervisor](https://github.com/openai/tunnel-client/blob/master/pkg/cloudflared/runtime/supervisor.go): `pkg/cloudflared/runtime/supervisor.go`

### Runtime services

- [Control-plane client](https://github.com/openai/tunnel-client/blob/master/pkg/controlplane/internal/tunnel_service_client.go): `pkg/controlplane/internal/tunnel_service_client.go`
- [MCP dispatcher](https://github.com/openai/tunnel-client/blob/master/pkg/dispatcher/internal/processor.go): `pkg/dispatcher/internal/processor.go`
- [MCP client transport](https://github.com/openai/tunnel-client/blob/master/pkg/mcpclient/serialized_forwarding_transport.go): `pkg/mcpclient/serialized_forwarding_transport.go`
- [OAuth discovery](https://github.com/openai/tunnel-client/blob/master/pkg/oauth/discovery.go): `pkg/oauth/discovery.go`
- [Harpoon adapter](https://github.com/openai/tunnel-client/blob/master/pkg/harpoon/server.go): `pkg/harpoon/server.go`
- [Harpoon tools](https://github.com/openai/tunnel-client/blob/master/pkg/runtimeharpoon/server.go): `pkg/runtimeharpoon/server.go`
- [Local proxy](https://github.com/openai/tunnel-client/blob/master/pkg/localproxy/localproxy.go): `pkg/localproxy/localproxy.go`

### Operations UI

- [Admin services](https://github.com/openai/tunnel-client/blob/master/pkg/adminui/startup.go): `pkg/adminui/startup.go`
- [Admin UI shell](https://github.com/openai/tunnel-client/blob/master/adminui/src/App.svelte): `adminui/src/App.svelte`
- [UI API client](https://github.com/openai/tunnel-client/blob/master/adminui/src/lib/api.ts): `adminui/src/lib/api.ts`
- [Overview panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/OverviewPanel.svelte): `adminui/src/components/OverviewPanel.svelte`
- [Metrics panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/MetricsPanel.svelte): `adminui/src/components/MetricsPanel.svelte`
- [OAuth panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/OAuthPanel.svelte): `adminui/src/components/OAuthPanel.svelte`
- [Harpoon panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/HarpoonPanel.svelte): `adminui/src/components/HarpoonPanel.svelte`
- [System panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/SystemPanel.svelte): `adminui/src/components/SystemPanel.svelte`
- [Logs panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/LogsPanel.svelte): `adminui/src/components/LogsPanel.svelte`
- [Codex panel](https://github.com/openai/tunnel-client/blob/master/adminui/src/components/CodexPanel.svelte): `adminui/src/components/CodexPanel.svelte`

### Codex management

- [Codex runtime manager](https://github.com/openai/tunnel-client/blob/master/pkg/codexplugin/manager.go): `pkg/codexplugin/manager.go`
- [Managed runtime session](https://github.com/openai/tunnel-client/blob/master/pkg/codexplugin/session/session.go): `pkg/codexplugin/session/session.go`

### Other components

- **Operator**
- **Private MCP server**
- **OpenAI tunnel service**

## Connections

- Private MCP server → MCP client transport: serves MCP (evidence: `README.md`)
- MCP client transport → MCP dispatcher: forwards requests
- MCP dispatcher → Control-plane client: polls tunnel
- Control-plane client → OpenAI tunnel service: exchanges tunnel data (evidence: `README.md`)
- Runtime composition → Control-plane client: wires (evidence: `pkg/runtimeapp/app.go`)
- Runtime composition → MCP dispatcher: wires (evidence: `pkg/runtimeapp/app.go`)
- Runtime composition → MCP client transport: wires (evidence: `pkg/runtimeapp/app.go`)
- Runtime composition → OAuth discovery: wires (evidence: `pkg/runtimeapp/app.go`)
- Runtime composition → Harpoon tools: wires (evidence: `pkg/runtimeapp/app.go`)
- Full-client composition → Admin services: wires (evidence: `pkg/app/app.go`)
- Full-client composition → Harpoon adapter: wires (evidence: `pkg/app/app.go`)
- Full-client composition → Cloudflared supervisor: starts supervisor (evidence: `pkg/app/app.go`)
- Harpoon adapter → Harpoon tools: adapts (evidence: `pkg/harpoon/server.go`)
- Operator → Admin UI shell: opens dashboard (evidence: `README.md`)
- Admin UI shell → Admin services: requests status
- Admin UI shell → Overview panel: renders (evidence: `adminui/src/App.svelte`)
- Admin UI shell → Metrics panel: renders (evidence: `adminui/src/App.svelte`)
- Admin UI shell → OAuth panel: renders (evidence: `adminui/src/App.svelte`)
- Admin UI shell → Harpoon panel: renders (evidence: `adminui/src/App.svelte`)
- Admin UI shell → System panel: renders (evidence: `adminui/src/App.svelte`)
- Admin UI shell → Logs panel: renders (evidence: `adminui/src/App.svelte`)
- Admin UI shell → Codex panel: renders (evidence: `adminui/src/App.svelte`)
- Overview panel → UI API client: fetches status (evidence: `adminui/src/components/OverviewPanel.svelte`)
- Metrics panel → UI API client: fetches metrics (evidence: `adminui/src/components/MetricsPanel.svelte`)
- OAuth panel → UI API client: fetches OAuth (evidence: `adminui/src/components/OAuthPanel.svelte`)
- Harpoon panel → UI API client: fetches targets (evidence: `adminui/src/components/HarpoonPanel.svelte`)
- System panel → UI API client: fetches system data (evidence: `adminui/src/components/SystemPanel.svelte`)
- Logs panel → UI API client: fetches logs (evidence: `adminui/src/components/LogsPanel.svelte`)
- Codex panel → UI API client: requests Codex data (evidence: `adminui/src/components/CodexPanel.svelte`)
- Codex panel → Codex runtime manager: manages runtimes
- Codex runtime manager → Managed runtime session: starts sessions (evidence: `pkg/codexplugin/manager.go`)
