Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
update docs
Antonio Ojead307186431da
diff --git a/README.md b/README.mdindex e533aed8..92b469ad 100644--- a/README.md+++ b/README.md@@ -33,24 +33,65 @@ SAM_HUB_KEY=$(openssl rand -hex 32) \./bin/sam-hub```-### 2. Login a node+### 2. Join a mesh (Enroll node)++To register the node's cryptographic identity with the hub:```bash-./bin/sam-node login --hub http://localhost:8080+./bin/sam-node join http://localhost:8080```-This prints a login URL. After authenticating in browser, paste the returned biscuit token back into the CLI prompt.+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+```-### 3. Run a node+Or run the node by explicitly passing OIDC credentials to dynamically authenticate and enroll on start:```bash-./bin/sam-node run+./bin/sam-node run \+ --oidc-issuer https://issuer.example.com \+ --client-id <id> \+ --client-secret <secret> \+ --api-token my-secret-token```-Or pass a token directly:+## 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-./bin/sam-node run --token <identity-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```## Local MCP Serverdiff --git a/docs/cli/reference.md b/docs/cli/reference.mdindex d037d76a..c5169e1e 100644--- a/docs/cli/reference.md+++ b/docs/cli/reference.md@@ -11,36 +11,52 @@ The current repository exposes two CLIs:sam-node --help```-### sam-node login+### sam-node join-Start the login flow and persist identity biscuit in the local store.+Join the Sovereign Agent Mesh hub and enroll the node.```bash-sam-node login --hub http://localhost:8080+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:-- `--hub`: hub base URL (default `http://localhost:8080`)+* `--data-dir`: Override directory for the agent store (defaults to OS user config dir).### sam-node run-Start the mesh node.+Start the sovereign mesh node.```bash-sam-node run+sam-node run [flags]```Flags:-- `--token`: identity biscuit override (if omitted, load from local store)-- `--listen`: repeatable libp2p listen addresses+* `--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-sam-node run --token <identity-biscuit>-sam-node run --listen /ip4/0.0.0.0/udp/5001/quic-v1 --listen /ip4/0.0.0.0/tcp/5002+# 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-hubdiff --git a/docs/quickstart.md b/docs/quickstart.mdindex dd3301cb..f9aafc3d 100644--- a/docs/quickstart.md+++ b/docs/quickstart.md@@ -31,26 +31,72 @@ SAM_HUB_KEY=$(openssl rand -hex 32) \./bin/sam-hub```-## Login Node+## Join Mesh (Enroll Node)++To register the node's cryptographic identity with the hub:```bash-./bin/sam-node login --hub http://localhost:8080+./bin/sam-node join http://localhost:8080```-The command prints a browser login URL and asks you to paste the identity biscuit token.+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.## Run Node-Using stored identity:+### Using Stored Identity++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):```bash-./bin/sam-node run+./bin/sam-node run --api-token my-secret-token```-Or using explicit 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:++```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 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++Enroll your node interactively into the testnet mesh (e.g. `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+```++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.++### 2. Run the Node++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:```bash-./bin/sam-node run --token <identity-biscuit>+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```## Test