Antler

In development

Early access

Docs

Records and chains

A record is one thing an agent did, or one thing the sensor or the server noted, written as one line of JSON, hashed, signed by the device that made it and linked to the record before it. A chain is one device's records in order. The server keeps a chain of its own, of administrative actions, signed with the workspace's audit key.

What each member of a record means is the record reference (docs/reference/records.md, and its JSON twin, which the API serves at /w/<ws>/api/v1/schema). This page specifies what a verifier needs: the line, its canonical encoding, its hash and signature, and the chain.

Vectors: 01-canonical-v1, 02-canonical-v2, 03-record-v1, 04-chain-v1, 05-server-chain-v1, 06-chain-v2, 24-canonical-context-v1, 25-chain-context-v1; for hardware anchors, 19-hardware-chain and 20-hardware-chain-copied.

The envelope

Every record, of every schema version, has these members. They are the only ones a verifier of chains must understand.

MemberTypeMeaning
vintegerThe schema version: 1 or 2 today
idstringThe record's id, a ULID
seqintegerIts position in its chain, from 1, without gaps
tsstringWhen the device made it, by its clock
device_idstringThe chain it belongs to: d_ and 32 hex digits for a device, server for the server's chain
eventstringWhat happened, such as tool.pre
prevstringThe hash of the record at seq - 1; empty for seq 1
hashstringThe record's hash (below)
sigstringThe signature (below), base64

v is the first member of the line and prev, hash, sig the last three, in that order.

A device's id is derived from its key: d_ followed by the first 16 bytes of the SHA-256 of its 32-byte Ed25519 public key, in lower-case hex. A verifier checks that the key it verifies a device chain with derives the chain's device_id. The server chain's id is the fixed string server.

The canonical encoding

The canonical encoding of a record is its line with hash and sig set to the empty string. A record line is always written in this encoding (with hash and sig filled in), so a verifier that holds a line gets the canonical bytes by replacing the values of the last two members with ""; it does not need to parse the record.

The encoding, which a writer must produce and a strict reader may check:

The canonical vectors hold records as a writer might spell them (input_b64), the canonical encoding each must produce (canonical) and that encoding's SHA-256 (sha256).

A line is at most 66,048 bytes (a record of at most 65,536 bytes and its envelope's growth). A reader refuses a longer one.

Hash and signature

A verifier of one record: take the line, form the canonical bytes, hash them, compare with hash exactly, and verify sig over the hash bytes with the chain's public key. 03-record-v1 is one line and its key.

A device chain is signed with the device's key. The server chain is signed with the workspace's audit key (05-server-chain-v1).

A chain

Records of one device_id form a chain when, in order:

A record whose seq is not greater than the one before is a replay; one whose seq skips is a gap; one whose prev names another hash is a fork. Each makes the chain invalid, with one exception.

Declared gaps

A device that lost records says so in the chain. A record with event coverage.gap and extra.reason lost_range declares records lost; its extra holds, as decimal strings, lost_from_seq, lost_to_seq and prev_seq. It may follow a record it does not link to when all of these hold, where last is the record before it in the file:

A verifier lists every declared gap it finds. A coverage.gap record with another extra.reason (such as append_failed, with extra.count) links like any record and is listed too.

Where a chain ends

A chain alone cannot show that its last records were not cut off. Its end is proven by one of:

Without one, a chain that otherwise checks is unproven, never valid.

Records of a newer schema

A verifier written for schema versions up to N may meet a line with a larger v. Such a line still ends with "prev":…,"hash":…,"sig":…} and its hash is still the SHA-256 of the line with hash and sig emptied, so the verifier checks its link, hash and signature exactly as above and does not judge what it says. When everything else checks, the result is "written by a newer schema: upgrade to check it", reported as unreadable input (exit code 2), never as tampering; when anything fails, the result is invalid.

Records the server redacted

When a device sent a secret, the server redacts its stored copy of the record. The log still holds the original hash, so the stored line no longer matches its hash.

Hardware-anchored heartbeats, version 1

Format name: antler-hardware-anchor-v1. Added on 17 November 2026. Nothing above changes: a record keeps its schema version, its canonical encoding, its hash and its Ed25519 signature, and a chain verifies by the rules above whether or not it carries anchors. A verifier written before this section reads an anchored chain as a chain and reports nothing about anchors.

A device's key is a file on its computer. A device in the hardware-backed mode also holds a second key, an ECDSA key on the curve P-256, which its computer's security chip made and keeps (a TPM 2.0 today). That key signs no record. It signs, in each sensor.heartbeat record of the device, a head of the device's chain: the seq and hash of a record before the heartbeat. The signature travels in the heartbeat's extra, so it is inside a record the device key signed.

A record is hardware-anchored when an anchor that holds covers it. What that shows: the key of that chip signed a head that commits to the record, and such a key cannot be copied to another computer, so a copy of the device's files can sign records but anchor none. What it does not show: that the computer was honest. Whoever fully controls it can ask its own chip to sign. That the key lives in a chip is what the device says; nothing in this format proves it to a third party.

The members

A heartbeat states where the device's key is kept and, in the hardware-backed mode, carries the anchor. Both are members of extra.

Member of extraValue
key_protectionhardware when the heartbeat carries an anchor; software when the device key is only a file, or when the chip did not answer. Absent in a heartbeat made before this section
hw_anchorThe anchor (below). Only on a sensor.heartbeat
hw_unavailableWith software, on a device that wanted an anchor: why it has none, a token such as no_chip, no_permission, chip_error, unsupported_platform or key_mismatch (the chip does not hold the key the device's files name)

The anchor

hw_anchor is seven fields joined by colons (0x3A), with no space:

v1:<store>:<key>:<head seq>:<head hash>:<attested>:<signature>
FieldForm
versionThe two characters v1
storeThe key store, as the device names it: 1 to 32 characters of a to z, 0 to 9 and -; tpm2 for a TPM 2.0 on Linux, cng for the TPM through the Windows platform provider
keyThe hardware key's public half: the standard base64, with padding, of 65 bytes, the uncompressed point (0x04, then X and Y, 32 bytes each, big-endian)
head seqThe head's seq, in decimal without a leading zero; 0 for an anchor that covers no record and only names the key
head hashThe head's hash, 64 lower-case hex digits; empty exactly when head seq is 0
attestedThe names of the members of this heartbeat's extra the signature covers, joined by commas (0x2C), in strictly ascending order of their bytes, each 1 to 64 characters of a to z, 0 to 9, ., - and _, at most 32 names, never hw_anchor; may be empty
signatureThe standard base64, with padding, of 64 bytes: the ECDSA signature's r, then s, 32 bytes each, big-endian

One anchor has one spelling: a reader refuses any other (another version, a missing field, a seq with a leading zero, upper-case hex, names out of order, base64 that is not strict). The whole value is at most 4,096 bytes.

What the hardware key signs

The signed message is these lines, each ended by a line feed (0x0A), as UTF-8 bytes:

  1. antler-hardware-anchor-v1
  2. the heartbeat's device_id
  3. the heartbeat's id
  4. the heartbeat's ts
  5. the anchor's store
  6. the anchor's key, as its base64 text
  7. the anchor's head seq, as its text
  8. the anchor's head hash (an empty line when head seq is 0)
  9. then, for each attested name in the anchor's order, <name>=<value>, where the value is that member of the heartbeat's extra

The signature is ECDSA with SHA-256 over those bytes (the chip is given the message's SHA-256), by the anchor's key. Any valid signature is accepted: r and s are each at least 1, and no rule restricts s to the lower half. A real chip's signatures differ on every run; the vectors' were made as RFC 6979 makes them so that the files do not change.

An anchor verifies for a heartbeat when all of these hold:

The attested names are how the heartbeat's posture is signed by the same key: a device attests key_protection and, among others, disk_encrypted, hooks and sensor_version when the heartbeat carries them. Changing an attested value, or removing it, makes the anchor fail. spool_head_seq and spool_head_hash are never attested: the device sets them after the chip signed, and the head the chip signed is in the anchor itself, at or before the spool head.

What a chain's anchors cover

A verifier that has checked a device chain's records (hash, signature, links) works out coverage by going through them in order:

The hardware-anchored records are the union of the covered runs. Every other record is signed by the device key only: the records after the newest confirmed head always are, until a later heartbeat anchors them.

Coverage is a statement about records, never a verdict: anchors that are not counted do not make a chain invalid, and a chain without anchors is as valid as it was. antler-verify prints, for each device chain that says anything about key protection, the anchored runs, the store and the first 12 hex digits of the SHA-256 of the key's 65 bytes, the records after the newest anchored head, and each anchor it did not count.

The vectors

19-hardware-chain is a chain of 13 records with anchors at seq 5 and 10: records 1 to 9 are anchored. 20-hardware-chain-copied continues that chain, after seq 12, the way a copy of the device's files on another computer would: a heartbeat with no anchor, then one anchored by another key. Its records all verify under the device key, and still only records 1 to 9 are anchored. The vector kind hardware-chain is in vectors.md.

The process context and the reach records

Two things a record can say are carried in extra, as keys of schema version 1, so a verifier needs nothing new for them: it hashes the line as written. They are named here because other tools read them.

The process context (antler-process-context-v1) is on the records that ask: session.start, prompt and tool.pre. It is what the operating system said about the programs above the hook when the record was written, whatever the agent's payload claims:

KeyValue
proc_exeThe path of the agent's program: the nearest process above the hook that is not a shell or a command wrapper. For an agent that runs on an interpreter, the interpreter.
proc_signatureembedded, adhoc or none: the code signature that program's file carries, read from the file's own headers (Mach-O, PE). It is not verified. Absent on Linux.
proc_ancestryThe paths of the programs above the hook, its parent first, separated by a line feed (U+000A), at most 8, each at most 400 bytes. A process whose path the system does not give is listed by its short name.
proc_ancestry_moretrue when there were more programs above the last one listed.

Paths only, never arguments or environment. A reader takes the keys as a context only when proc_signature, if present, is one of the three values and comes with proc_exe, proc_ancestry has 1 to 8 lines and none empty, and proc_ancestry_more, if present, is true and comes with proc_ancestry.

A reach record (antler-reach-v1) has the event reach.detected: one thing an AI tool on the device can reach, as the sensor's inventory read it from the tool's own configuration and the usual credential stores. It names no agent session and no account. extra.reach_kind is tool_server, plugin or credential; extra.reach_state is present or, on the one record written when the thing is no longer found, gone; extra.reach_baseline is true on the records of a device's first look. A tool server carries reach_transport, reach_command (the program and, for a package runner, what it runs; no other argument), reach_env (the names of its variables) and its hosts in target.hosts. A credential carries reach_via (file, env or tool_server), cred_type, and, when the sensor could name a single credential, cred_tag with redaction_kid: the keyed tag a version 2 record's creds gives the same credential. No record holds a credential's value. The record reference lists every key.