Skip to main content
Trace Commons is an opt-in program for contributing redacted traces of your agent’s runs. Contributions earn credit, and you can withdraw anything you’ve submitted.
Contribution is off by default. Nothing leaves your machine until you explicitly opt in, and every envelope is redacted locally before it is eligible to be sent.

​
Opting In

Check where you stand, then turn it on:
--endpoint is required — there is no default ingestion service. Use the URL given to you by whoever runs the collection you’re contributing to. The bearer token is read from IRONCLAW_TRACE_SUBMIT_TOKEN; override the variable name with --bearer-token-env. To turn it off again:
Bare opt-out is the full off switch — it disables the instance-level policy and your owner scope together. You can also manage participation from Settings → Trace Commons in the web interface.

​
Contributing a Trace

Preview first. preview builds the redacted envelope from a recorded trace file so you can see exactly what would be sent:
The file is a recorded trace produced by IRONCLAW_RECORD_TRACE. Add --output <path> to write the envelope to a file instead of stdout, or --enqueue to preview and queue in one step. Once you’re satisfied, submit it directly or queue it for the next flush:
flush-queue submits every eligible queued envelope using your standing opt-in policy. Inspect the queue at any time:

​
Reviewing and Withdrawing

revoke always removes the contribution from your local submission records. To also request deletion at the ingestion service, pass its revocation endpoint:
The bearer token is read from IRONCLAW_TRACE_SUBMIT_TOKEN; override the variable name with --bearer-token-env.
Without --endpoint, revocation is local only. A copy the ingestion service already accepted is not deleted, and removing your local record does not recall it.
Check your earned credit and where it came from:

​
Instance Enrollment

Operators can enroll an entire deployment with an invite link, so every user without a personal enrollment inherits it. This requires shell access to the instance host.
The invite accepts either https://<host>#<code> or <code>@<host>. Each inherited user is attributed through a salted per-user pseudonym rather than their real identity. To exclude one user from an instance-wide enrollment without disabling it for everyone:
Bare ironclaw traces opt-out on an enrolled instance disables the whole instance enrollment, not just your own participation. Use --user-scope to exclude a single user.

​
Public Profile

A second, separate opt-in publishes a community profile alongside your contributions:
--handle is required: 3–32 characters of ASCII letters, digits, -, or _. --bio is optional and capped at 280 bytes. ironclaw traces profile token mints a short-lived token for the Trace Commons web profile page.

​
Checking the Service

Accepts the base URL, the /health URL, or the /v1/traces URL. Reports whether an ingestion service is reachable and healthy.