Skip to main content

Run with Node.js

Run pfSense Actions directly with Node.js for development, or on a host you manage yourself, without Docker.

Requirements

  • Node.js 24 — The API workspace requires Node.js 24, and the repository pins npm 11.18.0.
  • Repository checkout — Commands run from the root of the pfSense Actions repository.
  • Prepared pfSense — SSH turned on and an account ready, as described in Prepare pfSense.

Install Dependencies

bash
npm install

Configure the Environment File

Copy the sample file. Every value in it is optional, so you can leave it as it is.

bash
cp apps/api/.env.sample apps/api/.env
  • DATA_DIRECTORY defaults to .data in the folder the process starts in, which is apps/api for the npm scripts.
  • PORT defaults to 22603, and the log shows a warning when it's unset.
  • On the first start, pfSense Actions generates an encryption key and saves it as keys/installation.key in the data directory. If that file goes missing, pfSense Actions makes a new key and removes the saved pfSense password or private key, the authenticator app, and every notification destination's secret fields, as described in Backup and Recovery.
  • The PFSENSE_* values are deprecated bootstrap values. Leave them empty to set everything up in the operations console.

warning

A source run listens on every network interface, as the Compose setup does. Because the listener serves plain HTTP, it's recommended to block the port with a host firewall or reach it only through a reverse proxy.

Run in Development

bash
npm run dev --workspace pfsense-actions-app-api

This starts two processes, and both reload when a source file changes.

  • API — Runs the source with tsx watch on port 22603, loads apps/api/.env, and sets NODE_ENV to development.
  • Console — Serves the console with Vite at http://localhost:5174/admin/ and passes its API calls to port 22603.

Build and Run in Production

bash
npm run build --workspace pfsense-actions-app-api
npm run prod --workspace pfsense-actions-app-api

build compiles the API into apps/api/build and the console into apps/api/build/admin. prod runs node build/index.js with NODE_ENV set to production, and it doesn't read apps/api/.env.

Set the variables in the process environment instead, for example through your service manager.

Create the Administrator Account

On the first start, the output shows a setup code, such as WARN Setup code: ABCDE-FGHJK-LMNPQ. Open the console, which is http://localhost:22603/admin/ after a build or http://localhost:5174/admin/ in development, and create the account as described in Install with Docker.

Deploy the controller