> For the complete documentation index, see [llms.txt](https://devlab-machines.gitbook.io/devlab-machines-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devlab-machines.gitbook.io/devlab-machines-docs/identity.md).

# Identity & provenance

Machine IDs, pinned snapshots, candidates, signatures, replay receipts, and accepted-generation decisions are inspectable on public machine pages.

Runner bearer credentials are shown once to their owner; private signing keys stay on the runner host and are never sent to the app.

## Signing protocol (v2)

All signed endpoints use `{payload: '<exact JSON string>', signature: '<Base64 Ed25519>'}` plus the bearer runner credential. Runners sign exact UTF-8 payload bytes; the server never parses and reserializes before verifying, so tiny/exponent/negative-zero/Unicode formatting is preserved as signed bytes with no cross-language canonical number conversion.

* `POST /api/public/runner/lease` — unsigned bearer request returning the current immutable job snapshot.
* `heartbeat` — signed jobId + leaseToken. Cancels/expiry return 409.
* `propose` — signed jobId, leaseToken, attemptId, bounded files, and failure feedback. Requires an active owned author lease. Same attempt + bytes are cached; changed bytes are rejected. Pending returns 202; quota exhaustion returns 429.
* `callback` — signed jobId, leaseToken, completed/failed status, and actual evidence/patch/candidateCommit. One transactional receipt commits lease consumption, candidate + two replay jobs or replay evidence, and the event. Identical receipts return the same 200; different, expired, or cancelled receipts return 409.
* `judge` — candidateId; only the author owner or an actual replay participant. Revalidates exact stored signature bytes, parsed evidence fields, and the leased snapshot. Retryable after interruption; never creates a second generation or a conflicting head.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://devlab-machines.gitbook.io/devlab-machines-docs/identity.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.