Monitoring

openbroker-monitoring is the optional operations dashboard for OpenBroker automations. Its local server reads ~/.openbroker/automation-audit.sqlite directly, so every standard openbroker auto run process appears without strategy-specific wiring, vault configuration, or webhooks.

The package also retains an optional remote audit observer. Local monitoring does not require remote forwarding.

Install

Install the latest published monitoring package through OpenBroker:

Terminal
openbroker install monitoring

The package is installed globally and exposes the openbroker-monitoring command. The generic installer can also show every supported companion package:

Terminal
openbroker install --list

Direct npm fallback:

Terminal
npm install --global openbroker-monitoring@latest

Operate the dashboard

Run an automation in one terminal:

Terminal
openbroker auto run ./my-automation.ts --id my-auto

Start the dashboard in another terminal:

Terminal
openbroker-monitoring serve --host 127.0.0.1 --port 3001

Open http://127.0.0.1:3001. The dashboard shows run health, account risk, portfolio NAV, exposure, guardrails, decisions, actions, fills, errors, and every metric emitted through api.audit.metric.

Stop the dashboard with Ctrl+C. This only stops the monitoring web server; trading automations continue running. Restart the command after changing configuration or upgrading the package.

Configuration

The defaults work for a standard OpenBroker installation:

Env varCLI flagPurpose
OB_MONITOR_HOST--hostBind address. Default: 127.0.0.1.
OB_MONITOR_PORT--portDashboard port. Default: 3001.
OPENBROKER_AUDIT_DB_PATH--dbAudit database. Default: ~/.openbroker/automation-audit.sqlite.

Example with every option explicit:

Terminal
openbroker-monitoring serve \
  --host 127.0.0.1 \
  --port 3001 \
  --db ~/.openbroker/automation-audit.sqlite

Keep the default loopback host unless you intentionally want to expose the dashboard to another machine and have added appropriate network access controls.

Upgrade

Re-run the install command to fetch the latest release, then restart the monitoring process:

Terminal
openbroker install monitoring
openbroker-monitoring serve --host 127.0.0.1 --port 3001

Pin or roll back to an exact release with --tag:

Terminal
openbroker install monitoring --tag 1.4.2

Preview the npm operation without changing anything:

Terminal
openbroker install monitoring --dry

Remote forwarding (optional)

When installed alongside OpenBroker, the package is also convention-loaded as an audit observer. Remote forwarding activates only when a dashboard URL and vault address are configured:

Env varPurpose
OB_DASHBOARD_URLRemote dashboard base URL.
OB_DASHBOARD_API_KEYOptional bearer token.
HYPERSTABLE_VAULT_ADDRESS or VAULTVault address used in remote endpoint paths.

If these variables are absent, remote forwarding stays disabled while the local dashboard continues to work.

What gets forwarded

The optional observer forwards audit notes, metrics, and audited write-method results. Requests use a five-second timeout and observer failures do not stop the trading loop.

  • api.audit.record(kind, payload) → POST {url}/api/vaults/{vault}/audit/notes
  • api.audit.metric(name, value, tags) → POST {url}/api/vaults/{vault}/audit/metrics
  • audited client writes → POST {url}/api/vaults/{vault}/agent/logs

Programmatic use

Embed the local server when another Node.js process owns its lifecycle:

monitor.ts
import { startMonitoringServer } from 'openbroker-monitoring/server';
 
const monitor = await startMonitoringServer({
  host: '127.0.0.1',
  port: 3001,
});
 
console.log(monitor.url);

For remote observer integration, import the default createDashboardObserver factory from openbroker-monitoring and pass the resulting observer to the OpenBroker automation runtime.

OpenClaw PluginReference