Edge Agent Overview

The Haltless edge agent is a lightweight service that runs on-premises to collect sensor data from your industrial equipment and push it to the Haltless cloud.

Why use an edge agent?

Approach	Best for	Pros	Cons
Edge agent (HTTP push)	Most deployments	Works behind firewalls, you control the schedule, supports any data source	Requires local installation
Direct ingestion (cloud polling)	Cloud-reachable OPC-UA/Modbus	No local software needed	Device must be accessible from internet

The edge agent is the recommended approach for most industrial environments because:

• Your machines don't need to be internet-accessible
• Data stays on your network until explicitly pushed
• You can buffer data during connectivity outages
• You have full control over collection frequency and data preprocessing

How it works

  ┌──────────────────────────────┐
  │       Your Plant Network     │
  │                              │
  │  OPC-UA Server ──┐          │
  │  Modbus Device ──┤          │
  │  CSV Export ─────┤          │
  │  Custom Script ──┤          │
  │                  ▼          │
  │           Edge Agent        │
  │        (collects data)      │
  │              │              │
  └──────────────│──────────────┘
                 │ HTTPS
                 ▼
  ┌──────────────────────────────┐
  │     POST /api/v1/ingest     │
  │     (X-API-Key auth)        │
  │                              │
  │      Haltless Cloud          │
  └──────────────────────────────┘

Key concepts

Machine identifier

Every sensor reading must reference a machine identifier , a unique string you assign when registering a machine (e.g., CNC-001, PUMP-A3). The edge agent maps your local device addresses to these identifiers.

Batch ingestion

The agent sends readings in batches via POST /api/v1/ingest. Each batch can contain up to 1,000 readings across multiple machines and metrics. The endpoint returns HTTP 207 with per-reading accept/reject status.

Heartbeat

The agent periodically calls GET /api/v1/agent/heartbeat to confirm connectivity and check subscription status. The response includes a next_check_seconds interval.

curl https://api.haltless.io/api/v1/agent/heartbeat \
  -H "X-API-Key: YOUR_API_KEY"

{
  "status": "active",
  "next_check_seconds": 300
}

If the subscription is inactive, the endpoint returns 402 Payment Required.

Metrics and units

Each reading has a metric_name (e.g., temperature, vibration, pressure) and a unit (e.g., celsius, mm/s, psi). Haltless auto-maps raw tags to standardized metric names using AI-assisted tag mapping.

Next steps

• Installation , install the agent on your edge gateway
• Configuration , configure connection settings and data collection
• Protocols , protocol-specific setup for OPC-UA, Modbus, and HTTP