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

# Redaction

> Keep sensitive payloads, secrets, and private data out of telemetry.

Telemetry is valuable only if teams trust what it captures. The safest strategy is layered: hiloop
omits supported OAuth token exchanges, scrubs high-confidence credential shapes automatically, you
minimize what gets captured, and you verify exported data before sharing it.

Treat the automatic layer as a backstop, not a boundary. It catches the most common accident, which
is a credential riding along in a request hiloop captured. It is not a filter you can push an
untrusted payload through and call the result safe.

## Automatic redaction: what it covers

`hiloop run` wraps your process in a capture proxy. That proxy uses a maintained credential detector
catalog to scrub high-confidence matches out of the copy it captures, before the copy is stored.
Traffic forwarded to the destination is never modified, so redaction cannot change what your agent
sends or receives.

On that path, automatic redaction covers:

* **Captured HTTP request and response bodies.** High-confidence detectors cover common provider,
  source-control, chat, payment, cloud, and private-key credential formats, plus `Bearer` and
  `hil_` tokens. Each match is replaced with `[REDACTED]`. PII and generic high-entropy matching are
  deliberately disabled, so ordinary prose and useful payloads survive untouched.
* **Environment variable values you opted into capturing** with `--env-allowlist`. Each listed
  value runs through the same patterns before it is recorded. Variables you do not list are never
  read.

Managed sandbox capture applies the same recognized-pattern scrubber to the telemetry copy of
supervised entrypoint, exec, and SSH terminal output, plus recorded argv and local attributes. It
does not modify bytes delivered to the terminal or the process itself.

## OAuth token exchanges are metadata-only

For supported Claude Code and Codex login and refresh token endpoints, hiloop does not collect the
request body, response body, or query values at all. It records only query-free exchange metadata,
status, encoding, observed byte counts, and the fact that the payload was omitted. Neighboring model
requests and other traffic to the same providers remain full capture.

This is an exact list of reviewed stock-client endpoints, not a generic OAuth classifier. Unknown
OAuth providers and custom login endpoints remain captured and receive the normal credential scan.
The omission is independent of the redaction toggle because the sensitive bytes never enter capture
storage in the first place.

## What automatic redaction does not cover

This is the part to plan around. Everything below reaches the store as produced, because it does not
pass through the pattern scrubber at any layer.

| Not scrubbed                                                                                                                                                                                | What that means for you                                                                                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Anything produced by something other than the capture proxy: the [OTLP endpoint](/observability/otlp-ingest), the bulk ingest lane, [annotations](/observability/annotations), and the SDKs | These never pass through the capture proxy, so no redaction runs on them. A credential in an OTLP-ingested body or attribute is stored exactly as you sent it. Scrub on your side before you send. |
| OTLP spans your own agent emits, including `gen_ai.*` and `llm.*` prompt and completion attributes                                                                                          | Span attributes are stored verbatim. A prompt, tool argument, or completion carrying a key keeps it.                                                                                               |
| `stdout` and `stderr` from local `hiloop run` or a direct producer                                                                                                                          | Stored as written. Managed sandbox supervision is the exception: its telemetry copy is pattern-scrubbed before normalization. A novel token shape still lands unchanged.                           |
| Request URLs, including the query string                                                                                                                                                    | Outside the supported metadata-only OAuth exchanges, a credential passed as `?api_key=...` is recorded intact. Prefer header-based authentication over query-string credentials.                   |
| Event attributes generally                                                                                                                                                                  | Pattern scrubbing runs on captured bodies and allowlisted environment values only. It does not run over attribute values.                                                                          |
| Anything your workload wrote to disk, an image, a command line, or a snapshot                                                                                                               | Redaction applies to captured telemetry, not to sandbox contents. Managed capture may scrub the recorded argv copy; it cannot hide that argv or credential from other processes in the sandbox.    |

A separate category never reaches the store at all, which is a different mechanism with a different
failure mode:

* **Request and response headers are not captured, apart from `Content-Type` and
  `Content-Encoding`.** No other header value is written to telemetry, so `Authorization`, `Cookie`,
  `X-Api-Key` and friends do not appear there. This is a stronger outcome than scrubbing, but it
  comes from not collecting headers rather than from scanning them.
* **Body bytes past the per-message capture cap are not captured**, so they are neither stored nor
  scanned.
* **Environment variables you did not list** in `--env-allowlist` are never read.

<Warning>
  The most common gap to design around: if you produce telemetry with your own OpenTelemetry SDK and
  send it to the OTLP endpoint, **no hiloop redaction runs on it**. Everything you send is stored.
  Apply your own scrubbing in your instrumentation before export.
</Warning>

## Is redaction on, and can it be turned off?

For `hiloop run` and managed sandbox capture, generic credential-pattern redaction is on by default.
For a local run, `hiloop run --no-redact` disables that generic scan and persists ordinary captured
bodies and explicitly allowlisted environment values verbatim. This can preserve a payload when a
detector mistakes useful data for a credential. Managed sandbox capture does not expose this
opt-out.

`--no-redact` never disables the supported OAuth token-exchange omission. Those exact exchanges
remain metadata-only because their body and query bytes never enter capture storage.

The open-source capture engine also accepts `--no-redact` or `HILOOP_NO_REDACT` when invoked
directly.

## Ingest and export do not add a layer

There is no server-side redaction stage. The gateway stores what it receives, and the
[forward sink and OTLP exporter](/observability/export) re-run no redaction, so forwarded events
carry whatever scrubbing happened at capture and nothing more. If your destination needs a stricter
guarantee than the capture layer provides, apply it in the pipeline you own on the far side.

## What to protect

Avoid capturing or exporting:

* API keys and bearer tokens;
* session cookies;
* private keys;
* passwords;
* cloud credentials;
* package registry tokens;
* customer personal data unless your deployment and agreement allow it;
* proprietary prompts or payloads where policy requires metadata-only capture.

## Capture controls

`hiloop run` captures network traffic, OTLP telemetry, and stdio by default. Use opt-outs when a run
should capture less:

```sh theme={null}
hiloop run --net-capture=off -- claude -p "summarize this repo"
hiloop run --no-otlp -- ./agent.sh
hiloop run --no-redact -- ./agent.sh
```

Use `--net-capture=off` when decrypting the child process's HTTPS traffic is not appropriate. Use
`--no-otlp` when you only want network and stdio capture. Use `--no-redact` only when preserving
ordinary payloads verbatim is more important than the generic credential-pattern backstop.

<Warning>
  `--no-redact` can store credentials present in non-OAuth bodies and allowlisted environment
  values. It does not reduce capture and does not affect the mandatory metadata-only OAuth routes.
</Warning>

Capturing less is the most reliable control on this page. It is the only one that does not depend on
a pattern matching the secret you are worried about.

## Metadata-first patterns

Prefer metadata over full payloads for sensitive workflows:

| Full payload                                     | Safer alternative                                          |
| ------------------------------------------------ | ---------------------------------------------------------- |
| Complete prompt                                  | Prompt hash, template id, token count.                     |
| Tool request body                                | Tool name, status, latency, payload hash.                  |
| Request URL with credentials in the query string | Path and host only, with the credential moved to a header. |
| File contents                                    | Path, size, digest, media type.                            |
| stdout/stderr                                    | Bounded output, hash, artifact id.                         |

## Validate before sharing

Before exporting or sharing telemetry, query a representative slice and scan it for secrets:

```sh theme={null}
hiloop query --run-id "$RUN_ID" --limit 100 --output json > telemetry.json
```

Review payload references, artifact outputs, and any exported files according to your team's data
handling policy. For anything leaving your organization, treat that review as the control, not the
automatic layer.