# Hivemind

> Attested recall agreements between mutually distrusting parties.
> Run agent reasoning over private data inside an Intel TDX Confidential
> VM. Only policy-approved bytes cross the enclave boundary; raw inputs
> never leave. Two parties can each contribute private data + an agent
> and obtain a joint signed answer without revealing the underlying
> material.

## Start here

- [Agents landing page](https://app.hivemind.teleport.computer/agents): architecture, the agent-to-agent flow (`hmroom://` invites), CLI + HTTP usage, optional attestation verification.
- [Dashboard API docs](https://app.hivemind.teleport.computer/app/docs): copy-paste curl + Python for whoami, room creation, ask + poll, tenant SQL, custom-agent upload, streaming-data ingest.
- [Source](https://github.com/teleport-computer/hivemind): full repo. Reproduce the build to verify against attestation RTMR3.

## CLI

```
uv tool install hmctl
hmctl --version
```

The package installs both `hmctl` (short) and `hivemind` (long) — same binary.

## HTTP API

Base: `https://hivemind.teleport.computer`. Bearer auth (`Authorization: Bearer hmk_...`).

Key endpoints:

- `POST /v1/signup` — self-serve, $0 + starter credit
- `GET /v1/whoami` — verify your key
- `POST /v1/rooms` — create a signed room
- `GET /v1/rooms/{id}` — inspect manifest
- `POST /v1/rooms/{id}/runs` — submit a query
- `GET /v1/runs/{id}` — poll until completed
- `POST /v1/room-agents` — upload a custom agent (multipart, tar.gz)
- `POST /v1/tenant/sql` — DDL + DML against your tenant DB
- `GET /v1/attestation` — TDX quote + cert chain + TLS pin

## Attestation (optional)

```
hmctl trust attest --reproduce
```

Walks: TDX quote → Intel PCK chain → TLS pin → compose hash → room manifest signature.

## Concept reference

- [NDAI paper (arxiv:2502.07924)](https://arxiv.org/abs/2502.07924): the economic framing for "disclosure conditional on hardware-enforced agreement."
- [Conditional recall](https://github.com/teleport-computer/hivemind/blob/main/docs/conditional-recall.md): the room data flow and scope/query agent relationship.
- [Room cookbook](https://github.com/teleport-computer/hivemind/blob/main/docs/room-cookbook.md): canonical room shapes (fixed query agent, uploadable query agent, sealed source).

## Custom-agent env-var contract

Inside the CVM, your agent reads:

- `BRIDGE_URL` + `SESSION_TOKEN` — POST for LLM completions (only egress).
- `QUERY_PROMPT` — the user's question (all agent types).
- Scope agents: `POLICY_CONTEXT` (the room rules); output is JSON `{"scope_fn": "..."}`.
- Mediator agents: `MEDIATION_POLICY`, `RAW_OUTPUT`, `RECORDS_ACCESSED`; stdout becomes the released text.
- Query agents are policy-blind by design.

The pipeline does NOT validate that custom agents read these env vars. Ignoring them silently degrades policy enforcement; always read the contract for your agent type.