Skip to content

docs: what a live codespace showed #529

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
aojea merged 1 commit into from
Sep 27, 2026
+19 −12
Merged

docs: what a live codespace showed #529

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .devcontainer/devcontainer-lock.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,4 @@
"integrity": "sha256:f5251b8e4325f68f7280973c6cd65daff414449c66f240621502d4e8e74eb7ee"
}
}
}
}
27 changes: 17 additions & 10 deletions site/content/docs/guides/codespaces.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Comment on lines +148 to +149

@gemini-code-assist gemini-code-assist Bot Sep 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrase 'is back' is a bit colloquial. Using 'comes back' or 'is restarted' is more precise and natural in this context.

Suggested change
tokens, and enrolled devices reconnect on their own as long as the mesh is
back within about three minutes.
tokens, and enrolled devices reconnect on their own as long as the mesh comes
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
Expand All @@ -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.
Comment on lines +168 to +170

@gemini-code-assist gemini-code-assist Bot Sep 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrase 'you start your nodes again' is a bit passive/colloquial. It would be clearer and more direct to say 'you will need to restart your nodes' or 'you must restart your nodes'.

Suggested change:

  for about three minutes exits on purpose, so after a longer stop you will need to restart
  your nodes (`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
Expand Down
2 changes: 1 addition & 1 deletion site/content/docs/reference/sam-one.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |

@gemini-code-assist gemini-code-assist Bot Sep 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The phrase 'incoming Host or X-Forwarded-Host and X-Forwarded-Proto headers' is slightly ambiguous. Clarifying this with parentheses makes it clear that X-Forwarded-Proto is always used alongside either host header.

Suggested change:

| `--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. |
Expand Down
Loading