Skip to content

Agent Mesh

docs: what a live codespace showed

Antonio Ojea9efb65aa7c2d
diff --git a/.devcontainer/devcontainer-lock.json b/.devcontainer/devcontainer-lock.json
index e9a98de6..34eb356a 100644
--- a/.devcontainer/devcontainer-lock.json
+++ b/.devcontainer/devcontainer-lock.json
@@ -21,4 +21,4 @@
"integrity": "sha256:f5251b8e4325f68f7280973c6cd65daff414449c66f240621502d4e8e74eb7ee"
}
}
-}
+}
\ No newline at end of file
diff --git a/site/content/docs/guides/codespaces.md b/site/content/docs/guides/codespaces.md
index 362a569b..dcbd3af3 100644
--- a/site/content/docs/guides/codespaces.md
+++ b/site/content/docs/guides/codespaces.md
@@ -88,8 +88,10 @@ so `sam-one` tells you in its log, after a few seconds:
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:
+Do that once, in the **PORTS** tab next to the terminal, or from your own
+machine with the `gh` command from the message (the codespace image does
+not include `gh`). `sam-one` keeps checking and confirms within a few
+seconds:
```text
INFO tunnel https://octocat-sam-abc123-8080.app.github.dev answers from the internet; devices can enroll
@@ -143,7 +145,8 @@ Scan the QR code under the banner with the mobile app to enroll a phone.
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.
+tokens, and enrolled devices reconnect on their own as long as the mesh is
+back within about three minutes.
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
@@ -157,15 +160,19 @@ CI.
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.
+ it, and it survives stops, starts and container rebuilds, so the router
+ keeps its peer ID and devices keep their identity: nothing enrolls twice.
- **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.
+ is stopped nothing answers at the URL. A `sam-node` that finds no router
+ for about three minutes exits on purpose, so after a longer stop you start
+ your nodes again (`sam-node run --daemonize`; they need no new
+ enrollment) or run them under a service manager that restarts them.
+ Resume the codespace from [github.com/codespaces](https://github.com/codespaces),
+ the README badge, or by connecting to it with `gh codespace code`, and run
+ `make testnet` again.
+- **Port visibility.** A restart makes the port private again. `sam-one`
+ says so in its log, and you set it to public once more.
- **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
diff --git a/site/content/docs/reference/sam-one.md b/site/content/docs/reference/sam-one.md
index ccfd2c7d..e1233af4 100644
--- a/site/content/docs/reference/sam-one.md
+++ b/site/content/docs/reference/sam-one.md
@@ -27,7 +27,7 @@ downloaded tunnel connector.
|---|---|---|
| `--bind-address` | `0.0.0.0` | Host to bind. |
| `--port` | `0` | TCP port. `0` picks a free one and prints it in the banner. |
-| `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `SAM_EXTERNAL_URL`. When omitted behind an HTTPS proxy (Cloud Run, Fly.io), `/info` infers the advertised `wss` address from the incoming `Host` / `X-Forwarded-Proto` headers automatically. |
+| `--external-url` | | Public URL on which nodes reach this instance, for a reverse proxy or a hosted platform. Can also be set with `SAM_EXTERNAL_URL`. When omitted behind an HTTPS proxy (Cloud Run, Fly.io, a forwarded Codespaces port), `/info` infers the advertised `wss` address from the incoming `Host` or `X-Forwarded-Host` and `X-Forwarded-Proto` headers automatically. |
| `--tunnel` | | Publish the port through a tunnel provider and use the resulting URL as the external URL. Providers: `cloudflare` (a free quick tunnel on `*.trycloudflare.com` by default, no account needed) and `codespaces` (the `https` URL GitHub Codespaces assigns to the forwarded port, read from `CODESPACE_NAME` and `GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN`; nothing is started, and the log reports whether the port answers from the internet). |
| `--tunnel-token-path` | | File containing the tunnel provider authentication token (can also be set with `SAM_TUNNEL_TOKEN`). Use together with `--tunnel <provider> --external-url https://mesh.example.com` for a permanent custom domain. |
| `--tunnel-install` | `false` | Download the pinned, digest-verified `cloudflared` into `<data-dir>/bin` without asking. Implies acceptance of its license. |