Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
fix(standalone): use custom responseRecorder and split Cloud Run / SkyPilot guides
Antonio Ojea5566d1bb3275
diff --git a/deploy/fly/fly.toml b/deploy/fly/fly.tomldeleted file mode 100644index 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.yamlindex 743ef06a..3a7ab307 100644--- a/deploy/skypilot/sam-one.yaml+++ b/deploy/skypilot/sam-one.yaml@@ -16,10 +16,13 @@name: sam-hubresources:- cpus: 2+- memory: 4+disk_size: 20use_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.goindex 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.goindex 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.mdindex 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.mdindex 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.mdindex 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: 5aliases:- /docs/user/cloud-run-deployment/@@ -8,29 +8,16 @@ aliases:`sam-one` serves its HTTP API, the web console, and the router's WebSockettransport 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```bashPROJECT=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 usingBiscuit 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 nodesOnce your control plane URL (`$URL`) is ready, verify end-to-end servicediscovery, 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)**:```bashcat > 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 1sam-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.mdnew file mode 100644index 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+```