Skip to content

Agent Mesh

docs: position cloud deployments for production and add 2-node verification

Antonio Ojea611cee08908c
diff --git a/deploy/skypilot/sam-one.yaml b/deploy/skypilot/sam-one.yaml
index 450209de..743ef06a 100644
--- a/deploy/skypilot/sam-one.yaml
+++ b/deploy/skypilot/sam-one.yaml
@@ -1,28 +1,24 @@
-# SkyPilot recipe for running a standalone SAM control plane + router (sam-one)
-# on the cheapest or Always-Free tier VM in your cloud account (GCP, AWS,
-# Azure, OCI, or Kubernetes).
+# SkyPilot recipe for deploying a standalone SAM control plane + router (sam-one)
+# on any cloud provider (GCP, AWS, Azure, OCI, or Kubernetes).
#
-# Quick start (free TryCloudflare HTTPS tunnel, zero DNS/TLS/firewall setup):
-# sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
-# sky logs sam-hub 1 --no-follow
-#
-# The startup banner in `sky logs sam-hub 1 --no-follow` prints:
-# - API URL: https://<name>.trycloudflare.com
-# - Web Console: https://<name>.trycloudflare.com/console
-# - Admin Token & Join Token
-# - The exact `sam-node join <URL>` command and mobile QR code
-#
-# Optional: For a permanent custom domain ($0/mo Cloudflare Named Tunnel), pass:
+# Production deployment with a permanent custom domain (Cloudflare Named Tunnel):
# sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run \
# --env SAM_EXTERNAL_URL=https://mesh.example.com \
# --secret CLOUDFLARE_TUNNEL_TOKEN
+#
+# Quick deployment with an automatic HTTPS tunnel:
+# sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
+# sky logs sam-hub 1 --no-follow
+#
+# Note: For lightweight testing, you can lower `cpus: 0.25+` and `memory: 1+`
+# to run on cloud free-tier instances (such as GCP `e2-micro` or AWS `t4g.micro`).
name: sam-hub
resources:
- cpus: 0.25+
- memory: 1+
- disk_size: 10
+ cpus: 2+
+ memory: 4+
+ disk_size: 20
use_spot: false
envs:
diff --git a/site/content/docs/getting-started/_index.md b/site/content/docs/getting-started/_index.md
index e3a9c268..515a538a 100644
--- a/site/content/docs/getting-started/_index.md
+++ b/site/content/docs/getting-started/_index.md
@@ -11,11 +11,11 @@ a **Control Plane URL** (`https://...`).
Pick the option that matches what you want to do right now:
-| Option | Command to get your URL | Cost & Setup | Best for |
+| Option | Command to get your URL | Architecture & Ingress | Best for |
|---|---|---|---|
-| **1. Public Testnet** | Use **`https://bananas.sam-mesh.dev`** directly | **$0** — zero setup, already running | Trying SAM and calling your first remote tool or model in 60 seconds ([Quick start](quickstart/)). |
-| **2. Your Laptop (Instant Public HTTPS)** | `sam-one --data-dir ~/sam-one --tunnel cloudflare --tunnel-install` | **$0** — no cloud account needed | Running your own private mesh across laptops, VMs, and phones in 10 seconds. Prints your `https://*.trycloudflare.com` URL, join token, and QR code in the terminal ([Your own mesh](your-own-mesh/)). |
-| **3. Your Own Cloud (1 Command)** | **SkyPilot**: `sky launch -c sam-hub deploy/skypilot/sam-one.yaml`<br>**Fly.io**: `fly launch --copy-config --config deploy/fly/fly.toml --ha=false`<br>**Cloud Run**: `gcloud run deploy sam-one --image ghcr.io/google/sam-one:latest ...` | **Free tiers** (GCP `e2-micro`, OCI, Cloudflare Named Tunnel, or serverless credits) | An always-on sovereign mesh in your own cloud account—without writing Terraform, building Docker images, or managing Kubernetes ([Cloud & Free-Tier Hosting](../guides/cloud-run/)). |
+| **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**: `gcloud run deploy sam-one --image ghcr.io/google/sam-one:latest ...`<br>**SkyPilot**: `sky launch -c sam-hub deploy/skypilot/sam-one.yaml`<br>**Fly.io**: `fly launch --copy-config --config deploy/fly/fly.toml --ha=false` | Managed TLS/WSS ingress + PostgreSQL or persistent volume *(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 Deployment](../guides/cloud-run/)). |
---
diff --git a/site/content/docs/guides/cloud-run.md b/site/content/docs/guides/cloud-run.md
index 9685b607..26770450 100644
--- a/site/content/docs/guides/cloud-run.md
+++ b/site/content/docs/guides/cloud-run.md
@@ -1,6 +1,6 @@
---
-title: "Cloud Run & Free-Tier Hosting"
-linkTitle: "Cloud Run & Free Tiers"
+title: "Cloud Deployment"
+linkTitle: "Cloud Deployment"
weight: 5
aliases:
- /docs/user/cloud-run-deployment/
@@ -8,26 +8,29 @@ aliases:
`sam-one` serves its HTTP API, the web console, and the router's WebSocket
transport on a single port (`8080`), and ships as a pre-built container image
-(`ghcr.io/google/sam-one:latest`). You can deploy a private control plane to
-your own cloud account in **one command**—without building Docker images,
-configuring container registries, or writing Terraform.
+(`ghcr.io/google/sam-one:latest`). You can deploy a production-ready standalone
+control plane and router to your cloud account in a single command—without
+building custom Docker images, configuring container registries, or maintaining
+Kubernetes manifests.
## Pick a deployment path
-| Platform | Command | Free Tier & Persistence | How you obtain the Control Plane URL |
+| Platform | Command | State & Persistence | How you obtain the Control Plane URL |
|---|---|---|---|
-| **1. SkyPilot** *(Any cloud: GCP, AWS, Azure, OCI, k8s)* | `sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run` | Uses your cloud's cheapest or **Always-Free VM** (`e2-micro`, `t4g.micro`) + persistent disk + free Cloudflare HTTPS tunnel | Run `sky logs sam-hub 1 --no-follow` and copy `API URL: https://...trycloudflare.com` |
-| **2. Fly.io** | `fly launch --copy-config --config deploy/fly/fly.toml --ha=false` | 1 GB persistent `/data` volume (SQLite + keys survive restarts) + automatic TLS/WSS | `https://<your-app>.fly.dev` (also printed in `fly logs`) |
-| **3. Google Cloud Run** | `gcloud run deploy sam-one --image ghcr.io/google/sam-one:latest ...` *(below)* | Serverless container; pair with a free Postgres (Neon / Supabase) for durable state across restarts | Printed at the end of `gcloud run deploy` (`Service URL: https://...a.run.app`) |
+| **1. Google Cloud Run** | `gcloud run deploy sam-one --image ghcr.io/google/sam-one:latest ...` *(below)* | Pair with PostgreSQL (`--db-driver=postgres`) for durable state across container revisions | Printed at the end of `gcloud run deploy` (`Service URL: https://...a.run.app`) |
+| **2. SkyPilot** *(GCP, AWS, Azure, OCI, k8s)* | `sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run` | Dedicated VM disk (`~/sam-one`) + Cloudflare Named Tunnel (or custom domain) | Run `sky logs sam-hub 1 --no-follow` and read `API URL:` from the banner |
+| **3. Fly.io** | `fly launch --copy-config --config deploy/fly/fly.toml --ha=false` | Persistent `/data` volume (SQLite, keys, and tokens survive restarts) + managed TLS/WSS | `https://<your-app>.fly.dev` (also printed in `fly logs`) |
+
+*(Note: For evaluation or testing, each of these options can also run within cloud provider free tiers—such as Cloud Run with a free serverless Postgres instance, or SkyPilot with `cpus: 0.25+` on an `e2-micro` / `t4g.micro` instance.)*
---
-## Option 1: Google Cloud Run (1 Command)
+## Option 1: Google Cloud Run
-Because `sam-one` automatically detects its public `wss://` address from Cloud
-Run's `Host` / `X-Forwarded-Proto` headers on `/info` and `/enroll` and derives
-a deterministic router `PeerID` from `SAM_ADMIN_TOKEN`, deploying to Cloud Run
-takes a single command using the pre-built image:
+Because `sam-one` automatically infers its public `wss://` router address from
+Cloud Run's `Host` and `X-Forwarded-Proto` headers on `/info` and `/enroll` and
+derives a deterministic router `PeerID` from `SAM_ADMIN_TOKEN`, deploying to
+Cloud Run takes a single command using the official image:
```bash
PROJECT=my-gcp-project
@@ -46,102 +49,50 @@ gcloud run deploy sam-one \
--set-env-vars "SAM_TOKEN=${JOIN_TOKEN},SAM_ADMIN_TOKEN=${ADMIN_TOKEN}"
```
-### Obtain your URL and join a node
+For production durability across container restarts and new revisions, attach a
+PostgreSQL database (such as Cloud SQL, AlloyDB, or Neon) by adding:
+
+```bash
+ --args="--data-dir=/data,--port=8080,--db-driver=postgres,--db-dsn=${POSTGRES_DSN}"
+```
+
+### Obtain your URL
-`gcloud run deploy` outputs your `Service URL` directly:
+`gcloud run deploy` prints your `Service URL` when deployment completes:
```text
Service [sam-one] revision [sam-one-00001-xxx] has been deployed and is serving 100 percent of traffic.
Service URL: https://sam-one-628944397724.us-central1.run.app
```
-Verify readiness and enroll a node from anywhere:
+You can also query it at any time:
```bash
URL=$(gcloud run services describe sam-one --project "$PROJECT" --region "$REGION" \
--format='value(status.url)')
-
-curl -s "$URL/readyz" # {"status":"ready"}
-
-echo -n "$JOIN_TOKEN" > join-token
-sam-node join "$URL" --bootstrap-token-path join-token
-sam-node run --daemonize
+curl -s "$URL/readyz" # {"status":"ready"}
```
-> [!TIP]
-> **Free-tier persistent database for Cloud Run:** By default, Cloud Run's
-> filesystem is in-memory, so when an instance restarts it keeps its router
-> `PeerID` and pinned tokens (`SAM_TOKEN`, `SAM_ADMIN_TOKEN`), while enrolled
-> nodes automatically re-enroll. To persist enrolled nodes, minted tokens, and
-> policies across restarts for **$0/mo**, create a free serverless Postgres
-> database (for example on [Neon](https://neon.tech) or
-> [Supabase](https://supabase.com)) and add
-> `--args="--data-dir=/data,--port=8080,--db-driver=postgres,--db-dsn=<YOUR_POSTGRES_URI>"`
-> to `gcloud run deploy`.
-
Why each Cloud Run flag matters:
- `--min-instances 1 --max-instances 1`: the router's DHT and relay state
- live in the single process. Two instances would be two separate meshes behind
- one URL.
+ live in the single process. Two instances would form two separate meshes
+ behind one URL.
- `--no-cpu-throttling`: the router runs background loops (lease renewal,
key sync, DHT maintenance) between HTTP requests.
-- `--timeout 3600`: Cloud Run limits the lifetime of a streaming request,
- and each node's WebSocket connection is one. Nodes reconnect seamlessly when
- the limit closes a connection.
-- `--allow-unauthenticated`: the mesh authenticates its own callers with
+- `--timeout 3600`: Cloud Run bounds the lifetime of a streaming request,
+ and each node's WebSocket connection is one. Nodes reconnect automatically
+ when the limit closes a connection.
+- `--allow-unauthenticated`: the mesh authenticates its own callers using
Biscuit credentials and tokens.
---
-## Option 2: SkyPilot (Multi-Cloud & Always-Free VMs)
+## Option 2: SkyPilot (Multi-Cloud VMs)
If you use [SkyPilot](https://docs.skypilot.co/) (`sky check`) with your GCP,
-AWS, Azure, OCI, or Kubernetes account, launch the included recipe in the
-background:
-
-```bash
-sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
-```
-
-SkyPilot provisions the cheapest available VM (including `e2-micro` / `t4g.micro`
-Always-Free instances), installs `sam-one`, and opens an outbound Cloudflare
-HTTPS tunnel (requiring zero inbound firewall ports or DNS setup).
-
-### Obtain your URL and join token from SkyPilot logs
-
-Read the startup banner from job `1`:
-
-```bash
-sky logs sam-hub 1 --no-follow
-```
-
-```text
-══════════════════════════════════════════════════════════════════
-SAM standalone mesh is ready!
-
-API URL: https://distinct-kent-bradford-elderly.trycloudflare.com
-Tunnel: https://distinct-kent-bradford-elderly.trycloudflare.com -> http://0.0.0.0:8080
-Web Console: https://distinct-kent-bradford-elderly.trycloudflare.com/console
-Router Peer: 12D3KooWScRWXVx2zSaPWC7NectYnuyhaGxpLYkNgCkp2g2tkfkY
-Admin Token: sam_adm_e4075529d72bb22d78446799f683dd89
-Join Token: sam_tok_05a5d01cf091187c980e68e1bd7d7d7a
-
-To enroll a node:
- sam-node join https://distinct-kent-bradford-elderly.trycloudflare.com --bootstrap-token-path /home/gcpuser/sam-one/join-token
-══════════════════════════════════════════════════════════════════
-```
-
-Save the `Join Token` on your local machine and join:
-
-```bash
-echo -n "sam_tok_..." > join-token
-sam-node join https://distinct-kent-bradford-elderly.trycloudflare.com --bootstrap-token-path join-token
-sam-node run --daemonize
-```
-
-To use a **permanent custom domain** for **$0/mo** via a Cloudflare Named
-Tunnel instead of a random `trycloudflare.com` hostname:
+AWS, Azure, OCI, or Kubernetes credentials, launch [`deploy/skypilot/sam-one.yaml`](https://github.com/google/sam/blob/main/deploy/skypilot/sam-one.yaml)
+with a permanent custom domain backed by a Cloudflare Named Tunnel:
```bash
sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run \
@@ -149,30 +100,73 @@ sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run \
--secret CLOUDFLARE_TUNNEL_TOKEN
```
-To tear down the SkyPilot hub when done:
+For quick testing without a custom domain, omit `--env` and `--secret` to open
+an automatic `trycloudflare.com` HTTPS tunnel:
```bash
-sky down -y sam-hub
+sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
+sky logs sam-hub 1 --no-follow
```
+Read the `API URL`, `Admin Token`, and `Join Token` printed in the banner from
+`sky logs sam-hub 1 --no-follow`.
+
---
-## Option 3: Fly.io (1 Command + Persistent Volume)
+## Option 3: Fly.io (Persistent Volume)
The repository includes [`deploy/fly/fly.toml`](https://github.com/google/sam/blob/main/deploy/fly/fly.toml),
-which deploys `ghcr.io/google/sam-one:latest` with a 1 GB persistent volume
-mounted at `/data` (so SQLite, `router.key`, `join-token`, and `admin-token`
-persist across restarts):
+which deploys `ghcr.io/google/sam-one:latest` with a persistent volume mounted
+at `/data` so SQLite, `router.key`, `join-token`, and `admin-token` survive
+restarts:
```bash
fly launch --copy-config --config deploy/fly/fly.toml --ha=false
```
-Once deployed, run `fly logs` to read your `Admin Token`, `Join Token`, and
+Run `fly logs` to read your `Admin Token`, `Join Token`, and
`sam-node join https://<your-app>.fly.dev` command from the startup banner.
---
+## Verify the dataplane with two nodes
+
+Once your control plane URL (`$URL`) is ready, verify end-to-end service
+discovery, Biscuit authorization, and WebSocket relay routing across two nodes:
+
+1. **Mint a bootstrap token** (or use `$JOIN_TOKEN`):
+ ```bash
+ export SAM_ADMIN_TOKEN="$ADMIN_TOKEN"
+ sam-one token create --server "$URL" --description "smoke-test" --max-usages 2
+ ```
+2. **Start Node A (exposing a service)**:
+ ```bash
+ cat > node-a.yaml <<'EOF'
+ version: "v1alpha1"
+ services:
+ - type: inference
+ name: prod-llm
+ target_url: "http://127.0.0.1:11434"
+ EOF
+
+ sam-node run --control-plane "$URL" \
+ --bootstrap-token-path join-token \
+ --config node-a.yaml --data-dir ~/node-a --bind-addr=
+ ```
+3. **Start Node B and call Node A's service through the mesh**:
+ ```bash
+ sam-node run --control-plane "$URL" \
+ --bootstrap-token-path join-token \
+ --data-dir ~/node-b --bind-addr=
+
+ curl -s --unix-socket ~/node-b/sam.sock http://localhost/v1/models
+ curl -s --unix-socket ~/node-b/sam.sock http://localhost/v1/chat/completions \
+ -H 'Content-Type: application/json' \
+ -d '{"model":"gemma3:1b","messages":[{"role":"user","content":"Ping across the mesh"}]}'
+ ```
+
+---
+
## Administer from your workstation
`sam-one` is also the admin client. With `SAM_ADMIN_TOKEN` exported: