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.

Conceptual workflow illustration; this is not a screenshot of the application.

How it works

flowchart LR
    Intent[Development intent] --> Playbook[Reviewed playbook]
    Profile[Repository profile] --> Composer[Task composer]
    Playbook --> Composer
    Composer --> Review[Compatibility and guardrail review]
    Review --> Output[Immutable task or verified Run Pack]

Choose a playbook, add a repository profile, describe the task, inspect the generated scope and validation requirements, then export the exact prompt or Run Pack for your coding agent. Simple mode guides common tasks; Expert mode exposes the detailed controls. The application keeps the authoring and review boundary visible before anything is handed to an agent.

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.

Create your first RunPack

After creating the owner account, select a built-in playbook, provide the repository profile and describe one bounded task. Review the composed prompt, assumptions and guardrails before exporting the RunPack. Start with a local profile if you do not need the optional Gitea connector.

DevRunbook produces an instruction package for a human or coding agent. Exporting a package does not execute its commands, modify a repository or establish that the requested work passed validation. Keep the exported package with the evidence produced by the actual execution.

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.