From 3dc6b15d5c5facd7276d40cf722f1de83f1a722a Mon Sep 17 00:00:00 2001 From: Antonio Ojea Date: Sun, 27 Sep 2026 11:51:43 +0000 Subject: [PATCH] docs: what a live codespace showed Port visibility reverts to private on every codespace restart, and sam-one says so again; gh is not in the image, so the gh command in the hint runs on your own machine; a sam-node that finds no router for about three minutes exits on purpose, so nodes are started again after a longer stop, with the identity they already hold. GitHub's proxy names the public host in X-Forwarded-Host, which the zero-config inference already reads, so the reference says so. The lock file loses its final newline: that is how Codespaces writes it, and the checkout stays clean. --- .devcontainer/devcontainer-lock.json | 2 +- site/content/docs/guides/codespaces.md | 27 ++++++++++++++++---------- site/content/docs/reference/sam-one.md | 2 +- 3 files changed, 19 insertions(+), 12 deletions(-) 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 --external-url https://mesh.example.com` for a permanent custom domain. | | `--tunnel-install` | `false` | Download the pinned, digest-verified `cloudflared` into `/bin` without asking. Implies acceptance of its license. |