Skip to content

Agent Mesh

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.md
index 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.md
index 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:
```bash
sam-node join https://bananas.sam-mesh.dev
diff --git a/site/content/docs/getting-started/your-own-mesh.md b/site/content/docs/getting-started/your-own-mesh.md
index 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: