| name | onboard |
| description | First-run onboarding for the opnsense-mgmt plugin. Interview the user about their OPNsense router — host/IP, SSH user, whether the OPNsense API is enabled, and where API credentials live — and persist the result to `$CLAUDE_USER_DATA/opnsense-mgmt/config.json`. Run this before any other skill in this plugin, or whenever the connection details change. Triggers on phrases like "set up opnsense", "onboard opnsense", "configure opnsense plugin". |
opnsense-mgmt: onboard
Establish the persistent connection profile for an OPNsense host. The same plugin install can serve multiple environments — only the values in config.json are environment-specific. No host details should ever be hard-coded into other skills in this plugin.
Workspace resolution
Resolve the plugin's data directory as $CLAUDE_USER_DATA/opnsense-mgmt/ if CLAUDE_USER_DATA is set; otherwise $XDG_DATA_HOME/claude-plugins/opnsense-mgmt/ if XDG_DATA_HOME is set; otherwise ~/.local/share/claude-plugins/opnsense-mgmt/. Create the directory if it doesn't exist. See the canonical convention in the claude-rudder:plugin-data-storage skill.
Shell form:
PLUGIN_DATA_DIR="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/opnsense-mgmt"
mkdir -p "$PLUGIN_DATA_DIR"
The config file is $PLUGIN_DATA_DIR/config.json.
When to use
- User says "set up opnsense", "onboard opnsense", "configure opnsense plugin".
- Any other opnsense-mgmt skill finds no
config.json at the resolved path — offer to run onboarding first.
- The user changes routers, IPs, or SSH credentials.
Procedure
-
Load existing config from $PLUGIN_DATA_DIR/config.json if present. Show the current values back. Offer Update vs Replace vs Cancel.
-
Interview the user. Ask each question; default sensibly when the user just hits enter:
| Field | Prompt | Notes |
|---|
host | "What's the LAN address of your OPNsense router?" | Default: 10.0.0.1. Accept hostname or IP. |
ssh_user | "SSH username?" | Default: root (OPNsense default admin). Accept anything. |
ssh_port | "SSH port?" | Default: 22. |
ssh_key_path | "Path to the SSH private key (or leave blank for default agent)?" | Optional. Expand ~. |
web_url | "Web UI URL?" | Default: https://<host>. |
api_enabled | "Is the OPNsense API enabled? (y/n)" | If yes, ask for the next two. |
api_key_ref | "Where is the API key stored? (e.g. 1password://OPNsense API/key, env var name, or file path)" | Store the reference, not the secret itself. |
api_secret_ref | "Where is the API secret stored?" | Same — reference only. |
notes | "Any free-text notes about this router?" | Optional. |
-
Test connectivity (best-effort, don't block on failure):
ssh -o ConnectTimeout=5 -o BatchMode=yes -p "$SSH_PORT" "$SSH_USER@$HOST" "uname -a" 2>&1
Re-running
If config.json already exists, never silently overwrite. Always confirm. If the user picks Replace, back up the existing file with .bak suffix first.
Hard rules
- Never store the API key/secret itself in
config.json. Only store a reference (1Password item path, env var name, file path). The seed skill resolves the reference at runtime.
- Never hard-code IPs, hostnames, or usernames into other skills. Every operational skill must read from
config.json.
- Default values are suggestions, not assumptions. Always confirm with the user — defaults exist to make the prompt less tedious, not to silently encode someone else's setup.
