I gave Claude access to my OPNsense firewall — here's what happened

builderall — Sat, 07 Mar 2026 20:33:06 +0000

Disclaimer: This software is provided as-is, without warranty of any kind. Upgrading firewall firmware carries inherent risk including temporary or permanent loss of network connectivity. Always maintain a tested backup of your configuration, ensure you have out-of-band access (console, IPMI) before performing major upgrades, and test in a non-production environment first. The authors are not responsible for any damage, data loss, or network outages resulting from the use of these tools. Use at your own risk.

TL;DR: OPNsense major upgrades can break in ways the web UI can't recover from. I built a stateful SSH upgrade script that handles reboots and pkg ABI mismatches automatically, plus a Claude MCP server so you can manage your firewall conversationally. During a live upgrade this week, we found and fixed two bugs in real time. Code on GitHub.

The upgrade that broke everything

If you run OPNsense at home or in a small business, you've probably been there. A major version upgrade starts cleanly in the web UI, the progress bar moves, the firewall reboots... and then nothing works. The packages are half-installed. pkg refuses to run. The web UI shows the old version. You're staring at a FreeBSD shell wondering what happened.

This is not a bug in OPNsense. It's a known limitation of how the web UI handles major upgrades. The FreeBSD base and kernel get upgraded first, triggering a reboot. After that reboot, the new base ships a different pkg ABI — and the old pkg binary can no longer install or upgrade anything. The web UI has no recovery path for this. You're on your own.

I hit this twice. The second time, I decided to fix it properly.

Part 1: The SSH Upgrade Script

The first tool I built is a Python script that runs directly on OPNsense via SSH as root. It treats a major upgrade as a stateful, multi-stage pipeline rather than a single operation.

Stage	What it does
Pre-checks	Disk space (2GB minimum), pkg database health, lock file cleanup
Cleanup	Remove unused packages, clean cache
Backup	Save `config.xml` and installed package list
Base/Kernel	`opnsense-update -bk` — reboots if kernel changed
Fix pkg	Reinstall `pkg` using `pkg-static` after base upgrade
Packages	Switch repo, refresh catalog, upgrade all packages
Verification	Check pkg database, verify critical services

Dry-run by default. Every run shows exactly what will happen without making any changes. You add -x to execute for real.

# Preview what a major upgrade would do
./opnsense-upgrade.py -t 26.1

# Execute it
./opnsense-upgrade.py -x -t 26.1

Stateful — survives reboots. When the script triggers a reboot, it saves its state to /var/db/opnsense-upgrade.state and installs an auto-resume script in /etc/rc.local.d/. After the firewall comes back up, it picks up exactly where it left off.

Fixes pkg automatically. After a base/kernel upgrade, the script detects the ABI mismatch and reinstalls pkg using pkg-static before attempting any package upgrades. This is the step the web UI misses entirely.

Safety guards. Major upgrades are blocked when minor updates are pending. The script also validates disk space, checks pkg database health, and blocks duplicate runs.

Testing status:

Major upgrade (25.7 → 26.1) — tested successfully in production, including base/kernel reboot and pkg ABI fix
Minor updates via SSH script (26.1.1 → 26.1.2) — tested successfully in production
Minor update via MCP server (26.1.2 → 26.1.3) — tested today, including live bug fixes
Next major upgrade — script is ready; OPNsense API currently reports 26.7 as the next major version but it has not been released yet

Part 2: The Claude MCP Server

The SSH script solved the reliability problem. But I wanted to go further — managing the firewall conversationally without logging into a shell at all.

This is where MCP (Model Context Protocol) comes in. MCP is Anthropic's open protocol for giving AI assistants structured access to external tools and data sources. You define tools with typed inputs and outputs, register the server with Claude Code, and Claude can call those tools in response to natural language requests.

I built an MCP server in Python (httpx + Anthropic's mcp SDK) that connects Claude directly to OPNsense's REST API. Once registered, you can manage your firewall from a chat window:

"Check my firewall for updates"
"Run a pre-upgrade health check"
"Show me the 26.7 changelog"
"Apply the latest update"

The tools

The server exposes 10 tools across two categories:

Read tools (no confirmation needed):

Tool	What it does
`get_version`	Current version, FreeBSD base, next major version
`check_updates`	Minor/major update availability, reboot status
`pre_upgrade_check`	Full health assessment with go/no-go verdict
`upgrade_status`	Monitor an in-progress upgrade
`get_changelog`	Changelog for any version
`list_packages`	All installed packages with versions
`system_info`	Uptime, load average, top processes

Write tools (require explicit confirmation):

Tool	What it does
`run_update`	Trigger a minor update
`run_upgrade`	Trigger a major upgrade
`reboot`	Reboot the firewall

Security model

This is worth dwelling on. Giving an AI access to your firewall sounds alarming. The MCP approach is actually safer than SSH in several ways:

Scoped API keys — the Claude MCP user can only call firmware and diagnostics endpoints. It cannot touch firewall rules, VPN config, DHCP, or anything else.
Revocable instantly — delete the API key in OPNsense and Claude loses access immediately.
Audit trail built in — OPNsense logs every API call under System > Log Files > Audit.
Confirmation required — write tools require you to explicitly approve before Claude proceeds.
Read-only mode — set OPNSENSE_READ_ONLY=true to disable all write tools entirely.

System > Access > Users — the claude-mcp user alongside root

Edit User — assign all four privileges in the Privileges field

Part 3: A live upgrade — and two bugs found mid-session

I recently used the MCP server to upgrade my OPNsense from 26.1.2 to 26.1.3. Here's what happened — including bugs found and fixed during the session.

Bug 1: Stale firmware cache blocks the update

You: Check my firewall for updates

Claude: Minor update available: 26.1.3
        Reboot status: not required
        Want me to run the update?

You: Yes

Claude: [calls run_update]
        "System is already up to date. No update needed."

check_updates just told us 26.1.3 was available. Why is run_update saying we're up to date?

The OPNsense firmware daemon caches its status. check_updates got a fresh response showing 26.1.3. run_update made a second API call seconds later and got a stale "up to date" response.

check_updates had a fallback: if product_latest != product_version (comparing version strings directly), report an update as available regardless of the status field. run_update only checked the status field.

Fix: apply the same two-condition logic to run_update. Committed and pushed mid-session.

The update runs — and the firewall reboots

After the fix, the update triggered successfully. 82 packages, 280MB of downloads. Then — connection lost.

check_updates had said "Reboot status: not required." Yet the firewall rebooted mid-update.

This is a subtle distinction: "reboot not required" reflects the current state — no reboot pending from a previous operation. It does not predict whether the upcoming update will reboot. The 26.1.3 update included kernel and base packages, so OPNsense rebooted automatically.

After ~3 minutes:

You: Check version

Claude: OPNsense version: 26.1.3 ✓
        Base package: 26.1.3
        Kernel package: 26.1.3

Bug 2: Post-reboot false "reboot needed" flag

Right after the reboot, check_updates reported "reboot needed" again.

The firmware daemon runs early in boot and sees the needs_reboot flag before it clears. The timing check then reports it as genuine: "daemon ran after boot, so flag is genuine." But the reboot already happened as part of the update that just completed.

Fix: extend the staleness check — if no packages are pending AND the installed version equals the latest available, the flag is always treated as a leftover artifact regardless of daemon timing. Two lines of Python, committed immediately.

Three bugs found and fixed in a single upgrade session. Real-world testing works.

Part 4: Pre-upgrade health check

Before any upgrade, pre_upgrade_check gives you a structured go/no-go assessment:

Pre-Upgrade Assessment
========================================

Current version: 26.1.3
Minor update:    up to date
Major upgrade:   26.7 -- planned, not yet released on mirror
Reboot:          not required
In-progress:     none
Obsolete py37:   none found

----------------------------------------
VERDICT: System is up to date. Major upgrade to 26.7 is planned but not yet released.

This covers everything that could cause an upgrade to fail: pending minor updates (must be applied before a major upgrade), stale reboot flags, in-progress upgrades, and obsolete Python 3.7 packages that break during FreeBSD base upgrades.

Part 5: Split routing recovery tools

The third component is for when a major upgrade goes wrong and takes your network with it.

If OPNsense loses LAN connectivity mid-upgrade, you're stuck: you need the internet to download packages, but you need the firewall to reach the internet. The PowerShell scripts in ps1/ solve this for Windows users by setting up split routing:

Wired interface → OPNsense directly (SSH access to resume the upgrade)
WiFi interface → Internet (download packages, read docs)

.\ps1\Enable-SplitRouting-WithModule.ps1

Then SSH into OPNsense and resume:

./opnsense-upgrade.py -x -r

Getting started

Everything is open source: https://github.com/builderall/opnsense-upgrade

opnsense-upgrade/
├── python/    # SSH upgrade script (runs on OPNsense)
├── mcp/       # Claude MCP server (runs on your workstation)
└── ps1/       # Windows split routing recovery tools

MCP server setup (10 minutes):

Create a restricted API user in OPNsense with these privileges:
- System: Firmware — check for updates, trigger upgrades, reboot
- Diagnostics: System Activity — uptime (used to validate reboot status)
- Diagnostics: Backup & Restore — configuration backup access
- Diagnostics: System Health — system health metrics
Generate an API key and store it in mcp/.env
Install dependencies: pip install -r mcp/requirements.txt
Register with Claude Code:

claude mcp add --scope user opnsense -- bash \
  -c "cd ~/projects/opnsense-upgrade/mcp && exec .venv/bin/python -m src.opnsense_mcp.server"

Restart Claude Code and ask: "What version is my OPNsense?"

Full instructions in mcp/SETUP.md.

What's next

The remaining untested scenario is a full major upgrade (26.1 → 26.7) — which requires OPNsense to actually release 26.7. When that happens, this will be the first real test of the auto-resume logic in the Python script.

The broader pattern here — wrapping device management APIs in MCP servers and letting Claude handle the conversational layer — applies well beyond OPNsense. Any device with a REST API and a need for careful, audited operations is a candidate.

MIT licensed. Contributions welcome at https://github.com/builderall/opnsense-upgrade

Forem: builderall