What is MomoBot?

MomoBot is an enterprise-grade cloud-controlled automation platform that lets you remotely manage, monitor, and automate tasks across any number of devices — servers, desktops, laptops, IoT hardware, and edge devices — from a single secure control plane.

Organizations use MomoBot to eliminate manual device management, reduce response time to system events, and maintain a complete auditable record of every automated action across their entire fleet.

What MomoBot Does

Key Features

Cloud Control Plane

• Centralized REST API for all agent, task, workflow, and schedule management
• Real-time WebSocket gateway for live agent status and task results
• Visual workflow builder with n8n-compatible DAG format
• Role-based access control (RBAC) — user and admin roles
• Policy engine that validates every task before dispatch
• Immutable audit log of every sensitive action
• Cron-based scheduler for automated recurring tasks
• Webhook ingress from Slack and Microsoft Teams
• AI-assisted workflow and task generation

Agent Capabilities

• Runs as a system service on any supported OS
• Connects outbound only — no inbound ports needed on agent hosts
• Automatic heartbeat and reconnect with exponential backoff
• Receives, validates, and executes tasks from the control plane
• Returns structured results: stdout, stderr, exit code, metadata
• Queued task delivery — tasks dispatched on reconnect after downtime

Security

• bcrypt password hashing (cost factor 12) + JWT access tokens
• Optional TOTP two-factor authentication
• 256-bit random agent API keys and secret keys
• HMAC-SHA256 signature verification on all webhook payloads
• 5-minute replay protection on all webhook integrations
• Automatic redaction of secrets in all log output
• Shell command deny-list (blocks destructive, exfiltration, and fork-bomb patterns)
• File path restrictions (blocks credential files, kernel interfaces, and traversal)
• Rate limiting on all API and auth endpoints

Quick Start

Get MomoBot running in under 5 minutes with this step-by-step guide.

cd momobot-platform
npm run install:all
cp server/.env.example server/.env
# Edit server/.env and set JWT_SECRET and JWT_REFRESH_SECRET
npm run dev

cd momobot-platform/momobot-agent
cp .env.example .env
# Edit .env:
#   SERVER_URL=http://localhost:4000
#   AGENT_API_KEY=bot_xxx
#   AGENT_SECRET_KEY=xxx
npm start

Architecture

MomoBot uses a cloud-first, thin-agent architecture. All intelligence, policy, scheduling, and orchestration lives in the cloud control plane. Agents on managed devices are lightweight and do nothing independently — they only act when the control plane tells them to.

Data Flow

Cloud Control Plane

The MomoBot server is the central hub of the platform. Every agent connects to it, every task flows through it, and every action is recorded by it.

Dashboard

The MomoBot dashboard is a React web application that provides complete visibility and control over your automation fleet.

Dashboard Capabilities

Agent Model

A MomoBot agent is a lightweight daemon installed on each managed device. Agents connect outbound to the control plane — no inbound firewall ports are ever needed.

How Agents Work

• Secure connection: Agents connect to the server over WebSocket with TLS (wss:// in production).
• API key authentication: Each agent authenticates using its unique 256-bit API key and secret key pair.
• Heartbeat: Agents send heartbeat pings every 30 seconds. The server marks agents offline if pings stop.
• Automatic reconnect: If the connection drops, agents reconnect automatically with exponential backoff up to a configurable maximum.
• Task execution: When a task arrives, the agent validates it, executes it, and sends back structured results.
• Offline safety: Tasks dispatched while the agent is offline are queued on the server and delivered the moment the agent reconnects.

Agent Isolation

• Each agent has unique credentials scoped to one owner user
• Regular users can only manage and task their own agents
• Admins can view and manage all agents across all users
• Agents can be individually enabled or disabled without deleting them
• Secret keys are generated once and shown once — not stored in plaintext

Task Types

MomoBot supports the following task types. Every task is validated by the Policy Engine before it reaches the agent.

Workflow Engine

MomoBot includes a built-in workflow engine for multi-step, conditional automation. Workflows are defined as directed acyclic graphs (DAGs) — a series of tasks connected by directed edges.

What Workflows Do

• Chain multiple tasks across one or more agents into a single automated workflow
• Define conditional branching — different paths depending on task results
• Add approval gates that pause execution until a human approves
• Schedule workflows to run automatically on a cron schedule
• Trigger workflows from the dashboard, Slack, Teams, or the REST API
• View per-execution traces showing the status of every node in the graph
• Export workflows in n8n-compatible JSON format for use with external tools

Workflow Components

AI-Assisted Generation

MomoBot can generate workflow definitions automatically from a natural-language description using the AI integration endpoint. The generated workflow is returned in n8n-compatible JSON format ready for import into the visual workflow builder.

AI Task Creator

The AI Task Creator is an admin tool that combines task configuration with AI analysis to help you build, validate, and execute tasks more confidently.

What the AI Task Creator Provides

• Natural-language task description: Describe what you want to accomplish in plain English. The AI suggests the correct task type, parameters, and configuration.
• Risk assessment: Before execution, the AI flags potential risks, destructive operations, or edge cases.
• Step-by-step plan: See a human-readable breakdown of exactly what the task will do on the target device.
• Time estimate: Understand roughly how long the task will take to complete.
• Command preview: Review the exact command that will be sent to the agent before you confirm execution.
• Workflow diagram: Visualize even single tasks as a start-to-finish flow diagram before running them.

Supported AI Models

Scheduler

The MomoBot scheduler lets you run tasks or entire workflows on a recurring cron-based schedule — no manual triggering required.

Scheduler Features

• Schedule any task type to run at any cron interval (minutes, hours, daily, weekly)
• Schedule full workflows to run automatically
• View all active schedules and their next run time in the dashboard
• Enable or disable individual schedules without deleting them
• All scheduled runs are logged in the audit trail with full task output

Slack Integration

MomoBot integrates with Slack so your team can trigger automation directly from any Slack channel using slash commands.

Setup

1. Create a Slack app in your workspace via the Slack API dashboard.
2. Add a Slash Command pointing to your MomoBot server at https://your-server/webhooks/slack.
3. Copy the Signing Secret from your Slack app settings.
4. Add it to your server environment file:

   SLACK_SIGNING_SECRET=your-signing-secret-here

5. Add the app to your Slack workspace.

Using Slack Commands

Once configured, anyone in your workspace with access can run:

/momobot run sysinfo on agent-my-laptop
/momobot status
/momobot agents list

Security

• Every incoming Slack request is verified with HMAC-SHA256 using your SLACK_SIGNING_SECRET.
• Requests with timestamps older than 5 minutes are automatically rejected (replay protection).
• Every slash command invocation is recorded in the audit log.

Microsoft Teams Integration

MomoBot integrates with Microsoft Teams so your team can trigger automation by mentioning the MomoBot app in any Teams channel.

Setup

1. In the Microsoft Teams admin center, create an Outgoing Webhook.
2. Set the webhook callback URL to https://your-server/webhooks/teams.
3. Copy the HMAC signing secret (base64-encoded) provided by Teams.
4. Add it to your server environment file:

   TEAMS_WEBHOOK_SECRET=base64encodedSecretHere==

Using Teams Commands

Mention the MomoBot app in any channel to trigger commands:

@MomoBot run diagnostic on server-001
@MomoBot get system info

Security

• Every incoming Teams request is verified with HMAC-SHA256 using your TEAMS_WEBHOOK_SECRET.
• Signature comparison uses timing-safe algorithms to prevent timing attacks.
• Every Teams message that triggers a task is recorded in the audit log.

Email (SMTP)

MomoBot can send email notifications at key points in your automation workflows using any SMTP relay.

What Email Notifications Cover

• Task completion or failure alerts
• Workflow approval request notifications
• Diagnostic report delivery

Configuration

Add SMTP settings to your server environment file:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=alerts@example.com
SMTP_PASS=yourpassword
SMTP_FROM=MomoBot <alerts@example.com>

Webhook Reference

MomoBot exposes webhook endpoints for supported integrations. All endpoints require a valid HMAC signature or return HTTP 401.

Planned Integrations

Security Overview

MomoBot is built with a defense-in-depth security model. Multiple independent layers of protection ensure that even if one layer is bypassed, others prevent harm.

Authentication

User Authentication

• Passwords hashed with bcrypt at cost factor 12 — industry-standard one-way hashing
• JWT access tokens with 15-minute expiry for all API requests
• Refresh tokens with 7-day expiry, stored in the database and revocable
• Optional TOTP two-factor authentication (HMAC-based time-based OTP via speakeasy)
• Sessions tracked in the database — individual sessions can be revoked

Agent Authentication

• Each agent is issued a unique API key and secret key, each generated with 256-bit entropy
• Agent credentials are transmitted only over TLS WebSocket in production
• Deactivated agents (is_active = false) are immediately blocked from connecting
• Secret keys are shown once at creation and not stored in plaintext

Generating Secure Secrets

# Generate JWT secrets (run once during setup)
openssl rand -base64 64   # For JWT_SECRET
openssl rand -base64 64   # For JWT_REFRESH_SECRET

Roles & Permissions

MomoBot uses a two-role access control system.

Policy Engine

The policy engine is the core safety gate of MomoBot. Every task — regardless of how it was triggered — passes through the policy engine before being dispatched to any agent. If a task fails policy validation, it is rejected and never reaches the device.

Task Type Allowlist

Only the following task types are permitted. Any other type is automatically blocked:

system_info  |  shell  |  script  |  file_read  |  file_write  |  process_list  |  screenshot  |  custom

Shell Command Deny Patterns

The following shell patterns are blocked regardless of who requests them:

File Path Restrictions

The following paths cannot be read or written by any task:

Timeout Limits

• Minimum timeout: 1 second — prevents degenerate zero-timeout tasks
• Maximum timeout: 5 minutes — prevents runaway long-running tasks

Audit Logging

MomoBot maintains an immutable audit log of every sensitive action. Every entry includes who performed the action, what they did, which resource was affected, from which IP, and whether it succeeded.

What Is Logged

Audit Log Fields

Automatic Secret Redaction

The following fields are automatically redacted before any audit log write, ensuring secrets never appear in logs:

password | password_hash | secret | secretKey | apiKey | api_key | token | refreshToken | access_token

Rate Limiting

MomoBot applies rate limiting to all API and authentication endpoints to protect against abuse and brute-force attacks.

Agent Installation — Linux

MomoBot agents run as systemd services on Linux. The automated installer sets everything up for you.

Prerequisites

• Node.js 18 or later
• An active MomoBot server (cloud or self-hosted)
• Agent credentials (API key + Secret key) from the MomoBot dashboard

Automated Install

sudo bash deploy/installers/linux/install.sh
sudo nano /etc/momobot/agent.env   # Add SERVER_URL, AGENT_API_KEY, AGENT_SECRET_KEY
sudo systemctl start momobot-agent
sudo journalctl -u momobot-agent -f   # View logs

Manual Install

cd momobot-platform/momobot-agent
npm install --omit=dev
cp .env.example .env
# Edit .env and fill in your credentials

sudo cp ../../../deploy/installers/linux/momobot-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable momobot-agent
sudo systemctl start momobot-agent
sudo systemctl status momobot-agent

Verifying Connection

After starting the agent, open the MomoBot dashboard and navigate to Settings → Agents → [Your Agent Name]. The agent status should show as Online within 30 seconds.

Troubleshooting

Agent Installation — Windows

The MomoBot agent runs as a Windows service via a PowerShell installer.

Prerequisites

• Node.js 18 or later (x64)
• PowerShell with RemoteSigned execution policy
• An active MomoBot server and agent credentials from the dashboard

Install

# Run as Administrator in PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
.\deploy\installers\windows\install.ps1

# Edit configuration
notepad C:\MomoBot\config\agent.env

# Start the service
Start-Service MomoBotAgent
Get-Service MomoBotAgent

Agent Configuration File

Edit C:\MomoBot\config\agent.env and set:

SERVER_URL=https://your-momobot-server.com
AGENT_API_KEY=bot_xxxxxxxxxxxx
AGENT_SECRET_KEY=xxxxxxxxxxxxxxxxxxxx

Agent Installation — macOS

The MomoBot agent runs as a launchd service on macOS, supporting both Intel and Apple Silicon.

Prerequisites

• Node.js 18 or later
• An active MomoBot server and agent credentials from the dashboard

Install

bash deploy/installers/macos/install.sh

# Edit configuration with your credentials
nano ~/.momobot-agent/agent.env

# Load and start the agent service
launchctl load ~/Library/LaunchAgents/com.momobot.agent.plist
launchctl start com.momobot.agent

# View logs
tail -f ~/Library/Logs/momobot-agent.log

Platform Support

Agent Installation — IoT / Raspberry Pi

MomoBot agents run on ARM Linux devices including Raspberry Pi 3/4, NVIDIA Jetson Nano, and industrial edge devices.

Supported Devices

• Raspberry Pi 4 (ARM64) — Recommended
• Raspberry Pi 3 (ARM32)
• NVIDIA Jetson Nano (ARM64)
• Generic ARM Linux devices
• Industrial Linux edge devices

Install Node.js on Raspberry Pi

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs git
node --version   # Should show v18.x.x

Install the Agent

cd momobot-platform/momobot-agent
npm install --omit=dev

sudo mkdir -p /etc/momobot
cp .env.example /etc/momobot/agent.env
sudo nano /etc/momobot/agent.env
# Set SERVER_URL, AGENT_API_KEY, AGENT_SECRET_KEY

sudo cp ../../../deploy/installers/linux/momobot-agent.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable momobot-agent
sudo systemctl start momobot-agent

Low-Memory Optimization

On resource-constrained devices, add these options to /etc/momobot/agent.env:

NODE_OPTIONS=--max-old-space-size=128
HEARTBEAT_INTERVAL=60000
MAX_RECONNECT_ATTEMPTS=50

Network Requirements

• Agents connect outbound only — no inbound ports required on the device
• Requires outbound TCP to your MomoBot server (typically port 443 for wss://)
• UDP is not used for cloud transport

Security on Edge Devices

• Agent credentials stored in /etc/momobot/agent.env with mode 600, owned by the momobot user
• Systemd service runs as a dedicated momobot user — not root
• TLS validation enabled by default (do not disable in production)

Local Development

Run the full MomoBot platform locally for development and testing.

Prerequisites

• Node.js 18 or later
• npm 8 or later

Setup

cd momobot-platform

# Install all dependencies (server + client + agent)
npm run install:all

# Configure the server
cp server/.env.example server/.env
# Edit server/.env — set at minimum:
#   JWT_SECRET=<strong random string, min 32 chars>
#   JWT_REFRESH_SECRET=<strong random string, min 32 chars>

# Configure the agent
cp momobot-agent/.env.example momobot-agent/.env
# Edit momobot-agent/.env — set:
#   SERVER_URL=http://localhost:4000
#   AGENT_API_KEY=<from dashboard after setup>
#   AGENT_SECRET_KEY=<from dashboard after setup>

# Start server + client
npm run dev

Then in a separate terminal:

cd momobot-platform/momobot-agent
npm start

Dashboard: http://localhost:3000 — Server API: http://localhost:4000

Docker Deployment

Docker Compose is the recommended way to deploy MomoBot for production on a single host.

Start with Docker Compose

cd momobot-platform

# Build and start all services in the background
docker-compose up -d

# View running containers and logs
docker-compose ps
docker-compose logs -f

# Stop all services
docker-compose down

What Docker Compose Provides

• MomoBot server on port 4000
• React client on port 3000
• Persistent SQLite data volume (data survives container restarts)

Kubernetes Deployment

For high-availability production deployments, MomoBot can be deployed to Kubernetes.

Deploy to Kubernetes

# Create namespace
kubectl create namespace momobot

# Create secrets (customize values first)
kubectl create secret generic momobot-secrets \
  --from-literal=JWT_SECRET="$(openssl rand -base64 64)" \
  --from-literal=JWT_REFRESH_SECRET="$(openssl rand -base64 64)" \
  -n momobot

# Apply all manifests
kubectl apply -f momobot-platform/k8s/ -n momobot

# Check status
kubectl get all -n momobot

AWS / Terraform Deployment

MomoBot includes Terraform configurations for a fully-managed AWS deployment.

What Terraform Provisions

• ECS Fargate cluster for the MomoBot server
• S3 + CloudFront for the React client
• RDS PostgreSQL for the production database
• Application Load Balancer for HTTPS termination
• AWS Secrets Manager for credentials storage

Deploy

cd momobot-platform/terraform

terraform init
terraform plan -var="environment=production"
terraform apply -var="environment=production"

Enterprise Architecture

For enterprise scale, MomoBot supports horizontal scaling across multiple server instances:

• Multiple server instances behind an AWS ALB or nginx load balancer
• Shared PostgreSQL database across all instances
• Redis adapter for Socket.IO shared WebSocket state
• ALB sticky sessions required for WebSocket connections

Environment Variables

Server Environment Variables

Agent Environment Variables

Operations Guide

Health Check

The server exposes a health check endpoint that requires no authentication:

GET https://your-server/health

# Response:
# {"status":"ok","timestamp":"2024-01-15T10:30:00.000Z","version":"1.0.0"}

Rotating Agent Credentials

To rotate an agent's API key and secret key (e.g., after a suspected compromise):

# Via the API
curl -X POST /api/agents/{agent-id}/regenerate-key \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN"

# Via the dashboard
# Agents → [Agent Name] → Rotate Key

The agent's new credentials must be updated in its .env file and the service restarted.

Disabling an Agent

To temporarily prevent an agent from connecting without deleting it:

# Via the dashboard: Agents → [Agent Name] → Disable
# Via the API:
curl -X PATCH /api/agents/{agent-id} \
  -H "Authorization: Bearer $YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

Viewing Audit Logs

# Via dashboard: Admin → Audit Logs

# Via SQLite (local/dev only)
sqlite3 momobot-platform/server/data/momobot.db \
  "SELECT * FROM audit_logs ORDER BY created_at DESC LIMIT 50;"

Production Security Checklist

• ✅ Set strong JWT_SECRET and JWT_REFRESH_SECRET (use openssl rand -base64 64)
• ✅ Enable TLS via a reverse proxy (nginx, Caddy, or AWS ALB)
• ✅ Set CLIENT_URL to your actual dashboard domain
• ✅ Set NODE_ENV=production
• ✅ Mount the SQLite data directory to persistent storage
• ✅ Block direct access to port 4000 via firewall
• ✅ Rotate agent credentials periodically
• ✅ Review audit logs regularly
• ✅ Set up log shipping to your SIEM

Scaling

Monitoring

Recommended Observability Stack

Key Metrics to Monitor

• Agent online/offline status — alert when any critical agent goes offline
• Task failure rate — alert when failure rate exceeds threshold
• Task queue depth — alert when tasks are not being dispatched
• API error rate — alert on 5xx response rates
• Audit log write rate — alert on anomalous spikes indicating unusual activity

Backup & Recovery

SQLite Backup (Single-Instance)

# Create a dated backup
sqlite3 momobot-platform/server/data/momobot.db \
  ".backup 'backup/momobot-$(date +%Y%m%d).db'"

PostgreSQL Backup (Multi-Instance)

# Dump and compress the database
pg_dump momobot | gzip > backup/momobot-$(date +%Y%m%d).sql.gz

# Restore
gunzip -c backup/momobot-20240115.sql.gz | psql momobot

Recovery Checklist

• Store backups off-site or in object storage (S3, GCS, Azure Blob)
• Test restore procedures before you need them
• Back up your .env files securely (AWS Secrets Manager, HashiCorp Vault, or Kubernetes Secrets) — they are not included in database backups
• Agent credentials do not need to be backed up separately — they are stored in the database and can be rotated if lost

API Reference

All REST API endpoints require a valid JWT Bearer token in the Authorization header, unless otherwise noted.

Authentication Endpoints

Agent Endpoints

Task Endpoints

Webhook Endpoints

System Endpoints

Known Limitations

Roadmap

Recently Shipped

• Industrial Automation module — SCADA-grade control with OPC-UA, Modbus, MQTT connectors
• Industrial Scenario Lab — 8 built-in physical-world scenarios with replay and learning signals
• Multi-Agent Control Pipeline — 7-role Planner→Safety→Simulation→Supervisor→Executor→Verifier→Optimizer
• Digital-Twin Simulation — risk scoring before hardware dispatch
• Predictive Maintenance — health scoring and anomaly-trend monitoring

Near Term

• PostgreSQL support as a first-class database option
• mTLS (Mutual TLS) agent authentication
• Google Chat integration
• WhatsApp Business integration
• Inbound email trigger parsing (email → task)

Medium Term

• Organization / team model (multi-tenant beyond per-user scoping)
• Redis adapter for multi-instance WebSocket (Socket.IO)
• ML-powered anomaly detection in the industrial telemetry pipeline (rule-based z-score and range detection already ships; ML-powered pattern recognition is planned)
• Agent local policy enforcement file (per-device allowlist)

Long Term

• Full n8n embedding for visual workflow building
• HSM-backed agent key storage
• OpenTelemetry integration for distributed tracing
• Agent auto-update mechanism

Industrial Automation & Control

MomoBot Industrial is a SCADA-grade extension that brings the platform's cloud control plane and thin-agent model to manufacturing floors, energy facilities, logistics networks, and any safety-critical operational-technology (OT) environment.

Unlike generic IT automation, industrial operations require cryptographically verified commands, hardware-aware safety rules, digital-twin validation before execution, and full operator-approval workflows for high-risk actions. MomoBot Industrial provides all of these out of the box.

Key Capabilities

Data Model Overview

Multi-Agent Control Pipeline

Every industrial command is processed by a deterministic pipeline of seven specialized agent roles before it is dispatched to hardware.

Pipeline Roles

Operator Approval Flow

When the Supervisor sets requires_approval = True, the command is held in pending_approval state. An authorized operator calls POST /v1/industrial/commands/{id}/approve or POST /v1/industrial/commands/{id}/reject. Only after approval does the Executor run.

OT Protocol Connectors

Connectors bridge the MomoBot control plane and physical OT devices. All connectors implement the same IndustrialConnector base interface.

Available Connectors

Connector Interface

class IndustrialConnector:
    def get_asset_status(self) -> dict: ...
    def send_command(self, action: str, parameters: dict) -> dict: ...
    def read_telemetry(self, tags: list[str]) -> list[dict]: ...
    def health_check(self) -> bool: ...

Adding a Custom Connector

1. Create a new file in modules/industrial/connectors/.
2. Subclass IndustrialConnector from base.py and implement all four methods.
3. Register it in connectors/__init__.py by adding an entry to _REGISTRY.
4. No changes to the router, pipeline, or any other module are required.

Safety Policy Engine

The Safety Policy Engine evaluates threshold-based rules against live telemetry or command parameters before any control action is dispatched. It is stage 2 of the multi-agent pipeline and can veto execution entirely.

Rule Structure

[
  {
    "tag": "temperature",
    "operator": "gt",
    "threshold": 90.0,
    "action": "emergency_stop",
    "description": "Motor temperature critical limit"
  },
  {
    "tag": "temperature",
    "operator": "gt",
    "threshold": 75.0,
    "action": "warn",
    "description": "Motor temperature high warning"
  }
]

Supported Operators

Action Severity Tiers

Telemetry Pipeline

The telemetry pipeline normalizes raw readings from any connector protocol into a uniform NormalizedReading, applies severity classification, and detects statistical anomalies.

Severity Classification

Anomaly Detection Methods

• Z-score: flags a reading when it deviates more than N standard deviations from a rolling sample mean.
• Range check: flags a reading outside a configured absolute [min, max] range.

Ingestion API

POST /v1/industrial/telemetry/ingest
{
  "machine_id": "uuid",
  "tenant_id": "tenant-1",
  "readings": [
    {"tag": "temperature", "value": 87.5, "unit": "C"},
    {"tag": "speed",       "value": 1450,  "unit": "rpm"},
    {"tag": "vibration",   "value": 0.12,  "unit": "mm/s"}
  ]
}

Predictive Maintenance

The maintenance advisor computes machine health scores from recent telemetry and generates maintenance recommendations, designed as a clean hook for future ML integration.

Health Score Bands

Machine Health API

GET /v1/industrial/machines/{machine_id}/health?tenant_id=tenant-1

# Response
{
  "machine_id": "uuid",
  "health_score": 0.67,
  "status": "degraded",
  "anomaly_fraction": 0.08,
  "recommendations": [
    "Schedule lubrication inspection.",
    "Check bearing temperature."
  ],
  "sample_count": 100
}

Digital-Twin Simulation

Before any high-risk action reaches hardware, the simulator runs a stateless dry-run that applies the proposed command to an in-memory copy of machine state and evaluates safety rules on the predicted post-action outcome.

How It Works

1. Snapshot — take a deep copy of the current machine state.
2. Apply effect — run the registered action handler on the copy.
3. Evaluate safety — run the safety policy engine against the predicted state.
4. Score risk — produce a 0–1 risk score based on the worst safety action triggered.
5. Return result — SimulationResult includes outcome, risk_score, predicted_state, and safety_violations.

Built-in Action Effects

Risk Score Mapping

Scenario Lab

The Scenario Lab provides a library of built-in physical-world scenarios for end-to-end testing and operator training, each covering a realistic industrial failure mode or safety-critical event.

Built-in Scenarios

Scenario Lifecycle

1. Seed — POST /v1/industrial/scenarios/seed-builtins loads all built-in scenarios.
2. List / Get — GET /v1/industrial/scenarios or fetch by ID.
3. Run — POST /v1/industrial/scenarios/{id}/run executes the scenario.
4. Results — GET /v1/industrial/scenarios/runs/{run_id}/results retrieves step results and incidents.
5. Replay — POST /v1/industrial/scenarios/runs/{run_id}/replay reproduces a past run deterministically.
6. Feedback — PUT /v1/industrial/scenarios/runs/{run_id}/feedback for operator notes.
7. Learning Signals — GET /v1/industrial/scenarios/learning-signals exports structured outcomes for ML pipelines.

Industrial API Reference

All industrial endpoints live under /v1/industrial. Mutating operations require the X-Operator-Token header. Read-only operations accept operator or viewer tokens.

Site & Facility Management

Machine Management

Telemetry

Safety Policies

Commands & Approvals

Incidents & Maintenance

Scenario Lab