OPNsense Admin 🛡️

Your OpenCode agent that only speaks OPNsense. No raw pfctl, no iptables, no hand-edited firewall configs — if it can’t go through the OPNsense API into config.xml, opnsense won’t build it that way. It refuses the wrong shape and hands you the OPNsense-native design instead.

● LIVE API-first · config.xml ★ stalane/opnsense

opn-* skills

firewall · vpn · system · services · diagnostics · plugins

API shape

/api/*

module / controller / command · Basic key+secret

Apply discipline

staged → live

search → add/set → apply · backup first

Docs stance

verified

endpoints checked vs docs.opnsense.org

🔌 API shape: one base, every plane

GET retrieves · POST mutates/executes · JSON bodies · per-user effective privileges · docs.opnsense.org/development/api.html

Plane	Modules
firewall	filter (rules + apply) · alias (+ GeoIP/URL tables) · source_nat · d_nat · one_to_one · npt · filter_util/rule_stats
vpn	ipsec · openvpn · wireguard — instances, peers, keys, status
system	firmware · core (services/backups) · auth · trust (certs) · routes/routing · HA/CARP
services	unbound (+DNSBL) · kea/dnsmasq/dhcrelay · ids (Suricata) · monit · ntpd · syslog · trafficshaper
diagnostics	diagnostics (ping/capture/lookup) · syslog files · core/service · Insight/NetFlow · health graphs
plugins	haproxy · caddy · acmeclient · crowdsec · tailscale/zerotier · telegraf/nodeexporter

export OPN_HOST=fw.example.com OPN_KEY=<key> OPN_SECRET=<secret>
curl -s -u "$OPN_KEY:$OPN_SECRET" \
  "https://$OPN_HOST/api/firewall/filter/searchRule" \
  -d '{"current":1,"rowCount":25,"sort":{},"searchPhrase":""}'

🛠 Skill router

one plane per skill · thin files, heavy reuse

Skill	Plane
opn-firewall	filter rules · aliases · NAT · apply flow
opn-vpn	IPsec · OpenVPN · WireGuard
opn-system	firmware · backups · users/keys · HA · certs
opn-services	Unbound · DHCP · IDS/IPS · Monit · NTP
opn-diagnostics	health · logs · NetFlow · capture · triage
opn-plugins	HAProxy · Caddy · ACME · CrowdSec · mesh

⛔ Hard rule: OPNsense-only

refuse the shape, redirect to the equivalent

Asked for	Built instead
Raw pfctl / pf.conf edits	firewall/filter + alias via API
iptables / nftables	firewall/filter rules + apply
Manual NAT scripts	source_nat / d_nat / 1:1 / NPT
Hand-rolled VPN configs	wireguard / openvpn / ipsec modules
Cron scripts poking pf	core/cron + configd actions
External DNS/DHCP boxes	unbound / kea / dnsmasq on-box
Reverse-proxy VPS	haproxy / caddy plugins

⬇ Install into your harness

OpenCode · an OPNsense firewall with an API key (System ‣ Access ‣ Users)

cp agent/opnsense.md ~/.config/opencode/agents/
cp -r skills/* ~/.config/opencode/skills/

Restart OpenCode, verify with opencode agent list (expect opnsense).
Host / key / secret travel per command as env vars — never stored in the repo, never logged.
Safety default: search → stage → apply, config.xml backup before mutating sessions, confirm before production apply.

✔ Verification record

measured, not claimed

API shapes verified 29 Sep 2026 — firewall plane (filter/searchRule/addRule/setRule/delRule/toggleRule/apply, alias/*, NAT controllers, filter_util/rule_stats) read against the live API reference; all other planes cite module/controller names from the same reference, parameters copied from GUI /api/ traffic.
Unknown-parameter rule banked: repeat the action in the GUI with devtools open, copy the /api/ request verbatim — never invent model fields.
Gotchas banked: staged writes are not live before apply/reconfigure; automation-namespace rules are separate from core GUI rules; curl -k is lab-only.