You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs+manifest: bring macOS/Linux connect to parity with Windows (native CLI)
All three agent-facing surfaces now document a real, source-verified macOS/Linux
connect path using Sentinel's native sentinel-dvpncli, instead of a bare GitHub
link. Payment is identical on every OS; only the connect step differs.
Verified against sentinel-dvpncli @ v4.0.0 source (cobra command tree + sentinel-go-sdk
config flags), not its README:
- install: go install github.com/sentinel-official/sentinel-dvpncli@latest (Go 1.24+)
- keys: echo "$MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test
- session: sentinel-dvpncli tx session-start <nodeAddress> --subscription-id <id>
--tx.fee-granter-addr <feeGranter> --tx.from-name agent --keyring.backend test
- connect: sentinel-dvpncli connect <sessionId>
Flags map 1:1 onto the x402 200 response (subscriptionId, feeGranter, nodeAddress).
Fedora called out as the sole unsupported OS (SELinux blocks VPN interfaces).
docs/llms.txt - rewrote Prerequisites (two equal paths), split Agent-flow step 8 by OS,
retitled the JS reference as "payment + Windows connect", added a full
"macOS & Linux - native CLI connect" section, added sentinel-dvpncli to Packages.
docs/index.html - relabelled Step 3 as the Windows JS path, added a parity "Step 3 - macOS &
Linux (easiest)" CLI code block, taught the embedded manifest JSON the
connectMacLinux/connectWindows split, annotated the full-flow example.
server/src/index.ts - /manifest now carries the platform split in tldr, flow step 8, and a new
sentinel.connectMacLinux block (+ platform notes on setup/connect/disconnect).
tsc --noEmit passes. NOTE: live server runs an older image; manifest reflects
this only after the host redeploys.
"setup": "await setup() from blue-js-sdk/ai-path — run once on a fresh machine; auto-downloads V2Ray (no admin), checks WireGuard; returns { ready, capabilities, recommended, issues }",
56
+
"platforms": "Payment is identical everywhere; only the connect step differs by OS.",
Copy file name to clipboardExpand all lines: docs/llms.txt
+69-6Lines changed: 69 additions & 6 deletions
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,12 @@ The agent signs an EIP-3009 message off-chain. The self-hosted facilitator settl
8
8
9
9
The agent needs exactly one thing before calling x402: an EVM private key with at least $1.00 USDC on Base (chainId 8453). Everything else — Sentinel wallet, P2P gas, node selection, tunnel keys — is provisioned by x402 or generated locally by `blue-js-sdk/ai-path`.
10
10
11
-
On a fresh machine with no tunnel binaries, run `await setup()` from `blue-js-sdk/ai-path` once before `connect()`. It auto-downloads V2Ray 5.2.1 to `~/.sentinel-sdk/bin` (no admin rights needed) and detects/auto-installs WireGuard (the Windows MSI install needs admin). It returns `{ ready, capabilities, recommended, issues }` — if `capabilities` includes `v2ray`, you can connect with zero manual installs. For macOS and Linux Sentinel's CLI tool shall be used to connect (ideally, compile it locally): https://github.com/sentinel-official/sentinel-dvpncli
11
+
**Payment is identical on every platform.** What differs is *connecting* the tunnel after the server returns 200. There are two equally-supported connect paths — pick by OS:
12
+
13
+
- **macOS & Linux (easiest):** WireGuard already ships with the OS, so there is nothing to install for the tunnel itself. Use the native `sentinel-dvpncli` (one `go install`), then drive it with three flag-only commands — see **"macOS & Linux — native CLI connect"** below. No admin/sudo for V2Ray; WireGuard may need sudo to bring an interface up, same as any WireGuard client. **Only exception: Fedora** — its SELinux blocks VPN interfaces and cannot be worked around programmatically; macOS, Ubuntu, Debian and other mainstream Linux are fine.
14
+
- **Windows (heavier):** run `await setup()` from `blue-js-sdk/ai-path` once on a fresh machine before `connect()`. It auto-downloads V2Ray 5.2.1 to `~/.sentinel-sdk/bin` (no admin) and detects/auto-installs WireGuard (the MSI install needs admin). It returns `{ ready, capabilities, recommended, issues }` — if `capabilities` includes `v2ray`, you can connect with zero manual installs. See **"Windows — JS-SDK connect"** below.
15
+
16
+
Both paths consume the exact same 200 response (`subscriptionId`, `planId`, `feeGranter`, `nodeAddress`) and end in the same `MsgStartSession` + direct WireGuard/V2Ray handshake.
12
17
13
18
How to fund a fresh EVM key with USDC on Base:
14
19
- **Coinbase / Coinbase CDP**: withdraw USDC and pick "Base" as the network. ~30 seconds, no bridge fee.
@@ -53,11 +58,17 @@ Free:
53
58
5. Facilitator settles USDC on Base.
54
59
6. Server submits atomic `MsgShareSubscription` + `MsgGrantAllowance` on Sentinel.
8. Agent runs `setup()` once on a fresh machine, then `connect({ mnemonic, subscriptionId, feeGranter, nodeAddress })`.
57
-
9. `MsgStartSession` on Sentinel — gas paid by `feeGranter`.
58
-
10. Direct WireGuard/V2Ray handshake — tunnel up.
61
+
8. Agent connects, using the path for its OS (both consume the same 200 fields):
62
+
- **macOS/Linux:** `sentinel-dvpncli tx session-start <nodeAddress> --subscription-id <subscriptionId> --tx.fee-granter-addr <feeGranter> --tx.from-name <key>` → note the returned session id → `sentinel-dvpncli connect <sessionId>`. (See "macOS & Linux — native CLI connect".)
63
+
- **Windows:** `setup()` once on a fresh machine, then `connect({ mnemonic, subscriptionId, feeGranter, nodeAddress })`. (See "Windows — JS-SDK connect".)
64
+
9. `MsgStartSession` on Sentinel — gas paid by `feeGranter` (the fee grant the server created in step 6, so the agent's session start costs zero P2P).
65
+
10. Direct WireGuard/V2Ray handshake — tunnel up. The operator never sees it.
66
+
67
+
## Reference code — payment (all platforms) + Windows connect
59
68
60
-
## Reference code
69
+
The payment half of this snippet is identical on every OS. The trailing `connect()` is the
70
+
Windows path (JS-SDK tunnel). On macOS/Linux, stop after you have `provision` and switch to the
71
+
CLI recipe in the next section — the request/response is byte-for-byte the same.
61
72
62
73
```typescript
63
74
import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
@@ -99,11 +110,63 @@ const vpn = await connect({
99
110
// vpn.connected === true
100
111
```
101
112
113
+
## macOS & Linux — native CLI connect
114
+
115
+
This is the easiest connect path. After the `paidFetch` call above returns `provision`
116
+
(`{ subscriptionId, planId, feeGranter, nodeAddress, ... }`), do NOT call the JS `connect()`.
117
+
Instead drive Sentinel's native `sentinel-dvpncli` — three fully flag-driven commands, no config
118
+
files, no interactive prompts when you pass the flags below. WireGuard already ships with macOS
119
+
and mainstream Linux, so there is nothing to install for the tunnel itself.
120
+
121
+
**Install once (Go 1.24+):**
122
+
123
+
```bash
124
+
go install github.com/sentinel-official/sentinel-dvpncli@latest # binary lands in $(go env GOPATH)/bin
125
+
# or from source: git clone https://github.com/sentinel-official/sentinel-dvpncli && cd sentinel-dvpncli && make install
126
+
sentinel-dvpncli version
127
+
```
128
+
129
+
**Connect (drive these with the fields from `provision`):**
130
+
131
+
```bash
132
+
# 1. Import the SAME wallet whose sentinelAddr (sent1...) you sent to x402.
133
+
# The mnemonic is read from stdin; --keyring.backend test makes it non-interactive (no OS keychain prompt).
134
+
echo "$AGENT_MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test
135
+
# (keyring.backend defaults to "os"; use "test" or "file" for scripted/agent use.)
136
+
137
+
# 2. Start the session against the subscription x402 shared with you.
138
+
# --tx.fee-granter-addr = provision.feeGranter => the operator pays the P2P gas, you pay zero.
0 commit comments