Overview
Give scripts and home-automation tools a small set of pfSense actions without sharing your firewall login or a remote shell.
What Is pfSense Actions?
pfSense Actions is a small self-hosted controller that sits between your automation and one pfSense firewall. It signs in to the firewall over SSH, runs one fixed operation per request, and reports the result.
Why Use pfSense Actions?
- Keeps the pfSense login in one place, so each script holds only its own personal access token.
- Limits each token to named scopes, so a Wake-on-LAN shortcut can't run other actions.
- Answers with a data-minimizing response, so scripts learn the outcome without seeing firewall output.
- Includes an operations console, so you can create and revoke tokens without editing files.
- Sends alerts to ntfy, Telegram, email, and other services when pfSense stops answering or sign-in is locked, so you hear about a problem before a script runs into it.
Supported Actions
| Request | What it does | Scope |
|---|---|---|
GET /api/v1/connectivity | Checks that pfSense Actions can sign in to the firewall. | pfsense:read |
GET /api/v1/system | Returns the firewall's operating system, release, and architecture. | pfsense:read |
POST /api/v1/ping | Asks the firewall to ping one IP address. | reachability:read |
POST /api/v1/wol | Sends a Wake-on-LAN packet from the firewall. | wol:execute |
The same actions also answer at GET /, GET /system, POST /ping, and POST /wol, so scripts written for 1.x keep working.
What It Doesn't Do
- It doesn't run arbitrary commands or open a remote shell for callers.
- It doesn't change, import, or export pfSense configuration.
- It doesn't replace the pfSense web interface, and the operations console can't change firewall settings.
- It manages one target firewall per deployment.
How It Works
- Your script sends a request with its personal access token.
- pfSense Actions checks the token and its scope before contacting the firewall.
- It signs in to the firewall over SSH, runs the commands for that action, and signs out.
- Your script receives a status code and a small JSON result, or three system fields for
GET /api/v1/system.
Requirements at a Glance
- pfSense firewall — SSH turned on and an account that pfSense Actions can sign in with.
- A host to run it — Docker with Compose on an amd64 or arm64 machine, or Node.js 24 to run from source.
- HTTPS — A reverse proxy or another encrypted path for any traffic that leaves the host.
Next Steps
- Prepare pfSense — Turn on SSH and set up an account and key for pfSense Actions.
- Install with Docker — Build and start pfSense Actions with Docker Compose.
- Request Basics — See how clients authenticate and read responses.
- Notifications — Get an alert when pfSense stops answering, sign-in is locked, or an action fails.
- Upgrade from v1.3.1 — Move an existing 1.x deployment to 2.0.0.