Quick start

This walkthrough uses command mode on a supported Linux host and a plaintext HTTP/1.1 application. Replace ./my-app with the application you want to supervise.

Check the host

chronicle doctor

Fix reported platform, cgroup, BTF, capability, or embedded-program issues before recording. doctor does not mutate the host.

Record behavior

chronicle record --name checkout -- ./my-app

Chronicle attaches capture first, then starts the application. Recording stops when the application exits, you press Ctrl+C, or an explicit --duration expires. While it runs, send representative requests from another terminal.

Without an explicit --duration, recording continues until the application exits or is stopped. Per epoch, the physical WAL ceiling is 4 GiB; a parent recording has no total-WAL cap.

Caution

The application must be reachable on a non-loopback address while recording. Command-mode replay starts a supervised copy on loopback and refuses to target the exact recorded destination.

Find the recording

chronicle list
chronicle inspect checkout

Recordings can be addressed by latest, rec_<uuid>, a bare UUID, or an exact name. inspect summarizes endpoints, operations, loss warnings, and replay eligibility without printing captured bodies or arbitrary header values.

Replay into a fresh copy

chronicle replay checkout -- ./my-app

Command mode plans before spawning the target, discovers one owned loopback listener, and replays only after target-independent policy checks pass. It automatically grants execution and read effects for the owned listener; writes and other effects stay denied unless explicitly authorized.

For an already-running application, use explicit target mode only with a loopback IP literal and all required gates:

chronicle replay checkout \
  --target http://127.0.0.1:8080 \
  --allow-host 127.0.0.1 \
  --allow-read \
  --execute

Add --allow-write only when the recording and target are prepared for write effects. Chronicle never uses the recorded production destination as a fallback.

Inspect machine-readable results

All public commands accept the global format option:

chronicle --format json list
chronicle --format json inspect checkout
chronicle --format json replay checkout -- ./my-app

JSON output is rendered after the bounded operation completes. Use it for tooling; keep human output for interactive diagnosis.