Skip to content

Agent Mesh

Organize documentation into user and developer sections

Antonio Ojeab0cd3f0a3c0b
diff --git a/README.md b/README.md
index 92b469ad..af86918e 100644
--- a/README.md
+++ b/README.md
@@ -2,131 +2,38 @@
<img alt="SAM" src="docs/sam_logo.png" />
-SAM is a smart network built for autonomous agents:
+SAM is a smart network built for autonomous AI agents:
-* **Zero Config:** Nodes discover each other and build the network automatically.
+* **Zero Config:** Nodes discover each other and build the P2P network automatically.
* **Zero Trust:** Every connection, node, and packet is strictly authenticated.
-* **Agentic Network:** Built for agents to use. The nodes provide the self-healing, peer-to-peer infrastructure, allowing autonomous agents to seamlessly plug in, communicate, and operate across the mesh.
-* **Portability:** Environment-agnostic and IP-independent. Network identity is cryptographic and travels with the node, enabling mobility across cloud, edge, and local setups.
+* **Agentic Network:** Formed by lightweight nodes (`sam-node`) that provide self-healing, P2P connectivity, allowing autonomous agents to plug in, communicate, and invoke tools dynamically.
+* **Portability:** Cryptographic identities are environment-agnostic, allowing seamless node mobility across cloud, local, and edge environments.
+---
-- `sam-hub`: The control plane for identity and policy distribution.
-- `sam-node`: The lightweight agents that form the actual peer-to-peer mesh.
+## Architecture Components
-## Build
+* `sam-hub`: The control plane for identity mapping and policy distribution.
+* `sam-node`: The P2P nodes providing the mesh transport layer and local MCP interfaces.
-```bash
-make build
-./bin/sam-node --help
-./bin/sam-hub --help
-```
+---
-## Basic Usage
-
-### 1. Run the hub
-
-```bash
-SAM_OIDC_ISSUER=https://issuer.example.com \
-SAM_OIDC_ID=sam-client \
-SAM_OIDC_SECRET=sam-secret \
-SAM_HUB_KEY=$(openssl rand -hex 32) \
-./bin/sam-hub
-```
-
-### 2. Join a mesh (Enroll node)
-
-To register the node's cryptographic identity with the hub:
-
-```bash
-./bin/sam-node join http://localhost:8080
-```
-
-This initiates the interactive OIDC Device Authorization flow. It prints a URL to open in your browser for authentication. Once authorized, it automatically receives the node's Biscuit identity token and saves it (along with the derived node private key) inside the local data store.
-
-### 3. Run the node
-
-Start the node using the stored identity (note that `--api-token` is mandatory to protect the local API when not using mTLS):
-
-```bash
-./bin/sam-node run --api-token my-secret-token
-```
-
-Or run the node by explicitly passing OIDC credentials to dynamically authenticate and enroll on start:
-
-```bash
-./bin/sam-node run \
- --oidc-issuer https://issuer.example.com \
- --client-id <id> \
- --client-secret <secret> \
- --api-token my-secret-token
-```
-
-## Docker Quick Start
-
-You can run the SAM node using Docker and the officially published image. To persist your node's identity, private key, and mesh discovery configuration across runs, use a host volume mounted to the container's data directory.
-
-### 1. Join the Mesh (Enroll)
-
-Run the container interactively to register your node with the community testnet (`https://bananas.sam-mesh.dev`):
-
-```bash
-docker run -it \
- -v $(pwd)/sam-data:/data \
- ghcr.io/google/sam-node:latest \
- join --data-dir /data https://bananas.sam-mesh.dev
-```
-
-- Follow the printed device authentication instructions in your browser.
-- This generates the node identity and stores it inside `./sam-data/agent.db` on the host.
-
-### 2. Run the Node
-
-Start the background mesh node container using the stored identity. Make sure to publish the required libp2p ports (5001/UDP and 5002/TCP), set a secure `--api-token` to protect the local MCP/Sidecar API, and bind the HTTP server to `0.0.0.0:8080` so that it can be reached from the host:
-
-```bash
-docker run -d \
- --name sam-node \
- -v $(pwd)/sam-data:/data \
- -p 5001:5001/udp \
- -p 5002:5002 \
- -p 8080:8080 \
- ghcr.io/google/sam-node:latest \
- run --data-dir /data --bind-addr 0.0.0.0:8080 --api-token my-secret-token
-```
-
-## Local MCP Server
-
-Each `sam-node` exposes a Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE) to allow local processes to discover the capabilities of the local agent and get information from the mesh.
-
-By default, the server listens at `127.0.0.1:8080`. You can change this with the `--bind-addr` flag.
-
-To query the mesh info via the MCP server, you can use the `mcp-client` tool provided in the repository:
-
-```bash
-./bin/mcp-client -url http://127.0.0.1:8080/mcp/events
-```
-
-## Testing
-
-```bash
-make test
-make test-e2e
-make test-e2e-container
-```
+## Documentation
-`test-e2e-container` runs a containerized BATS framework that starts:
+Start exploring the Sovereign Agent Mesh:
-- a mock OIDC container
-- a `sam-hub` container
-- multiple `sam-node` containers
+### For Users & Operators
+Get a node running on the public testnet (`bananas.sam-mesh.dev`) in minutes:
+- πŸš€ **[User Quick Start Guide](docs/quickstart.md)**: Connect and run a SAM node using Docker and query the local MCP server via `curl`.
+- πŸ“– **[CLI Reference](docs/cli/reference.md)**: Comprehensive CLI reference and configurations.
+- πŸ“‘ **[Testnet Validation Tutorial](docs/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.
-## Documentation
+### For Developers & Contributors
+Compile from source, run local clusters, or execute tests:
+- πŸ› οΈ **[Developer Guide](docs/development.md)**: Prereqs, compilation, local hub setup, and Kubernetes Kind deployment.
+- πŸ§ͺ **[Testing Guide](docs/testing.md)**: Go tests, E2E BATS, and containerized mesh execution.
-- Docs index: `docs/index.html`
-- Project docs landing page: `docs/README.md`
-- Quickstart: `docs/quickstart.md`
-- CLI reference: `docs/cli/reference.md`
-- Testing guide: `docs/testing.md`
+---
## License
@@ -134,6 +41,4 @@ See [LICENSE](LICENSE).
## Disclaimer
-This is not an officially supported Google product. This project is not eligible
-for the [Google Open Source Software Vulnerability Rewards
-Program](https://bughunters.google.com/open-source-security).
+This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
diff --git a/docs/README.md b/docs/README.md
index 590e9145..d3928c87 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -19,10 +19,11 @@ The documentation here is intentionally small and aligned with what is implement
## Start Here
-- [Quick Start](quickstart.md)
-- [CLI Reference](cli/reference.md)
-- [Testing](testing.md)
-- [Testnet Validation](testnet-validation.md)
+- [Quick Start](quickstart.md) - User Quick Start using Docker.
+- [CLI Reference](cli/reference.md) - CLI command usage reference.
+- [Developer Guide](development.md) - Building from source, local testing, and Kind setups.
+- [Testing Guide](testing.md) - Detailed test layer and troubleshooting information.
+- [Testnet Validation Tutorial](testnet-validation.md) - Real-time integration and MCP verification with public testnets.
## Notes
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 00000000..1ec9f980
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,89 @@
+# Developer Guide & Repository Setup
+
+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.
+
+---
+
+## Prerequisites
+
+To build and test the Go binaries natively:
+
+- **Go Toolchain**: Go 1.25+
+- **Docker**: For running containerized integration tests and building local images.
+- **BATS**: `bats-core` framework for running E2E shell tests.
+
+---
+
+## Build from Source
+
+Clone the repository and compile the binaries:
+
+```bash
+git clone https://github.com/google/sam.git
+cd sam
+make build
+```
+
+This compiles and generates the following binaries under `./bin/`:
+
+- `./bin/sam-hub`: The OIDC identity bridge and cryptographic Biscuit token issuer.
+- `./bin/sam-node`: The mesh agent node CLI supporting `join` and `run` commands.
+- `./bin/mcp-client`: A CLI-based utility to interact with MCP servers.
+
+---
+
+## Running a Local Dev Hub
+
+To run `sam-hub` locally for testing, you must supply OIDC issuer configurations and a 32-byte hexadecimal seed key:
+
+```bash
+# Generate a random 32-byte key for biscuit signing
+export SAM_HUB_KEY=$(openssl rand -hex 32)
+export SAM_OIDC_ISSUER=https://issuer.example.com
+export SAM_OIDC_ID=sam-client
+export SAM_OIDC_SECRET=sam-secret
+
+./bin/sam-hub
+```
+
+---
+
+## Testing
+
+The repository implements a testing pyramid. Ensure the test suites are green before pushing code:
+
+### 1. Go Unit & Integration Tests
+Runs the packages' unit tests and multi-node integration tests:
+```bash
+make test
+```
+
+### 2. Local E2E Tests (BATS)
+Validates local command-line behaviors for `sam-node` and `sam-hub`:
+```bash
+make test-e2e
+```
+
+### 3. Containerized Mesh E2E (BATS)
+Builds local Docker images, spins up a mock OIDC server, runs `sam-hub` and multiple `sam-node` containers in a local bridge network, and performs end-to-end device flows and tool discovery:
+```bash
+make test-e2e-container
+```
+
+---
+
+## Local Kubernetes Test Setup
+
+For end-to-end integration testing in a local Kubernetes environment:
+
+1. **Start Kind Cluster**:
+ Ensure you have a Kind cluster running.
+2. **Build and Load Images**:
+ ```bash
+ make docker-build-node
+ make docker-build-hub
+ kind load docker-image sam-node:local
+ kind load docker-image sam-hub:local
+ ```
+3. **Deploy Config Templates**:
+ Deploy and template configuration files located under `.github/k8s/` or `development/kind/` to spin up local nodes and vLLM inference engines.
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 0be00470..920ba891 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,110 +1,111 @@
# Quick Start
-## Prerequisites
+This guide gets you up and running with a SAM node connected to the public `bananas.sam-mesh.dev` mesh using Docker.
-- Go toolchain
-- Docker (for containerized e2e tests)
-- BATS (`bats-core`)
+---
-## Build
+## 1. Join the Mesh
-```bash
-git clone https://github.com/google/sam.git
-cd sam
-make build
-```
-
-This creates:
-
-- `./bin/sam-hub`
-- `./bin/sam-node`
-
-## Start Hub
+To register your node with the mesh and obtain a cryptographic identity token (Biscuit), run the OIDC device authorization flow.
-`sam-hub` requires OIDC issuer settings and a 32-byte hex key seed.
+Create a local directory on your host to persist your node identity:
```bash
-SAM_OIDC_ISSUER=https://issuer.example.com \
-SAM_OIDC_ID=sam-client \
-SAM_OIDC_SECRET=sam-secret \
-SAM_HUB_KEY=$(openssl rand -hex 32) \
-./bin/sam-hub
+mkdir -p $(pwd)/sam-data
```
-## Join Mesh (Enroll Node)
-
-To register the node's cryptographic identity with the hub:
+Enroll your node:
```bash
-./bin/sam-node join http://localhost:8080
+docker run -it \
+ -v $(pwd)/sam-data:/data \
+ ghcr.io/google/sam-node:latest \
+ join --data-dir /data https://bananas.sam-mesh.dev
```
-This initiates an interactive OIDC Device Authorization flow. It prints a verification URL for you to navigate to in your browser. Once authenticated, the hub registers your node ID and responds with the cryptographic Biscuit identity token. This token, along with the derived node private key and hub discovery addresses, is stored in your local data directory.
+1. The container will output a Device Authorization URL and a validation code.
+2. Open the URL in your web browser and sign in.
+3. Once authenticated, the container registers the node, saves the identity to `/data/agent.db` (persisted on your host at `./sam-data/agent.db`), and exits.
-## Run Node
+---
-### Using Stored Identity
+## 2. Run the Node
-If the node has already joined a mesh, start it simply by running (note that `--api-token` is mandatory to protect the local API when not using mTLS):
+Start your node in the background. We set a security `--api-token` to protect access to the local control plane API and map the required ports:
+
+- `5001/udp` and `5002/tcp`: Libp2p swarm connection ports.
+- `8080/tcp`: Local MCP SSE HTTP API.
```bash
-./bin/sam-node run --api-token my-secret-token
+docker run -d \
+ --name sam-node \
+ -v $(pwd)/sam-data:/data \
+ -p 5001:5001/udp \
+ -p 5002:5002 \
+ -p 8080:8080 \
+ ghcr.io/google/sam-node:latest \
+ run --data-dir /data --bind-addr 0.0.0.0:8080 --api-token my-secret-token
```
-This automatically loads the private key and authorized Biscuit token from the persistent local store.
-
-### Using explicit OIDC Credentials
-
-Alternatively, you can skip the manual `join` step and pass OIDC client credentials directly on startup so the node registers and enrolls dynamically:
+To verify the node is running and connected to the testnet, check the logs:
```bash
-./bin/sam-node run \
- --oidc-issuer https://issuer.example.com \
- --client-id <id> \
- --client-secret <secret> \
- --api-token my-secret-token
+docker logs sam-node
```
-## Docker Quick Start
+You should see:
+```text
+INFO sam-node [AuthN] Successfully authenticated with hub via libp2p: ...
+SAM Node Online.
+PeerID: 12D3KooW...
+```
-You can fully manage and run your SAM node using Docker. To persist the node identity, cryptographic keys, and peer authorization store, mount a local directory as a volume to the container.
+---
-### 1. Join the Mesh
+## 3. Query the Local MCP API
-Enroll your node interactively into the testnet mesh (e.g. `https://bananas.sam-mesh.dev`):
+Your SAM node exposes a standard Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE) at `http://localhost:8080/mcp/message`. You can interact with it using simple `curl` commands.
+
+### List Local Control Plane Tools
+Query the list of tools available on your local node (e.g. peer discovery, message broadcast, and remote tool execution):
```bash
-docker run -it \
- -v $(pwd)/sam-data:/data \
- ghcr.io/google/sam-node:latest \
- join --data-dir /data https://bananas.sam-mesh.dev
+curl -X POST \
+ -H "Authorization: Bearer my-secret-token" \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
+ http://localhost:8080/mcp/message
```
-1. The CLI will output a Device Authorization URL.
-2. Visit the URL in your browser to authenticate.
-3. Upon successful login, the container will complete registration, save the credentials inside `/data/agent.db` (persisted at `./sam-data/agent.db` on your host), and terminate.
+### Discover Remote Services in the Mesh
+List active MCP services currently registered across the public mesh network:
-### 2. Run the Node
+```bash
+curl -X POST \
+ -H "Authorization: Bearer my-secret-token" \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"discover_remote_services","arguments":{"type":"mcp"}},"id":2}' \
+ http://localhost:8080/mcp/message
+```
-Start your node as a background container using the stored configuration and credentials. Make sure to bind the internal HTTP server to `0.0.0.0:8080` so that you can access the local MCP/Sidecar API from outside the container, publish the libp2p network ports, and set the required `--api-token` parameter:
+### Find Remote Tools on a Peer
+Using a `peer_id` returned from the service discovery, find the tools available on that peer:
```bash
-docker run -d \
- --name sam-node \
- -v $(pwd)/sam-data:/data \
- -p 5001:5001/udp \
- -p 5002:5002 \
- -p 8080:8080 \
- ghcr.io/google/sam-node:latest \
- run --data-dir /data --bind-addr 0.0.0.0:8080 --api-token my-secret-token
+curl -X POST \
+ -H "Authorization: Bearer my-secret-token" \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"find_remote_tools","arguments":{"peer_id":"<target-peer-id>"}},"id":3}' \
+ http://localhost:8080/mcp/message
```
-## Test
+### Call a Remote Tool
+Call a tool hosted on a remote peer through your local node's P2P stream reverse proxy:
```bash
-make test
-make test-e2e
-make test-e2e-container
+curl -X POST \
+ -H "Authorization: Bearer my-secret-token" \
+ -H "Content-Type: application/json" \
+ -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"call_remote_tool","arguments":{"peer_id":"<target-peer-id>","tool_name":"everything.get-sum","arguments":{"a":12.5,"b":7.5}}},"id":4}' \
+ http://localhost:8080/mcp/message
```
-
-`make test-e2e-container` runs hub + multiple node containers with a mock OIDC provider.