Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
devcontainers: a mesh of your own in a GitHub codespace
Antonio Ojeaa58700be2b6a
diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfilenew file mode 100644index 00000000..b6d1ee9f--- /dev/null+++ b/.devcontainer/Dockerfile@@ -0,0 +1,3 @@+# Toolchain for contributors: Go from the image, Node and Python for the+# SDKs and Docker for `make lint` arrive as features in devcontainer.json.+FROM mcr.microsoft.com/devcontainers/go:1.27-bookworm@sha256:adc326255c019241228f9da4a1cb5d6a89abaaa0eb8d926a355b00af7daafd00diff --git a/.devcontainer/devcontainer-lock.json b/.devcontainer/devcontainer-lock.jsonnew file mode 100644index 00000000..8e9ed57d--- /dev/null+++ b/.devcontainer/devcontainer-lock.json@@ -0,0 +1,19 @@+{+ "features": {+ "ghcr.io/devcontainers/features/docker-in-docker:2": {+ "version": "2.17.0",+ "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c",+ "integrity": "sha256:25b9f05705ffba7dbe503230ac76081419306f8c8bc88e0ce78c4ecd99a0c78c"+ },+ "ghcr.io/devcontainers/features/node:1": {+ "version": "1.7.1",+ "resolved": "ghcr.io/devcontainers/features/node@sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6",+ "integrity": "sha256:8c0de46939b61958041700ee89e3493f3b2e4131a06dc46b4d9423427d06e5f6"+ },+ "ghcr.io/devcontainers/features/python:1": {+ "version": "1.8.0",+ "resolved": "ghcr.io/devcontainers/features/python@sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511",+ "integrity": "sha256:fbcad6955caeecc5ad3f7886baf652e25cba5225a6c4c2287c536de2e5607511"+ }+ }+}diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.jsonnew file mode 100644index 00000000..815abc74--- /dev/null+++ b/.devcontainer/devcontainer.json@@ -0,0 +1,22 @@+{+ "name": "SAM (develop)",+ "build": { "dockerfile": "Dockerfile" },+ "features": {+ "ghcr.io/devcontainers/features/node:1": {},+ "ghcr.io/devcontainers/features/python:1": {},+ "ghcr.io/devcontainers/features/docker-in-docker:2": {}+ },+ "onCreateCommand": "make build",+ "forwardPorts": [8080],+ "portsAttributes": {+ "8080": { "label": "SAM mesh (sam-one)", "protocol": "http" }+ },+ "customizations": {+ "vscode": {+ "extensions": ["golang.go"]+ },+ "codespaces": {+ "openFiles": ["site/content/docs/guides/codespaces.md"]+ }+ }+}diff --git a/.devcontainer/testnet-latest/devcontainer.json b/.devcontainer/testnet-latest/devcontainer.jsonnew file mode 100644index 00000000..6ea923dc--- /dev/null+++ b/.devcontainer/testnet-latest/devcontainer.json@@ -0,0 +1,16 @@+{+ "name": "SAM testnet (latest from main)",+ "build": {+ "dockerfile": "../testnet/Dockerfile",+ "args": { "SAM_CHANNEL": "latest" }+ },+ "forwardPorts": [8080],+ "portsAttributes": {+ "8080": { "label": "SAM mesh (sam-one)", "protocol": "http" }+ },+ "customizations": {+ "codespaces": {+ "openFiles": ["site/content/docs/guides/codespaces.md"]+ }+ }+}diff --git a/.devcontainer/testnet/Dockerfile b/.devcontainer/testnet/Dockerfilenew file mode 100644index 00000000..cfae6b60--- /dev/null+++ b/.devcontainer/testnet/Dockerfile@@ -0,0 +1,11 @@+# A mesh without a toolchain: the released sam-one and sam-node binaries are+# copied out of the published images. SAM_CHANNEL selects `stable` (the last+# release tag, what hub.sam-mesh.dev runs) or `latest` (main, what+# bananas.sam-mesh.dev runs).+ARG SAM_CHANNEL=stable+FROM ghcr.io/google/sam-one:${SAM_CHANNEL} AS sam-one+FROM ghcr.io/google/sam-node:${SAM_CHANNEL} AS sam-node++FROM mcr.microsoft.com/devcontainers/base:bookworm@sha256:3aacff4130e6cf04709f9cab1d7a6d3e1cc4bff6202bc61611831a18d3755673+COPY --from=sam-one /sam-one /usr/local/bin/sam-one+COPY --from=sam-node /sam-node /usr/local/bin/sam-nodediff --git a/.devcontainer/testnet/devcontainer.json b/.devcontainer/testnet/devcontainer.jsonnew file mode 100644index 00000000..771f629f--- /dev/null+++ b/.devcontainer/testnet/devcontainer.json@@ -0,0 +1,16 @@+{+ "name": "SAM testnet (stable release)",+ "build": {+ "dockerfile": "Dockerfile",+ "args": { "SAM_CHANNEL": "stable" }+ },+ "forwardPorts": [8080],+ "portsAttributes": {+ "8080": { "label": "SAM mesh (sam-one)", "protocol": "http" }+ },+ "customizations": {+ "codespaces": {+ "openFiles": ["site/content/docs/guides/codespaces.md"]+ }+ }+}diff --git a/.github/dependabot.yml b/.github/dependabot.ymlindex 7953b4f7..c00d27e4 100644--- a/.github/dependabot.yml+++ b/.github/dependabot.yml@@ -35,6 +35,24 @@ updates:cooldown:default-days: 7+ # Dev container features, and the digest-pinned base images of the two+ # dev container Dockerfiles.+ - package-ecosystem: "devcontainers"+ directory: "/"+ schedule:+ interval: "weekly"+ cooldown:+ default-days: 7++ - package-ecosystem: "docker"+ directories:+ - "/.devcontainer"+ - "/.devcontainer/testnet"+ schedule:+ interval: "weekly"+ cooldown:+ default-days: 7+- package-ecosystem: "npm"directories:- "/tests/ui"diff --git a/.gitignore b/.gitignoreindex c63f0761..56ed5cd4 100644--- a/.gitignore+++ b/.gitignore@@ -34,6 +34,8 @@ go.work.sum#bin/dist/+# State of `make testnet` (database, router key, tokens)+.sam-one/# Stray binaries from `go build ./cmd/<name>/` in the repo root/sam-node/sam-boxdiff --git a/Makefile b/Makefileindex af562e3c..08129dd9 100644--- a/Makefile+++ b/Makefile@@ -152,6 +152,17 @@ kind-local-node:kind-e2e-mesh: build./development/kind/test-mesh-e2e.sh+# A mesh of your own on port 8080. In a GitHub codespace the port is+# published on the codespace's https URL; anywhere else this is a local+# sam-one. Uses ./bin/sam-one when built, else sam-one on PATH. State lives+# in ./.sam-one (ignored by git; in a codespace it survives rebuilds). Extra+# flags pass through: make testnet ARGS="--issuer https://accounts.google.com".+SAM_ONE_BIN ?= $(if $(wildcard $(OUT_DIR)/sam-one),$(OUT_DIR)/sam-one,sam-one)+SAM_ONE_DATA_DIR ?= $(REPO_ROOT)/.sam-one+.PHONY: testnet+testnet:+ $(SAM_ONE_BIN) --data-dir "$(SAM_ONE_DATA_DIR)" --port 8080 $(if $(CODESPACE_NAME),--tunnel codespaces) $(ARGS)+test:CGO_ENABLED=1 go test -v -race -count 1 $(if $(WHAT),-run $(WHAT)) ./...CGO_ENABLED=1 go -C cmd/nano-init test -race -count 1 $(if $(WHAT),-run $(WHAT)) ./...diff --git a/README.md b/README.mdindex 24be25df..5e2c7250 100644--- a/README.md+++ b/README.md@@ -37,6 +37,16 @@ no uptime promise; the [quick start](https://sam-mesh.dev/docs/getting-started/qwalks through it, and [your own mesh](https://sam-mesh.dev/docs/getting-started/your-own-mesh/)runs a control plane on your laptop in one command.+To run a control plane of your own without installing anything, open a+GitHub codespace with the released binaries and run `make testnet`. It+starts on a public `https` URL that your laptop and phone can enroll into,+on your GitHub account's free quota:++[](https://codespaces.new/google/sam?quickstart=1&devcontainer_path=.devcontainer%2Ftestnet%2Fdevcontainer.json)++The [Codespaces guide](https://sam-mesh.dev/docs/guides/codespaces/) has the+steps, what persists and what stops.+## What is in a mesh| Program | Role |@@ -57,6 +67,12 @@ runs a control plane on your laptop in one command.- [Preview](https://sam-mesh.dev/docs/preview/): sandboxed agents and the mobile app, which work but are still settling.- [Contributing](https://sam-mesh.dev/docs/contributing/): building, testing and the local kind environment.+The repository has a dev container with the Go, Node and Python toolchains+and Docker, so you can build and test in a codespace or in VS Code without+installing anything:++[](https://codespaces.new/google/sam?quickstart=1)+## StatusSAM is pre-1.0. The node, routers, control plane, identity and policy modeldiff --git a/site/content/docs/contributing/_index.md b/site/content/docs/contributing/_index.mdindex b31d675f..2fd563f6 100644--- a/site/content/docs/contributing/_index.md+++ b/site/content/docs/contributing/_index.md@@ -45,6 +45,14 @@ make docker-build # container images tagged :localmake proto # regenerate api/sam.pb.go after editing sam.proto```+The repository has a dev container (`.devcontainer/devcontainer.json`) with+Go, Node, Python and Docker, and `make build` runs when it is created. Open+it in a [GitHub codespace](https://codespaces.new/google/sam?quickstart=1)+or with the VS Code Dev Containers extension to build and test with nothing+installed locally. `make testnet` inside a codespace starts `sam-one` on the+codespace's public URL, so you can point an SDK program or a phone at your+branch; the [Codespaces guide](../guides/codespaces/) has the steps.+Node and router control-plane requests identify themselves as`sam-node/<version>` and `sam-router/<version>`, including the router inside`sam-one`. These headers contain the software component and build version.diff --git a/site/content/docs/getting-started/_index.md b/site/content/docs/getting-started/_index.mdindex 34e36191..fd0dc63c 100644--- a/site/content/docs/getting-started/_index.md+++ b/site/content/docs/getting-started/_index.md@@ -19,7 +19,8 @@ Pick the option that matches what you want to do:|---|---|---|---|| **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/)). |+| **3. Codespace Control Plane (`sam-one`)** | Open the repository in a [GitHub codespace](../guides/codespaces/), run `make testnet`, make port 8080 public | `sam-one` in a container on your GitHub account, published on `https://<codespace>-8080.app.github.dev` | A control plane of your own with nothing installed and no cloud account, for as long as the codespace runs ([Codespaces](../guides/codespaces/)). |+| **4. 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/your-own-mesh.md b/site/content/docs/getting-started/your-own-mesh.mdindex 798e9f72..5f3c084d 100644--- a/site/content/docs/getting-started/your-own-mesh.md+++ b/site/content/docs/getting-started/your-own-mesh.md@@ -31,6 +31,7 @@ for nodes to connect to it.| **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** | `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) |+| **A GitHub codespace, nothing installed** | Open the repository in a codespace and run `make testnet` ([Codespaces](../../guides/codespaces/)) | Public `https://<codespace>-8080.app.github.dev` URL once you make the port public || **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/_index.md b/site/content/docs/guides/_index.mdindex 1f75dd37..18d4be8a 100644--- a/site/content/docs/guides/_index.md+++ b/site/content/docs/guides/_index.md@@ -9,5 +9,5 @@ aliases:Step-by-step pages for common tasks: publish a service, connect an agentclient, enroll machines that cannot log in, and deploy a control plane on-Kubernetes or Cloud Run. Each page assumes that you have read the-[quick start](../getting-started/quickstart/).+Kubernetes, Cloud Run, SkyPilot or a GitHub codespace. Each page assumes+that you have read the [quick start](../getting-started/quickstart/).diff --git a/site/content/docs/guides/codespaces.md b/site/content/docs/guides/codespaces.mdnew file mode 100644index 00000000..362a569b--- /dev/null+++ b/site/content/docs/guides/codespaces.md@@ -0,0 +1,176 @@+---+title: "GitHub Codespaces"+linkTitle: "Codespaces"+weight: 5+---++A codespace is a container that GitHub runs for you, with a terminal, an+editor and an `https` URL for every port you forward. Started from this+repository, it gives you a control plane of your own with nothing installed+on your machine and no cloud account. `sam-one` runs inside it, your laptop+and your phone enroll over the public URL, and your GitHub account pays with+its free Codespaces quota (120 core-hours a month on a Free plan; a 2-core+machine is enough). The same setup lets you develop SAM, or a program that+uses one of its SDKs, against a mesh that external clients can reach.++## 1. Open a codespace++The repository has three dev container configurations. Pick one from the+badge, or from **Code → Codespaces → New with options** on GitHub:++| Configuration | Contents | For |+|---|---|---|+| **testnet** (default badge in the README) | The released `sam-one` and `sam-node` binaries, copied from the `stable` images that also run `hub.sam-mesh.dev`. No toolchain. | Trying SAM, enrolling your devices. |+| **testnet-latest** | The same, from the `latest` images built from `main`, which also run `bananas.sam-mesh.dev`. | Trying what is not released yet. |+| **develop** (`.devcontainer/devcontainer.json`) | Go, Node, Python and Docker. `make build` runs when the codespace is created, so `./bin` holds the binaries of the branch you opened. | Contributing, or developing an SDK program against your own branch. |++[](https://codespaces.new/google/sam?quickstart=1&devcontainer_path=.devcontainer%2Ftestnet%2Fdevcontainer.json)++The codespace opens with this page in the editor and a terminal at the+repository root.++## 2. Start the mesh++```bash+make testnet+```++The target runs one command, which is the same command you would run+anywhere else (the codespace checks the repository out under+`/workspaces/sam`):++```bash+sam-one --data-dir /workspaces/sam/.sam-one --port 8080 --tunnel codespaces+```++`--tunnel codespaces` tells `sam-one` that GitHub already forwards the port:+it reads the codespace name and the forwarding domain from the environment,+advertises `https://<codespace>-8080.app.github.dev` as the mesh URL, and+starts nothing. After a moment the banner appears:++```text+══════════════════════════════════════════════════════════════════+SAM standalone mesh is ready!++API URL: https://octocat-sam-abc123-8080.app.github.dev+Tunnel: https://octocat-sam-abc123-8080.app.github.dev -> http://0.0.0.0:8080+Web Console: https://octocat-sam-abc123-8080.app.github.dev/console+Router Peer: 12D3KooWBzUDQCkZhz2rWrYBhpjcCH8VnrRNcwCW6DoF36iADYrY+Admin Token: sam_adm_…+Join Token: sam_tok_…++To enroll a node:+ sam-node join https://octocat-sam-abc123-8080.app.github.dev --bootstrap-token-path /workspaces/sam/.sam-one/join-token+══════════════════════════════════════════════════════════════════+```++A QR code for the [mobile app](../../preview/mobile/) follows the banner.++Any `sam-one` flag passes through `ARGS`. To let people log in with an+identity provider instead of the join token, for example:++```bash+make testnet ARGS="--issuer https://accounts.google.com --allowed-audiences <client-id>"+```++The [sam-one reference](../../reference/sam-one/) lists every flag. Outside+a codespace, `make testnet` starts a plain local `sam-one` on port 8080.++## 3. Make the port public++Every forwarded port starts **private**: GitHub's proxy lets your own+browser through and answers everyone else with its login page. Open the+**Web Console** URL from the banner in your browser now and it works. A+`sam-node` on your laptop or the app on your phone cannot log in to GitHub,+so `sam-one` tells you in its log, after a few seconds:++```text+WARN tunnel GitHub answers for https://octocat-sam-abc123-8080.app.github.dev: port 8080 is private, so only your own browser can open it. To let devices enroll, make it public: PORTS tab -> right-click 8080 -> Port Visibility -> Public (or `gh codespace ports visibility 8080:public -c octocat-sam-abc123`)+```++Do that once, in the **PORTS** tab next to the terminal. `sam-one` keeps+checking and confirms:++```text+INFO tunnel https://octocat-sam-abc123-8080.app.github.dev answers from the internet; devices can enroll+```++A public port is reachable by anyone who has the URL, with the same exposure+as a `sam-one` on Cloud Run: `/healthz`, `/info` and the console login page+answer without credentials, enrollment needs the join token or a token you+minted, the console and the admin API need the admin token, and every+router connection needs a credential the control plane issued. The first+boot seeds the open development policy and logs a warning; replace it+before you share the URL, as described in+[Your own mesh](../../getting-started/your-own-mesh/#5-before-you-share-it).++If your organization forbids public ports, keep the port private and let+`sam-one` publish itself through a Cloudflare quick tunnel instead:+`make testnet ARGS="--tunnel cloudflare --tunnel-install"`.++## 4. Enroll your devices++On your laptop, install `sam-node` ([quick start](../../getting-started/quickstart/#1-install)),+save the join token from the banner to a file, and join:++```bash+URL=https://octocat-sam-abc123-8080.app.github.dev+echo -n 'sam_tok_…' > join-token++sam-node join "$URL" --bootstrap-token-path join-token+sam-node run --daemonize+```++The node appears in the console under **Nodes**. From here the+[Your own mesh](../../getting-started/your-own-mesh/#2-put-a-member-on-it)+walkthrough applies unchanged: publish a model or an MCP server from one+device and call it from another. The second device can be the codespace+itself, where `sam-node` is installed too. It reaches `sam-one` over+loopback, which `--allow-loopback` permits, and `--bind-addr=` keeps its+local API on a Unix socket so it does not compete with `sam-one` for port+8080:++```bash+sam-node run --control-plane http://127.0.0.1:8080 \+ --bootstrap-token-path .sam-one/join-token \+ --data-dir ~/node-a --bind-addr= --allow-loopback+```++Scan the QR code under the banner with the mobile app to enroll a phone.++## 5. Develop against it++In the **develop** configuration, `make testnet` runs `./bin/sam-one`, the+binary built from your branch. Edit, `make build`, stop the mesh with+`Ctrl-C` and start it again; the data directory keeps the identity and the+tokens, so enrolled devices reconnect without doing anything.++A program written with a [native SDK](../../guides/native-sdks/) on your+laptop, or a page using the browser SDK, points at the same URL and the+same join token. `make test` and `make lint` run in the codespace like they+do locally; the end-to-end suite needs kind and is better run locally or in+CI.++## What persists and what stops++- **The URL.** The codespace name is fixed for the codespace's lifetime, so+ the URL survives stop and start.+- **The mesh state.** `.sam-one` in the checkout holds the database (members,+ policy, bootstrap tokens), the router key and the two tokens. Git ignores+ it, and it survives stops, starts and container rebuilds. Devices keep+ their identity across restarts and reconnect on their own.+- **The idle stop.** A codespace stops after 30 minutes without activity by+ default; you can raise that to four hours in your GitHub settings. While it+ is stopped nothing answers at the URL and devices retry until it returns.+ Resume it from [github.com/codespaces](https://github.com/codespaces), the+ README badge, or by connecting to it with `gh codespace code`.+- **Port visibility.** Check the PORTS tab after a restart; set it to public+ again if it reverted.+- **Deletion.** A stopped codespace is deleted after 30 days by default. The+ mesh is gone with it, and devices enroll elsewhere.+- **One mesh per codespace.** The router's relay and discovery state live in+ the single `sam-one` process. A second codespace is a second mesh.++When you want the mesh to stay up, take the same command and its flags to+[Cloud Run](../cloud-run/), [SkyPilot](../skypilot/) or+[Kubernetes](../kubernetes/).