# google/sam architecture

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

- Interactive diagram: https://gitdiagram.com/google/sam
- Repository: https://github.com/google/sam

## Overview

SAM is a private network for AI agents: operators enroll nodes, the control plane verifies identity and issues credentials, and nodes connect through a router to discover and invoke policy-authorized services. Nodes also publish local tools and models, expose MCP and OpenAI-compatible interfaces to agents, and support direct connections or relay. The map preserves control-plane administration, persistence, standalone deployment, and sandboxing. README establishes the product workflow; sampled source supports selected control-plane, inference, console, and sandbox details, so uncertain wiring is omitted.

Main entry points: [`internal/node/node.go`](https://github.com/google/sam/blob/main/internal/node/node.go) (Mesh node), [`internal/controlplane/server.go`](https://github.com/google/sam/blob/main/internal/controlplane/server.go) (Control plane), [`internal/standalone/standalone.go`](https://github.com/google/sam/blob/main/internal/standalone/standalone.go) (Standalone server), [`internal/router/router.go`](https://github.com/google/sam/blob/main/internal/router/router.go) (Mesh router)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_enrollment["Identity and policy"]
  node_node_cli["Node CLI<br/>[main.go]"]
  node_node_enrollment["Node enrollment<br/>[enroll.go]"]
  node_control_plane["Control plane<br/>[server.go]"]
  node_identity["Identity verification<br/>[oidc.go]"]
  node_policy["Policy model<br/>[policy.go]"]
  node_state_store[("Control-plane state<br/>[sql_store.go]")]
end

subgraph group_mesh["Mesh runtime"]
  node_mesh_node["Mesh node<br/>[node.go]"]
  node_node_sync["Control-plane sync"]
  node_discovery["Service discovery<br/>[discovery.go]"]
  node_router["Mesh router<br/>[router.go]"]
  node_service_registry["Published services"]
end

subgraph group_agent_access["Agent access"]
  node_mcp["MCP access<br/>[mcp_service.go]"]
  node_inference["Model inference"]
  node_openai_api["OpenAI facade<br/>[openai_facade.go]"]
  node_local_backend["Local backends<br/>[backend_target.go]"]
  node_sdk["Client SDKs<br/>[index.ts]"]
end

subgraph group_operations["Operations and deployment"]
  node_standalone["Standalone server<br/>[standalone.go]"]
  node_console["Web console<br/>[server.go]"]
  node_console_ui["Console UI<br/>[app.js]"]
  node_sandbox["Agent sandbox<br/>[connect.go]"]
  node_tunnel["Public tunnel<br/>[tunnel.go]"]
end

node_operator(("Operator"))
node_agent(("Agent"))

node_operator -->|"starts enrollment"| node_node_cli
node_node_cli -->|"initiates enrollment"| node_node_enrollment
node_node_enrollment -->|"requests credential"| node_control_plane
node_control_plane -->|"verifies identity"| node_identity
node_control_plane -->|"reads and writes"| node_state_store
node_control_plane -->|"manages policy"| node_policy
node_node_cli -->|"starts node"| node_mesh_node
node_mesh_node -->|"synchronizes config"| node_node_sync
node_node_sync -->|"fetches node config"| node_control_plane
node_mesh_node -->|"connects to mesh"| node_router
node_mesh_node -->|"announces services"| node_discovery
node_discovery -->|"publishes discovery"| node_router
node_mesh_node -->|"registers services"| node_service_registry
node_agent -->|"uses local tools"| node_mcp
node_mcp -->|"finds mesh services"| node_discovery
node_mcp -->|"calls remote services"| node_router
node_agent -->|"requests models"| node_openai_api
node_openai_api -->|"routes inference"| node_inference
node_inference -->|"proxies requests"| node_local_backend
node_service_registry -->|"serves configured backends"| node_local_backend
node_agent -.->|"integrates client"| node_sdk
node_sdk -.->|"uses mesh APIs"| node_mesh_node
node_operator -->|"runs deployment"| node_standalone
node_standalone -->|"starts control plane"| node_control_plane
node_standalone -->|"starts router"| node_router
node_operator -->|"administers mesh"| node_console_ui
node_console_ui -->|"calls console routes"| node_console
node_console -->|"queries control-plane info"| node_control_plane
node_mesh_node -.->|"connects sandbox"| node_sandbox
node_standalone -.->|"opens public access"| node_tunnel

click node_node_cli "https://github.com/google/sam/blob/main/cmd/sam-node/main.go"
click node_node_enrollment "https://github.com/google/sam/blob/main/internal/node/enroll.go"
click node_control_plane "https://github.com/google/sam/blob/main/internal/controlplane/server.go"
click node_identity "https://github.com/google/sam/blob/main/internal/identity/oidc.go"
click node_policy "https://github.com/google/sam/blob/main/api/policy.go"
click node_state_store "https://github.com/google/sam/blob/main/internal/storage/sql_store.go"
click node_mesh_node "https://github.com/google/sam/blob/main/internal/node/node.go"
click node_node_sync "https://github.com/google/sam/blob/main/internal/node/controlplane_sync.go"
click node_discovery "https://github.com/google/sam/blob/main/internal/node/discovery/discovery.go"
click node_router "https://github.com/google/sam/blob/main/internal/router/router.go"
click node_service_registry "https://github.com/google/sam/blob/main/internal/node/service_registry.go"
click node_mcp "https://github.com/google/sam/blob/main/internal/node/mcp_service.go"
click node_inference "https://github.com/google/sam/blob/main/internal/node/inference_service.go"
click node_openai_api "https://github.com/google/sam/blob/main/internal/node/openai_facade.go"
click node_local_backend "https://github.com/google/sam/blob/main/internal/node/backend_target.go"
click node_sdk "https://github.com/google/sam/blob/main/sdk/js/src/index.ts"
click node_standalone "https://github.com/google/sam/blob/main/internal/standalone/standalone.go"
click node_console "https://github.com/google/sam/blob/main/internal/console/server.go"
click node_console_ui "https://github.com/google/sam/blob/main/internal/console/public/app.js"
click node_sandbox "https://github.com/google/sam/blob/main/internal/sambox/connect.go"
click node_tunnel "https://github.com/google/sam/blob/main/internal/tunnel/tunnel.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_node_cli,node_node_enrollment,node_control_plane,node_identity,node_policy,node_state_store toneBlue
class node_mesh_node,node_node_sync,node_discovery,node_router,node_service_registry toneAmber
class node_mcp,node_inference,node_openai_api,node_local_backend,node_sdk toneMint
class node_standalone,node_console,node_console_ui,node_sandbox,node_tunnel toneRose
class node_operator,node_agent toneIndigo
```

## Components

### Identity and policy

- [Node CLI](https://github.com/google/sam/blob/main/cmd/sam-node/main.go): `cmd/sam-node/main.go`
- [Node enrollment](https://github.com/google/sam/blob/main/internal/node/enroll.go): `internal/node/enroll.go`
- [Control plane](https://github.com/google/sam/blob/main/internal/controlplane/server.go): `internal/controlplane/server.go`
- [Identity verification](https://github.com/google/sam/blob/main/internal/identity/oidc.go): `internal/identity/oidc.go`
- [Policy model](https://github.com/google/sam/blob/main/api/policy.go): `api/policy.go`
- [Control-plane state](https://github.com/google/sam/blob/main/internal/storage/sql_store.go): `internal/storage/sql_store.go`

### Mesh runtime

- [Mesh node](https://github.com/google/sam/blob/main/internal/node/node.go): `internal/node/node.go`
- [Control-plane sync](https://github.com/google/sam/blob/main/internal/node/controlplane_sync.go): `internal/node/controlplane_sync.go`
- [Service discovery](https://github.com/google/sam/blob/main/internal/node/discovery/discovery.go): `internal/node/discovery/discovery.go`
- [Mesh router](https://github.com/google/sam/blob/main/internal/router/router.go): `internal/router/router.go`
- [Published services](https://github.com/google/sam/blob/main/internal/node/service_registry.go): `internal/node/service_registry.go`

### Agent access

- [MCP access](https://github.com/google/sam/blob/main/internal/node/mcp_service.go): `internal/node/mcp_service.go`
- [Model inference](https://github.com/google/sam/blob/main/internal/node/inference_service.go): `internal/node/inference_service.go`
- [OpenAI facade](https://github.com/google/sam/blob/main/internal/node/openai_facade.go): `internal/node/openai_facade.go`
- [Local backends](https://github.com/google/sam/blob/main/internal/node/backend_target.go): `internal/node/backend_target.go`
- [Client SDKs](https://github.com/google/sam/blob/main/sdk/js/src/index.ts): `sdk/js/src/index.ts`

### Operations and deployment

- [Standalone server](https://github.com/google/sam/blob/main/internal/standalone/standalone.go): `internal/standalone/standalone.go`
- [Web console](https://github.com/google/sam/blob/main/internal/console/server.go): `internal/console/server.go`
- [Console UI](https://github.com/google/sam/blob/main/internal/console/public/app.js): `internal/console/public/app.js`
- [Agent sandbox](https://github.com/google/sam/blob/main/internal/sambox/connect.go): `internal/sambox/connect.go`
- [Public tunnel](https://github.com/google/sam/blob/main/internal/tunnel/tunnel.go): `internal/tunnel/tunnel.go`

### Other components

- **Operator**
- **Agent**

## Connections

- Operator → Node CLI: starts enrollment
- Node CLI → Node enrollment: initiates enrollment
- Node enrollment → Control plane: requests credential
- Control plane → Identity verification: verifies identity
- Control plane → Control-plane state: reads and writes
- Control plane → Policy model: manages policy
- Node CLI → Mesh node: starts node
- Mesh node → Control-plane sync: synchronizes config
- Control-plane sync → Control plane: fetches node config
- Mesh node → Mesh router: connects to mesh
- Mesh node → Service discovery: announces services
- Service discovery → Mesh router: publishes discovery
- Mesh node → Published services: registers services
- Agent → MCP access: uses local tools
- MCP access → Service discovery: finds mesh services
- MCP access → Mesh router: calls remote services
- Agent → OpenAI facade: requests models
- OpenAI facade → Model inference: routes inference
- Model inference → Local backends: proxies requests
- Published services → Local backends: serves configured backends
- Agent → Client SDKs: integrates client
- Client SDKs → Mesh node: uses mesh APIs
- Operator → Standalone server: runs deployment
- Standalone server → Control plane: starts control plane
- Standalone server → Mesh router: starts router
- Operator → Console UI: administers mesh
- Console UI → Web console: calls console routes
- Web console → Control plane: queries control-plane info
- Mesh node → Agent sandbox: connects sandbox
- Standalone server → Public tunnel: opens public access