120 lines
4.5 KiB
Markdown
120 lines
4.5 KiB
Markdown
---
|
|
name: nordvpn-client
|
|
description: Use when managing NordVPN on macOS or Linux, including install/bootstrap, login, connect, disconnect, status checks, or verifying a VPN location before running another skill.
|
|
---
|
|
|
|
# NordVPN Client
|
|
|
|
Cross-platform NordVPN lifecycle management for macOS and Linux hosts.
|
|
|
|
## Use This Skill For
|
|
|
|
- probing whether NordVPN automation is ready
|
|
- bootstrapping missing backend dependencies
|
|
- validating auth
|
|
- connecting to a country or city
|
|
- verifying the public exit location
|
|
- disconnecting and restoring the normal network state
|
|
|
|
## Command Surface
|
|
|
|
```bash
|
|
node scripts/nordvpn-client.js status
|
|
node scripts/nordvpn-client.js install
|
|
node scripts/nordvpn-client.js login
|
|
node scripts/nordvpn-client.js verify
|
|
node scripts/nordvpn-client.js verify --country "Germany"
|
|
node scripts/nordvpn-client.js verify --country "Japan" --city "Tokyo"
|
|
node scripts/nordvpn-client.js connect --country "Germany"
|
|
node scripts/nordvpn-client.js connect --country "Japan" --city "Tokyo"
|
|
node scripts/nordvpn-client.js disconnect
|
|
node scripts/nordvpn-client.js status --debug
|
|
```
|
|
|
|
## Backend Model
|
|
|
|
- Linux:
|
|
- use the official `nordvpn` CLI
|
|
- `install` uses the official NordVPN installer
|
|
- token login is supported
|
|
- macOS:
|
|
- use NordLynx/WireGuard through `wireguard-go` and `wireguard-tools`
|
|
- `install` bootstraps them with Homebrew
|
|
- `login` validates the token for the WireGuard backend
|
|
- the generated WireGuard config stays free of `DNS = ...`
|
|
- `connect` now requires a bounded persistence gate plus a verified exit before success is declared
|
|
- the skill snapshots and applies NordVPN DNS only to eligible physical services while connected
|
|
- NordVPN DNS is applied only after the tunnel remains up and the final liveness check still shows the requested exit
|
|
- `disconnect` restores the saved DNS/search-domain state even if the tunnel state is stale
|
|
- Tailscale is suspended before connect and resumed after disconnect or failed connect
|
|
- `NordVPN.app` may remain installed but is only the manual fallback
|
|
|
|
## Credentials
|
|
|
|
Default OpenClaw credential paths:
|
|
|
|
- token: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/token.txt`
|
|
- password: `~/.openclaw/workspace/.clawdbot/credentials/nordvpn/password.txt`
|
|
|
|
Supported env vars:
|
|
|
|
- `NORDVPN_TOKEN`
|
|
- `NORDVPN_TOKEN_FILE`
|
|
- `NORDVPN_USERNAME`
|
|
- `NORDVPN_PASSWORD`
|
|
- `NORDVPN_PASSWORD_FILE`
|
|
|
|
## macOS Requirements
|
|
|
|
Automated macOS connects require all of:
|
|
|
|
- `wireguard-go`
|
|
- `wireguard-tools`
|
|
- `NORDVPN_TOKEN` or the default token file
|
|
- non-interactive `sudo` for the installed helper script:
|
|
- `~/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh`
|
|
|
|
Exact `visudo` rule for the installed OpenClaw skill:
|
|
|
|
```sudoers
|
|
stefano ALL=(root) NOPASSWD: /Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh probe, /Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh up, /Users/stefano/.openclaw/workspace/skills/nordvpn-client/scripts/nordvpn-wireguard-helper.sh down
|
|
```
|
|
|
|
Operational note:
|
|
|
|
- the persistence gate reuses the already-allowed `probe` action to confirm the live `utun*` WireGuard runtime and does not require extra sudoers actions beyond `probe`, `up`, and `down`
|
|
|
|
## Agent Guidance
|
|
|
|
- run `status` first when the machine state is unclear
|
|
- on macOS, if tooling is missing, run `install`
|
|
- if auth is unclear, run `login`
|
|
- use `connect` before location-sensitive skills such as `web-automation`
|
|
- use `verify` after connect when you need an explicit location check
|
|
- use `disconnect` after the follow-up task
|
|
- if `connect` fails its persistence or final verification gate, treat that as a safe rollback, not a partial success
|
|
|
|
## Output Rules
|
|
|
|
- normal JSON output redacts local path metadata
|
|
- use `--debug` only when deeper troubleshooting requires internal local paths and helper/config metadata
|
|
|
|
## Troubleshooting Cues
|
|
|
|
- `Invalid authorization header`:
|
|
- token file exists but the token is invalid; replace the token and rerun `login`
|
|
- `sudoReady: false`:
|
|
- the helper is not allowed in sudoers; add the `visudo` rule above
|
|
- connect succeeds but final state looks inconsistent:
|
|
- rely on the verified public IP/location first
|
|
- then inspect `status --debug`
|
|
- `verified: true` but `persistence.stable: false` should not happen anymore; if it does, the skill should roll back instead of pinning DNS
|
|
- disconnect should leave:
|
|
- normal public IP restored
|
|
- no active WireGuard state
|
|
- Tailscale resumed if the skill suspended it
|
|
|
|
For full operator setup and troubleshooting, see:
|
|
|
|
- `docs/nordvpn-client.md`
|