--- name: openvpn-on-demand-setup description: "Configure openvpn-on-demand for this project — pick BYO vs ephemeral mode, write .claude/openvpn-on-demand.local.md, and add it to .gitignore. Read-only against the host; runs nothing privileged." --- Resolve `../..` from this SKILL.md's directory to the absolute plugin root. Substitute that path for `` in the instructions and commands below; do not assume a plugin-root shell variable is set. Keep the working directory at the consuming project root. In Codex, select `$openvpn-on-demand:openvpn-on-demand-setup` or `$openvpn-on-demand:openvpn-on-demand-doctor`. In Claude Code, the equivalent commands are `/openvpn-on-demand:setup` and `/openvpn-on-demand:doctor`. You are running `openvpn-on-demand-setup`, an interactive configurator. Write **only** `.claude/openvpn-on-demand.local.md` and, if needed, a `.gitignore` line. **Never** run anything privileged, import an openvpn3 config, or call a `vpn_*` MCP tool. First read `/setup-checklist.md` (checks 1–9 and their remediation text); use that text verbatim on failures. ## Flow ### 1. Host prerequisites Run checks 1–4. Check 1 decides the backend (openvpn3, else OpenVPN 2); for the openvpn2 variants of checks 2 and 4 run exactly `python3 "/servers/openvpn/src/openvpn_mcp/ovpn2_helper.py" probe` once and read its JSON. If any fails, print its remediation and **stop**; tell the user to re-run `openvpn-on-demand-setup` after fixing. Remediations are instruct-only: show the `sudo` lines, don't run them. Then run check 9 without a hostname — exactly `python3 "/servers/openvpn/src/openvpn_mcp/dnscheck.py"`. On WARN or FAIL print its output but **don't stop**; its root-only fix goes in the summary. ### 2. Existing settings file? Run check 5. If the file exists, Read it, show its frontmatter, and ask the user: *Keep as-is* / *Reconfigure (overwrite)* / *Abort*. Stop on Keep or Abort. ### 3. Pick the mode Ask the user — "Which mode should this project use?": - **BYO** — openvpn3: "You import and maintain an openvpn3 config; the plugin starts/stops its sessions and writes its connect overrides (`dns-scope=tunnel` plus any `config_overrides`) into it, where they persist." openvpn2: "You keep the profile at `/etc/openvpn/client/.conf` (root-owned); the plugin starts/stops a tunnel from it and changes nothing in it." - **Ephemeral** — "A command prints the `.ovpn` body on stdout; the plugin makes a fresh single-use config from it each VPN-gated turn. Nothing to import." ### 4. Mode-specific question **BYO** → Ask for `profile_name` (openvpn3: the `--name` for `openvpn3 config-import`; openvpn2: the file name under `/etc/openvpn/client/`, without `.conf`). Run check 7; if the name isn't listed (openvpn2: always, it can't be checked without root), print check 7's remediation verbatim, noting it applies *after* this command writes the settings file. Don't import it yourself. **Ephemeral** → Ask for `ovpn_provision_cmd`, showing these shapes: - `vault read -field=config secret/vpn/my-prod` - `aws s3 cp s3://my-bucket/vpn/my-prod.ovpn -` - `cat ~/.config/openvpn3/my-prod-vpn.ovpn` - `make get_vpn_client_config OUTPUT=/dev/stdout` Stress: stdout must be the `.ovpn` body — not a path or status line. Keep it task-agnostic; hard-coded per-task values lock the file to one task. The assistant adds them at call time from the project's AGENTS.md / CLAUDE.md — as arguments where the command takes them (`make … ENV=dev`), else as a leading assignment (`AWS_PROFILE=… vault read …`), never a leading `ENV=` (Claude Code refuses it in worktree-isolated sessions). ### 5. Optional fields Ask which optional fields to configure (default none): - `post_connect_cmd` — shell command run after a fresh `vpn_connect`. Non-fatal. - `post_disconnect_cmd` — shell command run after a fresh `vpn_disconnect` (not on `not_connected`). Non-fatal. - `config_overrides` — **openvpn3 only** (on the openvpn2 backend they are not applied; say so and don't offer it). openvpn3 `config-manage` overrides set before each tunnel start (hyphenated: `dns-scope`, `persist-tun`, `log-level`, …) on top of the `dns-scope=tunnel` baseline; override only for fully tunnel-routed DNS or other tweaks. In BYO mode, tell the user the baseline and these values persist in their profile (also for their own `openvpn3 session-start`) and that removing a key needs `openvpn3 config-manage --config --unset-override `. If chosen, ask for the map. ### 6. Write `.claude/openvpn-on-demand.local.md` Create the directory if needed. Use this template: the chosen mode's field uncommented, the other's commented out, each chosen optional uncommented with its value: ```markdown --- # Generated by openvpn-on-demand-setup. Edits take effect immediately — no restart. # Exactly one of profile_name / ovpn_provision_cmd. profile_name: # ovpn_provision_cmd: # Optional: # post_connect_cmd: # post_disconnect_cmd: # config_overrides: # log-level: 4 --- # Project VPN notes (for humans — not read by the plugin) Which account this profile is for, how to rotate its credentials, who to ping when it breaks. ``` ### 7. `.gitignore` Run check 8. If not covered and `.gitignore` has no such line, append `.claude/*.local.md` (create `.gitignore` if absent). If the line is already there, the file is tracked: print check 8's second FAIL text and change nothing. If covered, say so and change nothing. ### 8. Summary Print the path written, the mode, and what the user still owes: - BYO → openvpn3: the `config-import` line again if the profile isn't imported. openvpn2: the `sudo install … /etc/openvpn/client/.conf` line from check 7 (it could not be checked). - openvpn3 only: check 4 borderline / skipped → the netcfg note again. - Check 9 WARN / FAIL → its fix lines again, and say that until they're applied programs may not resolve private names even with the tunnel up. End with: "Done. No restart needed — the skill re-reads this file every turn. Run `openvpn-on-demand-doctor` any time to re-check." Add that asking the assistant for something VPN-gated triggers the skill, that the assistant decides per operation, and that a line in the project's `AGENTS.md` / `CLAUDE.md` marking resources VPN-only covers what it can't recognise from the command (a host in a config file, another plugin's calls).