Metadata-Version: 2.5
Name: runtimetruth
Version: 0.2.1
Summary: Runtime verification and drift detection for AI agents.
Project-URL: Homepage, https://sidelobe.dev/open-source/runtimetruth/
Project-URL: Repository, https://github.com/sidelobe-labs/runtimetruth
Project-URL: Issues, https://github.com/sidelobe-labs/runtimetruth/issues
Project-URL: Documentation, https://github.com/sidelobe-labs/runtimetruth/tree/main/docs
Project-URL: Changelog, https://github.com/sidelobe-labs/runtimetruth/blob/main/CHANGELOG.md
Author: Sidelobe Labs
License: MIT
License-File: LICENSE
Keywords: agent-security,ai-agents,drift-detection,mcp,runtime
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: rfc8785==0.1.4
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Description-Content-Type: text/markdown

# RuntimeTruth

**Runtime integrity verification for AI agents.**

[![PyPI](https://img.shields.io/pypi/v/runtimetruth?style=flat-square&label=PyPI)](https://pypi.org/project/runtimetruth/) [![Python](https://img.shields.io/pypi/pyversions/runtimetruth?style=flat-square&label=Python)](https://pypi.org/project/runtimetruth/) [![CI](https://img.shields.io/github/actions/workflow/status/sidelobe-labs/runtimetruth/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/sidelobe-labs/runtimetruth/actions/workflows/ci.yml) [![License](https://img.shields.io/github/license/sidelobe-labs/runtimetruth?style=flat-square)](https://github.com/sidelobe-labs/runtimetruth/blob/main/LICENSE)

RuntimeTruth detects drift between intended and live AI-agent runtime state. It compares evidence from declared, resolved, and live sources across models, instructions, tools, MCP servers, permissions, runtime versions, and the execution environment.

[PyPI](https://pypi.org/project/runtimetruth/) · [Sidelobe overview](https://sidelobe.dev/open-source/runtimetruth/) · [Case study](https://artur.panek.tech/work/runtimetruth/) · [Engineering note](https://artur.panek.tech/notes/ai-agent-config-vs-runtime/) · [Release notes](https://github.com/sidelobe-labs/runtimetruth/releases/tag/v0.2.1)

> **Public alpha · v0.2.1.** Core inspect, diff, verification, policy, and signed-baseline flows are covered by CI and exercised against real local runtimes.

## Why

AI agents have more mutable runtime state than ordinary applications:

- model and provider routing
- system and project instructions
- tools and MCP schemas
- skills and plugins
- sandbox and network permissions
- executable/runtime versions
- environment and process identity
- repository/code state

A deployment can therefore look unchanged while the effective agent runtime has drifted.

RuntimeTruth currently focuses on two questions:

1. **What runtime state can be established with explicit evidence?**
2. **What changed since a known baseline?**

Broader policy evaluation and organizational provenance remain later phases. The current policy file is intentionally narrow: it persists only the evidence selectors that should gate runtime verification.

## Project model

RuntimeTruth is currently distributed as free, local-first open-source software. There is no RuntimeTruth hosted control plane, account system, telemetry service, paid support plan or SLA.

A verification result is deliberately narrow: **PASS means the selected evidence matched the selected baseline.** It does not mean the agent is secure, compliant, safe, or correctly configured in ways RuntimeTruth did not inspect.

See the [trust model](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/trust-model.md), [data handling](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/data-handling.md), [support policy](https://github.com/sidelobe-labs/runtimetruth/blob/main/SUPPORT.md), and [MIT License](https://github.com/sidelobe-labs/runtimetruth/blob/main/LICENSE) for the current project boundary.

## Origin

RuntimeTruth grew out of operating self-hosted workers and noticing that source code and deployment configuration were not enough to answer a simple question: **what is actually running right now?**

The project is built from evidence outward. It started with systemd, procfs, and Git identity, then used the same model to inspect agent-specific Codex state.

[Read the origin story](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/origin.md).

## Installation

For the CLI, use an isolated tool environment:

```bash
pipx install runtimetruth
```

or:

```bash
uv tool install runtimetruth
```

Standard `pip` is also supported inside a virtual environment:

```bash
python -m pip install runtimetruth
```

Then verify the install:

```bash
runtimetruth --version
```

For CI workflows that require an exact source revision, pin the Git commit rather than following a moving branch. See [CI integration](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/ci.md).

## Quick start

Capture effective Codex runtime state:

```bash
runtimetruth inspect codex . --resolve-thread --pretty > baseline.json
```

Verify the current runtime against that baseline:

```bash
runtimetruth verify baseline.json --codex . --resolve-thread
```

Protect only selected runtime invariants when strict snapshot equality is too broad:

```bash
runtimetruth verify baseline.json --codex . --resolve-thread \
  --protect codex.thread.model \
  --protect codex.instructions
```

Persist repeated selectors in an explicit TOML policy:

```toml
version = 1
protect = [
  "codex.thread.model",
  "codex.thread.sandbox",
  "codex.instructions",
]
```

```bash
runtimetruth verify baseline.json --codex . --resolve-thread \
  --policy .runtimetruth/policy.toml
```

The same policy can be used with `verify-attestation`; signer identity and baseline binding are verified before policy evaluation.

Add `--json` for a versioned machine-readable PASS/DRIFT report.

Bind a reviewed baseline to an identity-backed Sigstore attestation:

```bash
runtimetruth digest baseline.json

runtimetruth attest baseline.json \
  --statement baseline.intoto.json \
  --bundle baseline.sigstore.json

runtimetruth verify-attestation \
  baseline.json \
  --statement baseline.intoto.json \
  --bundle baseline.sigstore.json \
  --certificate-identity "EXPECTED_IDENTITY" \
  --certificate-oidc-issuer "EXPECTED_ISSUER" \
  --codex . \
  --resolve-thread
```

Attestation uses RFC 8785 canonical JSON, SHA-256, in-toto Statement v1 and Sigstore Cosign rather than a RuntimeTruth-specific signature scheme. See [signed baseline attestations](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/attestation.md).

## Current CLI

Inspect a local target:

```console
runtimetruth inspect systemd <unit>
runtimetruth inspect git <path>
runtimetruth inspect codex <cwd>
runtimetruth inspect codex <cwd> --resolve-thread
runtimetruth inspect codex <cwd> --resolve-mcp
```

Compare two snapshots:

```console
runtimetruth diff <before.json> <after.json>
```

Verify a current snapshot against a baseline:

```console
runtimetruth verify <baseline.json> <current.json>
```

Or collect the current Codex runtime and verify it directly:

```console
runtimetruth verify <baseline.json> --codex <cwd> --resolve-thread
runtimetruth verify <baseline.json> --codex <cwd> --resolve-mcp
```

Verification uses stable process exit codes:

- `0` — runtime matches the baseline
- `2` — semantic runtime drift detected
- `1` — collection, input, or comparison error

Selective runtime invariants can be protected explicitly:

```console
runtimetruth verify baseline.json --codex <cwd> --resolve-thread \
  --protect codex.thread.model \
  --protect codex.instructions
```

For automation, add `--json` to emit a versioned structured PASS/DRIFT report without changing the exit-code contract.

Canonical baseline identity and signed verification are separate commands:

```console
runtimetruth digest <baseline.json>

runtimetruth attest <baseline.json> \
  --statement <baseline.intoto.json> \
  --bundle <baseline.sigstore.json>

runtimetruth verify-attestation <baseline.json> [current.json] \
  --statement <baseline.intoto.json> \
  --bundle <baseline.sigstore.json> \
  --certificate-identity <expected-identity> \
  --certificate-oidc-issuer <expected-issuer>
```

`verify-attestation` can also use `--codex <cwd>`, `--resolve-thread`, `--resolve-mcp`, `--policy <file>`, repeatable `--protect`, and `--json`.

Creating or verifying identity-backed attestations requires a recent [Sigstore Cosign](https://docs.sigstore.dev/cosign/system_config/installation/) executable. Normal inspect/diff/verify commands do not require Cosign.

`--resolve-thread` creates an ephemeral Codex thread without starting a turn. `--resolve-mcp` additionally probes thread-scoped MCP runtime state and may contact configured MCP servers or refresh authentication; it does not call MCP tools.

## Evidence currently collected

The intentionally narrow implementation includes:

- systemd unit/runtime state
- procfs process identity
- Git repository identity
- Codex executable/version
- Codex canonical resolved workspace configuration
- effective state materialized for an ephemeral Codex thread
- Codex-reported instruction source paths
- SHA-256 fingerprints of those instruction source files without storing their plaintext
- thread-scoped MCP server status and bounded tool-catalog fingerprints

Each evidence record keeps its provenance and is classified as declared, resolved, or live where the source supports that claim.

## Project boundary

RuntimeTruth is not intended to become a generic process monitor, LLM trace backend, MCP proxy/firewall, GitOps controller, or hosted observability dashboard.

The current focus is external validation of the baseline, attestation and policy model before adding additional agent adapters or cloud features.

See:

- [Origin](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/origin.md)
- [Vision](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/vision.md)
- [Landscape and positioning](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/landscape.md)
- [Roadmap](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/roadmap.md)
- [Architecture](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/architecture.md)
- [CI integration](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/ci.md)
- [Signed baseline attestations](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/attestation.md)
- [Verification policy](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/policy.md)
- [Contributing](https://github.com/sidelobe-labs/runtimetruth/blob/main/CONTRIBUTING.md)
- [Security](https://github.com/sidelobe-labs/runtimetruth/blob/main/SECURITY.md)
- [Trust model](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/trust-model.md)
- [Data handling](https://github.com/sidelobe-labs/runtimetruth/blob/main/docs/data-handling.md)
- [Support](https://github.com/sidelobe-labs/runtimetruth/blob/main/SUPPORT.md)

## Development

Requires Python 3.12+.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
pytest
```

## License

MIT.
