Telltale

Install Telltale

Early Development

Start with the Telltale repository, verify the scanner against synthetic fixtures, then move to bounded read-only checks against real session stores only when you understand the privacy boundary.

Get Telltale

Install from the public Telltale repository. This page is a short safety-oriented companion to the Telltale install guide, not a replacement for it.

Open Telltale on GitHub Read install docs

Source material checked for this page

This page summarizes install and validation guidance from the Telltale repository. It does not vendor Telltale code and it does not replace the Telltale install guide.

Artifact Paths

Install guide

docs/install.md

Source for release archive, source build, fixture verification, real-store scan, watch, status, service, and SIEM setup guidance.

Project README

README.md

Source for project scope, quick start, source support status, and repository layout.

Fixture tree

tests/fixtures/session_stores

Synthetic session stores used for safe local verification examples.

Prerequisites

Rust and Cargo are required when building from source.
Local access is required for any real agent session stores you choose to scan.
A SIEM or log shipper is optional; Telltale can write local JSONL first.
Use synthetic fixtures for public demos, docs, screenshots, and validation examples.

Quick install (Linux)

A user-first Linux installer is available. It downloads the latest release archive, verifies it against published SHA256SUMS, and installs both telltale and the adr compatibility command to ~/.local/bin without sudo. It can optionally set up a user-level systemd timer that runs periodic scans as your user. It does not create system accounts or configure SIEM shippers.

Curl install

curl -fsSL https://agentarchaeology.ai/telltale_install.sh | bash

Add --from-source to build with cargo instead of downloading a prebuilt binary. Add --no-timer to skip the systemd timer.

Build from source

Tagged GitHub releases can publish platform-specific telltale-* binary archives. Canonical archives contain the primary telltale binary and the deprecated adr compatibility binary; matching adr-* assets remain exact copies through 0.2.x. Source builds remain supported. When building locally, run the commands from the Telltale repository root.

Source build

git clone https://github.com/Dark-Roast-Cyber/telltale.git
cd telltale
cargo build --release

The primary binary is written to target/release/telltale; target/release/adr remains the compiled compatibility binary.

Compatibility names and scheduled actions

The canonical 0.2.0 installer and archive behavior uses telltale for new commands and timer or task actions. Stable Linux unit names remain adr-scan.service and adr-scan.timer, and the Windows scheduled-task identity remains TelltaleScan. The compiled adr command and adr-* archive aliases remain deprecated compatibility surfaces through 0.2.x; the earliest possible removal is 0.3.0 after at least six months of compatibility and advance notice.

Verify with synthetic fixtures first

Run fixture-backed checks before pointing the scanner at real local session stores. These commands use checked-in synthetic data and avoid writing event output during the scan step.

Fixture-safe verification

cargo run --bin telltale -- scan --once --dry-run --root tests/fixtures/session_stores
cargo run --bin telltale -- rules validate --rules config/rules/tool-call-regex.yaml
cargo test

Use --dry-run for fixture checks. The Telltale documentation reserves --allow-fixtures for intentional synthetic writes in CI or local development.

Move to real stores carefully

A first real-store check should be read-only and bounded. The Telltale install guide recommends using the directory that contains supported session-store roots, usually $HOME on a single-user workstation, but the first check should filter by client and cap the number of scanned sources.

Bounded real-store health check

cargo run --bin telltale -- scan --once --dry-run --root "$HOME" --client codex --max-sources 5

This example is read-only because it uses --dry-run. Adjust the client only after checking current source support in the Telltale README and source validation matrix.

Intentional local JSONL output

cargo run --bin telltale -- scan --once --emit-activity --root "$HOME"

Use this only after reviewing what your environment allows Telltale to capture. The default user path profile writes telemetry to an OS-standard per-user location such as ~/.local/state/telltale/logs/adr-events.jsonl on Linux, ~/Library/Logs/Telltale/adr-events.jsonl on macOS, or %LOCALAPPDATA%\Telltale\Logs\adr-events.jsonl on Windows.

Useful output paths and commands

After a scan writes JSONL telemetry, the default user path profile keeps the event file under an OS-standard per-user location and uses built-in size-based rotation by default. Use --path-profile system for managed service deployments, --path-profile project for repo-relative development paths, or an explicit --log-path to override any profile default. Service managers can also set ADR_LOG_PATH and ADR_STATE_PATH. Broad log-directory forwarding risks indexing diagnostics, source logs, or unrelated sensitive files.

Artifact Paths

Default user telemetry path (Linux)

~/.local/state/telltale/logs/adr-events.jsonl

Default user path profile on Linux. $XDG_STATE_HOME is honored when set. macOS uses ~/Library/Logs/Telltale/adr-events.jsonl and Windows uses %LOCALAPPDATA%\Telltale\Logs\adr-events.jsonl.

Managed Linux system path

/var/log/telltale/adr-events.jsonl

Used with --path-profile system for service-manager deployments. Pair with config/examples/telltale-logrotate for OS-native rotation, or disable built-in rotation with --log-rotate-disabled when a managed OS rotation policy owns the file.

Event schema

schemas/event.schema.json

Schema for emitted SIEM events, including event_type, severity, risk_score, client, session_id, evidence, triage, and response fields.

Bundled rules

config/rules/tool-call-regex.yaml

Bundled YAML rules used by default unless scan-time rule files replace the set.

Review latest scanner status

cargo run --bin telltale -- status

status reads the default user profile state path unless ADR_STATE_PATH or --state-path overrides it.

Scoped watch mode

cargo run --bin telltale -- watch --client codex --client opencode --root "$HOME"

Watch mode accepts repeated --client filters so monitoring can stay scoped to selected supported clients.