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.

Introduction to Runmark

**Know what makes your code run.**

*Git tracks your code. Runmark tracks what makes your code run.*

Runmark is a local-first, zero-telemetry developer infrastructure tool designed to observe, snapshot, compare, verify, and diagnose developer machine environments.

What is Runmark?

Modern software depends on an intricate web of invisible machine state:

Exact runtime minor/patch versions (Python 3.12.4 vs 3.11.9, Node.js 22.14.0 vs 20.18.0)

Host operating system semantics and architecture (Windows AMD64, Linux x86_64, macOS arm64)

Background backing services (PostgreSQL 16.3 on port 5432, Redis 7.2 on port 6379)

Required environment variables (e.g. DATABASE_URL, SECRET_KEY)

Container tooling and Docker Compose definitions

While Git tracks the lines of code in your files, Git has zero awareness of whether your local machine satisfies the runtime requirements needed to execute that code.

Runmark bridges this gap. It creates deterministic fingerprints of your environment, alerts you to drift before runtime crashes happen, and proves whether a developer machine or CI runner satisfies project requirements.

The Problem: "Works on My Machine"

Consider a typical scenario across engineering teams:

Developer A has Python 3.12, Node 22, PostgreSQL 16 running on port 5432, and all required environment variables set.

Developer B has Python 3.11, Node 20, PostgreSQL not installed, Redis stopped, and a missing environment variable.

Both developers checkout the exact same Git commit, yet the application crashes for Developer B. Hours of debugging follow, usually culminating in: *"Oh, you need Python 3.12 and a local Postgres instance running on port 5432."*

Runmark eliminates this entire class of developer friction.

How Runmark Helps

1. Observe Without Mutating: Runs non-destructive, safe inspection across runtimes, dependencies, services, ports, and environment variables.

2. Deterministic Fingerprints: Generates a canonical SHA-256 digest of your machine state decoupled from Git commits, timestamps, and usernames.

3. Environment Contracts (`runmark.json`): Allows teams to declare and version-control environment requirements alongside source code.

4. Contract Proof (`runmark check`): Evaluates host machine compliance with clear diagnostic cards before builds or tests run.

5. Semantic Drift Triage: Compares environments and classifies discrepancies into CRITICAL, WARNING, and INFO severity tiers.

6. Actionable Doctor Advice: Explains why an environment failed with concrete observed evidence and exact remediation commands.

7. Zero-Secret Export: Generates sanitized Markdown or JSON reports ready to share with teammates without leaking API keys or credentials.

What Runmark is NOT

Runmark is NOT a package manager. It does not replace pip, uv, npm, pnpm, or cargo.

Runmark is NOT a container manager. It does not replace docker, podman, or Kubernetes.

Runmark is NOT an AI assistant. It operates on deterministic facts, structural inspection, and formal JSON schemas.

Runmark is NOT a cloud platform. It is 100% offline, local-first, and contains zero external telemetry.

Runmark is NOT an automatic installer. It never mutates system packages or installs software without user consent.

Core Principles

Local-First & Offline: All metadata is stored strictly in .runmark/ in your project root.

Zero Secrets: Multi-pass redactors scrub credentials, API tokens, and passwords in database URIs before any persistence.

Evidence-Driven: Project manifests (pyproject.toml, package.json, Dockerfile) take precedence over machine observations.

Deterministic: Given identical environment configurations, Runmark produces identical canonical fingerprints.