Connect a Common Measure edge

The hub receives source records from the Common Measure edge (commonmeasure) on each machine. A machine delivers once it is enrolled, and only from project directories an owner has approved for reporting. The operator can also relay a published batch run explicitly; a run belongs to no project and needs no approval. Neither route is configured by default.

A managed edge takes the organisation’s policy from the hub (policy distribution); on any other machine the policy is a file on the machine.

Enrol the machine

A machine enrols in one of two ways. Either the person at the machine runs the install command or connect with no token and approves the code it shows in the hub, or someone signed in mints a token on API keys and the command is run with it. Both make the same enrolment.

Approve a code

On a machine without Common Measure, as the person who works on it, run the install command the enrol card prints first, on API keys or on an empty Fleet evidence, in the project directory whose sessions the hub should see (API keys):

curl -fsSL https://github.com/commonmeasure/commonmeasure/releases/latest/download/install.sh | sh -s -- --connect https://<your hub>

It installs the binary, registers it with every agent host it finds, connects, enrols the directory and relays its first evidence. On a machine that already has the binary, run:

commonmeasure connect https://<your hub> --managed

Either command names the machine to the hub (by default its host name), prints a code such as BCDF-GHJK and the address https://<your hub>/connect, and waits. Open that address signed in to the hub, enter the code and check what the page shows: the machine’s name, the organisation and the member the machine will belong to. A member approves their own machine; an owner picks any member of the organisation. To approve for another organisation, switch to it first. Approve finishes the enrolment on the machine within a few seconds; Deny stops it.

Approve only a code your own terminal shows: an approved machine delivers its evidence into the organisation. The code expires after 15 minutes and works once; a used, denied or expired code is refused with the reason, and running the command again prints a new one. This route needs an edge release that enrols by code; an older one asks for --token.

Paste a token

Sign in and open API keys. An owner enrols a machine for any member under Enrol an edge; a member enrols their own under Enrol this machine. Beneath the command with no token, enter a name for the machine, one that tells you whose it is, and choose Mint enrolment token. The name labels its keys and groups its sessions in the fleet view. The page prints two commands with the token in them. On a machine without Common Measure, run the first in the project directory whose sessions the hub should see; it does what the install command without a token does, with no code to approve (API keys):

curl -fsSL https://github.com/commonmeasure/commonmeasure/releases/latest/download/install.sh | sh -s -- --connect https://<your hub> --token et_…

On a machine that already has the binary, run the second:

commonmeasure connect https://<your hub> --token et_… --managed

Run one of them on the machine, as the person who works on it, within 15 minutes. The token works once. This is the route for an owner enrolling someone else’s machine without being at it.

Until the command runs, the token is listed under Enrolment tokens awaiting exchange and can be cancelled. An expired or cancelled token is refused; mint another.

What either route does

The command reports the organisation it enrolled in, the key id the hub assigned and the result of a first delivery, then the policy signer it pinned and the result of a first policy sync.

The edge mints its signing key and keeps the private half on the machine; the hub registers the public half under the organisation and issues the ingest key the relay delivers under, which connect stores in ~/.commonmeasure/relay.json without printing it.

After enrolment the machine appears twice on the keys page, both times under the name you gave: as an ingest key, which delivers, and as an edge key, which signs its fetches. API keys says what each does and the bot identity what publishers see.

Take the organisation’s policy from the hub

--managed makes the machine take the organisation’s policy from the hub: it pins the hub’s policy signer in ~/.commonmeasure/deployment.json and makes a first policy sync, which reports accepted (revision N). A new organisation has revision 1, { "policy_mode": "observe" }, from its creation, so a machine connected straight afterwards takes that revision; an owner edits the policy on Policy. A machine whose organisation has no published revision still enrols and pins the signer; it reports that it is waiting for a revision and keeps its local policy, and commonmeasure policy sync takes the policy once an owner publishes one. Any other synchronisation failure fails the command.

commonmeasure policy sync checks the envelope’s signature against the pinned signer, validates the policy through the edge’s ordinary loader and replaces policy.json, or keeps the last accepted policy when any check fails. Policy distribution covers what the signer is and what the edge checks.

Enrol a project from your agent

A machine delivers only from project directories approved for reporting. After connecting the machine once, invoke /commonmeasure:enrol (Claude Code plugin) or $commonmeasure-enrol (Codex), or ask your agent to enrol this project; with commonmeasure install claude the MCP server offers context_enrol instead. You can also run commonmeasure enrol --name "<project>" --reporting hub --include-history in the project directory. The agent shows the actual directory, edge and applied policy, and asks for a project name and local recording or hub reporting.

Who approves depends on whose machine it is:

• An owner’s own machine. The request is approved when it is made, and recorded as self-approved by that owner. Once the edge has fetched its approvals, commonmeasure enrol --sync shows "reporting": "permitted" without a visit to Project reporting.
• A member’s machine, including one an owner enrolled for a member with an enrolment token minted for them, and a machine enrolled to no member. The request waits for an owner. enrol answers "reporting": "approval_pending".

Owners review requests on Project reporting, where each project shows its Edge, approval state and, once approved, either “Self-approved (owner)” or the approving owner. Project identity expands its ID and local binding; reporting scope and retention consequences appear beside Approve reporting or Revoke reporting. No folder path reaches the hub; confirm the project name with its operator before approving. Any owner can revoke a project, self-approved or not; repeating the same enrol command does not undo the revocation. On an owner’s own machine, commonmeasure enrol --remove followed by enrolling again makes a new request, which is approved as it is made. A project pending when its member becomes an owner stays pending until an owner approves it or it is removed and enrolled again. An approval stays when the owner who gave it is made a member.

After approval, commonmeasure enrol --sync shows "reporting": "permitted". Reporting covers the selected directory and its descendants, including existing eligible evidence; related Git worktrees are enrolled separately. Confidential exclusions and source restrictions in the policy still apply.

A reporting approval expires within 24 hours. Each relay run renews it from the hub before it projects anything, so an edge that reaches the hub needs no further step. An edge that cannot reach the hub cannot renew it, and withholds evidence until it can. Evidence withheld while approval was revoked or expired stays on the machine and is sent once after approval returns. commonmeasure enrol --remove stops reporting from the directory and keeps its evidence and the machine’s connection. Evidence already delivered stays at the hub.

What arrives and what does not

What arrives is the Content Telemetry projection of each witnessed crossing in an approved directory: the source address, the content hash and estimated token count of what was grounded, the licence the source declared, the time the crossing happened, the supplier and the host tool, under a session id and the edge’s key id. A count of the session’s refused crossings arrives with a session that delivers at least one event.

What stays on the machine: prompts, answers, page content, the addresses and reasons of refused crossings, crossings to private addresses or named internal sources, fetches that failed or were answered outside 2xx, the engagement name, spend and quotes, and the edge’s private signing key. History reconstructed with commonmeasure import from transcripts of work done before Common Measure was installed never leaves the machine.

Enrolment can deliver sessions recorded before it: the relay applies the policy and approvals in force to each session’s recorded working directory. A session recorded before the machine enrolled carries no key id, so its events arrive under the agent id commonmeasure. Review what an approval covers before approving it.

commonmeasure relay --dry-run prints the events and source hosts that would leave, without sending anything. Add --policy <file> to forecast a draft policy instead of the one in force.

A delivery that fails stays on the machine and is sent again on the next run; a delivery that arrives twice is counted once.

Or paste a key

Enrolment is the intended route. If a machine cannot run connect, mint a key with the Telemetry ingest preset instead and, on the machine, either pass it on the command line:

commonmeasure relay --receiver https://<your hub>/api/v1/telemetry --api-key ak_…

or write it once into ~/.commonmeasure/relay.json:

{ "receiver": "https://<your hub>/api/v1/telemetry", "api_key": "ak_…" }

Give the address as shown; the relay adds /events itself. A machine connected this way delivers but has no edge key, so publishers cannot verify its fetches, and its sessions show no member in the fleet view.

Leave the hub

commonmeasure disconnect revokes the machine’s edge key and ingest key at the hub when it can reach it, and removes the relay configuration, the private key, the enrolment record and deployment.json from the machine either way. The machine keeps its policy file and returns to local mode. Edge keys shows the key as revoked by the edge. If the hub could not be reached, an owner revokes both keys on API keys. The hub records the disconnect under the machine’s edge identity, naming both credential ids. If it cannot save that record, the revocations are rolled back.

Change the edge’s organisation

Switching organisation in the hub changes the view; it does not move an enrolled edge. Before re-enrolling an existing edge, confirm the destination organisation, its published policy, the member who will own the edge and the projects its owners will approve.

Keep the previous organisation’s local records, delivery queue and credentials separate from the new enrolment. Connecting can deliver previously recorded eligible sessions, so do not point an existing queue at a new organisation. Prepare separate state and a recovery plan before exchanging the new organisation’s enrolment token. Receipts already at the hub stay with the organisation that received them.

A reporting approval from the old organisation does not authorise delivery to the new one. After re-enrolling, check a permitted fetch and its receipt in the destination organisation, and a policy refusal in the edge’s record.

For a hosted edge, coordinate its Hosted edge URL and user sign-in as well. An origin belongs to one organisation. Removing or replacing its registration ends its OAuth grants and outstanding authorisation codes; adding it back restores none. Existing access tokens can remain valid for up to an hour. Connected clients has the revocation controls.