Skip to content

Agent Mesh

fix(standalone): use custom responseRecorder and split Cloud Run / SkyPilot guides

Antonio Ojea5566d1bb3275
diff --git a/deploy/fly/fly.toml b/deploy/fly/fly.toml
deleted file mode 100644
index bc85c233..00000000
--- a/deploy/fly/fly.toml
+++ /dev/null
@@ -1,44 +0,0 @@
-# Fly.io blueprint for running a persistent standalone SAM mesh (sam-one).
-#
-# Deploy in one command:
-# fly launch --copy-config --config deploy/fly/fly.toml --ha=false
-# fly logs
-#
-# What you get automatically:
-# - Public HTTPS + WebSocket URL: https://<your-app-name>.fly.dev
-# - 1 GB persistent volume mounted at /data (preserves SQLite DB, router PeerID,
-# join-token, and admin-token across restarts)
-# - Automatic /info wss:// address discovery from the Fly.io Host header
-# - Startup banner in `fly logs` with your URL, Admin Token, and Join Token
-
-app = "sam-one-hub"
-primary_region = "ord"
-
-[build]
- image = "ghcr.io/google/sam-one:latest"
-
-[env]
- PORT = "8080"
-
-[[mounts]]
- source = "sam_data"
- destination = "/data"
- initial_size = "1gb"
-
-[http_service]
- internal_port = 8080
- force_https = true
- auto_stop_machines = "off"
- auto_start_machines = true
- min_machines_running = 1
-
- [[http_service.checks]]
- interval = "15s"
- timeout = "5s"
- grace_period = "10s"
- method = "GET"
- path = "/readyz"
-
-[[vm]]
- size = "shared-cpu-1x"
- memory = "512mb"
diff --git a/deploy/skypilot/sam-one.yaml b/deploy/skypilot/sam-one.yaml
index 743ef06a..3a7ab307 100644
--- a/deploy/skypilot/sam-one.yaml
+++ b/deploy/skypilot/sam-one.yaml
@@ -16,10 +16,13 @@
name: sam-hub
resources:
- cpus: 2+
- memory: 4+
disk_size: 20
use_spot: false
+ any_of:
+ - infra: gcp
+ instance_type: e2-standard-2
+ - cpus: 2+
+ memory: 4+
envs:
SAM_EXTERNAL_URL: ""
diff --git a/internal/standalone/standalone.go b/internal/standalone/standalone.go
index 8762b5b0..e2f5b7db 100644
--- a/internal/standalone/standalone.go
+++ b/internal/standalone/standalone.go
@@ -29,7 +29,6 @@ import (
"fmt"
"net"
"net/http"
- "net/http/httptest"
"net/url"
"os"
"path/filepath"
@@ -673,6 +672,31 @@ func ensureRouterKey(keyPath, adminToken string) error {
return os.WriteFile(keyPath, data, 0o600)
}
+type responseRecorder struct {
+ header http.Header
+ body bytes.Buffer
+ code int
+}
+
+func newResponseRecorder() *responseRecorder {
+ return &responseRecorder{
+ header: make(http.Header),
+ code: http.StatusOK,
+ }
+}
+
+func (r *responseRecorder) Header() http.Header {
+ return r.header
+}
+
+func (r *responseRecorder) Write(b []byte) (int, error) {
+ return r.body.Write(b)
+}
+
+func (r *responseRecorder) WriteHeader(statusCode int) {
+ r.code = statusCode
+}
+
// wrapPublicHTTPHandler augments control-plane endpoints that return
// RouterAddresses (/info, /enroll, /enroll/status, /enroll/oidc, /refresh) on
// the public listener when no explicit --external-url was configured: it
@@ -691,25 +715,26 @@ func (s *Server) wrapPublicHTTPHandler(next http.Handler) http.Handler {
next.ServeHTTP(w, r)
return
}
- rec := httptest.NewRecorder()
+ rec := newResponseRecorder()
next.ServeHTTP(rec, r)
for k, vals := range rec.Header() {
for _, v := range vals {
w.Header().Add(k, v)
}
}
- if rec.Code != http.StatusOK {
- w.WriteHeader(rec.Code)
- _, _ = w.Write(rec.Body.Bytes())
+ if rec.code != http.StatusOK {
+ w.WriteHeader(rec.code)
+ _, _ = w.Write(rec.body.Bytes())
return
}
- out, ok := prependInferredRouterAddr(r.URL.Path, rec.Body.Bytes(), inferredAddr)
+ out, ok := prependInferredRouterAddr(r.URL.Path, rec.body.Bytes(), inferredAddr)
if !ok {
- w.WriteHeader(rec.Code)
- _, _ = w.Write(rec.Body.Bytes())
+ w.WriteHeader(rec.code)
+ _, _ = w.Write(rec.body.Bytes())
return
}
w.Header().Set("Content-Type", "application/x-protobuf")
+ w.Header().Del("Content-Length")
w.WriteHeader(http.StatusOK)
_, _ = w.Write(out)
})
diff --git a/internal/standalone/standalone_test.go b/internal/standalone/standalone_test.go
index 1aae3ae8..6db0e728 100644
--- a/internal/standalone/standalone_test.go
+++ b/internal/standalone/standalone_test.go
@@ -184,3 +184,22 @@ func TestPrependInferredRouterAddr(t *testing.T) {
t.Fatalf("BootstrapEnrollResponse.RouterAddresses = %v, want [%s %s]", enrollOut.RouterAddresses, inferred, local)
}
}
+
+func TestResponseRecorder(t *testing.T) {
+ rec := newResponseRecorder()
+ rec.Header().Set("Content-Length", "12")
+ rec.WriteHeader(http.StatusCreated)
+ if _, err := rec.Write([]byte("hello world!")); err != nil {
+ t.Fatalf("rec.Write: %v", err)
+ }
+ if rec.code != http.StatusCreated {
+ t.Fatalf("rec.code = %d, want %d", rec.code, http.StatusCreated)
+ }
+ if got := rec.body.String(); got != "hello world!" {
+ t.Fatalf("rec.body = %q, want %q", got, "hello world!")
+ }
+ if got := rec.Header().Get("Content-Length"); got != "12" {
+ t.Fatalf("rec.Header(Content-Length) = %q, want 12", got)
+ }
+}
+
diff --git a/site/content/docs/getting-started/_index.md b/site/content/docs/getting-started/_index.md
index 515a538a..8b4bd6ae 100644
--- a/site/content/docs/getting-started/_index.md
+++ b/site/content/docs/getting-started/_index.md
@@ -15,7 +15,7 @@ Pick the option that matches what you want to do right now:
|---|---|---|---|
| **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/)). |
+| **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/)). |
---
diff --git a/site/content/docs/getting-started/your-own-mesh.md b/site/content/docs/getting-started/your-own-mesh.md
index 86c166cd..059c7a98 100644
--- a/site/content/docs/getting-started/your-own-mesh.md
+++ b/site/content/docs/getting-started/your-own-mesh.md
@@ -30,7 +30,7 @@ command to copy-paste.
| **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) |
-| **Always-on Cloud Deployment** *(Cloud Run, SkyPilot, Fly.io)* | See [Cloud Deployment](../../guides/cloud-run/) (`gcloud run deploy`, `sky launch`, or `fly launch`) | `https://<svc>.a.run.app`, `https://mesh.example.com`, or `https://<app>.fly.dev` |
+| **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:
diff --git a/site/content/docs/guides/cloud-run.md b/site/content/docs/guides/cloud-run.md
index 26770450..e6642210 100644
--- a/site/content/docs/guides/cloud-run.md
+++ b/site/content/docs/guides/cloud-run.md
@@ -1,6 +1,6 @@
---
-title: "Cloud Deployment"
-linkTitle: "Cloud Deployment"
+title: "Cloud Run"
+linkTitle: "Cloud Run"
weight: 5
aliases:
- /docs/user/cloud-run-deployment/
@@ -8,29 +8,16 @@ 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 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.
+(`ghcr.io/google/sam-one:latest`). 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`, you can deploy a standalone control plane and router to
+Google Cloud Run in a single command.
-## Pick a deployment path
+*(Note: For multi-cloud VM deployments on GCP, AWS, Azure, OCI, or Kubernetes,
+see the [SkyPilot guide](../skypilot/).)*
-| Platform | Command | State & Persistence | How you obtain the Control Plane URL |
-|---|---|---|---|
-| **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
-
-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:
+## 1. Deploy `sam-one` to Cloud Run
```bash
PROJECT=my-gcp-project
@@ -49,28 +36,20 @@ gcloud run deploy sam-one \
--set-env-vars "SAM_TOKEN=${JOIN_TOKEN},SAM_ADMIN_TOKEN=${ADMIN_TOKEN}"
```
-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}"
-```
+### Production persistence with PostgreSQL
-### Obtain your URL
+By default, Cloud Run's container filesystem is in-memory. When an instance
+restarts, `sam-one` preserves its router `PeerID` (derived from
+`SAM_ADMIN_TOKEN`) and pinned tokens (`SAM_TOKEN`, `SAM_ADMIN_TOKEN`), and
+active nodes re-enroll automatically.
-`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
-```
-
-You can also query it at any time:
+For full state durability across container revisions and restarts (preserving
+enrolled peers, minted tokens, and console policy edits), connect `sam-one` to
+a PostgreSQL database (such as Cloud SQL, AlloyDB, or a serverless Postgres
+instance for testing):
```bash
-URL=$(gcloud run services describe sam-one --project "$PROJECT" --region "$REGION" \
- --format='value(status.url)')
-curl -s "$URL/readyz" # {"status":"ready"}
+ --args="--data-dir=/data,--port=8080,--db-driver=postgres,--db-dsn=${POSTGRES_DSN}"
```
Why each Cloud Run flag matters:
@@ -86,60 +65,33 @@ Why each Cloud Run flag matters:
- `--allow-unauthenticated`: the mesh authenticates its own callers using
Biscuit credentials and tokens.
----
-
-## Option 2: SkyPilot (Multi-Cloud VMs)
+## 2. Obtain your Control Plane URL
-If you use [SkyPilot](https://docs.skypilot.co/) (`sky check`) with your GCP,
-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 \
- --env SAM_EXTERNAL_URL=https://mesh.example.com \
- --secret CLOUDFLARE_TUNNEL_TOKEN
-```
-
-For quick testing without a custom domain, omit `--env` and `--secret` to open
-an automatic `trycloudflare.com` HTTPS tunnel:
+`gcloud run deploy` prints your `Service URL` when deployment completes:
-```bash
-sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
-sky logs sam-hub 1 --no-follow
+```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
```
-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 (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 persistent volume mounted
-at `/data` so SQLite, `router.key`, `join-token`, and `admin-token` survive
-restarts:
+You can also query it at any time:
```bash
-fly launch --copy-config --config deploy/fly/fly.toml --ha=false
+URL=$(gcloud run services describe sam-one --project "$PROJECT" --region "$REGION" \
+ --format='value(status.url)')
+curl -s "$URL/readyz" # {"status":"ready"}
```
-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
+## 3. 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`):
+1. **Save the bootstrap token** (or mint one with `sam-one token create`):
```bash
- export SAM_ADMIN_TOKEN="$ADMIN_TOKEN"
- sam-one token create --server "$URL" --description "smoke-test" --max-usages 2
+ echo -n "$JOIN_TOKEN" > join-token
```
-2. **Start Node A (exposing a service)**:
+2. **Start Node A (exposing an inference service)**:
```bash
cat > node-a.yaml <<'EOF'
version: "v1alpha1"
@@ -165,13 +117,12 @@ discovery, Biscuit authorization, and WebSocket relay routing across two nodes:
-d '{"model":"gemma3:1b","messages":[{"role":"user","content":"Ping across the mesh"}]}'
```
----
-
-## Administer from your workstation
+## 4. Administer from your workstation
`sam-one` is also the admin client. With `SAM_ADMIN_TOKEN` exported:
```bash
+export SAM_ADMIN_TOKEN="$ADMIN_TOKEN"
sam-one token create --server "$URL" --role sam:role:node --max-usages 1
sam-one token qr --server "$URL"
sam-one token list --server "$URL"
diff --git a/site/content/docs/guides/skypilot.md b/site/content/docs/guides/skypilot.md
new file mode 100644
index 00000000..d7cee592
--- /dev/null
+++ b/site/content/docs/guides/skypilot.md
@@ -0,0 +1,126 @@
+---
+title: "SkyPilot"
+linkTitle: "SkyPilot"
+weight: 6
+---
+
+[SkyPilot](https://docs.skypilot.co/) provisions and manages compute across
+Google Cloud, AWS, Azure, OCI, and Kubernetes using your existing cloud
+credentials (`sky check`). The repository includes a ready-to-run recipe,
+[`deploy/skypilot/sam-one.yaml`](https://github.com/google/sam/blob/main/deploy/skypilot/sam-one.yaml),
+that deploys a standalone `sam-one` control plane and router with a persistent
+disk and an outbound Cloudflare HTTPS tunnel (requiring no inbound firewall
+rules).
+
+*(Note: While `deploy/skypilot/sam-one.yaml` defaults to production VM sizing
+(`cpus: 2+`, `memory: 8+`, matching `e2-standard-2` on GCP or `t3.large` on AWS),
+you can also set `cpus: 0.25+` and `memory: 1+` to run on cloud provider free
+tiers such as GCP `e2-micro` or AWS `t4g.micro` for testing.)*
+
+## 1. Deploy `sam-one` with SkyPilot
+
+### Production deployment (custom domain via Cloudflare Named Tunnel)
+
+If you have a Cloudflare Named Tunnel token bound to a custom hostname (such as
+`https://mesh.example.com`), launch the cluster with `SAM_EXTERNAL_URL` and
+`CLOUDFLARE_TUNNEL_TOKEN`:
+
+```bash
+export CLOUDFLARE_TUNNEL_TOKEN="eyJhIjoi..."
+
+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 (automatic HTTPS tunnel)
+
+To launch immediately with an automatic `https://<name>.trycloudflare.com`
+address and zero DNS setup:
+
+```bash
+sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --detach-run
+```
+
+To target a specific cloud provider (for example Google Cloud), pass `--infra gcp`:
+
+```bash
+sky launch -y -c sam-hub deploy/skypilot/sam-one.yaml --infra gcp --detach-run
+```
+
+## 2. Obtain your Control Plane URL and tokens
+
+Read the `sam-one` 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
+══════════════════════════════════════════════════════════════════
+```
+
+Copy the `API URL` and `Join Token` from the banner:
+
+```bash
+URL="https://distinct-kent-bradford-elderly.trycloudflare.com"
+echo -n "sam_tok_05a5d01cf091187c980e68e1bd7d7d7a" > join-token
+```
+
+## 3. Verify the dataplane with two nodes
+
+Once you have `$URL` and `join-token`, verify end-to-end service discovery,
+Biscuit authorization, and WebSocket relay forwarding between two nodes:
+
+1. **Start Node A (exposing an inference 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=
+ ```
+2. **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"}]}'
+ ```
+
+## 4. Manage the cluster
+
+```bash
+# Check status of the SkyPilot cluster
+sky status sam-hub
+
+# Administer tokens and policies remotely using sam-one
+export SAM_ADMIN_TOKEN="sam_adm_..."
+sam-one token create --server "$URL" --role sam:role:node --max-usages 1
+sam-one token list --server "$URL"
+
+# Tear down the cluster when no longer needed
+sky down -y sam-hub
+```