User and Operator Guides on SAM

Hub Configuration Guide

Mon, 01 Jan 0001 00:00:00 +0000

The sam-hub acts as the control plane for the Sovereign Agent Mesh. It is responsible for bridging user identities from OpenID Connect (OIDC) providers, issuing cryptographically signed Biscuit authorization tokens, and distributing network and tool policies to nodes.

1. Core Services

When you run sam-hub, it launches two core service endpoints:

libp2p P2P Endpoint: Used by sam-node clients to execute cryptographic handshakes and perform DHT resource discovery.
HTTP/HTTPS Service Endpoint: Used for health status checks (/healthz), prometheus metrics (/metrics), and administrative commands (like banning nodes).

2. Command-Line Arguments & Environment Variables

The hub is highly configurable. Each setting can be passed as a command-line flag or bound to a corresponding environment variable:

Node Configuration Guide

Mon, 01 Jan 0001 00:00:00 +0000

The sam-node acts as a local security gateway and tool proxy for AI agents. While the Hub acts as the central control plane, each Node independently defines its own local tool catalogue and enforces its own local security identity.

1. Node Configuration File (`sam-node.yaml`)

By default, sam-node runs without exposing any local tools to the mesh. To expose local tools or strictly enforce your node’s network identity, you must create a Node configuration file and pass it to the daemon using the --config flag:

Agent Usage & Connectivity Guide

Mon, 01 Jan 0001 00:00:00 +0000

SAM nodes (sam-node) act as local security gateways and tool proxies for your AI agents (such as Google Gemini, Claude Code, or Claude Desktop). This document explains how to authenticate a node to the mesh and configure your agents to use it.

1. Node Lifecycle Overview

Connecting your AI agent to the Sovereign Agent Mesh involves two phases:

sequenceDiagram
 actor User as Developer/Operator
 participant Node as sam-node (Local)
 participant Hub as sam-hub (Mesh)
 participant Agent as AI Agent (Gemini/Claude)
 
 Note over User,Hub: Phase 1: Mesh Join (OIDC Authorization)
 User->>Node: sam-node join <hub-url>
 Node->>Hub: Get Hub OIDC Info
 Hub-->>Node: OIDC Issuer, Client ID
 Node->>User: Display Login URL & Code
 User->>User: Login in Browser
 Node->>Hub: Exchange Code for Biscuit Identity
 Node->>Node: Persist Biscuit in Local Store (agent.db)

 Note over User,Agent: Phase 2: Agent Tool Invocation
 User->>Node: sam-node run --api-token "secret-key"
 Node->>Node: Start local MCP server on 127.0.0.1:8080
 Agent->>Node: Connect to local MCP (with Bearer "secret-key")
 Agent->>Node: Call Remote P2P Tool
 Node->>Hub: Verify Biscuit / Allowed Policies
 Node-->>Agent: Execute tool and return result

2. Phase 1: Joining the Mesh (`sam-node join`)

Before starting the node daemon, you must authorize your node and obtain a cryptographic Biscuit identity.

Production Kubernetes Deployment

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains how to deploy a production-grade SAM cluster (Hub, DNS synchronizer, OIDC bridge, and Nodes) in a Kubernetes environment (like GKE, EKS, AKS, or custom bare-metal clusters), based on our official public testnet architectures.

1. Architecture Overview

A production SAM deployment consists of:

Dex (OIDC Provider): Serves as the identity bridge, federation point, and login broker.
SAM Hub (sam-hub): Runs as a StatefulSet to maintain stable network identity. P2P nodes query these bootstrap pods to connect to the mesh.
DNS Sync CronJob: Dynamically queries the StatefulSet pod IP addresses and updates DNS A/AAAA records for P2P bootstrap resolution.
SAM Nodes (sam-node): Deployed as containerized gateways that authenticate securely to the hub using Kubernetes Workload Identity (ServiceAccount token projection).

graph TD
 User([User / Client]) -->|HTTPS / OIDC| Dex[Dex Identity Bridge]
 Node[sam-node Gateway Pod] -->|ServiceAccount Token| Hub[sam-hub StatefulSet]
 Hub -->|OIDC Discovery Check| Dex
 Cron[DNS Sync CronJob] -->|Poll Pod IPs| K8sApi[Kubernetes API]
 Cron -->|Update A Records| CloudDNS[Cloud DNS / DNS Registry]
 Node -->|Bootstrap DNS Resolution| CloudDNS

2. Step 1: Deploying the OIDC Provider (Dex)

Dex maps external accounts (Google, GitHub, LDAP) to standard OIDC identities in the cluster.

User and Operator Guides on SAM

Hub Configuration Guide

1. Core Services

2. Command-Line Arguments & Environment Variables

Node Configuration Guide

1. Node Configuration File (sam-node.yaml)

Agent Usage & Connectivity Guide

1. Node Lifecycle Overview

2. Phase 1: Joining the Mesh (sam-node join)

Production Kubernetes Deployment

1. Architecture Overview

2. Step 1: Deploying the OIDC Provider (Dex)

1. Node Configuration File (`sam-node.yaml`)

2. Phase 1: Joining the Mesh (`sam-node join`)