What is Runmark and what problem does it solve?

Runmark is a local-first development environment observability, fingerprinting, comparison, and verification tool designed to permanently eliminate 'works on my machine' issues across teams and CI pipelines.

How does Runmark detect development environment drift?

Runmark scans runtime interpreters, package dependencies, OS packages, port bindings, and environment variables into a deterministic canonical digest and compares it against expected environment contracts.

How does Runmark compare to Docker?

Runmark works directly on native host environments without the heavy overhead, virtualization, or build times of Docker containers, while also being able to verify inside containers and CI jobs.

Does Runmark inspect or leak sensitive secrets?

No. Runmark features a zero-secret security architecture. Environment variable values matching secret heuristics (API tokens, passwords, private keys) are automatically redacted locally before calculating digests.

How do I install Runmark?

Runmark is available on PyPI. You can install it using 'pip install runmark' or run it directly in your virtual environment.

Complete Feature Suite

Features

Everything you need for reproducible, reliable, and consistent development environments.

Environment Scanning

Runmark inspects host operating system facts, runtimes (Python, Node, Docker, Git), project signals (pyproject.toml, package.json, Dockerfile), declared/locked dependencies, background services (PostgreSQL, Redis), and port availability without mutating system state.

✓Zero system mutation — safe read-only inspection

✓Subprocess timeout clamping and bounded memory

✓Automatic detection of Python, Node, Docker, Git, Postgres, Redis

✓Clean visual tree representation with Rich terminal formatting

$ runmark scanDocs

Smart Snapshots

Persist immutable environment snapshots into local atomic storage (`.runmark/snapshots/`). Every snapshot includes a deterministic SHA-256 fingerprint generated from canonicalized environment properties.

✓Deterministic SHA-256 environment fingerprinting

✓Decoupled from code commits and developer hostnames

✓Atomic filesystem persistence with fsync protection

✓Tagged messages for tracking onboarding milestones

$ runmark snapshot -m "Initial dev baseline"Docs

Drift Detection

Semantic diff engine that compares your live environment against a baseline snapshot or two snapshots against each other. Categorizes changes as ADDED, REMOVED, CHANGED, or UNCHANGED with rule-driven severity.

✓Categorized diffing: ADDED, REMOVED, CHANGED, UNCHANGED

✓Severity triage: CRITICAL, WARNING, INFO

✓Highlights subtle minor/patch version drifts before runtime failures

✓Supports machine-readable JSON output for automation

$ runmark diffDocs

New

Environment Contracts

Declare required runtimes, dependencies, services, ports, container tools, and environment variable requirements in a version-controlled `runmark.json` file validated against formal JSON schemas.

✓Evidence-driven contract synthesis (pyproject.toml, package.json, Dockerfile)

✓Strict numeric version constraint checking (>=3.11, 3.12.x, <4.0)

✓Semantic contract diffing against Git HEAD (runmark contract diff)

✓Zero secret storage guarantee (names only, never credentials)

$ runmark contract init --dry-runDocs

Verification & CI Exit Codes

Evaluates the host machine against a verified snapshot or project contract, yielding standardized exit codes suitable for CI pipelines, pull request gates, and pre-commit hooks.

✓Deterministic exit codes: 0 (Success), 1 (Drift/Failure), 2 (Usage), 3 (Internal), 4 (Security)

✓Ideal for pre-commit hooks and GitHub Actions workflows

✓Strict mode enforcing exact version matches

✓Prevent broken PRs caused by environment discrepancies

$ runmark verify --strictDocs

Doctor / Diagnostics

Deep diagnostic engine that breaks down issues into concrete observed evidence, inferred reasoning, and clear read-only fix instructions to get developers back to coding quickly.

✓Concrete observed facts vs inferred deductions

✓Actionable commands to restore missing runtimes or services

✓Port conflict and daemon outage diagnostics

✓Structured diagnostic codes (ENV_MISSING_REQUIRED, RUNTIME_VERSION_MISMATCH)

$ runmark doctorDocs

Zero-Secret Guarantee

In-memory redactor automatically recognizes API keys (OpenAI, AWS, GitHub, Stripe, Slack), private keys, JWTs, and database URIs, masking values before storage or report export.

✓Pattern matching for cloud providers, tokens, and cryptographic keys

✓Automatic username & user home masking (<USER_HOME>)

✓Export boundary canary checks aborting on credential leaks (Exit code 4)

✓URI sanitization stripping embedded passwords from database connection strings

$ runmark share --output report.mdDocs

Cross-Platform Precision

Engineered specifically to handle path separators, binary names (.exe vs POSIX), architecture strings (AMD64, arm64, x86_64), and platform-specific service discovery gracefully.

✓Native Windows, macOS (Darwin), and Linux support

✓Consistent POSIX relative paths in snapshots and contracts

✓Safe binary decoding with errors='replace' protection

✓Universal CLI experience across team members

Architecture ConceptDocs

Roadmap

Extensible Architecture

Designed around single-responsibility Detector base classes. Community and custom team detectors can observe bespoke internal databases, cloud emulators, and SDKs.

✓Standard Detector base class with DetectionContext

✓Custom service and runtime inspection plugins

✓Safe isolation preventing plugin crashes from corrupting scans

✓Coming in Roadmap Milestone v0.5.0

Architecture ConceptDocs

$ runmark scan

Scanning environment...

✓ Python 3.12.10 detected

✓ Node.js 22.19.0 detected

✓ PostgreSQL 16.3 (Port 5432) active

✓ Environment secrets redacted

Canonical Digest: ce19840abda567...

Snapshot saved successfully.

Developer Experience

More than just a tool.

Runmark is designed to fit naturally into your workflow, helping you build, share, and maintain consistent environments across your entire development journey.

Explore Documentation

Trusted with the tools you already use

Python

3.10, 3.11, 3.12, 3.13

Django

4.x, 5.x Frameworks

FastAPI

ASGI • Modern APIs

Next.js

React & Node Runtimes

Node.js

v20, v22 LTS

Docker

Compose & Containers

PostgreSQL

v14, v15, v16

Git

Repositories & Branches

uv & pip

Deterministic Locks

Redis

Key-Value & Cache