RunGlass
Run a command. Get a receipt for what changed.
RunGlass is a Linux-first CLI for commands where terminal history is not enough: AI agents, install scripts, package managers, Docker Compose, deploy scripts, CI jobs, and anything else you want an audit trail for.
Terminal history shows what you ran. RunGlass shows what happened:
- files created, modified, and deleted
- stdout, stderr, exit code, duration, and timeline
- child processes and process tree
- outbound network hosts and listening ports
- Docker containers, images, volumes, networks, and published ports
- risk notes for changes worth reviewing
- HTML, Markdown, JSON, compact summaries, AI summaries, bundles, CI artifacts, and reverse-patch exports
CI/PR use case:
What You Get
RunGlass turns one command boundary into a local receipt:
Command: codex exec "fix this failing test"
Files: 3 created, 2 modified, 0 deleted
Runtime: 7 child processes, 2 outbound hosts, 0 listening ports
Docker: 0 containers, 0 images, 0 volumes
Risk: low
Exports: receipt.html, receipt.md, receipt.json, summary.md, ai-summary.txt
Supported receipts can also preview and apply file reverts when RunGlass has stored the needed before-run snapshots.
Example Receipt
This full-stack demo wraps a provisioning command and shows the resulting file changes, processes, network activity, Docker changes, timeline, risk notes, and revert/export controls in one receipt.
More examples:
Install
RunGlass is Linux-first in this release. normal mode uses Linux process and socket sources, and deep mode uses strace when available. macOS and Windows command observation is not supported yet.
Install from crates.io:
Prebuilt Linux x86_64 release archives are published from tagged GitHub releases and include SHA-256 checksum files:
runglass-<version>-x86_64-unknown-linux-gnu.tar.gz
runglass-<version>-x86_64-unknown-linux-gnu.tar.gz.sha256
For local development, install this checkout into your Cargo bin directory:
Or build without installing:
normal mode is a single-binary experience. The embedded web UI, local server, collectors, exports, and revert flow ship inside the Rust runglass binary.
deep mode is still the same binary, but on Linux it uses strace when available for better short-lived process and socket visibility.
Platform Support
| Platform | Status | Notes |
|---|---|---|
| Linux x86_64 | Supported | Primary target. normal mode uses /proc and socket sampling; deep mode can use strace. |
| Linux other architectures | Expected to build | Not yet covered by release binaries. Build from crates.io/source. |
| macOS | Not supported for observation | The CLI may build, but command observation is Linux-first and currently exits clearly on unsupported platforms. |
| Windows | Not supported | Command observation is not implemented for Windows yet. |
Quick Start
Run a command:
Open the receipt:
Use deep mode when you want stronger process and network fidelity:
Wrap an AI agent command:
Why It Exists
Terminal history shows what you ran.
RunGlass shows what happened.
That matters when a command can create files, edit config, pull images, open ports, phone home, spawn child processes, or leave behind state that is easy to miss.
Common Workflows
RunGlass is strongest when one command has one clear boundary:
runglass run -- codex exec "fix this failing test"runglass run codex exec "fix this failing test"runglass run -- docker compose up -drunglass run docker compose up -drunglass run -- npm installrunglass run -- ./install.shrunglass run -- ./deploy-preview.sh
The repository includes repeatable workloads under examples, but they are support material. RunGlass itself is meant to wrap your real commands.
Revert And Export
Export the latest receipt:
Preview and apply supported file reverts:
The web UI can preview file reverts, warn when files changed after the receipt ended, and apply supported reversions.
What Revert Can And Cannot Undo
RunGlass reverts supported file changes from a receipt. It compares the current workspace to the receipt's recorded after-state before writing anything.
It can:
- restore modified files when stored before-run snapshots are available
- delete files that were created by the wrapped command and have not changed since
- restore files that were deleted by the wrapped command when stored before-run snapshots are available
- skip or force files that changed after the receipt finished
It does not automatically roll back non-file side effects such as Docker changes, network calls, external database writes, package manager global changes, external service mutations, or commands run outside the watched working directory.
RunGlass still helps with those side effects by showing the observed Docker before/after state, outbound hosts, listening ports, process activity, command output, and risk notes. For example, a receipt can show which containers, images, volumes, networks, or ports appeared during a command so you can decide on the right cleanup action deliberately.
Bundle exports are portable tar archives named runglass-receipt-<id>.tar with a runglass-receipt-<id>/ directory containing receipt.html, receipt.md, summary.md, ai-summary.txt, receipt.json, reverse.patch, and an artifacts/ folder.
Compact Summaries
Use compact summaries when the full HTML receipt is too much for a PR comment, CI log, issue report, or AI-agent feedback loop:
summary-md is a short Markdown report with impact counts and review-next items. ai is a deterministic text block designed to paste back into a coding agent without dumping full logs by default.
Example agent workflow:
GitHub PR Comments
RunGlass works with GitHub pull requests and GitHub Actions. It can post or update one compact receipt summary on a pull request:
In GitHub Actions pull-request workflows, use --auto with the CI receipt JSON to infer the repository, PR number, commit SHA, and run URL:
Authentication is read from GITHUB_TOKEN, GH_TOKEN, or gh auth token. RunGlass does not accept GitHub tokens as CLI arguments, so tokens do not need to appear in shell history or process listings. Tokens are not written into receipt artifacts. The GitHub token needs permission to write issue or pull request comments.
See GitHub integration docs for workflow examples, API behavior, and token permissions.
CI Receipts
Use runglass ci when an agent, install script, or remote runner should leave reviewable artifacts behind:
The command writes a stable receipt directory with receipt.html, receipt.md, receipt.json, summary.md, ai-summary.txt, reverse.patch, bundle.tar, stdout/stderr captures, metadata, diffs, and file snapshots when available. In CI mode, RunGlass returns the wrapped command's exit code after artifacts are written, so failing commands still fail the job while keeping the receipt available.
In GitHub Actions, runglass ci --provider github appends the compact Markdown summary to $GITHUB_STEP_SUMMARY when that file is available. Upload the output directory as an artifact, then comment on the PR from the generated receipt.json:
- run: runglass ci --provider github --output runglass-receipt -- npm test
- uses: actions/upload-artifact@v4
if: always()
with:
name: runglass-receipt
path: runglass-receipt/
- run: runglass github comment --receipt runglass-receipt/receipt.json --auto
if: always() && github.event_name == 'pull_request'
env:
GITHUB_TOKEN: ${{ github.token }}
Starter workflows are included for GitHub Actions and GitLab CI. See CI receipt workflows for the full artifact layout and local smoke test.
RunGlass also dogfoods this workflow in its own repository: pull requests run cargo test --workspace --locked through runglass ci, upload the generated receipt artifact, and update the RunGlass PR comment when token permissions allow it.
Observation Modes
RunGlass currently supports two Linux observation modes:
normal: adaptive/procpolling plussssampling. Fast, lightweight, and dependency-light.deep: normal mode plusstrace-based exec and socket tracing for better short-lived process and outbound network visibility.
Docker changes are captured from Docker Engine before/after state. File changes are captured from a scoped working-directory snapshot and diff.
How It Works
RunGlass keeps one command as the unit of review:
- snapshots the working directory before and after the command
- samples Linux process and socket state while the command runs
- uses
straceindeepmode when available for better short-lived exec and socket visibility - compares Docker Engine state before and after the command
- stores stdout, stderr, JSON receipt data, export artifacts, and reversible file snapshots locally
The result is intentionally best-effort rather than magic. RunGlass is designed to answer "what changed because I ran this command?" with useful evidence, while still being clear about snapshot caps, ignored paths, platform support, and tracing limitations.
Snapshot Controls
RunGlass defaults to a 10 MiB per-file snapshot cap so one large artifact does not turn a receipt into a heavy crawl.
Override the cap:
RUNGLASS_MAX_SNAPSHOT_BYTES=26214400
Ignore local paths with .runglassignore:
dist/
node_modules/
*.sqlite
tmp/
secret.env
See .runglassignore.example and .env.example for starter settings.
CLI Helpers
Scope
RunGlass is for one command, one boundary, one receipt.
It is not trying to be:
- a full terminal replacement
- a multi-command shell session recorder
- perfect system-wide tracing for every event on the machine
It is a pragmatic local receipt for commands you want to understand before you trust.