aiopnsense

What it is and what it does

aiopnsense is an async Python client for OPNsense, a firewall and router platform. It abstracts the OPNsense REST API behind a single async client object, OPNsenseClient, so you can query router state and trigger actions programmatically without building HTTP requests by hand. The library covers system information, firmware management, interface and hardware telemetry, diagnostics, DHCP and ARP tables, firewall and NAT rules, service control, SMART queries, Unbound blocklists, VPN status, and other operations.

The package depends on aiohttp for async HTTP, awesomeversion for version handling, and python-dateutil for timestamp parsing. It requires OPNsense Firmware 25.1 or later; firmware 26.1.1 or later is recommended because earlier versions return empty data for Firewall and NAT methods. The library is actively maintained and was extracted from the hass-opnsense Home Assistant integration, where it serves as the primary external dependency.

Use it for:

• Monitor router health and interface metrics from a Python application without writing raw HTTP calls.
• Automate firewall rule or NAT rule management in response to application events.
• Query DHCP leases and ARP tables to track network device state programmatically.
• Control VPN instances (OpenVPN, WireGuard) or trigger service restarts from a centralized management tool.
• Integrate OPNsense telemetry (CPU, memory, temperature, traffic) into a monitoring or alerting system.
• Fetch firmware version and update status to plan maintenance windows.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

An async Python client library that wraps OPNsense REST endpoints, allowing applications to query router state and trigger supported OPNsense actions without manually building HTTP requests.

Yes, if you need to programmatically interact with OPNsense and are running firmware 25.1 or later. The library is actively maintained, has low install friction, permissive licensing, and no known vulnerabilities. The async design and broad endpoint coverage make it suitable for integration into monitoring, automation, and Home Assistant deployments. Verify that your OPNsense firmware version meets the minimum requirement and that the endpoints you need are supported.

Install

aiopnsense on PyPI

pip install aiopnsense

uv add aiopnsense

poetry add aiopnsense

Installing aiopnsense

Before you install

Low install friction with a pure-Python wheel. Active maintenance: released 6 days ago with a recent commit on 2026-08-10. Depends on three common async libraries (aiohttp, awesomeversion, python-dateutil), all well-established.

License in practice

Apache-2.0 is permissive, allowing commercial and private use with minimal restrictions—suitable for most deployment contexts.

Quickstart

pip install aiopnsense

from aiopnsense import OPNsenseClient
import aiohttp

async with aiohttp.ClientSession() as session:
    client = OPNsenseClient(session, host, key, secret)
    system_info = await client.system_info()

Requires OPNsense Firmware >= 25.1; Firmware >= 26.1.1 recommended for full Firewall and NAT method support.

Verify before relying

• Whether the library's coverage of OPNsense endpoints is complete or if some actions require manual API calls.
• Performance characteristics when querying large datasets (e.g., many firewall rules or ARP table entries).
• Whether error handling and retry logic are built in for transient network failures.

Package facts

Evidence: aiopnsense-1.1.7-py3-none-any.whl

Tags

More Networking packages