SAM

Quick Start

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

Quick Start

This guide gets you up and running with a SAM node connected to the public bananas.sam-mesh.dev mesh. You can run SAM either directly via a binary or using Docker.

1. Install SAM

Option A: Install Script (macOS / Linux)

The easiest way to install the latest binaries directly:

curl -sL https://sam-mesh.dev/install.sh | bash

Option B: Go Install (macOS / Linux / Windows)

If you have Go installed, you can compile and install directly from the repository:

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.

Exposing Inference Services: OpenRouter

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

Exposing Inference Services: OpenRouter

In the Sovereign Agent Mesh (SAM), large language models (LLMs) and foundational model APIs are exposed across the mesh as Inference Services, not just standard Model Context Protocol (MCP) servers. This allows your deployed agents to dynamically discover, route, and consume inference capabilities directly through the P2P network, utilizing SAM’s decentralized authorization (Biscuit) for access control.

This guide explains how to expose OpenRouter as an inference service to the mesh, completely shielding your API keys from external peers.

Integrating SAM with Claude Code

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

You can connect your sam-node to Claude Code as a remote MCP server, giving Claude Code agents the ability to discover and invoke tools across the SAM mesh.

Overview

sam-node exposes a standard Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE). Claude Code is a generic MCP client, so once the server is registered its tools — discover_remote_services, find_remote_tools, describe_remote_tool, and call_remote_tool — are surfaced directly to your agent.

Integrating SAM with Claude Desktop

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

You can connect your sam-node to the Claude Desktop app as an MCP server. Unlike Claude Code, Claude Desktop has its own configuration and does not read Claude Code’s MCP settings.

Overview

Claude Desktop’s claude_desktop_config.json natively launches stdio MCP servers (a local command). sam-node exposes an SSE server, so you bridge the two with mcp-remote — a small stdio-to-remote proxy that Claude Desktop launches locally and that connects to your node’s SSE endpoint.

Integrating SAM with Google Antigravity

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

You can connect your sam-node to Google Antigravity as an MCP server. By exposing the SAM Model Context Protocol (MCP) server to Antigravity, the agent can dynamically discover tools hosted by other peers in the mesh, describe them, and execute them to solve tasks.

Overview

Antigravity natively supports Streamable HTTP MCP servers via the serverUrl configuration. Since sam-node implements the Streamable HTTP transport, you can connect it directly without any bridge.

Integrating SAM with OpenClaw

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

You can seamlessly integrate your sam-node as a remote MCP server in OpenClaw, allowing your agents to dynamically discover and invoke tools across the mesh.

Overview

By configuring your sam-node as an MCP server, you enable your OpenClaw agents to access the P2P mesh, discovering tools from remote nodes and executing services as if they were local.

Configuration

To bridge your local sam-node into your OpenClaw agent runtime, use the openclaw mcp CLI. Ensure your node is running and identify the API token configured in your sam-node launch arguments.

Kubernetes Deployment and Local Testing Guide

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

This guide explains how to deploy the sam-hub in a Kubernetes cluster and how to test it locally using kind and cloud-provider-kind.

[!TIP] This guide focuses on local development sandboxing. For production-grade Kubernetes deployments (GKE, EKS, AKS), see the Production Kubernetes Deployment guide.

This guide supports using either Google OIDC or a Mock OIDC Provider for authentication. The mock provider is recommended for quick local testing as it does not require creating external credentials.

Release Tracks, Autoupdate, and Autoscaling

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

Sovereign Agent Mesh (SAM) is deployed to public endpoints using automated environments, release tracks, and self-healing/scaling infrastructure.

1. Release Tracks

The public deployment has two isolated release tracks:

A. Testnet Track (Bananas)

Domain Name: bananas.sam-mesh.dev
Source Branch: Tracks the main branch.
Deployment Trigger: Automatically deployed on every new push/commit to the main branch.
Target Tag: The deployment is tagged with the Git commit SHA (github.sha).
Purpose: Serves as the staging/testing playground for the latest features and continuous integration.

B. Production Track (Hub)

Domain Name: hub.sam-mesh.dev
Source Branch: Tracks semantic version tags matching v*.*.*.
Deployment Trigger: Automatically deployed whenever a new version tag is pushed to GitHub.
Target Tag: The deployment is tagged with the exact Git release tag (e.g. v1.0.0).
Purpose: Stable, audited release track for production workloads.

2. Autoupdate Mechanism

Updates to both release tracks are fully automated via a robust Continuous Deployment pipeline:

Running a Gemini AI Agent on the Mesh

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

This tutorial demonstrates how to connect a local AI Agent powered by Google Gemini (using the official google-genai SDK) to your local SAM node.

By exposing the SAM Model Context Protocol (MCP) server to Gemini, the agent can dynamically discover tools hosted by other peers in the mesh, describe them, and execute them to solve tasks.

Prerequisites

Python 3.10+: Ensure Python is installed on your host.
SAM Node Running: A local SAM node should be running and enrolled on the testnet (see the Quick Start Guide).
Gemini API Key: Obtain an API key from Google AI Studio and export it:
```
export GEMINI_API_KEY="your-api-key-here"
```

1. Setup the Python Client

Go to the sam-mcp-python directory in the repository:

SAM Policy & Authorization Reference

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

SAM uses a decentralized authorization model powered by Biscuit. The sam-hub authenticates users via OIDC and injects Facts into their token based on policies.yaml. The sam-node operates offline, evaluating the token against baseline rules and optional local attenuation policies.

1. OIDC to Biscuit Translation

The Hub automatically translates OIDC claims into undeniable cryptographic facts:

OIDC Claim / Data	Biscuit Fact	Description
`sub`	`user("<sub-id>")`	The unique subject ID from the identity provider.
`email`	`email("<email>")`	The user’s email address (if present).
`groups`	`group("<group-name>")`	One fact is injected for each group the user possesses.
`roles` / Resolved Roles	`role("<role-name>")`	One fact is injected for each role mapped or direct role.
Peer ID	`node("<peer-id>")`, `client_peer_id("<peer-id>")`	Binds the token to the specific agent’s libp2p cryptographic identity.
Expiration	`expiration(<date>)`	The token expiration date based on the OIDC session.

1.1 Translating Identity to Capability: OIDC to Biscuit

The core innovation of the SAM Network’s security model is translating standard web identity (OIDC JSON Web Tokens defined in OpenID Connect Core 1.0) into decentralized capability tokens (Biscuits). This translation happens securely at the sam-hub during the authentication phase.

Testing

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

Current testing is intentionally minimal and aligned with the current binaries.

Test Layers

Go tests: make test
BATS CLI tests: make test-e2e
Containerized BATS mesh tests: make test-e2e-container

Commands

make build
make test
make test-e2e
make test-e2e-container

Go Tests

Run all Go tests with race detection:

make test

Run only integration package:

go test ./tests/integration/...

BATS CLI Tests

These tests validate current command behavior for:

sam-node
sam-hub

Run:

make test-e2e

Containerized Mesh BATS

The container framework is implemented in:

Testnet & Mesh Validation Tutorial

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

This tutorial guides you through validating your local environment integration with the public Sovereign Agent Mesh (SAM) testnets (bananas.sam-mesh.dev or hub.sam-mesh.dev). You will learn how to verify your node’s connection, discover remote MCP services, and invoke remote tools.

Prerequisites

Before starting, ensure you have:

Compiled the local binaries (sam-node and mcp-client) by running:
```
make build
```

An active local sam-node container or process running and successfully joined to the target public testnet. For example, join via:

bin/sam-node join https://bananas.sam-mesh.dev

And run via:

docker run --name sam-node \
 -v ~/.config/sam-mesh:/data \
 -p 5001:5001/udp -p 5002:5002 -p 8080:8080 \
 sam-node:local \
 run --data-dir /data \
 --hub https://bananas.sam-mesh.dev \
 --bind-addr 0.0.0.0:8080 \
 --api-token secret-token \
 --log-level debug

Step 1: Verifying Local Connection to the Testnet

Check the logs of your local sam-node to ensure it has successfully joined and is online:

SAM

Quick Start

Quick Start

1. Install SAM

Option A: Install Script (macOS / Linux)

Option B: Go Install (macOS / Linux / Windows)

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)

Exposing Inference Services: OpenRouter

Exposing Inference Services: OpenRouter

Integrating SAM with Claude Code

Overview

Integrating SAM with Claude Desktop

Overview

Integrating SAM with Google Antigravity

Overview

Integrating SAM with OpenClaw

Overview

Configuration

Kubernetes Deployment and Local Testing Guide

Release Tracks, Autoupdate, and Autoscaling

1. Release Tracks

A. Testnet Track (Bananas)

B. Production Track (Hub)

2. Autoupdate Mechanism

Running a Gemini AI Agent on the Mesh

Prerequisites

1. Setup the Python Client

SAM Policy & Authorization Reference

1. OIDC to Biscuit Translation

1.1 Translating Identity to Capability: OIDC to Biscuit

Testing

Test Layers

Commands

Go Tests

BATS CLI Tests

Containerized Mesh BATS

Testnet & Mesh Validation Tutorial

Prerequisites

Step 1: Verifying Local Connection to the Testnet

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

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