Documentation · Set up

Connection modes

When the dashboard, an AI assistant or an incident review needs a live read from your site, it creates a job from a fixed list of read capabilities. Each capability answers one question, such as how many scheduled actions failed in the last hour? or what state is this order in?. The plugin checks a job's parameters before answering, a job cannot carry code, and no capability writes data, runs SQL, PHP or shell commands, or changes a setting. The connection mode decides only how a job reaches the site.

The mode is chosen on the site, in Settings → Operanse, and mirrored in the dashboard's site settings. Operanse can never switch it remotely.

Mode	How a job arrives	Best for
Outbound only (default)	The plugin checks for pending jobs on cron, every minute with a system cron.	Every store. No inbound endpoint exists.
Persistent stream	A process you run on the host holds an outbound connection open, so jobs arrive in seconds.	Hosts where you can run a long-lived process or a cron line.
Direct inbound	Operanse sends a signed request to the plugin's REST route.	Sites where you choose to open an endpoint for faster investigations.

All three run the same closed list of read-only capabilities through the same code path, with the same audit record. Cron polling keeps running as the fallback in every mode.

Outbound only

Nothing to set up. With a system cron the plugin polls every minute; on WordPress's built-in trigger it polls when the site gets a visit, so investigations wait longer on a quiet site.

Persistent stream

Choose Persistent stream in Settings → Operanse, and choose the same mode for the site in the dashboard.
Run wp operanse stream as the web server user under something that restarts it. The process exits on its own after --max-jobs (default 500) or --max-minutes (default 30) so every restart starts fresh, backs off between one and sixty seconds on errors, and stops if its signature is rejected (pair again, and the next restart picks it up).

With systemd:

# /etc/systemd/system/operanse-stream.service
[Unit]
Description=Operanse agent job stream
After=network-online.target

[Service]
User=www-data
Group=www-data
WorkingDirectory=/path/to/wordpress
ExecStart=/usr/local/bin/wp operanse stream --max-minutes=30 --max-jobs=500
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target

Without systemd (Cloudways and most managed hosts), run it from cron under flock, so at most one copy runs and a crashed one is replaced within a minute:

# crontab -e, as the web user (on Cloudways: the application's system user, not root)
* * * * * cd /path/to/wordpress && /usr/bin/flock -n /tmp/operanse-stream.lock /usr/local/bin/wp operanse stream --max-minutes=30 --max-jobs=500 >> /path/outside/web/root/operanse-stream.log 2>&1

Put the lock file and the log outside the web root. If wp is not on the cron PATH, use its full path. The dashboard's connection card shows connected within a minute of the first tick, and not connected (falling back to cron polling) if the process stops. While the stream runs, it also handles the plugin's uploads and heartbeats, so a site whose WP-Cron is broken still reports.

Direct inbound

Choose Direct inbound on both sides. The plugin then registers the REST route operanse/v1/read and accepts only requests signed with the site's pairing key. Add your firewall's or proxy's addresses to the inbound allow-list on the settings page if you want a second check before the signature; behind a reverse proxy, set OPERANSE_TRUSTED_PROXIES so the forwarded address is the one checked. A request that fails either check is refused and counted. The route does not exist in the other two modes.