Runroot

Runroot is an MCP-native runtime and orchestration platform for durable developer and ops workflows.

Why Runroot

Most agent tooling still optimizes for short-lived chats, not long-running operational workflows. Runroot is designed for teams that need a self-hosted runtime with durable execution, explicit approvals, replayable history, and clean integration boundaries.

Runroot focuses on:

• durable run execution with pause and resume
• human approval paths instead of hidden side effects
• replayable event history for audit and debugging
• MCP-native tool integration
• boring, maintainable infrastructure suitable for small teams and open-source contributors

Current Status

Phase 19 (Cross-Run Audit Catalog Review Assignments and Operator Handoffs) is complete on this branch. The repository now includes:

• the Phase 2 runtime core for runs, steps, checkpoints, and retries
• the Phase 3 tool layer and minimal MCP adapter
• the Phase 4 approval and replay foundations
• a thin operator API and CLI
• the first real workflow templates for GitHub, Slack, and shell automation
• a minimal web console for runs, approvals, and replay
• observability adapter seams for logging and tracing
• contributor onboarding guides and example guidance for open-source collaboration
• issue and pull request templates for public contribution flow
• a documented release-readiness workflow and release-note strategy
• a Postgres-first persistence baseline with a SQLite local-development fallback
• migration entrypoints and local infra guidance for the database-backed path
• a shared queue-backed execution seam and minimal worker coordination path
• a minimal worker app that can claim queued runs and drive them through the existing runtime
• persisted tool history and minimal telemetry correlation across inline and queued execution
• a correlated audit projection that joins replay, approval, dispatch, worker, and tool facts through the existing operator seams
• a minimal operator-facing audit view in SDK, API, CLI, and web
• shared cross-run audit queries and thin operator-facing filters in SDK, API, CLI, and web
• shared cross-run audit drilldowns and identifier-constrained operator reads in SDK, API, CLI, and web
• shared audit navigation that links cross-run summaries, constrained drilldowns, and existing run-scoped audit views through the same seams
• shared saved audit views that preserve constrained navigation state and reopen it through the same SDK, API, CLI, and web seams
• shared audit view catalogs that publish constrained saved views into curated reusable presets through the same SDK, API, CLI, and web seams
• shared catalog visibility metadata that keeps curated presets personal or shared through the same SDK, API, CLI, and web seams without becoming a collaboration or SaaS layer
• shared catalog review signals and shared notes that let operators mark visible presets as recommended or reviewed through the same SDK, API, CLI, and web seams without becoming a threaded collaboration or approval layer
• shared catalog review assignments and operator handoffs that let operators assign reviewed visible presets through the same SDK, API, CLI, and web seams without becoming a workflow engine, RBAC layer, or collaboration platform

Persisted tool history is additive audit data. It does not become part of the shared replay or approval source of truth.

Correlated audit views are also additive. They do not redefine replay or approval correctness.

Cross-run audit queries remain derived operator read models. They do not become replay, approval, or workflow-state source of truth.

Identifier-driven audit drilldowns remain derived operator read models as well. They do not become replay, approval, or workflow-state source of truth.

Audit navigation remains a derived operator read model too. It links existing summary, drilldown, and run-audit reads without becoming a second source of truth for replay or approvals.

Saved audit views remain derived operator state as well. They store stable filters and navigation references without snapshotting audit facts or becoming workflow-state source of truth.

Audit view catalogs remain a derived operator layer too. They publish constrained saved views through stable metadata and references without becoming workflow-state source of truth, a collaborative catalog product, or a dashboard/search surface.

Catalog visibility remains a derived operator layer as well. It adds minimal shared-preset visibility state over catalog entries without becoming replay, approval, RBAC, multi-tenant access control, or a collaborative catalog product.

Catalog review signals remain a derived operator layer too. They add thin review state and optional shared notes over visible presets without becoming replay, approval, workflow correctness, threaded collaboration, or a dashboard/search surface.

Planned Capabilities

• Runtime core for runs, steps, retry, checkpoints, and event logging
• Tool layer for local tools and MCP-backed tools
• Approval model for pause, decision, resume, and rejection
• Replay and timeline views backed by immutable events
• API, CLI, and a minimal web console
• Practical templates for GitHub triage, PR review, Slack approvals, and shell runbooks

Quick Start

pnpm install
pnpm bootstrap
pnpm dev

Operator examples:

pnpm --filter @runroot/cli dev templates list
pnpm --filter @runroot/cli dev runs start shell-runbook-flow --input-file examples/phase-5/shell-runbook.json

Quality commands:

pnpm lint
pnpm typecheck
pnpm test
pnpm test:integration
pnpm build

Architecture Overview

Runroot is organized as a TypeScript monorepo:

• apps/api: Fastify-based control plane API
• apps/web: Next.js console for runs and approvals
• apps/worker: minimal queued-execution worker surface
• packages/*: runtime, domain, persistence, dispatch, events, tools, approvals, replay, observability, SDK, CLI, and templates
• docs/architecture: system design docs and ADRs

The core rule is simple: runtime concerns stay in packages, and apps remain thin transport and presentation layers.

Phase 3 adds one more rule: runtime can depend on the shared tool invocation contract, but concrete tool implementations and MCP translation stay outside @runroot/core-runtime.

Phase 4 adds a second rule: approval facts enter the shared runtime event stream, while tool lifecycle hooks remain package-level hooks until a later phase proves they belong in persisted replay history.

Phase 5 adds a third rule: API and CLI remain thin operator surfaces, while workflow templates are assembled in packages and reused through a shared operator service.

Phase 6 adds a fourth rule: the web console stays a thin visualization layer over the API surface, and observability begins as logging and tracing adapters rather than a new runtime center.

Phase 8 adds a fifth rule: database-backed persistence must stay behind the shared persistence contracts. Postgres is the primary backing store, SQLite is the local-development fallback, and the JSON-file adapter is no longer the default operator path.

Phase 9 adds a sixth rule: queued execution must stay behind shared dispatch and worker seams. Runs may execute out of process, but replay, approval, and operator semantics still derive from persisted runtime and approval events.

Phase 10 adds a seventh rule: persisted tool history remains additive to replay. It can record scoped tool outcomes and telemetry correlation, but replay and approval still derive only from persisted runtime and approval events.

Phase 11 adds an eighth rule: correlated audit views stay derived and operator-facing. They can join replay facts with additive dispatch, worker, and tool-history records, but they do not become a second workflow-state model.

Phase 12 adds a ninth rule: cross-run audit queries stay thin and structured. They can filter or summarize derived audit facts across runs, but they do not expand into a dashboard, analytics suite, or backend observability platform.

Phase 13 adds a tenth rule: identifier-driven drilldowns stay constrained and operator-facing. They can narrow derived audit facts by stable identifiers, but they do not expand into a dashboard, search product, or analytics platform.

Phase 14 adds an eleventh rule: linked audit navigation stays thin and operator-facing. It can connect summaries, drilldowns, and run-scoped audit views, but it does not expand into a dashboard, search product, or analytics platform.

Phase 15 adds a twelfth rule: saved audit views stay thin and derived. They can persist constrained navigation state and reopen it through existing seams, but they do not expand into a catalog, dashboard, analytics suite, or replay replacement.

Phase 16 adds a thirteenth rule: audit view catalogs stay thin and operator-facing. They can publish curated presets over existing saved views, but they do not expand into a collaborative catalog, dashboard, search product, or analytics platform.

Phase 17 adds a fourteenth rule: catalog visibility stays thin and operator-facing. It can distinguish personal and shared presets through stable visibility metadata, but it does not expand into RBAC, multi-tenant access models, discovery products, or collaborative SaaS catalog behavior.

Phase 18 adds a fifteenth rule: catalog review signals stay thin and operator-facing. They can attach stable review state and optional shared notes to visible presets, but they do not expand into threaded collaboration, assignments, RBAC, multi-tenant access models, dashboards, search products, or analytics platforms.

Phase 19 adds a sixteenth rule: catalog review assignments stay thin and operator-facing. They can attach stable assignee and handoff metadata to reviewed visible presets, but they do not expand into threaded collaboration, workflow engines, RBAC, multi-tenant access models, dashboards, search products, or analytics platforms.

Example Use Cases

• GitHub issue triage with optional human approval
• Pull request review workflows with durable checkpoints
• Slack approval and resume for sensitive operations
• Shell-driven runbooks with audit trails

Guides

• Quickstart
• Contributor Onboarding
• Good First Issues
• API Usage
• CLI Usage
• Templates
• Web Console
• Observability
• Persistence Baseline
• Queued Execution
• Tool Telemetry
• Audit Projections
• Audit Queries
• Audit Drilldowns
• Audit Navigation
• Audit Saved Views
• Audit View Catalogs
• Audit Catalog Visibility
• Audit Catalog Review Signals
• Audit Catalog Review Assignments
• Release Readiness
• Examples
• Web Console
• Observability

Roadmap

The current roadmap is maintained in docs/roadmap.md. The architecture baseline for this phase lives in phase-0-blueprint.md.

Contributing

See CONTRIBUTING.md for environment setup, coding standards, test expectations, and documentation requirements.

For the most useful contributor entrypoints, start with:

• Contributor Onboarding
• Good First Issues
• Examples
• Templates Guide
• Release Readiness
• Security Policy
• Code Of Conduct