Skip to content

📖 Scribe: Document meshguard connect command #65

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

Closed
igorls wants to merge 1 commit into from
Closed

📖 Scribe: Document meshguard connect command #65

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
5 changes: 5 additions & 0 deletions .jules/scribe.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,8 @@
**Gap:** The documentation stated the SWIM protocol period was 1000ms (1s), but the implementation uses 5000ms (5s) in both `src/config.zig` and `src/discovery/swim.zig`.
**Learning:** The documentation likely reflected an early design decision or standard SWIM defaults, but the implementation settled on a more conservative 5s interval for WAN stability, and docs were not updated.
**Prevention:** Add a CI check that grep's `docs/guide/configuration.md` for values that match constants exported in `src/config.zig`.

## 2026-03-06 - CLI reference missing command
**Gap:** `meshguard connect` command was missing from `docs/reference/cli.md` despite being implemented in `src/main.zig`.
**Learning:** Adding new commands in `src/main.zig` does not automatically update the CLI reference documentation since CLI parsing is manual. This creates a high risk of documentation drift.
**Prevention:** Check for undocumented commands by comparing `fn cmd...` implementations in `src/main.zig` against documented commands in `docs/reference/cli.md`.
23 changes: 23 additions & 0 deletions docs/reference/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,29 @@ meshguard config show

---

## `meshguard connect`

Direct peer connection via token exchange (no seed node needed). Performs a coordinated UDP hole punch.

Comment on lines +142 to +143
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

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

meshguard connect binds the gossip UDP port (51821) and will fail if the daemon is already running (it only attempts to stop the systemd service). The docs should mention that the port must be free / meshguard should be stopped (or run as a service) before running connect, to avoid confusing bind errors.

Copilot uses AI. Check for mistakes.
```bash
meshguard connect --generate [--in <minutes>]
meshguard connect --join <mg://token>
```

| Flag | Description |
| -------------- | ---------------------------------------------- |
| `--generate` | Generate an initial token to share with a peer |
| `--join` | Accept a token and generate a response token |
| `--in <mins>` | Delay until punch time (default: 1 minute) |
Comment on lines +149 to +153
Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

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

The --in flag is only used for the --generate flow (the joiner uses the punch time embedded in the initiator token). The table currently reads like --in applies generically; please clarify it’s --generate-only and consider using the same placeholder (<minutes> vs <mins>) consistently between the usage block and the flag table.

Suggested change
| Flag | Description |
| -------------- | ---------------------------------------------- |
| `--generate` | Generate an initial token to share with a peer |
| `--join` | Accept a token and generate a response token |
| `--in <mins>` | Delay until punch time (default: 1 minute) |
| Flag | Description |
| ----------------- | --------------------------------------------------------------------------- |
| `--generate` | Generate an initial token to share with a peer |
| `--join` | Accept a token and generate a response token |
| `--in <minutes>` | Initiator-only: delay punch time when using `--generate` (default: 1 minute) |

Copilot uses AI. Check for mistakes.

**Flow:**
1. Initiator runs `--generate` and shares the `mg://` token with the peer.
2. Peer runs `--join <token>` and shares the generated response token back.
3. Initiator pastes the response token.
4. Both sides punch simultaneously (NTP-synced).

Copy link

Copilot AI Mar 6, 2026

Choose a reason for hiding this comment

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

The connect flow mutates local trust/config on success (it auto-adds the peer to authorized_keys and saves the punched endpoint as a seed). This is security-relevant behavior and should be documented explicitly so users understand it’s not a purely ephemeral connection attempt.

Suggested change
**Security note**: On successful connection, `meshguard connect` **persists trust state**:
- The remote peer is added to your local trust/`authorized_keys` (or equivalent) store.
- The discovered endpoint is saved as a seed for future connections.
This is **not** a purely ephemeral connectivity test. Only run `connect` with peers you intend to trust, and clean up the corresponding entries if you want to revoke that trust later.

Copilot uses AI. Check for mistakes.
---

## `meshguard service`

Manage service access control policies (port-level allow/deny rules).
Expand Down