---
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, the final liveness check still shows the requested exit, and system hostname resolution still works afterward
  - `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
  - the skill writes a short-lived Tailscale suppression marker during VPN connect so host watchdogs do not immediately re-run `tailscale up`
  - `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 and helper-hardening diagnostics
- 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`