aiopnsense

aiopnsense is an async Python client library for OPNsense.

What this library does

aiopnsense wraps supported OPNsense REST endpoints behind a single async client, OPNsenseClient. It is designed for applications that need to query router state or trigger supported OPNsense actions without manually building HTTP requests.

The client currently includes helpers for:

• system information, notices, certificates, CARP, Wake-on-LAN, reboot, and interface reloads
• firmware version checks, update status, and upgrade actions
• interface, gateway, CPU, memory, filesystem, and temperature telemetry
• diagnostics traffic snapshots and live interface traffic stream samples
• DHCP lease and ARP table access
• firewall rules, NAT rules, alias toggling, and state killing
• service status lookup and service start/stop/restart operations
• SMART device listing and per-device SMART detail queries
• Unbound blocklist management
• OpenVPN and WireGuard status plus VPN instance toggling
• vnStat metrics, captive portal vouchers, and speed test data

Requirements

• Requires OPNsense Firmware >= 25.1

• Recommended OPNsense Firmware >= 26.1.1

  • For firmware < 26.1.1, the Firewall and NAT methods will return empty data.

Documentation

• Read the Docs: https://aiopnsense.readthedocs.io

Live test scripts

The scripts/ directory includes live diagnostic helpers for maintainers:

• aiopnsense_dump.py runs supported aiopnsense client endpoints and prints the raw data returned by the library.
• opnsense_api_call.py calls an arbitrary OPNsense API endpoint with a specified method and optional POST payload.

Both scripts read credentials from scripts/aiopnsense.env by default. Copy scripts/aiopnsense.env.example to create your local env file; it is ignored by git. Full CLI reference is generated in the Read the Docs script documentation.

Origin and Purpose

aiopnsense was initially extracted from the hass-opnsense integration. It is primarily for use as an external dependency by Home Assistant for its OPNsense Integration.