Experimental Cloud telemetry

The feature covers three independent streams:

• native Claude Code traces and structured logs;
• native Codex traces and structured logs;
• traces from the Ratel SDK runtime hosted by the daemon.

They use one daemon-owned loopback relay and Cloud credential. Ratel Local does not merge or correlate their trace ids.

Enable the daemon-wide gate

For a new installation:

RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local setup

Setup copies the enabled flag into a new macOS launchd or Linux systemd service. A plain restart does not rewrite an existing service definition. Enable an existing service by reinstalling it:

ratel-local daemon uninstall
RATEL_FEATURE_CLOUD_TELEMETRY=1 ratel-local daemon install

To return to stable default behavior, reinstall without the environment assignment:

ratel-local daemon uninstall
ratel-local daemon install

These lifecycle commands preserve Ratel configuration and saved Cloud settings. Saved credentials never enable the feature by themselves.

Configure Ratel Cloud

Open ratel-local daemon open, then use Settings → Ratel Cloud. Enter the trace endpoint and an rtl_... API key. The daemon stores them in ~/.ratel/cloud-traces.json with user-only permissions.

The authenticated UI returns only the endpoint and whether a key exists. It never reads the saved key back to the browser or CLI. Native agent configuration contains only the daemon's loopback route, never the Cloud key.

Sign in to Ratel Cloud, then create a key in Settings. Enter it through the CLI's masked prompt or the UI password field; do not put it in project configuration, agent configuration, command history, or chat.

Inspect or change native exporters

Check status before changing an agent:

ratel-local traces status
ratel-local traces status --agent codex --json

Enable the safest level explicitly for one or both hosts:

ratel-local traces enable --agent claude-code --agent codex
ratel-local traces disable --agent codex

Plain enable selects Redacted.

All enhanced levels can contain sensitive material. Interactive flows show a warning and ask for consent. Non-interactive content-bearing setup must be fully explicit:

ratel-local traces enable --agent claude-code --level full-content \
  --confirm-content --yes

Ratel-managed Claude levels always set raw API body capture off. Codex Tool activity may include output snippets even when prompt logging is off.

If status reports a conflicting exporter, Ratel Local does not replace it by default. Interactive overwrite warns that no backup is retained. Automation requires both --overwrite and --yes.

Setup automation

Interactive setup offers tracing only when the feature gate is enabled. Plain setup --yes always skips it.

RATEL_FEATURE_CLOUD_TELEMETRY=1 \
  ratel-local setup --yes --traces --agent claude-code --agent codex

--overwrite-traces is available only with --traces and should be used only for a known conflicting exporter.

Privacy-safe relay behavior

The daemon accepts OTLP/HTTP protobuf only on loopback and forwards the payload bytes unchanged over HTTPS with the daemon-held credential.

It does not decode, filter, enrich, join, or persist a retry queue for native payloads. Cloud failures return an error to the exporter. Invalid Cloud settings or telemetry provider initialization fail open: the daemon UI, MCP endpoint, and Local gateway remain available.

When the gate is off, the relay routes and mutation controls are unavailable. An unset flag, 0, or any value other than 1 keeps all experimental Cloud behavior off.

Local telemetry remains separate

The JSONL stream used by the Claude Code statusline stays on the machine and has its own retention controls. See Statusline & local telemetry.

Next steps