Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
incorporate jim feedback
Antonio Ojea4a6ede3bb4c9
diff --git a/site/content/_index.md b/site/content/_index.mdindex f0788c9e..7ae41a7c 100644--- a/site/content/_index.md+++ b/site/content/_index.md@@ -2,4 +2,8 @@title: SAMdescription: Sovereign Agent Mesh - A zero-config, zero-trust decentralized mesh network built for autonomous AI agents.---+SAM (Sovereign Agent Mesh) provides a secure, zero-trust P2P network specifically designed for AI agents to discover, share, and invoke tools across machines.+Think of it as a private, zero-trust overlay network tailored for agent-to-agent communication.++**Secure by Default**: You do not join a mesh automatically, and your tools are never exposed by default. SAM relies on a Zero-Trust architecture, meaning you are 100% isolated until you explicitly join a hub and allow access. You can use our public testnet for "Easy Mode" testing, or run completely in "DIY Mode" by hosting your own control plane.diff --git a/site/content/docs/_index.md b/site/content/docs/_index.mdindex 808e464e..9d7528c6 100644--- a/site/content/docs/_index.md+++ b/site/content/docs/_index.md@@ -2,24 +2,36 @@title: "SAM Documentation"linkTitle: "Documentation"----SAM (Sovereign Agent Mesh) is a smart, zero-config, zero-trust P2P network built for autonomous AI agents.+SAM (Sovereign Agent Mesh) is a smart, zero-config, zero-trust P2P network built for autonomous AI agents. Think of it as a modern, zero-trust overlay network (similar to a private VPN), but specifically designed and scoped for agent-to-agent tool sharing and communication.-## Architecture+## Why SAM?-* **`sam-hub`**: The control plane for identity mapping, token issuing, and policy distribution.-* **`sam-node`**: The P2P nodes providing the mesh transport layer, self-healing connectivity, and local Model Context Protocol (MCP) HTTP interfaces.+Instead of exposing your agent's tools (like local scripts, LLM endpoints, or internal APIs) to the public internet, SAM allows you to create secure, private mesh networks. This is especially critical because modern AI agents operate across highly heterogeneous environmentsβspanning cloud servers, on-premises datacenters, personal laptops, Raspberry Pis, and Android devices. SAM seamlessly connects them all, regardless of complex network topologies or NATs.++**Security & Trust Boundaries (Read This First!)**+* **Isolated by Default:** You do NOT join any mesh by default. You must explicitly configure the control plane (Hub) you want to join.+* **Closed by Default:** Joining a mesh does not expose your tools. By default, your node does not allow any services to be reached by others. You must explicitly configure policies to share tools.+* **Bring Your Own Control Plane (DIY):** While we offer public testnets, the core design allows you to host your own `sam-hub` control plane. You retain 100% control over your data, identities, and authorization policies.---## Where to Start-### For Users & Operators-Get a node running on the public testnet (`bananas.sam-mesh.dev`) in minutes:-- π **[User Quick Start Guide](quickstart.md)**: Connect and run a SAM node using binaries or Docker, and query the local MCP server.-- π€ **[Agent Integration Guide](user/agent-usage.md)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to call tools across the mesh.-- π‘ **[Testnet Validation Tutorial](development/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.+### "Easy Mode" (Public Testnet)+For the fastest way to get started and experiment, you can join our public beta testnet (`bananas.sam-mesh.dev`). *Note: While convenient, remember this is a public testnet. Ensure you only expose tools you are comfortable sharing in a testing environment.*++- π **[User Quick Start Guide](quickstart/)**: Connect and run a SAM node using binaries or Docker, and query the local MCP server.+- π€ **[Agent Integration Guide](user/agent-usage/)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to call tools across the mesh.+- π‘ **[Testnet Validation Tutorial](development/testnet-validation/)**: Real-time verification, remote tool invocation, and HTTP stream proxies.++### "DIY Mode" (Self-Hosted for Developers & Operators)+Compile from source, run local clusters, host your own control plane, or execute tests:+- π οΈ **[Developer Guide](development/)**: Prereqs, compilation, local hub setup, and Kubernetes Kind deployment.+- π§ͺ **[Testing Guide](development/testing/)**: Go tests, E2E BATS, and containerized mesh execution.-### For Developers & Contributors-Compile from source, run local clusters, or execute tests:-- π οΈ **[Developer Guide](development/_index.md)**: Prereqs, compilation, local hub setup, and Kubernetes Kind deployment.-- π§ͺ **[Testing Guide](development/testing.md)**: Go tests, E2E BATS, and containerized mesh execution.+---++## Architecture++* **`sam-hub`**: The control plane for identity mapping, token issuing, and policy distribution.+* **`sam-node`**: The P2P nodes providing the mesh transport layer, self-healing connectivity, and local Model Context Protocol (MCP) HTTP interfaces.diff --git a/site/content/docs/integrations/_index.md b/site/content/docs/integrations/_index.mdindex 856af7b0..eee1f485 100644--- a/site/content/docs/integrations/_index.md+++ b/site/content/docs/integrations/_index.md@@ -15,11 +15,11 @@ Every `sam-node` runs a local MCP server that allows agents to:Explore the step-by-step guides to integrate SAM with your favorite AI Agent systems:-- [Google Gemini](gemini.md): Build an interactive client using the official `google-genai` Python SDK.-- [Google Antigravity](antigravity.md): Connect your local node as a remote MCP server to Google Antigravity.-- [Claude Code](claude-code.md): Connect your local node as a remote MCP server to Claude Code.-- [Claude Desktop](claude-desktop.md): Use SAM to expose the P2P tool mesh to Claude Desktop.-- [OpenClaw](openclaw.md): Integrate your node as a remote tool bridge for OpenClaw.+- [Google Gemini](gemini/): Build an interactive client using the official `google-genai` Python SDK.+- [Google Antigravity](antigravity/): Connect your local node as a remote MCP server to Google Antigravity.+- [Claude Code](claude-code/): Connect your local node as a remote MCP server to Claude Code.+- [Claude Desktop](claude-desktop/): Use SAM to expose the P2P tool mesh to Claude Desktop.+- [OpenClaw](openclaw/): Integrate your node as a remote tool bridge for OpenClaw.## Connecting via MCPdiff --git a/site/content/docs/integrations/claude-code.md b/site/content/docs/integrations/claude-code.mdindex af650f66..d4b1f204 100644--- a/site/content/docs/integrations/claude-code.md+++ b/site/content/docs/integrations/claude-code.md@@ -10,7 +10,7 @@ You can connect your `sam-node` to [Claude Code](https://claude.com/claude-code)## Prerequisites-- A running `sam-node` with its local control-plane API reachable (default `http://localhost:8080`). See the [Quick Start](../quickstart.md).+- A running `sam-node` with its local control-plane API reachable (default `http://localhost:8080`). See the [Quick Start](../quickstart/).- The `--api-token` you launched the node with.- Claude Code installed (the `claude` CLI).diff --git a/site/content/docs/integrations/claude-desktop.md b/site/content/docs/integrations/claude-desktop.mdindex 79c1ab27..7acf2ed6 100644--- a/site/content/docs/integrations/claude-desktop.md+++ b/site/content/docs/integrations/claude-desktop.md@@ -2,7 +2,7 @@title: "Integrating SAM with Claude Desktop"linkTitle: "Integrating SAM with Claude Desktop"----You can connect your `sam-node` to the [Claude Desktop](https://claude.com/download) app as an MCP server. Unlike [Claude Code](./claude-code.md), Claude Desktop has its own configuration and does **not** read Claude Code's MCP settings.+You can connect your `sam-node` to the [Claude Desktop](https://claude.com/download) app as an MCP server. Unlike [Claude Code](./claude-code/), Claude Desktop has its own configuration and does **not** read Claude Code's MCP settings.## Overview@@ -49,7 +49,7 @@ Restart Claude Desktop for the change to take effect. The `sam-node` tools β `## Discovering and Invoking Remote Tools-The tool flow is identical to the [Claude Code guide](./claude-code.md#discovering-and-invoking-remote-tools):+The tool flow is identical to the [Claude Code guide](./claude-code/#discovering-and-invoking-remote-tools):1. `discover_remote_services` β list active services and obtain their `peer_id`s.2. `find_remote_tools` (`peer_id`) β list the tools a peer hosts.diff --git a/site/content/docs/integrations/gemini.md b/site/content/docs/integrations/gemini.mdindex 3a06181c..1b662695 100644--- a/site/content/docs/integrations/gemini.md+++ b/site/content/docs/integrations/gemini.md@@ -11,7 +11,7 @@ By exposing the SAM Model Context Protocol (MCP) server to Gemini, the agent can## Prerequisites1. **Python 3.10+**: Ensure Python is installed on your host.-2. **SAM Node Running**: A local SAM node should be running and enrolled on the testnet (see the [Quick Start Guide](../quickstart.md)).+2. **SAM Node Running**: A local SAM node should be running and enrolled on the testnet (see the [Quick Start Guide](../quickstart/)).3. **Gemini API Key**: Obtain an API key from Google AI Studio and export it:```bashexport GEMINI_API_KEY="your-api-key-here"diff --git a/site/content/docs/user/_index.md b/site/content/docs/user/_index.mdindex 7ac5d094..d5b66c7f 100644--- a/site/content/docs/user/_index.md+++ b/site/content/docs/user/_index.md@@ -8,11 +8,11 @@ Welcome to the User & Operator Guides. This section provides detailed documentat### In This Section-1. **[Hub Configuration](hub-configuration.md)**+1. **[Hub Configuration](hub-configuration/)**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)**+2. **[Agent Usage & Connectivity](agent-usage/)**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).-3. **[Production Kubernetes Deployment](kubernetes-deployment.md)**+3. **[Production Kubernetes Deployment](kubernetes-deployment/)**Deploy a production-grade mesh cluster in Kubernetes, including Dex OIDC setups, StatefulSet P2P hubs, DNS A-record synchronizers, and Workload Identity ServiceAccount token projections.diff --git a/site/content/docs/user/agent-usage.md b/site/content/docs/user/agent-usage.mdindex fdf2af0a..111c8c0b 100644--- a/site/content/docs/user/agent-usage.md+++ b/site/content/docs/user/agent-usage.md@@ -98,7 +98,7 @@ Authorization: Bearer my-agent-super-token-123### Specific Integration GuidesExplore 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.+* π **[Google Gemini AI Agent](../integrations/gemini/)**: Connect using Python scripts and the google-genai SDK.+* π» **[Claude Desktop](../integrations/claude-desktop/)**: Expose P2P tools directly to your Claude Desktop application menu.+* π€ **[Claude Code](../integrations/claude-code/)**: Add your local node tools directly to the Claude CLI.+* π **[OpenClaw](../integrations/openclaw/)**: Setup remote tool bridges for OpenClaw clusters.