Heartbeat protocol

Every few seconds a worker posts a complete process snapshot to one authenticated endpoint. Core records the snapshot and returns the latest desired state and command token. The response travels on the same connection; Core never calls the worker.

POST {coreUrl}/api/v1/workers/heartbeat
Authorization: Bearer <worker-token>

Spring Boot

synapsys:
  core-url: ${SYNAPSYS_CORE_URL}
  core-token: ${SYNAPSYS_CORE_TOKEN}
  heartbeat-interval: 5s

The starter builds, sends, and applies the heartbeat automatically.

Node.js

const synapsys = new Synapsys({
  workerName: 'billing-api',
  heartbeatInterval: '5s',
});
synapsys.start();

The SDK reads SYNAPSYS_CORE_URL and SYNAPSYS_CORE_TOKEN by default.

Raw API

{
  "workerName": "billing-api",
  "framework": "unknown",
  "host": "worker-01",
  "heartbeatInterval": 5,
  "processes": [
    {
      "name": "nightly-sync",
      "type": "endless",
      "currentState": "running",
      "ackToken": 7,
      "runId": 1788012345678901234
    }
  ],
  "logs": []
}

See the implementation guide for the complete request and response behaviour.

Commands use tokens

Comparing only desired and current state would replay a slow stop command on every heartbeat. Instead, Core increments desiredToken whenever an operator issues a command. The worker applies it exactly once:

if desiredToken > ackToken:
    apply desiredState
    ackToken = desiredToken

Advance the acknowledgement only after handling succeeds. A failed handler leaves the token pending so Core can redeliver it.

caution

desiredState: idle means “no outstanding command,” never “stop.” A stop command is stopping.

State and logs travel together

The request reports every process, including idle ones. It can also include stdout and stderr lines captured since the previous successful heartbeat. Each line belongs to a process and run. If delivery fails, official libraries keep the lines for a later retry.

Failure is isolated

An unavailable Core does not stop user work. The worker keeps running and retries. A malformed process or log entry is skipped individually when possible so valid siblings and pending commands can still be processed.

Next: execution states and security and connectivity.