Running Pulse

Runtime inputs, database expectations, and what the stock Pulse shell can and cannot run.

On this page
  1. Runtime Inputs
  2. Start The Shell
  3. What Pulse Records

Running Pulse

Pulse is the durable runtime for compiled circuits. It stores task definitions, runs, stage state, events, checkpoints, signals, and recovery metadata in Postgres.

Runtime Inputs

A Pulse process needs:

InputCLI or sourcePurpose
Postgres connection--db-host, --db-port, --db-user, --db-name, --db-password-fileStores task definitions, runs, checkpoints, signals, and event logs.
Lease owner--lease-ownerIdentifies the logical Pulse instance that owns active work.
JWT signing secret--jwt-secret-fileMints runner tokens for host calls.
Service credential--service-credential-fileAuthenticates internal Pulse-to-host actions.
Task registryHaskell value passed to runPulseMaps task kinds to Haskell executors.
Host API URL--api-urlEndpoint Pulse calls when a task runner needs host-owned side effects.
Hot-loadable workflow input--workflow-dirOptional directory containing hot-loadable .cr workflows.

The stock cortex-pulse binary supplies an empty task registry. Use it to inspect runtime configuration and health wiring; use a consumer-bound binary for real task execution.

Start The Shell

The executable requires a JWT secret file. Database password and service credential files are optional at the CLI level, but real deployments should provide them through files or equivalent secret mounts.

printf 'dev-jwt-secret' > /tmp/cortex-jwt-secret

nix run .#cortex-pulse -- \
  --db-host localhost \
  --db-port 5432 \
  --db-user cortex \
  --db-name cortex \
  --jwt-secret-file /tmp/cortex-jwt-secret \
  --health-port 9090

For a useful run, replace this shell with a binary that calls Cortex.Pulse.runPulse with a non-empty registry.

What Pulse Records

Pulse is intentionally observable. A run leaves behind:

  • current graph state
  • stage attempts
  • checkpoint envelopes
  • run events
  • signal waits and deliveries
  • final outcome

Use Pulse schema, events, and signals for exact storage and event semantics.