Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: showcase the beginner demo, reshape quickstart around join-then-run
Antonio Ojea7888aa492917
diff --git a/README.md b/README.mdindex 8ce6257c..c9c9f5fd 100644--- a/README.md+++ b/README.md@@ -9,7 +9,7 @@ SAM is a smart network built for autonomous AI agents:* **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.-Getting started is a one-liner: install, add the skill, and your agent is on the mesh.+Getting started is a one-liner (see the [Quick Start Guide](site/content/docs/quickstart.md)): install, add the skill, and your agent is on the mesh.<img src="site/static/demo.gif" alt="Demo: installing SAM, adding the sam-mesh skill, and an agent discovering and calling tools across the mesh" width="100%" />diff --git a/site/content/docs/quickstart.md b/site/content/docs/quickstart.mdindex d6e8ace1..42c986c8 100644--- a/site/content/docs/quickstart.md+++ b/site/content/docs/quickstart.md@@ -40,73 +40,13 @@ Expand-Archive -Path "sam.zip" -DestinationPath "$env:ProgramFiles\sam"## 2. Connect Your Node to the Mesh-Getting a node onto the mesh takes two things: **joining** — registering the node and obtaining its cryptographic identity (a Biscuit token) via an OIDC login — and **running** it. The `--join` flag on `run` does both in one command: it enrolls the first time (when the node has no identity yet), then starts serving; on every later restart it's a no-op since the identity is already stored.+**Shortcut: let your agent do it.** If you use an agent that supports skills (Claude Code, Google Antigravity, …), install the [agent skill](#4-teach-your-ai-agent-to-use-the-mesh) with `sam-node skill install`, restart the agent, and ask it to connect to the mesh. The skill walks it through starting the node and registering the MCP endpoint on its own — the only thing it hands back to you is the one-time enrollment login below.-### Recommended: One Command+Getting a node onto the mesh takes two steps: **joining** — registering the node and obtaining its cryptographic identity (a Biscuit token) via an OIDC login — and **running** it. We recommend doing them as two explicit commands: enrollment is a one-time step per machine whose prompts (browser login, admin approval) are easier to follow on their own, and it is the same flow the [agent skill](#4-teach-your-ai-agent-to-use-the-mesh) guides your agent through. If you prefer a single command, see the [alternative below](#alternative-one-command).-#### Using the Binary-The binary is the simplest way to run a node locally — no volumes or port mapping to think about:-```bash-SAM_API_TOKEN=my-secret-token sam-node run --join --bind-addr 127.0.0.1:8080-```-The CLI will open your browser for login (or print a device code if headless). Once authenticated:-```text-Successfully joined the Sovereign Agent Mesh!-INFO sam-node [AuthN] Successfully authenticated with router via libp2p: ...-SAM Node Online.-PeerID: 12D3KooW...-```--#### Using Docker-Docker works the same way, but needs a persistent volume for the identity and explicit port mapping (`5001/udp`, `5002/tcp` for libp2p, `8080/tcp` for the local API):-```bash-mkdir -p $(pwd)/sam-data-docker run -it \- --user "$(id -u):$(id -g)" \- -v $(pwd)/sam-data:/data \- -p 5001:5001/udp \- -p 5002:5002 \- -p 8080:8080 \- -e SAM_API_TOKEN=my-secret-token \- ghcr.io/google/sam-node:latest \- run --join --data-dir /data --bind-addr 0.0.0.0:8080-```-Use `-it` for this first run so you can complete the browser/device-code login; once enrolled, restart it detached with `-d` instead (`--join` is a no-op at that point, so it's safe to leave in your start command). If there's no interactive terminal attached (e.g. `-d` on the very first run), the node instead comes up as an unauthenticated sidecar waiting for out-of-band enrollment over MCP.--By default `--join` enrolls with the public testnet (`bananas.sam-mesh.dev`); pass `--control-plane <url>` to join a different mesh.--#### Running It in the Background+### Recommended: Join, Then Run-`sam-node run` stays in the foreground. Add `--daemonize` to start it detached and return as soon as its local API answers — useful when an AI agent is driving the setup, or when you don't want a terminal dedicated to the node:--```bash-sam-node run --daemonize-```-```text-sam-node is running in the background.- PID 48213- Endpoint http://127.0.0.1:8080/mcp- Token /home/you/.config/sam-mesh/api-token- Logs /home/you/.config/sam-mesh/sam-node.log- Stop kill 48213-```--If no API token is configured (`SAM_API_TOKEN` or `--api-token-path`), `--daemonize` generates one under the data directory and reuses it on later starts. The command is idempotent: re-run it to confirm a node is up. Enrollment still needs a one-time login, so on a node with no identity it tells you to run `sam-node join --headless <control-plane-url>` first. In headless mode, SAM prefers OAuth device flow automatically when the provider supports it, and falls back to OOB code-paste only when needed.--#### Starting Over--A node reuses whatever is already in its data directory, which is what you want day to day but not when you are testing setup flows. Two levels of reset:--```bash-sam-node reset # forget the mesh identity only, keep the PeerID-sam-node reset --all # delete every file the node keeps, including its key-```--`--all` asks for confirmation, and needs `--yes` when there is no terminal to ask on. Both refuse while a node is still running, so stop it first (`kill <pid>` from the `--daemonize` output). After `--all` the node generates a new PeerID and has to enroll again.--### Alternative: Join and Run Separately--If you're deploying headlessly with a pre-issued bootstrap token, or just prefer explicit steps, you can join and run as two commands instead.+Join once to enroll the node, then run it. The identity is stored in the node's data directory and reused on every later start.#### Step 1: Join the Mesh@@ -186,6 +126,66 @@ docker run -d \```Verify the node is running with `docker logs sam-node`.+#### Running It in the Background++`sam-node run` stays in the foreground. Add `--daemonize` to start it detached and return as soon as its local API answers — useful when an AI agent is driving the setup, or when you don't want a terminal dedicated to the node:++```bash+sam-node run --daemonize+```+```text+sam-node is running in the background.+ PID 48213+ Endpoint http://127.0.0.1:8080/mcp+ Token /home/you/.config/sam-mesh/api-token+ Logs /home/you/.config/sam-mesh/sam-node.log+ Stop kill 48213+```++If no API token is configured (`SAM_API_TOKEN` or `--api-token-path`), `--daemonize` generates one under the data directory and reuses it on later starts. The command is idempotent: re-run it to confirm a node is up. Enrollment still needs a one-time login, so on a node with no identity it tells you to run `sam-node join --headless <control-plane-url>` first. In headless mode, SAM prefers OAuth device flow automatically when the provider supports it, and falls back to OOB code-paste only when needed.++#### Starting Over++A node reuses whatever is already in its data directory, which is what you want day to day but not when you are testing setup flows. Two levels of reset:++```bash+sam-node reset # forget the mesh identity only, keep the PeerID+sam-node reset --all # delete every file the node keeps, including its key+```++`--all` asks for confirmation, and needs `--yes` when there is no terminal to ask on. Both refuse while a node is still running, so stop it first (`kill <pid>` from the `--daemonize` output). After `--all` the node generates a new PeerID and has to enroll again.++### Alternative: One Command++The `--join` flag on `run` does both steps in one command: it enrolls the first time (when the node has no identity yet), then starts serving; on every later restart it's a no-op since the identity is already stored. By default `--join` enrolls with the public testnet (`bananas.sam-mesh.dev`); pass `--control-plane <url>` to enroll with a different mesh.++#### Using the Binary+```bash+SAM_API_TOKEN=my-secret-token sam-node run --join --bind-addr 127.0.0.1:8080+```+The CLI will open your browser for login (or print a device code if headless). Once authenticated:+```text+Successfully joined the Sovereign Agent Mesh!+INFO sam-node [AuthN] Successfully authenticated with router via libp2p: ...+SAM Node Online.+PeerID: 12D3KooW...+```++#### Using Docker+```bash+mkdir -p $(pwd)/sam-data+docker run -it \+ --user "$(id -u):$(id -g)" \+ -v $(pwd)/sam-data:/data \+ -p 5001:5001/udp \+ -p 5002:5002 \+ -p 8080:8080 \+ -e SAM_API_TOKEN=my-secret-token \+ ghcr.io/google/sam-node:latest \+ run --join --data-dir /data --bind-addr 0.0.0.0:8080+```+Use `-it` for this first run so you can complete the browser/device-code login; once enrolled, restart it detached with `-d` instead (`--join` is a no-op at that point, so it's safe to leave in your start command). If there's no interactive terminal attached (e.g. `-d` on the very first run), the node instead comes up as an unauthenticated sidecar waiting for out-of-band enrollment over MCP.+## 3. Query the Local MCP APIYour SAM node exposes a standard Model Context Protocol (MCP) server. The easiest way to interact with it is using the `mcp-client` CLI tool (which is installed alongside `sam-node`):@@ -249,3 +249,5 @@ sam-node skill show # print the document, for agents with a diffe```Re-run `sam-node skill install` after upgrading `sam-node` to refresh the document. Then connect your agent to the node's MCP endpoint — see the [integration guides](../integrations/) — and restart it so both the skill and the tools load.++With the skill installed you can also skip the manual setup entirely and ask the agent to bring itself online (for example: *"connect to the sam mesh and show me what tools are available"*). The skill teaches it to start the node with `sam-node run --daemonize`, read the API token, and register the MCP endpoint itself; it only stops to hand you the one-time `sam-node join` login, which stays with a human by design.diff --git a/site/content/docs/use-cases/warm-agent-pool.md b/site/content/docs/use-cases/warm-agent-pool.mdindex a6761722..0f9461e0 100644--- a/site/content/docs/use-cases/warm-agent-pool.md+++ b/site/content/docs/use-cases/warm-agent-pool.md@@ -8,7 +8,7 @@ Fan a batch of work across a pool of identical, already-running worker agentsbuilt entirely from ordinary mesh MCP services, no gossip and no node changes.<video autoplay loop muted playsinline controls style="width: 100%; border-radius: 8px;">- <source src="/demo-warm-agent-pool.mp4" type="video/mp4">+ <source src="../../../demo-warm-agent-pool.mp4" type="video/mp4"></video>Source: [`development/examples/code-reviewer-pool/`](https://github.com/google/sam/tree/main/development/examples/code-reviewer-pool).