Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
order menus
Antonio Ojeaeb130dfc681f
diff --git a/README.md b/README.mdindex 772ac401..65910860 100644--- a/README.md+++ b/README.md@@ -25,14 +25,14 @@ Start exploring the Sovereign Agent Mesh:### For Users & OperatorsGet a node running on the public testnet (`bananas.sam-mesh.dev`) in minutes:- π **[User Quick Start Guide](site/content/docs/quickstart.md)**: Connect and run a SAM node using binaries or Docker, and query the local MCP server.-- π€ **[Agent Integration Guides](site/content/docs/agent_integration.md)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to dynamically discover and call tools across the mesh.+- π€ **[Agent Integration Guides](site/content/docs/integrations/_index.md)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to dynamically discover and call tools across the mesh.- π **[CLI Reference](site/content/docs/cli/reference.md)**: Comprehensive CLI reference and configurations.-- π‘ **[Testnet Validation Tutorial](site/content/docs/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.+- π‘ **[Testnet Validation Tutorial](site/content/docs/development/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.### For Developers & ContributorsCompile from source, run local clusters, or execute tests:-- π οΈ **[Developer Guide](site/content/docs/development.md)**: Prereqs, compilation, local hub setup, and Kubernetes Kind deployment.-- π§ͺ **[Testing Guide](site/content/docs/testing.md)**: Go tests, E2E BATS, and containerized mesh execution.+- π οΈ **[Developer Guide](site/content/docs/development/_index.md)**: Prereqs, compilation, local hub setup, and Kubernetes Kind deployment.+- π§ͺ **[Testing Guide](site/content/docs/development/testing.md)**: Go tests, E2E BATS, and containerized mesh execution.---diff --git a/site/content/docs/_index.md b/site/content/docs/_index.mdindex f42b5266..aa6dc087 100644--- a/site/content/docs/_index.md+++ b/site/content/docs/_index.md@@ -22,6 +22,8 @@ The documentation here is intentionally small and aligned with what is implement## Start Here- [Quick Start](quickstart.md) - User Quick Start using Docker.+- [Hub Configuration](user/hub-configuration.md) - OIDC authentication, key rings, and custom policy rules in `policies.yaml`.+- [Agent Usage](user/agent-usage.md) - Node authorization flows, MCP endpoints, and how agents connect.- [CLI Reference](cli/reference.md) - CLI command usage reference.- [Developer Guide](development/_index.md) - Building from source, local testing, and Kind setups.- [Testing Guide](development/testing.md) - Detailed test layer and troubleshooting information.diff --git a/site/content/docs/cli/reference.md b/site/content/docs/cli/reference.mddeleted file mode 100644index 06dfe445..00000000--- a/site/content/docs/cli/reference.md+++ /dev/null@@ -1,90 +0,0 @@-----title: "CLI Reference"-linkTitle: "CLI Reference"-----The current repository exposes two CLIs:--- `sam-node`-- `sam-hub`--## sam-node--```bash-sam-node --help-```--### sam-node join--Join the Sovereign Agent Mesh hub and enroll the node.--```bash-sam-node join [hub_url] [flags]-```--If `hub_url` is omitted, you will be prompted to join the default community testing network (`https://bananas.sam-mesh.dev`). This command initiates an interactive OIDC device login flow and stores the returned identity Biscuit token and generated keypair in the database.--Flags:--* `--data-dir`: Override directory for the agent store (defaults to OS user config dir).--### sam-node run--Start the sovereign mesh node.--```bash-sam-node run [flags]-```--Flags:--* `--data-dir`: Override directory for the agent store (defaults to OS user config dir) where identity and private keys are loaded.-* `--bind-addr`: Local TCP address for the HTTP server (MCP and Sidecar API) (default `"127.0.0.1:8080"`).-* `--listen`: libp2p Listen Addrs (default `[/ip4/0.0.0.0/udp/5001/quic-v1,/ip4/0.0.0.0/tcp/5002]`).-* `--jwt`: Pre-fetched JWT token to enroll dynamically.-* `--jwt-path`: Path to a file containing a pre-fetched JWT token.-* `--oidc-issuer`: OIDC Issuer URL for M2M auto-enrollment.-* `--client-id`: OIDC Client ID for M2M auto-enrollment.-* `--client-secret`: OIDC Client Secret for M2M auto-enrollment.-* `--api-token`: Static Bearer token for API authorization.-* `--log-level`: Log level (debug, info, warn, error) (default `"info"`).--Examples:--```bash-# Start using saved identity-sam-node run--# Start with explicit OIDC details-sam-node run --oidc-issuer https://issuer.example.com --client-id my-id --client-secret my-secret--# Start and bind HTTP API to all interfaces (e.g. inside Docker)-sam-node run --bind-addr 0.0.0.0:8080-```--## sam-hub--```bash-sam-hub --help-```--`sam-hub` runs the OIDC bridge, issues identity biscuits, and gates unauthenticated peers.--Flags:--- `--issuer`: OIDC issuer URL-- `--client-id`: OIDC client ID-- `--client-secret`: OIDC client secret-- `--key`: 32-byte hex seed used to derive Ed25519 biscuit signing key-- `--listen`: repeatable libp2p listen addresses-- `--mesh`: mesh name-- `--public-url`: public callback base URL--Example:--```bash-sam-hub \- --issuer https://issuer.example.com \- --client-id sam-client \- --client-secret sam-secret \- --key $(openssl rand -hex 32)-```diff --git a/site/content/docs/development/_index.md b/site/content/docs/development/_index.mdindex c41205e0..3a228702 100644--- a/site/content/docs/development/_index.md+++ b/site/content/docs/development/_index.md@@ -1,6 +1,7 @@---title: "Developer Guide"linkTitle: "Developer Guide"+weight: 4---This document is for developers who want to compile SAM from source, run a local development mesh, run the test suites, or contribute to the repository.diff --git a/site/content/docs/integrations/_index.md b/site/content/docs/integrations/_index.mdindex 94baf6f1..c0c52158 100644--- a/site/content/docs/integrations/_index.md+++ b/site/content/docs/integrations/_index.md@@ -1,6 +1,7 @@---title: "Agent Integration Guide"linkTitle: "Agent Integration Guide"+weight: 2---SAM is designed to be the networking layer for autonomous AI agents. The easiest way for your agent to interact with the mesh is through the **Model Context Protocol (MCP)** exposed locally by your node.diff --git a/site/content/docs/quickstart.md b/site/content/docs/quickstart.mdindex 32ac6b7e..48d758c8 100644--- a/site/content/docs/quickstart.md+++ b/site/content/docs/quickstart.md@@ -1,7 +1,7 @@---title: "Quick Start"linkTitle: "Quick Start"-weight: 10+weight: 1---# Quick Startdiff --git a/site/content/docs/user/_index.md b/site/content/docs/user/_index.mdnew file mode 100644index 00000000..a6525d2d--- /dev/null+++ b/site/content/docs/user/_index.md@@ -0,0 +1,15 @@+---+title: "User and Operator Guides"+linkTitle: "User Guides"+weight: 3+---++Welcome to the User & Operator Guides. This section provides detailed documentation on how to configure, run, and manage Sovereign Agent Mesh (SAM) clusters, hubs, and node configurations.++### In This Section++1. **[Hub Configuration](hub-configuration.md)**+ Learn how to configure the OIDC identity bridge, set up cryptographic private keys, enforce TLS/mTLS, and write custom security role policy mappings in `policies.yaml`.++2. **[Agent Usage & Connectivity](agent-usage.md)**+ Understand how nodes connect to the mesh via OIDC login, secure credentials, run local Model Context Protocol (MCP) servers, and expose secure remote tool access to agents (like Google Gemini and Claude).diff --git a/site/content/docs/user/agent-usage.md b/site/content/docs/user/agent-usage.mdnew file mode 100644index 00000000..9e1abfc9--- /dev/null+++ b/site/content/docs/user/agent-usage.md@@ -0,0 +1,104 @@+---+title: "Agent Usage & Connectivity Guide"+linkTitle: "Agent Usage"+weight: 20+---++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:+```mermaid+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 <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++ 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.++### Standard Login+Run the `join` command, pointing to the mesh control hub:+```bash+sam-node join --hub https://bananas.sam-mesh.dev+```++* **Browser Flow**: The CLI will discover the OIDC credentials from the hub, print an OIDC authorization URL, and attempt to open your system's default web browser automatically.+* **Approval**: Log in with your corporate or identity credentials (e.g. Google Accounts), approve the authorization request, and return to the terminal. The node will automatically exchange the credentials for a Biscuit token and save it to `~/.config/sam-mesh/identity.json`.++### Headless (Server) Login+If you are running the node on a remote server via SSH (without a web browser), force headless out-of-band mode:+```bash+sam-node join --hub https://bananas.sam-mesh.dev --headless+```+The CLI will print a verification URL and code (e.g. `https://google.com/device` and `ABCD-EFGH`). Open this URL on your local laptop, enter the code, complete the login, and the remote terminal session will activate automatically.++### Automatic Token Renewal+To allow long-lived nodes to automatically renew their tokens in the background, request offline access (refreshes the OIDC session):+```bash+sam-node join --hub https://bananas.sam-mesh.dev --offline-access+```++---++## 3. Phase 2: Running the Node daemon (`sam-node run`)++Once authorized, you start the node gateway. The gateway spins up a local Model Context Protocol (MCP) server.++Run the node daemon, securing the local API endpoint with a custom token:+```bash+sam-node run --api-token "my-agent-super-token-123" --bind-addr "127.0.0.1:8080"+```++### Key CLI Parameters+* `--bind-addr`: The local TCP address where the node's local HTTP server runs (default: `127.0.0.1:8080`).+* `--api-token`: A security token required by any local AI agent attempting to connect to your node.+* `--data-dir`: Custom path to store configurations and Biscuit tokens (defaults to `~/.config/sam-mesh` or env `SAM_DATA_DIR`).++---++## 4. Connecting your AI Agents++Your AI agent connects to the node's local MCP server. The local server translates standard MCP queries (like `listTools` or `callTool`) into secure P2P mesh commands.++### Exposing the API+The local MCP endpoint is served via **HTTP Server-Sent Events (SSE)** at:+`http://127.0.0.1:8080/mcp/events`++### Authentication+When configuring your agent client, you must pass the API token in the headers:+```http+Authorization: Bearer my-agent-super-token-123+```++### Specific Integration Guides+Explore our step-by-step guides for integrating your node with popular agent clients:+* π **[Google Gemini AI Agent](../integrations/gemini.md)**: Connect using Python scripts and the google-genai SDK.+* π» **[Claude Desktop](../integrations/claude-desktop.md)**: Expose P2P tools directly to your Claude Desktop application menu.+* π€ **[Claude Code](../integrations/claude-code.md)**: Add your local node tools directly to the Claude CLI.+* π **[OpenClaw](../integrations/openclaw.md)**: Setup remote tool bridges for OpenClaw clusters.diff --git a/site/content/docs/user/hub-configuration.md b/site/content/docs/user/hub-configuration.mdnew file mode 100644index 00000000..1d90c39f--- /dev/null+++ b/site/content/docs/user/hub-configuration.md@@ -0,0 +1,101 @@+---+title: "Hub Configuration Guide"+linkTitle: "Hub Configuration"+weight: 10+---++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:+1. **libp2p P2P Endpoint**: Used by `sam-node` clients to execute cryptographic handshakes and perform DHT resource discovery.+2. **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:++| CLI Flag | Environment Variable | Default Value | Description |+| :--- | :--- | :--- | :--- |+| `--issuer` | `SAM_OIDC_ISSUER` | `https://accounts.google.com` | Comma-separated list of trusted OIDC Provider URLs. |+| `--client-id` | `SAM_OIDC_ID` | *None* | Client ID registered with the OIDC provider. |+| `--key` | `SAM_HUB_KEY` | *None* | Private Key seed (32-byte hexadecimal string) used to sign Biscuit tokens. |+| `--listen` | *None* | `[]` | Comma-separated libp2p multiaddrs to listen on (e.g. `/ip4/0.0.0.0/tcp/9090`). |+| `--bind-address` | *None* | `:9090` | Host and port to listen on for the HTTP/HTTPS admin service. |+| `--policy-file` | *None* | `policies.yaml` | Path to the YAML file defining authorization roles and bindings. |+| `--allowed-audiences` | *None* | `sam-audience` | Comma-separated list of allowed JWT audiences. |+| `--insecure-skip-tls-verify` | *None* | `false` | Set to `true` to skip certificate validation for development/testing OIDC providers. |+| `--keys-db` | *None* | `keys.db` | Path to the BoltDB file storing public/private keys for token validation. |+| `--admin-token` | *None* | *None* | Secret token string required in the HTTP Header `Authorization: Bearer <token>` for admin operations. |+| `--tls-cert-file` | *None* | *None* | Path to the TLS certificate file (enables HTTPS on the admin server). |+| `--tls-key-file` | *None* | *None* | Path to the TLS private key file. |++---++## 3. Configuring Role-Based Policies (`policies.yaml`)++The hub dynamically issues permissions inside the Biscuit token based on identity claims (users or groups) mapped to specific roles in the policy file.++### Example Policy Mapping+Create a `policies.yaml` file in the directory where you run `sam-hub`:++```yaml+version: v1alpha1++# Define authorization roles and their specific network/tool permissions+roles:+ developer-role:+ network:+ allowedTargets:+ - "10.0.0.0/8"+ - "192.168.1.0/24"+ mcp:+ allowedServers:+ - "local-shell-tools"+ - "git-helper"++ admin-role:+ network:+ allowedTargets:+ - "10.0.0.0/8"+ - "172.16.0.0/12"+ mcp:+ allowedServers:+ - "*" # Allow access to all MCP servers++# Bind OIDC user emails or group claims to roles+bindings:+ - user: "[email protected]"+ role: "admin-role"+ - group: "eng-team"+ role: "developer-role"+```++---++## 4. Bootstrapping Example++Here is a script demonstrating how to boot the hub in a secure development environment using Google Accounts as the OIDC provider:++```bash+# 1. Generate a secure 32-byte signing seed+export SAM_HUB_KEY=$(openssl rand -hex 32)++# 2. Configure environment settings+export SAM_OIDC_ISSUER="https://accounts.google.com"+export SAM_OIDC_ID="my-google-client-id.apps.googleusercontent.com"++# 3. Launch sam-hub with HTTPS and policies configured+./bin/sam-hub \+ --listen "/ip4/0.0.0.0/tcp/5001/udp/5001/quic-v1" \+ --policy-file "./policies.yaml" \+ --bind-address "0.0.0.0:9090" \+ --admin-token "super-secret-admin-token" \+ --tls-cert-file "/etc/sam/certs/hub.crt" \+ --tls-key-file "/etc/sam/certs/hub.key"+```diff --git a/site/hugo.toml b/site/hugo.tomlindex 708378d8..693ebd38 100644--- a/site/hugo.toml+++ b/site/hugo.toml@@ -45,19 +45,26 @@ sectionPagesMenu = "main"url = "/docs/quickstart/"weight = 2+ [[menu.main]]+ identifier = "user"+ name = "User Guides"+ title = "User Guides"+ url = "/docs/user/"+ weight = 3+[[menu.main]]identifier = "integrations"name = "Agent Integrations"title = "Agent Integrations"url = "/docs/integrations/"- weight = 3+ weight = 4[[menu.main]]identifier = "development"name = "Developer Guides"title = "Developer Guides"url = "/docs/development/"- weight = 4+ weight = 5[params]privacy_policy = "https://policies.google.com/privacy"