CLI: observe

kairos observe launches a live terminal dashboard that runs a fly-by-wire session and displays real-time telemetry.

Usage

kairos observe \
  --scenario <scenario-id> \
  --artifact <artifact.json> \
  --policy <policy.json> \
  [options]

Flags

Required

Flag	Description
`--scenario`	Scenario ID to simulate
`--artifact`	Path to calibration artifact JSON
`--policy`	Path to deployment policy JSON

Optional

Flag	Default	Description
`--manifest`	Embedded	Path to scenario manifest (uses embedded scenarios if omitted)
`--events`	None	Path to EDMS event script JSON
`--license`	`~/.kairos/license.key`	Path to license file
`--seed`	From scenario	Seed override
`--tick-rate`	`200`	Simulation tick interval in milliseconds (50 to 2000)
`--max-ticks`	Unlimited	Maximum number of ticks to step
`--alerts`	Off	Enable acoustic alerts on threshold breach
`--alert-threshold`	`0.8`	Criticality threshold for acoustic alerts
`--markers`	`auto`	Chart marker style: `braille`, `halfblock`, or `auto`
`--export-dir`	None	Directory for snapshot exports (enables `S` keybinding)
`--sentinel`	Off	Enable Sentinel assessment panel
`--hitl`	Off	Activate HITL operator mode
`--coordinator-url`	`http://127.0.0.1:8787`	Coordinator service URL
`--operator-key-id`	None	Operator key ID. Required with `--hitl`

Examples

Basic observation

kairos observe \
  --scenario axelrod-tournament \
  --artifact artifact.json \
  --policy policy.json

Full featured

kairos observe \
  --scenario axelrod-tournament \
  --artifact artifact.json \
  --policy policy.json \
  --tick-rate 200 \
  --alerts \
  --alert-threshold 0.75 \
  --sentinel \
  --export-dir /tmp/snapshots

Dashboard Features

Tabbed Actor Selection

Multi-actor scenarios show one tab per actor. Switch actors with number keys (1 to 9) or Tab and Shift+Tab.

Gauges

Real-time gauges display:

Severity: Magnitude of detected instability
Imminence: How soon the instability will manifest
Risk: Combined risk metric (inertia and optimized variants)
Criticality: Overall system criticality
Gamma Floor: The Gamma floor of the loaded deployment

Predictive Radar Chart

The chart shows current telemetry, recent history, and projected risk movement when projection data is available.

Sentinel Assessment Panel

--sentinel enables this panel. The panel displays a rule-based structured assessment:

Risk level: NOMINAL, ELEVATED, or CRITICAL
Steps-to-impact urgency
Path divergence analysis
Upcoming events list

Physics Log

This panel is an immutable scrolling log of engine events, decisions, and state transitions.

Snapshot Export

When --export-dir is set, press s or S to export the current dashboard state as a JSON snapshot.

Keyboard Shortcuts

Key	Action
`q`, `Q`, or `Ctrl+C`	Quit
`Space`	Pause or resume simulation
`Tab`	Select next actor (not in HITL mode)
`Shift+Tab`	Select previous actor (not in HITL mode)
`1` to `9`	Select actor by index (not in HITL mode)
`s` or `S`	Export snapshot (when `--export-dir` is set)

With --hitl, these keys act on the coordinator’s request list:

Key	Action
`Up`, `Down`	Select the previous or next request. The dashboard switches to that request’s actor.
`r` or `R`	Refresh the request list from the coordinator
`Enter`	Show or hide the details of the selected request
`a` or `A`	Approve the selected request (asks for confirmation)
`d` or `D`	Deny the selected request (asks for confirmation)
`y` or `Y`	Confirm the approval or denial
`n`, `N`, or `Esc`	Cancel the confirmation