Configuring heartd#

heartd reads one TOML file. Relative paths are resolved against that file. examples/pump-station/heartd.toml is a minimal example, and unknown keys are rejected.

Sections#

| uplink | gateway_url | none | Join this Gateway | | | token_file | required | Token used to join, with scope heart.send | | | extra_ca | none | Extra certificate to trust for the Gateway | | | push_clearance | internal | Highest level sent to the Gateway | | | every_sec | 30 | How often to announce again | | | commands | false | Keep a command channel (API Standard 9.3): the Card is pushed without endpoints, as for a device behind NAT, and heartd long-polls the Gateway's inbox with Prefer: wait. Each command must be signed with [server] gateway_public_key, be for this system, be at most 60 seconds old and new; anything else is dropped unanswered and recorded as security.command.refused. A command runs through the API and the gate as a request from the Gateway would, and its answer goes back as a heart.reply. Needs gateway_public_key | | | poll_wait_sec | 25 (1 to 30) | How long one long poll waits for a command |

Optional modules served by the Core#

Each of these sections offers one module of API Standard 13.1, and adds it to the Card's modules. Without the section the module's operations answer 501. Every store is bounded; the ceiling is given after the default.

Updates follow the SUIT architecture (RFC 9019): a signed manifest describes the payload, and the Core verifies the signature, then the payload's size and SHA-256, before anything is installed. Installing is destructive: a person proves presence with the request, or another person approves it. A manifest file is:

{"manifest": {"name": "station-fw", "version": "3.3.0", "kind": "firmware", "sizeBytes": 524288,
              "sha256": "<hex of the payload>", "payload": "station-3.3.0.bin", "channel": "stable",
              "notes": "Fixes the level sensor", "security": false},
 "signature": "<base64url Ed25519 signature over the RFC 8785 JSON of manifest>"}

payload is a file name in the update source, without ... While the payload downloads the update can be cancelled, and Stop cancels it; once it installs, it cannot.

Schedules run as their author. Each run is a new Action, with scheduleId, that passes the gate as the author at that moment: a destructive run waits for a person, a peer's or AI's run follows the mode and the allowlist as they are then, and while autonomy is stopped no run that changes anything starts. A schedule made by ai, peer or rule is proposed until a person approves it. cron is read in UTC. A lifecycle request with delaySec becomes a schedule.

Privacy. PUT /valve/policy and PUT /ai/policy replace the whole policy. Tightening the Valve policy is write and runs at once for a person; loosening it (a higher llmCeiling, a lower or removed classification, a longer retention) and any change to the AI policy are destructive, so a person proves presence with the request, or another person approves it. The Valve policy starts from the Card's valve and retention_days; once changed through the API it is kept in the state file, until the Card's valve changes. llmCeiling: private needs a granted consent for model-provider. An export or erasure is asked by the person (sub of the token), or by a person with heart.admin who says in authority what they act under. Erasing removes the person's Memory, consents, ratings, receipt links and stored exports, writes [erased] for their identifier in Actions, Rhythm and logs, and keeps only a record with a keyed digest of the identifier.

Keys, owners and trust. POST /security/rotate is destructive. heartd makes a new identity key and a rotation statement signed with the old one, keeps the old key in identity.key.previous and in the key set for 7 days, and sends the statement as Heart-Key-Rotation with every Card, and as heartkeyrotation when it pushes its Card to a Gateway, which then moves its pin. Another rotation within those 7 days answers 409. A claim takes the code from the box, records ownerKey and issuer, and from then on heartd accepts only tokens that key signs: the [auth] key no longer works. A transfer moves that to the new owner at once, and removes presence methods, grants, subscriptions, consents and schedules, and cancels the Actions waiting for approval. A release does the same without naming anyone, and the system is claimable again. A factory reset also erases personal data (Memory, consents, ratings, receipt links, erasure records and every other Action) and removes peers; a decommission does the same, and the system can never be claimed again. Each makes a new claim code (none after a decommission), and on a Basic system a new owner key. Trusting a peer and changing the allowlist pass the gate like any change to authority; a peer's messages stay data. A batch's items each pass every check as if sent alone; an item that needs an Idempotency-Key uses the batch's key with . and its position.

The Reasoning Gateway keeps the owner's instructions in the system prompt and puts every context item and the conversation in marked blocks, escaped so that they cannot close their block. Provider keys are added by heartd only; a provider's error text is never passed on. GET /security/attestation?nonce= answers evidence signed by the identity key.

Model pins. PUT /evolution/pins/{purpose} is destructive; the model is pinned only if regression_command passes, and the Rhythm records evolving.model.adopted or evolving.model.rejected. POST /evolution/rollback (write) returns to the pin before the last change. Pins set under [model] are the starting point.

Secrets never reach a log or a bundle: the values of private and never-share settings, key=value and key: value pairs whose key names a password, secret, token, API key or authorisation, and the word after Bearer are replaced by [redacted] before a line is kept.

[inventory]
probe_every_sec = 30
[[inventory.components]]
id = "controller"
kind = "board"
name = "Pump controller"
[[inventory.components]]
id = "pump"
kind = "actuator"
parent = "controller"
[[inventory.dependencies]]
id = "plc"
kind = "network"
probe = "192.168.1.20:502"

[config]
file = "settings.json"
apply_command = ["/usr/lib/pump/apply-settings"]
[config.settings.flow_target]
type = "integer"
minimum = 0
maximum = 120
default = 40
privacy = "public"
[config.settings.plc_password]
type = "string"
privacy = "never-share"

[telemetry]
log_file = "/var/log/pump/pump.log"
[[telemetry.metrics]]
name = "com.acme.tank.level"
unit = "cm"

[diagnostics]
[diagnostics.tests.self-check]
command = ["/usr/lib/pump/self-check"]
[diagnostics.tests.flush-lines]
command = ["/usr/lib/pump/flush-lines"]
disruptive = true
cancellable = true
timeout_sec = 120

[software]
channel = "stable"
sbom_file = "sbom.spdx.json"
update_source = "/var/lib/pump/updates"
update_keys = ["A6EHv_POEL4dcN0Y50vAmWfk1jCbpQ1fHdyGZBJVMbg"]
install_command = ["/usr/lib/pump/install-update"]
rollback_command = ["/usr/lib/pump/rollback"]
[[software.packages]]
name = "station-fw"
version = "3.2.1"
kind = "firmware"

[artifacts]
max_count = 100
max_total_bytes = 67108864

[schedules]
max = 50
min_interval_sec = 300

[privacy]
consent_required = ["model-provider", "subscriber"]
retention_days = 365

[ai]
providers = ["acme"]
uses = ["explain", "serve"]
monthly_budget_usd = 20.0

[memory]
max_items = 500

[evolving]
suite = "pump-answers"
regression_command = ["/usr/lib/pump/model-regression"]
timeout_sec = 600

[security]
audit_capacity = 5000
secure_boot = true

[platform]
model = "PX-200"
serial = "SN-0042"
power_source = "mains"
clock_source = "ntp"
clock_synced_file = "/run/systemd/timesync/synchronized"

[provisioning]
claim_code_file = "/etc/heartd/claim-code"
local_only = true

[peers]
max = 50

[batch]
max_items = 50

[native]
protocols = ["modbus-tcp"]
targets = ["tcp:127.0.0.1:502:1"]
[[native.protected]]
target = "tcp:127.0.0.1:502:1"
register = 40100

[reasoning_gateway]
ceiling = "internal"
daily_budget_usd = 2.0
[[reasoning_gateway.upstreams]]
name = "main"
provider = "openai"
model = "gpt-4o-mini"
api = "openai"
base_url = "https://api.openai.com/v1"
api_key_env = "OPENAI_API_KEY"
input_usd_per_mtok = 0.15
output_usd_per_mtok = 0.6
[[reasoning_gateway.upstreams]]
name = "backup"
provider = "anthropic"
model = "claude-haiku-4-5"
api = "anthropic"
base_url = "https://api.anthropic.com"
api_key_file = "/etc/heartd/anthropic.key"
input_usd_per_mtok = 1.0
output_usd_per_mtok = 5.0

Host feed#

Write one JSON object per line to host_socket. Each line gets ok, or error with a reason.

{"event": "compressor.started", "severity": "info", "component": "compressor", "summary": "optional"}
{"vital": "errorRate", "value": 0.02}
{"state": "cooling"}
{"phase": "maintenance"}
{"recovered": "compressor"}
{"log": "Compressor started after 3 tries", "severity": "warning", "component": "compressor"}
{"platform": {"power": {"source": "battery", "batteryPct": 64, "lowPower": false}, "network": {"connected": true, "signalDbm": -61}, "clock": {"synced": true, "driftMs": 3}}}

A log line is kept in the telemetry module's log, with secrets removed; without that module it gets error. A platform line updates what GET /platform shows.

Unlike messages from peers, these events can trigger Tending rules, so only the product's own user may open the socket. Names starting circulation., security. or valve. are refused.

Fleet approvals. A fleet command that is not read is approved once at the Gateway, over the fleet digest (the command, the operation, its body, physical, the selector, the sorted target IDs and the rollout). The Gateway then sends each system the operation with a new actionId and a presence of method fleet that it signs for that system. A system with gateway_public_key accepts it as the approval of its own Action only if the signature checks, it is among the targets, the request is exactly the one approved, the approval is at most 300 seconds old, and the approver is not the caller; a physical Action also needs fleet_physical. Its gate, guards and Stop still apply. Every system's request body carries the whole target list, so [server] max_body_bytes bounds the size of a fleet (about 8,000 targets with the default).

Gateway#

heartd gateway <file> reads a different file, shown in examples/gateway/heartd.toml:

To route a system over its Unix socket, place the socket inside socket_dir, set trust_gateway_headers = true and gateway_uid on that system, and add an [uplink] section. To route over TLS, set gateway_public_key on the system instead. A system behind NAT sets [uplink] commands = true and gateway_public_key: the Gateway serves it as pushed, and passes any request it cannot answer from what was pushed to the system's command channel, waiting up to 30 seconds for the answer (504 system-unreachable after that, 501 while the system has not polled in the last 65 seconds).

Security rules (Advisory HEART-2026-001)#

• Tokens must carry aud equal to the system ID (the Gateway's ID for the Gateway). A token with cnf.jkt must come with a DPoP proof. Off the loopback address, unbound tokens are refused with token-not-bound. A token whose act claim names any actor other than a HEART Gateway the issuer marked with "heart_gateway": true is treated as ai and loses heart.approve; a person working through such a Gateway stays human. The Card's level: full needs control in modules, or heartd does not start.
• Approvals carry a passkey assertion over the Action's digest, in presence in the decision body. A person's own destructive or physical request carries it in the request body itself, with the actionId the client chose, on POST, PUT, PATCH or DELETE; without it the request waits for another person, because nobody approves their own Action. Passkeys come from [presence] and from enrolment through the API. The first one may be enrolled through the Unix socket or loopback while none is enrolled.
• Playbooks added through the API are destructive, and only an administrator can adopt one. A Playbook runs only its own capability, and a physical one only if the rule has "physical": true. Rules in rules are treated as adopted by whoever installed the file.
• Receipts are salted. The salt goes to the recipient: receiptSalt to a model, Heart-Receipt-Salt to a Gateway, and the heartreceiptsalt attribute to a webhook. The commitment covers the message without these.
• Joining a Gateway at Connected or Full needs a signed Card, sent automatically by [uplink]. The Gateway pins the key.

Access tokens#

heartd is an OAuth 2.0 resource server. It accepts JWTs signed with EdDSA, from your authorisation server, with these claims:

Tending rules#

{
  "id": "pump-link-lost",
  "enabled": true,
  "status": "adopted",
  "description": "Raise an alert when the pump controller stops answering",
  "when": { "event": "component.failed", "component": "optional", "count": 3, "windowSec": 30 },
  "then": { "raise": { "code": "connectivity.dependency-unreachable", "severity": "error", "summary": "Pump controller is not answering" },
            "capability": "optional_capability", "arguments": {} }
}

A rule runs only if enabled is true and status is adopted (Core Standard 4.3). Writing adopted in this file is the owner's adoption; a rule with no status is proposed and does nothing. Set adoptedPhysical: true to let it run a physical capability. Use a check such as { "signal": "errorRate", "op": ">", "value": 0.1 } in when to watch a metric; it fires each time a new sample makes the check hold. The older forms ({"vital", "above"}, withinSec, a raise string, physical) are still read. A rule's capability must list rule in callers, and it passes the same gate as any other request.

Running as a service#

packaging/heartd.service is a systemd unit that sets CPU and memory ceilings and runs with few privileges.

Reserve the HEART port so Linux never lends it to an outgoing connection:

echo "net.ipv4.ip_local_reserved_ports = 43278" | sudo tee /etc/sysctl.d/99-heart.conf
sudo sysctl --system