Skip to content

Hall Monitor

Hall Monitor is the Tauri v2 desktop application for monitoring a running Hall API. It shows enrolled workers, live routing decisions, and governance alerts at a glance.

Platforms: macOS, Linux, Windows.

Download: pyhall.dev/tools

First-Time Setup

On first launch, Hall Monitor walks you through a brief setup sequence:

  1. Passphrase prompt — enter a passphrase to protect local app state.
  2. Setup wizard — the wizard copies the hall scaffold command to your clipboard so you can enroll your first worker from the terminal. Follow the on-screen steps.
  3. Main app — after setup completes, the main dashboard loads.

Authentication

Hall Monitor uses GitHub OAuth for login. The JWT issued on successful login is held in memory for the session only — it is never written to disk.

If you close and reopen Hall Monitor, you will be asked to authenticate again.

Namespace Management

After logging in, Hall Monitor displays your registered namespaces from the pyhall.dev registry. You can view namespace details and manage enrollment from the UI.

Running a Local Hall API

Terminal window
pip install pyhall-wcp flask
python -m hall_api.server
# [hall-api] PyHall API v0.3.0 starting on http://127.0.0.1:8765

The server listens on http://localhost:8765 by default. Point Hall Monitor at this URL.

Environment variables:

VariableDefaultDescription
HALL_API_PORT8765Port to listen on.
HALL_API_HOST127.0.0.1Host to bind.
HALL_DB_PATHhall.dbSQLite database path.

Connecting to a Remote Hall API via SSH Tunnel

If your Hall API is running on a remote server, use an SSH tunnel to access it securely without exposing it to the internet.

Terminal window
ssh -L 8765:localhost:8765 user@your-server

Then point Hall Monitor at http://localhost:8765. Traffic is forwarded through the SSH connection.

The Six Screens

Hall Monitor has six screens, accessible via the sidebar.

Hall Status

The main dashboard. Shows the health of the connected Hall API and summary metrics:

  • Hall version and connection status
  • Workers enrolled
  • Total decisions / decisions today
  • Denials today
  • Last updated timestamp

Live Feed

A real-time stream of routing decisions, newest first. Each row shows:

  • Timestamp
  • Capability ID
  • Tenant ID
  • Environment
  • Outcome (allowed / denied)
  • Selected worker
  • Blast score

Decisions update on each poll interval.

Crew on Books

The worker registry — all enrolled workers with their details:

  • Worker ID and species ID
  • Capabilities handled
  • Risk tier
  • Enrollment timestamp
  • Status

Alerts

Governance alerts from the Hall, newest first. Alerts are raised for events like worker code hash mismatches (DENY_WORKER_TAMPERED), controls violations, and other governance failures.

Each alert shows:

  • Timestamp
  • Level (warning / critical)
  • Code
  • Message
  • Affected worker and capability (if applicable)

Enroll Worker

A form to enroll a new worker directly from the UI. Submits to the POST /enroll endpoint. Required fields:

  • Worker ID
  • Worker Species ID
  • Capabilities (comma-separated)
  • Risk Tier
  • Artifact Hash

The form computes the artifact hash on the client when a record JSON is pasted.

Config

Connection configuration for Hall Monitor:

  • Hall API URL — the base URL of your Hall API (e.g., http://localhost:8765)
  • Poll interval — how often to refresh data (seconds)
  • Notifications — enable/disable desktop notifications for new alerts

Settings are persisted locally in the app.

Poll Behavior

Hall Monitor polls the Hall API on a configurable interval (default: every 5 seconds). It fetches:

  • GET /status — for the Hall Status screen
  • GET /workers — for the Crew on Books screen
  • GET /dispatches?limit=50 — for the Live Feed screen
  • GET /alerts — for the Alerts screen

No WebSocket connection is required. The Hall API is stateless HTTP.