# stacklok/toolhive architecture

> Architecture diagram of the GitHub repository stacklok/toolhive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stacklok/toolhive
- Repository: https://github.com/stacklok/toolhive

## Overview

##### Project type and purpose
- ToolHive is a multi-component Go-based system that provides a CLI, a local container runner (“proxyrunner”), an HTTP/gRPC API server, and a Kubernetes Operator to deploy and manage Model Context Protocol (MCP) servers in secure containers.
- It supports local (Docker) and cluster (Kubernetes) deployment, secrets management, telemetry, and pluggable registries/auth.

##### High-level components
a. CLI client (“thv” binary under cmd/thv)
b. Local runner (“proxyrunner” binary under cmd/thv-proxyrunner)
c. API server (pkg/api exposing HTTP/JSON endpoints)
d. Kubernetes Operator (cmd/thv-operator + deploy/charts/operator)
e. Container runtime interfaces (pkg/container/docker, pkg/container/kubernetes)
f. Secrets & config backends (pkg/secrets, pkg/config, pkg/state)
g. Registry providers (pkg/registry/provider_{local,remote})
h. Authn/Authz middleware (pkg/auth, pkg/authz)
i. Telemetry & audit (pkg/telemetry, pkg/audit)
j. External services: Docker/K8s API, container registries, OIDC providers (Keycloak/GitHub), telemetry backends (Prometheus/OTLP/Jaeger)

##### Relationships and data flows
- CLI “thv” → API server (HTTP/gRPC) for registry discovery, group management, and remote control
- CLI “thv” → direct container runtime calls (Docker or K8s) via pkg/container for local mode
- API server → registry providers to fetch available MCP tool definitions
- CLI/Operator → secrets manager for fetching credentials (1Password, keyring, env)
- CLI → proxyrunner via STDIO/SSE/streamable proxy for bidirectional tunnel to MCP server process
- Operator watches CRDs (MCPServer, MCPRegistry, ToolConfig) using controllers → creates Kubernetes Deployments (mcpserver + proxyrunner sidecar) via Helm chart
- Telemetry middleware intercepts HTTP and SSE traffic → pushes metrics/traces to OTLP or Prometheus
- Audit middleware logs events to audit sink

##### Architectural patterns and design principles
- Modular Go packages following “pkg/…” for domain separation (auth, audit, registry, container, transport, secrets, telemetry)
- Adapter/factory patterns for pluggable implementations (registry providers, secrets stores, transport layers)
- Operator pattern for Kubernetes CRD reconciliation (controller-runtime)
- Middleware chaining (HTTP handlers for auth, audit, telemetry)
- State abstraction (local file vs. Kubernetes API)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        CLI["CLI (cmd/thv)"]:::client
        Runner["Local Runner<br>(cmd/thv-proxyrunner)"]:::client
    end

    %% Control Layer
    subgraph "Control Layer"
        APIServer["API Server<br>(pkg/api)"]:::backend
        Operator["K8s Operator<br>(cmd/thv-operator)"]:::k8s
    end

    %% Services
    subgraph "Services"
        Secrets["Secrets & Config<br>(pkg/secrets, pkg/config)"]:::backend
        State["State Stores<br>(pkg/state)"]:::backend
        RegistryFactory["Registry Factory<br>(pkg/registry)"]:::backend
        Auth["Auth Middleware<br>(pkg/auth)"]:::backend
        Authz["Authz Middleware<br>(pkg/authz)"]:::backend
        Telemetry["Telemetry Middleware<br>(pkg/telemetry)"]:::backend
        Audit["Audit Middleware<br>(pkg/audit)"]:::backend
        Transport["Transport Layer<br>(pkg/transport)"]:::backend
    end

    %% Execution Layer
    subgraph "Execution Layer"
        subgraph "Local Execution"
            DockerRuntime["Docker Runtime<br>(pkg/container/docker)"]:::backend
            K8sRuntime["Kubernetes Runtime<br>(pkg/container/kubernetes)"]:::backend
        end
        subgraph "K8s Cluster"
            Pod["MCPServer Pod<br>(mcpserver + proxyrunner)"]:::k8s
        end
    end

    %% Infrastructure / External
    subgraph "Infrastructure / External"
        DockerDaemon["Docker Daemon"]:::infra
        K8sAPI["Kubernetes API"]:::infra
        RegistryExt["Container Registry"]:::infra
        OIDC["OIDC Provider<br>(Keycloak/GitHub)"]:::infra
        TelemetryExt["Telemetry Backends<br>(Prometheus/OTLP/Jaeger)"]:::infra
    end

    %% Relationships
    CLI -->|HTTP/gRPC| APIServer
    CLI -->|Docker API| DockerRuntime
    CLI -->|STDIO/SSE| Runner
    APIServer -->|registry lookup| RegistryFactory
    APIServer -->|authn| Auth
    APIServer -->|authz| Authz
    APIServer -->|secrets| Secrets
    APIServer -->|audit events| Audit
    APIServer -->|telemetry| Telemetry
    Operator -->|CRD events| K8sAPI
    Operator -->|deploy via Helm| Pod
    Operator -->|secrets| Secrets
    DockerRuntime -->|Docker API| DockerDaemon
    K8sRuntime -->|Kubernetes API| K8sAPI
    Pod -->|uses container| K8sAPI
    Pod -->|sidecar tunnel| Transport
    CLI -->|telemetry| Telemetry
    Runner -->|telemetry| Telemetry
    Telemetry -->|push metrics/traces| TelemetryExt
    Audit -->|sink logs| TelemetryExt
    RegistryFactory -->|fetch definitions| RegistryExt
    Auth -->|OIDC flows| OIDC

    %% Click Events
    click CLI "https://github.com/stacklok/toolhive/tree/main/cmd/thv"
    click Runner "https://github.com/stacklok/toolhive/tree/main/cmd/thv-proxyrunner"
    click APIServer "https://github.com/stacklok/toolhive/tree/main/pkg/api"
    click Operator "https://github.com/stacklok/toolhive/tree/main/cmd/thv-operator"
    click DockerRuntime "https://github.com/stacklok/toolhive/tree/main/pkg/container/docker"
    click K8sRuntime "https://github.com/stacklok/toolhive/tree/main/pkg/container/kubernetes"
    click Transport "https://github.com/stacklok/toolhive/tree/main/pkg/transport"
    click Secrets "https://github.com/stacklok/toolhive/blob/main/pkg/secrets/factory.go"
    click RegistryFactory "https://github.com/stacklok/toolhive/blob/main/pkg/registry/factory.go"
    click Auth "https://github.com/stacklok/toolhive/tree/main/pkg/auth/oauth"
    click Authz "https://github.com/stacklok/toolhive/tree/main/pkg/authz"
    click Telemetry "https://github.com/stacklok/toolhive/tree/main/pkg/telemetry/providers/otlp"
    click Audit "https://github.com/stacklok/toolhive/tree/main/pkg/audit"
    click State "https://github.com/stacklok/toolhive/tree/main/pkg/state"
    click Operator "https://github.com/stacklok/toolhive/tree/main/deploy/charts/operator"
    click Operator "https://github.com/stacklok/toolhive/tree/main/deploy/charts/operator-crds"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef k8s fill:#FFA500,stroke:#333,stroke-width:1px
```
