Installation

This content is for 0.1. Switch to the latest version for up-to-date documentation.

Release installer

Install latest stable Chronicle release:

Chronicle release binaries are supported on Linux x86_64 and aarch64/arm64. The repository installer will resolve the configured stable GitHub Release, select the matching archive, verify SHA256SUMS, and install only after verification succeeds.

curl -fsSL https://raw.githubusercontent.com/r05323028/chronicle/main/install.sh | sh

The default destination is $HOME/.local/bin. The script does not edit shell configuration. If the directory is not on PATH, it prints an export PATH=... instruction.

Verify the binary and host:

chronicle --version
chronicle doctor

doctor is non-destructive. It reports platform, architecture, cgroup v2, BTF, embedded capture programs, attachment, capabilities, WAL/output, protocol, and replay-policy readiness with remediation.

Pin a release

The version may include or omit the leading v:

curl -fsSL https://raw.githubusercontent.com/r05323028/chronicle/main/install.sh \
  | CHRONICLE_VERSION=v0.1.0 sh

Choose an install directory

curl -fsSL https://raw.githubusercontent.com/r05323028/chronicle/main/install.sh \
  | CHRONICLE_INSTALL_DIR=/some/path sh

Manual release installation

Use this path when the installer cannot run:

Download the matching chronicle-<version>-<target>.tar.gz and SHA256SUMS files from a GitHub Release.
Verify the archive before extraction.
Terminal window
```
sha256sum -c SHA256SUMS
```
Extract the archive and put the top-level chronicle binary on PATH.
Run chronicle --version and chronicle doctor.

The release workflow publishes x86_64-unknown-linux-gnu and aarch64-unknown-linux-gnu archives. Do not guess a target name for another platform.

Build from source

The workspace pins its Rust toolchain in rust-toolchain.toml:

git clone https://github.com/r05323028/chronicle
cd chronicle
cargo build --release --locked

Linux builds include the checked-in eBPF capture object. Other platforms build the portable surface: listing, inspection, replay planning and verification, doctor, and fixture recording, without live capture.

Only eBPF pipeline development needs the separate nightly rebuild described in the repository README. Run chronicle doctor after building to see what the current host supports.

Host requirements for live capture

Release binaries target little-endian x86_64 and aarch64/arm64.
The 0.1 release-verified live-capture environment is Ubuntu 24.04 with Linux 6.8 and aarch64.
Other Linux 6.1+ kernels and x86_64 require matching privileged acceptance; binary availability is not runtime proof.
cgroup v2 enabled, BTF available at /sys/kernel/btf/vmlinux, and required eBPF capabilities.
CAP_BPF and CAP_NET_ADMIN for the recording process.
Embedded capture programs present in the binary.

The application must expose plaintext HTTP/1.1 traffic. TLS ciphertext is opaque to the current capture path.