OMP Dashboard & Telemetry Blueprint

OMP Dashboard & Telemetry Blueprint #

This blueprint outlines the deployment architecture for the OMP Dashboard and OMP Telemetry (Stats) endpoints, their integration with the local agent environment, and how they are securely exposed.

1. Core Architecture #

The system utilizes two primary user-space applications hosted via systemd user services to expose visualization and management layers for active agents.

  • Pi Agent Dashboard: Serves the UI for managing agents, inspecting sessions, and interacting with the local Pi-AI workspace.
  • OMP Stats Dashboard: A secondary telemetry visualizer running omp stats.

2. Port and Firewall Configuration #

Backend Port Assignments #

  • Pi Dashboard backend is bound to 0.0.0.0:45433 (modified via systemd).
  • OMP Stats backend is bound to :::45434 (modified via systemd).

Nginx Reverse Proxy (Frontend) #

To implement a robust, basic authentication layer without relying on external OAuth providers, Nginx is deployed as a reverse proxy:

  • Nginx listens on the originally intended public ports: 55433 and 55434 with TLS (ssl) enabled.
  • Let’s Encrypt certificates for 0rk.de are bound directly, ensuring credentials are not transmitted in plaintext over the internet.
  • It enforces auth_basic (HTTP Basic Auth) using credentials stored in ~/.nginx_auth/.htpasswd.
  • Nginx proxies the authenticated traffic locally to 127.0.0.1:45433 and 127.0.0.1:45434.
server {
    listen 55433 ssl;
    server_name 0rk.de;
    ssl_certificate /etc/letsencrypt/live/0rk.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/0rk.de/privkey.pem;
    auth_basic "OMP Dashboard Restricted";
    auth_basic_user_file /home/dev/.nginx_auth/.htpasswd;
    ...
}

Because the node and binary backends cannot easily restrict their bind interfaces without compiling, iptables is used to drop external traffic directly hitting the backend ports (45433 and 45434).

sudo iptables -A INPUT -p tcp -m multiport --dports 45433,45434 ! -s 127.0.0.1 -j DROP
sudo ip6tables -A INPUT -p tcp -m multiport --dports 45433,45434 ! -s ::1 -j DROP

This forces all external traffic to go through the authenticated Nginx ports.

3. Systemd User Services #

Services run under the dev user and start on boot via loginctl enable-linger dev.

pi-dashboard.service # 

[Unit]
Description=Pi Agent Dashboard
After=network.target

[Service]
Type=simple
ExecStart=/home/dev/.bun/bin/bun run /home/dev/.omp/plugins/node_modules/@blackbelt-technology/pi-agent-dashboard/packages/server/src/cli.ts --port 45433
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

omp-stats.service # 

[Unit]
Description=OMP Stats Dashboard
After=network.target

[Service]
Type=simple
ExecStart=/home/dev/.local/bin/omp stats --port 45434
Restart=always
RestartSec=3

[Install]
WantedBy=default.target

4. Pi Dashboard Configuration #

The underlying Fastify server of the Pi Dashboard includes an internal Localhost Guard. Since Nginx connects from 127.0.0.1 and passes the original host/IP headers, or if accessing via an external IP previously, the network must be trusted. Configured in ~/.pi/dashboard/config.json:

{
  "port": 45433,
  "trustedNetworks": ["0.0.0.0/0"],
  "cors": {
    "allowedOrigins": [
      "http://0rk.de:55433",
      "http://0rk.de:55434",
      "https://0rk.de:55433",
      "https://0rk.de:55434"
    ]
  },
  "tunnel": { "enabled": false }
}

Note: Although trustedNetworks is wide open (0.0.0.0/0), the Nginx proxy handles all necessary security upstream.

5. The “PI Dashboard Doctor” False Positives #

When inspecting the Pi Dashboard, you may encounter PI Dashboard Doctor warnings complaining about missing pi CLI commands or missing tsx loaders. These are false positives and must be ignored.

Why? The local system utilizes the native OMP Orchestrator. The orchestrator automatically provides the execution engine and bridges the connection over the default WS port (9999). A standalone pi CLI installation is redundant because OMP includes the @blackbelt-technology/pi-dashboard-extension which correctly handles the bridging.

6. Pi-Langfuse Telemetry #

The pi-langfuse extension proxies AI telemetry to Langfuse endpoints. The configuration at ~/.pi/agent/pi-langfuse/config.json correctly points back to the external server at http://95.111.224.175:19030 to aggregate traces and tokens externally. This provides out-of-band monitoring independently of the local dashboard workloads.