DevRunbook

DevRunbook is a self-hosted platform for turning development intent into structured, reusable and verifiable tasks for coding agents such as Codex. It combines a reviewed playbook, repository context, risk controls and validation requirements into a deterministic prompt or multi-file Run Pack.

The platform helps developers stop rewriting the same instructions while keeping scope, provenance and evidence visible. It does not execute repository commands or write to your Git forge.

What users can do

Browse and search 28 built-in, versioned development playbooks.
Create reusable repository profiles with commands, protected paths and policies.
Compose tasks in a guided Simple flow or a detailed Expert flow.
Inspect compatibility, provenance, guardrails and prompt-lint results before generation.
Save immutable generated tasks and export exact Markdown or verified Run Pack archives.
Connect Gitea read-only to import bounded repository evidence while retaining useful local state during an outage.
Author and review private playbooks in Prompt Lab without making draft claims look validated.

The interface supports Dutch and English presentation, keyboard navigation, reduced motion, light/dark themes and responsive desktop/mobile layouts.

Quick start with Docker Compose

Requirements:

Docker Engine with Docker Compose 2.40 or newer;
a release checkout of this repository;
four independently generated secrets.

cp .env.example .env
chmod 600 .env

openssl rand -hex 24       # POSTGRES_PASSWORD
openssl rand -hex 32       # SESSION_SECRET
openssl rand -base64 32    # INTEGRATION_ENCRYPTION_KEY
openssl rand -hex 24       # BOOTSTRAP_TOKEN

Place those values in .env, set PUBLIC_BASE_URL, then start the stack:

docker compose -p devrunbook --env-file .env build
docker compose -p devrunbook --env-file .env up -d
docker compose -p devrunbook --env-file .env ps

Open PUBLIC_BASE_URL/setup, enter the bootstrap token and create the first owner. The setup route closes after successful initialization. Keep public registration closed unless you deliberately configure an invitation workflow.

Health endpoints:

curl --fail http://127.0.0.1:3000/health/live
curl --fail http://127.0.0.1:3000/health/ready

For production upgrades, backups, restores, Unraid and reverse-proxy guidance, read the operator guide. Do not publish PostgreSQL, mount the Docker socket or weaken the default Gitea network policy. The reference stack binds its HTTP port to host loopback; terminate public HTTPS at a maintained reverse proxy on the same host or adjust the binding deliberately.

Local development

DevRunbook requires Node.js 24, pnpm 10.33.0 and Python 3 for the specification contracts. PostgreSQL is required for integration tests and a complete local application flow.

corepack enable
pnpm install --frozen-lockfile
python3 scripts/validate_pack.py
python3 scripts/reference_compose.py --check
pnpm verify
pnpm test:security

pnpm verify runs formatting, linting, strict type checks, unit tests, specification/golden-fixture validation and production builds. See docs/15-test-strategy.md for integration, Playwright, clean-room and release gates.

Architecture and safety

DevRunbook is a TypeScript modular monolith with separate web and worker roles and PostgreSQL as its only required data service. Important boundaries include:

generated runs and published playbook versions are immutable snapshots;
imported repository text is untrusted evidence, never governing instruction;
templates and conditions use restricted, non-executable data models;
archives are bounded, inventoried and verified without unsafe extraction;
workspace authorization is enforced server-side for every private resource;
Gitea tokens are encrypted at rest and the first integration is read-only;
default containers run non-root with read-only roots, dropped capabilities and no Docker socket.

Start with the product vision, technical architecture and security threat model. Contributors should also read AGENTS.md and CONTRIBUTING.md.

Project status

The implemented release candidate covers the core library, repository profiles, deterministic composition, exports, read-only Gitea intelligence, Prompt Lab, operations, localization and accessibility hardening. Detailed evidence is in CURRENT_STATE.md and docs/19-acceptance-criteria.md.

Direct code execution, forge writes, a public marketplace, billing, Kubernetes as a required deployment and vector search remain deliberately out of scope.

The application and Unraid icons were created for this project; their source and licensing are recorded in the asset notice.

BUILD_PACK.json, FILE_INDEX.txt, PACK_MANIFEST.sha256 and the version 1.2 documents describe the historical implementation-contract pack from which the 0.1 application was built. They are not the current application version or a release manifest. See publication readiness for the remaining owner-controlled launch decisions.

License and security

DevRunbook is available under the MIT License. Please report vulnerabilities through the private channel described in SECURITY.md; do not post tokens, private repository contents or exploit details in a public issue.

5.5 KiB Raw Permalink Blame History