> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Trace Commons

> Optionally contribute redacted agent traces and earn credit

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.

<Info>
  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.
</Info>

***

## Opting In

Check where you stand, then turn it on:

```bash theme={null}
ironclaw traces status
ironclaw traces opt-in --endpoint https://traces.example.com/v1/traces
```

`--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:

```bash theme={null}
ironclaw traces opt-out
```

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](/using/webui).

***

## Contributing a Trace

Preview first. `preview` builds the redacted envelope from a recorded trace file so you
can see exactly what would be sent:

```bash theme={null}
ironclaw traces preview --recorded-trace ./trace.json
```

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:

<CodeGroup>
  ```bash Submit now theme={null}
  ironclaw traces submit \
    --envelope ./envelope.json \
    --endpoint https://traces.example.com/v1/traces
  ```

  ```bash Queue for later theme={null}
  ironclaw traces enqueue --envelope ./envelope.json
  ironclaw traces flush-queue
  ```
</CodeGroup>

`flush-queue` submits every eligible queued envelope using your standing opt-in policy.
Inspect the queue at any time:

```bash theme={null}
ironclaw traces queue-status
```

***

## Reviewing and Withdrawing

```bash theme={null}
ironclaw traces list-submissions
ironclaw traces revoke <submission-id>
```

`revoke` always removes the contribution from your local submission records. To also
request deletion at the ingestion service, pass its revocation endpoint:

```bash theme={null}
ironclaw traces revoke <submission-id> --endpoint https://traces.example.com/v1/revoke
```

The bearer token is read from `IRONCLAW_TRACE_SUBMIT_TOKEN`; override the variable name
with `--bearer-token-env`.

<Warning>
  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.
</Warning>

Check your earned credit and where it came from:

```bash theme={null}
ironclaw traces credit
```

***

## 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.

```bash theme={null}
ironclaw traces enroll-instance --invite 'https://traces.example.com#your-invite-code'
```

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:

```bash theme={null}
ironclaw traces opt-out --user-scope <tenant-id>/<user-id>
```

<Warning>
  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.
</Warning>

***

## Public Profile

A second, separate opt-in publishes a community profile alongside your contributions:

```bash theme={null}
ironclaw traces profile set --handle your-handle --bio "Short description"
ironclaw traces profile withdraw
```

`--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

```bash theme={null}
ironclaw traces ingest-health --endpoint https://traces.example.com
```

Accepts the base URL, the `/health` URL, or the `/v1/traces` URL.

Reports whether an ingestion service is reachable and healthy.