Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs(getting-started): clarify that a mesh requires a running control plane and its URL
Antonio Ojea4479a97ef000
diff --git a/site/content/docs/getting-started/_index.md b/site/content/docs/getting-started/_index.mdindex 8b4bd6ae..34e36191 100644--- a/site/content/docs/getting-started/_index.md+++ b/site/content/docs/getting-started/_index.md@@ -4,18 +4,22 @@ linkTitle: "Getting started"weight: 1----To connect an agent or machine to a SAM mesh, `sam-node` only needs one thing:-a **Control Plane URL** (`https://...`).+Every SAM mesh has a **control plane** (which enrolls members, distributes+policy, and runs the router) and the **members** (`sam-node` or native SDK+programs) that connect to it.-## How to obtain a Control Plane URL+To connect an agent or machine to a mesh, you need **a running control plane+and its URL** (`https://...`).-Pick the option that matches what you want to do right now:+## How to get a control plane and its URL-| Option | Command to get your URL | Architecture & Ingress | Best for |+Pick the option that matches what you want to do:++| Control plane option | How to run it and obtain its URL | Architecture & Ingress | Best for ||---|---|---|---|-| **1. Public Testnet** | Use **`https://bananas.sam-mesh.dev`** directly | Hosted shared playground (no setup required) | Trying SAM and calling your first remote tool or model in 60 seconds ([Quick start](quickstart/)). |-| **2. Local / Workstation (`sam-one`)** | `sam-one --data-dir ~/sam-one --tunnel cloudflare --tunnel-install` | Single binary with SQLite + automatic HTTPS tunnel | Running a private mesh across workstations, VMs, and phones in seconds. Prints your HTTPS URL, join token, and QR code in the terminal ([Your own mesh](your-own-mesh/)). |-| **3. Cloud Deployment (1 Command)** | **[Cloud Run](../guides/cloud-run/)**: `gcloud run deploy sam-one --image ghcr.io/google/sam-one:latest ...`<br>**[SkyPilot](../guides/skypilot/)**: `sky launch -c sam-hub deploy/skypilot/sam-one.yaml` | Managed TLS/WSS ingress + PostgreSQL or persistent disk *(can also run on cloud free tiers for testing)* | An always-on production control plane in your own cloud account without custom Docker builds or Kubernetes ([Cloud Run](../guides/cloud-run/) · [SkyPilot](../guides/skypilot/)). |+| **1. Shared Public Testnet** | Already running — use **`https://bananas.sam-mesh.dev`** | Hosted shared control plane and router | Trying `sam-node` and calling your first remote tool or model in 60 seconds ([Quick start](quickstart/)). |+| **2. Local Control Plane (`sam-one`)** | Run `sam-one --data-dir ~/sam-one --tunnel cloudflare --tunnel-install` and copy `API URL:` from the startup banner | Single binary (control plane + router + console) with SQLite and an HTTPS tunnel | Running your own private mesh from a workstation or VM in seconds ([Your own mesh](your-own-mesh/)). |+| **3. Cloud Control Plane (`sam-one`)** | **[Cloud Run](../guides/cloud-run/)**: `gcloud run deploy sam-one --image ghcr.io/google/sam-one:latest ...`<br>**[SkyPilot](../guides/skypilot/)**: `sky launch -c sam-hub deploy/skypilot/sam-one.yaml` | Always-on `sam-one` with managed TLS/WSS ingress + PostgreSQL or persistent disk *(can also run on cloud free tiers for testing)* | Operating a dedicated production control plane in your own cloud account ([Cloud Run](../guides/cloud-run/) · [SkyPilot](../guides/skypilot/)). |---diff --git a/site/content/docs/getting-started/quickstart.md b/site/content/docs/getting-started/quickstart.mdindex 343c30c7..6b4284f0 100644--- a/site/content/docs/getting-started/quickstart.md+++ b/site/content/docs/getting-started/quickstart.md@@ -33,14 +33,15 @@ On Windows, download `sam_Windows_x86_64.zip` from the[releases page](https://github.com/google/sam/releases) and put `sam-node.exe`on your `PATH`.-## 2. Enroll with a Control Plane URL+## 2. Enroll with a control plane-Every node joins a mesh using its **Control Plane URL**:+Every node joins a mesh by enrolling with a running **control plane** at its+**URL**:-- **Public playground (used below)**: `https://bananas.sam-mesh.dev` — open to any developer; authenticates in your browser.-- **Your own mesh**: run `sam-one --tunnel cloudflare --tunnel-install` (or deploy `ghcr.io/google/sam-one:latest` via [SkyPilot, Fly.io, or Cloud Run](../your-own-mesh/#where-to-get-your-control-plane-url)) and copy the `API URL` and `sam-node join` command printed in the startup banner.+- **Shared public testnet (used below)**: `https://bananas.sam-mesh.dev` is an already-running control plane open to any developer; it authenticates in your browser.+- **Your own control plane**: start your own control plane with `sam-one` on your workstation or in the cloud ([Your own mesh](../your-own-mesh/), [Cloud Run](../../guides/cloud-run/), or [SkyPilot](../../guides/skypilot/)) and copy the `API URL` and `sam-node join` command printed in the `sam-one` startup banner.-Enroll your node against the public testnet:+Enroll your node against the public testnet control plane:```bashsam-node join https://bananas.sam-mesh.devdiff --git a/site/content/docs/getting-started/your-own-mesh.md b/site/content/docs/getting-started/your-own-mesh.mdindex 059c7a98..798e9f72 100644--- a/site/content/docs/getting-started/your-own-mesh.md+++ b/site/content/docs/getting-started/your-own-mesh.md@@ -15,21 +15,22 @@ code as a Kubernetes deployment, so what you learn here applies there too.You need the `sam-one` and `sam-node` binaries. The[install script](../quickstart/#1-install) provides both.-## 1. Start the control plane and get your URL+## 1. Start the control plane and obtain its URL-`sam-one` packages the control plane, the libp2p WebSocket router, and the web-console into a single binary on one port. Whenever it starts—on your laptop, in-a container, or on a cloud VM—it prints a startup banner containing your-**Control Plane URL (`API URL`)**, your tokens, and the exact `sam-node join`-command to copy-paste.+Every SAM mesh needs a running control plane and router. `sam-one` packages the+control plane, the libp2p WebSocket router, and the web console into a single+binary on one port. When `sam-one` starts—on your machine, in a container, or+on a cloud VM—it brings up the control plane and prints a startup banner+containing its **URL (`API URL`)**, its tokens, and the `sam-node join` command+for nodes to connect to it.-### Where to get your Control Plane URL+### Ways to run `sam-one` and obtain its URL-| Where your nodes run | How to start `sam-one` | Control Plane URL you get |+| Where your nodes run | How to run `sam-one` | Control plane URL you get ||---|---|---|| **Across machines, VMs, or phones** *(Instant HTTPS tunnel)* | `sam-one --data-dir ~/sam-one --tunnel cloudflare --tunnel-install` | Public `https://<name>.trycloudflare.com` URL + terminal QR code || **Same machine only** *(Local development)* | `sam-one --data-dir ~/sam-one` | Local `http://127.0.0.1:<port>` URL |-| **Custom domain behind NAT/firewall** *(Cloudflare Named Tunnel)* | `sam-one --data-dir ~/sam-one --tunnel cloudflare --tunnel-token-path ~/cf-token --external-url https://mesh.example.com` | Permanent `https://mesh.example.com` URL (no inbound firewall ports) |+| **Custom domain behind NAT/firewall** | `sam-one --data-dir ~/sam-one --tunnel cloudflare --tunnel-token-path ~/token --external-url https://mesh.example.com` | Permanent `https://mesh.example.com` URL (no inbound firewall ports) || **Always-on Cloud Deployment** *(Cloud Run, SkyPilot)* | See [Cloud Run](../../guides/cloud-run/) (`gcloud run deploy`) or [SkyPilot](../../guides/skypilot/) (`sky launch`) | `https://<svc>.a.run.app` or `https://mesh.example.com` |For example, starting `sam-one` locally: