# Autonomous (Sentinel)

> Fully self-funded private internet for AI agents. The agent holds its own P2P, picks any Sentinel node, and pays that node directly per gigabyte. No operator, no fee-grant, no subscription, no HTTP server in the middle. One import, one `connect()` call from `blue-js-sdk/ai-path`. Maximum sovereignty: the agent controls keys, gas, node selection, and payment.

This is the **autonomous** path. There is a separate **managed** path at https://x402.sentinel.co where the agent pays USDC on Base and an operator provisions a Sentinel subscription + gas grant (zero prerequisites beyond USDC). Same network, same direct WireGuard/V2Ray tunnels. Use autonomous when you want zero intermediaries and are willing to hold P2P + pay your own gas; use managed when you only want to hold USDC. See https://x402.sentinel.co/llms.txt for that path.

## How Sentinel works (the network this talks to)

Sentinel is a decentralized VPN: 1,500+ independent node operators across 70+ countries, coordinated entirely on-chain. There is no central server, no account, no API key. The node registry IS the blockchain, protected by consensus.

- Native coin: **P2P**, denom `udvpn`, where **1 P2P = 1,000,000 udvpn**. It pays for bandwidth, pays gas, is staked to secure the chain, and votes in governance.
- Pricing is pay-as-you-go, posted by each node. Each node lists both a **per-gigabyte** rate and a **per-hour** rate (on-chain `gigabyte_prices` and `hourly_prices`); the agent picks the model per session — per-GB is the default. Protocol floor `100 udvpn/GB`. Live network median **~40 P2P/GB**; cheapest nodes **~2 P2P/GB**. Bandwidth revenue splits **80% node host / 20% stakers**.
- Two tunnel protocols: **WireGuard** (~30% of nodes, faster, full system route, needs admin once on Windows) and **V2Ray** (~70% of nodes, zero-admin userspace SOCKS5 proxy).
- Session lifecycle is all peer-to-peer: direct HTTPS node probe → on-chain `MsgStartSession` (agent pays its own gas) → node confirms → WireGuard/V2Ray handshake → encrypted tunnel. No intermediary touches the payment, the session, or the traffic.

Verified live on mainnet (a representative run; sessionId, exit IP and timing vary per run): a test agent, no operator in the loop, picked a US node, opened session **45943402**, paid **40.19 P2P** for a 1 GB V2Ray session, and the SDK confirmed exit IP **192.3.53.166** through the tunnel in about 35 s. The 40 P2P is right at the live network median; auto-select balances price against speed and uptime, so it will not always pick the ~2 P2P/GB cheapest node.

## Prerequisites

The agent needs exactly two things it manages itself:

1. **A Sentinel wallet it controls.** `createWallet()` from `blue-js-sdk/ai-path` returns `{ address, mnemonic }`. The mnemonic never leaves the agent.
2. **P2P in that wallet** — covers both per-GB node payments and its own gas (gas is bundled into the session TX). A fresh wallet starts empty: fund it by buying P2P on an exchange that lists it (e.g. MEXC) and withdrawing to the new address, or by bridging in.

There is no operator to provision anything. No fee-grant, no subscription, no USDC.

## Agent flow

1. Agent holds P2P in its own wallet.
2. Agent reads the live node registry and picks by country / speed / price — or passes `country` and lets the SDK auto-select; or pins one with `nodeAddress`.
3. Agent calls `connect()` → starts an on-chain session, pays the node directly in P2P at its posted per-GB rate, pays its own gas.
4. Agent and node complete a WireGuard or V2Ray handshake — tunnel up. No middleman.
5. The SDK verifies the exit IP THROUGH the tunnel and returns it as `vpn.ip`.
6. `await disconnect()` — soft: session preserved on-chain, unused GB stays available.

## Reference code — the verified autonomous path

```js
import { connect, disconnect, getBalance } from 'blue-js-sdk/ai-path';

// Agent already holds P2P in its own Sentinel wallet.
const bal = await getBalance(process.env.SENTINEL_MNEMONIC); // { address, udvpn, p2p, sufficient }

const vpn = await connect({
  mnemonic: process.env.SENTINEL_MNEMONIC,  // agent holds its own keys
  country: 'US',          // optional — or nodeAddress: 'sentnode1...' to pin one; omit for best anywhere
  protocol: 'v2ray',      // 'v2ray' (zero admin, auto-downloads binary, ~70% of nodes) or 'wireguard' (full route, admin once)
  gigabytes: 1,           // default 1 — pay per-GB; or { preferHourly: true, hours: 24 }
});
// vpn → {
//   sessionId: '45943402',        // on-chain session, paid by the agent
//   protocol: 'v2ray',
//   nodeAddress: 'sentnode1zjecy...',
//   ip: '192.3.53.166',           // exit IP, verified THROUGH the tunnel by the SDK
//   socksPort: 11375,             // dynamic — always read this from the result, never hardcode
// }

// ...do work over the tunnel...

await disconnect(); // soft: session preserved on-chain, unused GB stays available
```

> **V2Ray routing — choose your scope.** `protocol: 'v2ray'` runs a SOCKS5 proxy and can encrypt the whole device or only the requests you choose. **Whole device** — pass `systemProxy: true` to `connect()`; the SDK sets the system proxy (Windows registry / macOS `networksetup` / Linux gsettings) and all traffic routes through the node, restored on `disconnect()`. **Per-request (split tunnel)** — omit `systemProxy` and send chosen requests through `vpn.socksPort`; use `socks5h://` (not `socks5://`) so DNS resolves at the exit node and no DNS leaks. CRITICAL: Node's native `fetch()` ignores SOCKS5 agents and exits on the real IP — use `axios` with `SocksProxyAgent` and `adapter: 'http'` (`httpAgent` + `httpsAgent`), not `fetch()`. Verified live on Windows (session 45984926): the `axios`+`SocksProxyAgent` request exited on the node IP while a plain `fetch()` on the same machine stayed on the host IP — only the routed request changed IP. **WireGuard** — `protocol: 'wireguard'` for a kernel-level full tunnel. `socksPort` is dynamic — read it from the `connect()` result, never hardcode. `vpn.ip` is the exit IP, already verified through the tunnel by the SDK. `connect()` registers cleanup handlers automatically, so a crashed process never strands the tunnel.

## Platforms

The chain payment (node selection, the per-GB payment, `MsgStartSession`) is identical everywhere, and so is the V2Ray JS `connect()` path. The native CLI is only an alternative for WireGuard or Node-less environments.

- **V2Ray via blue-js-sdk — cross-platform, zero admin (Windows, macOS, Linux).** `protocol: 'v2ray'` needs no admin and no manual install on ANY of the three: `connect()` auto-downloads the same v2ray binary to `~/.sentinel-sdk/bin` on first use (the SDK ships SHA256-verified binaries for win32, darwin x64/arm64 and linux x64/arm64). The identical `connect({ protocol: 'v2ray' })` call works as-is on all three OSes (~70% of nodes). Add `systemProxy: true` for whole-device routing — the SDK sets the OS proxy (Windows registry / macOS `networksetup` / Linux gsettings); on headless or non-GNOME Linux that OS-proxy step is a no-op, but per-request `socksPort` routing still works there. WireGuard nodes (the other ~30%, faster) need admin ONCE on Windows for the MSI install + tunnel service; the SDK checks for admin BEFORE payment and refuses a WireGuard node when not elevated, so no P2P is wasted. Can't elevate? Stay on v2ray.
- **Native CLI (`sentinel-dvpncli`) — the WireGuard / Node-less alternative.** Not required for V2Ray (the JS path above covers that on every OS). Reach for it when you want a WireGuard node or run without Node. `go install github.com/sentinel-official/sentinel-dvpncli@latest` (Go 1.24+). The CLI does NOT bundle a tunnel — it shells out to `wg-quick` for WireGuard nodes, so install **wireguard-tools** first (`apt`/`brew`/`pacman`). Import the wallet (`printf '%s\n\n' "$AGENT_MNEMONIC" | sentinel-dvpncli keys add agent --keyring.backend test`), `sentinel-dvpncli tx session-start "$NODE_ADDRESS" --tx.from-name agent --keyring.backend test --rpc.chain-id sentinelhub-2 --output-format json`, then `sentinel-dvpncli connect "$SESSION_ID"`. Tear down with `tx session-cancel`. Only exception across all platforms: **Fedora** (SELinux blocks VPN interfaces).

## Packages

- `blue-js-sdk/ai-path` — the agent entry point, cross-platform (Windows, macOS, Linux). Wallet (`createWallet`, `importWallet`, `getBalance`), tunnel (`connect`, `disconnect`), node/plan discovery (`rpcQueryNodesForPlan`, `createRpcQueryClientWithFallback`), environment setup (`setup` — pre-fetches tunnel binaries for all three OSes). WireGuard + V2Ray. The same `connect({ protocol: 'v2ray' })` call works on every OS.
- `sentinel-dvpncli` — the WireGuard / Node-less alternative: native Go CLI (`go install github.com/sentinel-official/sentinel-dvpncli@latest`, Go 1.24+). Not required for V2Ray (the JS path covers that on all platforms). Does NOT bundle a tunnel: shells out to `wg-quick` (install wireguard-tools) or `v2ray` on PATH.

## Sentinel chain endpoints

`blue-js-sdk` ships verified RPC and LCD fallbacks and rotates through them automatically (`createRpcQueryClientWithFallback()`); add more at runtime with `addRpcEndpoint(url)`. RPC-first — LCD is fallback only.

- RPC: `rpc.sentinel.co:443`, `sentinel-rpc.polkachu.com`, `rpc.mathnodes.com`, `sentinel-rpc.publicnode.com`, `rpc.sentinel.quokkastake.io`, `rpc.sentinel.suchnode.net`
- LCD (fallback only): `lcd.sentinel.co`, `sentinel-api.polkachu.com`, `api.sentinel.quokkastake.io`, `sentinel-rest.publicnode.com`, `api.sentinel.suchnode.net`

## Security properties

- Keys never leave the agent. It generates and holds its own Sentinel mnemonic and signs `MsgStartSession` locally. No operator, no server, no node ever receives the private key.
- The tunnel is always agent ↔ node. Nothing sits in the middle to see traffic, keys, or destinations.
- No operator, no fee-grant, no subscription, no plan. The agent pays its own gas and pays the node directly in P2P. No third party can revoke, throttle, or de-anonymize it.
- No PII anywhere. The agent never registers, never gives an email, never passes KYC. The chain sees a pseudonymous address and a session; the node sees encrypted traffic.
- Decentralized by design — the node registry is the blockchain, not a directory any company controls. No central server to compromise, subpoena, or shut down.

## Source

- GitHub: https://github.com/Sentinel-Bluebuilder/autonomous
- SDK: https://www.npmjs.com/package/blue-js-sdk
- Managed path (pay USDC): https://x402.sentinel.co — https://x402.sentinel.co/llms.txt
- Sentinel: https://sentinel.co — https://docs.sentinel.co