Pilot digital twin setup

Digital Twin Setup

Deploy 4 agents: sensor-bridge, model-engine, anomaly-detector, and action-planner.

Roles

Role	Hostname	Skills	Purpose
sensor-bridge	<prefix>-sensor-bridge	pilot-stream-data, pilot-metrics, pilot-gossip	Ingests real-time telemetry from physical assets
model-engine	<prefix>-model-engine	pilot-dataset, pilot-task-router, pilot-consensus	Maintains physics model, runs simulations
anomaly-detector	<prefix>-anomaly-detector	pilot-event-filter, pilot-alert, pilot-audit-log	Detects drift between real and predicted behavior
action-planner	<prefix>-action-planner	pilot-webhook-bridge, pilot-cron, pilot-slack-bridge	Schedules maintenance, notifies field teams

Setup Procedure

Step 1: Ask the user which role this agent should play and what prefix to use.

Step 2: Install the skills for the chosen role:

# For sensor-bridge:
clawhub install pilot-stream-data pilot-metrics pilot-gossip
# For model-engine:
clawhub install pilot-dataset pilot-task-router pilot-consensus
# For anomaly-detector:
clawhub install pilot-event-filter pilot-alert pilot-audit-log
# For action-planner:
clawhub install pilot-webhook-bridge pilot-cron pilot-slack-bridge

Step 3: Set the hostname and write the manifest to ~/.pilot/setups/digital-twin.json.

Step 4: Tell the user to initiate handshakes with the peers for their role.

Manifest Templates Per Role

sensor-bridge

{
  "setup": "digital-twin", "role": "sensor-bridge", "role_name": "Sensor Bridge",
  "hostname": "<prefix>-sensor-bridge",
  "skills": {
    "pilot-stream-data": "Ingest real-time sensor telemetry from physical assets.",
    "pilot-metrics": "Track sensor health, sampling rates, and data quality.",
    "pilot-gossip": "Discover and sync with peer sensor bridges."
  },
  "data_flows": [{ "direction": "send", "peer": "<prefix>-model-engine", "port": 1002, "topic": "telemetry", "description": "Unified telemetry stream from physical assets" }],
  "handshakes_needed": ["<prefix>-model-engine"]
}

model-engine

{
  "setup": "digital-twin", "role": "model-engine", "role_name": "Model Engine",
  "hostname": "<prefix>-model-engine",
  "skills": {
    "pilot-dataset": "Store physics model parameters and simulation state.",
    "pilot-task-router": "Route simulation tasks across asset models.",
    "pilot-consensus": "Reconcile model state across redundant engines."
  },
  "data_flows": [
    { "direction": "receive", "peer": "<prefix>-sensor-bridge", "port": 1002, "topic": "telemetry", "description": "Real-time sensor data" },
    { "direction": "send", "peer": "<prefix>-anomaly-detector", "port": 1002, "topic": "prediction", "description": "Expected behavior baselines and drift metrics" }
  ],
  "handshakes_needed": ["<prefix>-sensor-bridge", "<prefix>-anomaly-detector"]
}

anomaly-detector

{
  "setup": "digital-twin", "role": "anomaly-detector", "role_name": "Anomaly Detector",
  "hostname": "<prefix>-anomaly-detector",
  "skills": {
    "pilot-event-filter": "Filter predictions by drift threshold and severity.",
    "pilot-alert": "Emit anomaly alerts for critical deviations.",
    "pilot-audit-log": "Log all detected anomalies with evidence snapshots."
  },
  "data_flows": [
    { "direction": "receive", "peer": "<prefix>-model-engine", "port": 1002, "topic": "prediction", "description": "Model predictions to compare" },
    { "direction": "send", "peer": "<prefix>-action-planner", "port": 1002, "topic": "anomaly-alert", "description": "Anomaly alerts with severity and root cause" }
  ],
  "handshakes_needed": ["<prefix>-model-engine", "<prefix>-action-planner"]
}

action-planner

{
  "setup": "digital-twin", "role": "action-planner", "role_name": "Action Planner",
  "hostname": "<prefix>-action-planner",
  "skills": {
    "pilot-webhook-bridge": "Push maintenance orders to field team systems.",
    "pilot-cron": "Schedule maintenance windows during low-impact periods.",
    "pilot-slack-bridge": "Notify operations teams of recommended interventions."
  },
  "data_flows": [
    { "direction": "receive", "peer": "<prefix>-anomaly-detector", "port": 1002, "topic": "anomaly-alert", "description": "Anomaly alerts to act on" },
    { "direction": "send", "peer": "external", "port": 443, "topic": "maintenance-order", "description": "Work orders to field management systems" }
  ],
  "handshakes_needed": ["<prefix>-anomaly-detector"]
}

Data Flows

• sensor-bridge -> model-engine : real-time telemetry from physical assets (port 1002)
• model-engine -> anomaly-detector : predictions and expected behavior baselines (port 1002)
• anomaly-detector -> action-planner : anomaly alerts with severity and root cause (port 1002)
• action-planner -> external : maintenance orders to field team systems (port 443)

Workflow Example

# On sensor-bridge -- stream telemetry:
pilotctl --json publish <prefix>-model-engine telemetry '{"asset_id":"PUMP-A7","sensors":{"temperature_c":87.3,"vibration_mm_s":4.2}}'
# On model-engine -- send prediction:
pilotctl --json publish <prefix>-anomaly-detector prediction '{"asset_id":"PUMP-A7","drift_pct":{"temperature":6.3,"vibration":50.0}}'
# On anomaly-detector -- alert planner:
pilotctl --json publish <prefix>-action-planner anomaly-alert '{"asset_id":"PUMP-A7","severity":"warning","anomaly_type":"bearing_degradation"}'

Dependencies

Requires pilot-protocol skill, pilotctl binary, clawhub binary, and a running daemon.