oakridge

Oakridge is a workflow-first orchestration system for agent-driven software work. DBOS owns durable execution, recovery, fan-out/fan-in, and waits; Oakridge owns workflow definitions, stages, artifact contracts, review policy, executor adapters, and operator projections. kbbl provides the operator PWA and the current interactive Claude Code executor.

Layout

oakridge/
├── oakridge-dbos/         # TypeScript domain backend and DBOS workflows
├── kbbl/                  # operator PWA and interactive agent sessions
├── workflow-config/       # versioned workflow definitions and shared prompts
├── legit-biz-club/        # future headless-agent integration surface
├── lbc-dashboard/         # read-only legit-biz-club study dashboard
├── docs/                  # operator documentation
└── comms/                 # design records and archived specifications

StageInstance is deliberately execution-agnostic: it starts and finishes. Executors are adapters beneath DBOS workflows. The current adapter uses kbbl; the boundary also permits a future headless legit-biz-club adapter without changing workflow or stage semantics.

Quick start

Prerequisites: Bun, Git, and either Docker or an existing PostgreSQL database.

bun install
bun run oakridge

Open http://127.0.0.1:8788/#oakridge. The command:

1. creates or starts a persistent oakridge-postgres container when DBOS_SYSTEM_DATABASE_URL is unset;
2. applies Oakridge domain migrations;
3. starts the DBOS backend on 127.0.0.1:8790;
4. rebuilds and starts kbbl on 127.0.0.1:8788; and
5. stops DBOS and kbbl together on Ctrl-C.

The PostgreSQL container and oakridge-postgres-data volume remain running and persistent across application restarts. The bundled dev-flow v14 definition is seeded automatically.

To use an existing PostgreSQL database instead of managed Docker:

export DBOS_SYSTEM_DATABASE_URL=postgres://user:password@127.0.0.1:5432/oakridge
bun run oakridge

DBOS_APPLICATION_VERSION defaults to the current Git commit. Override it only when deliberately operating DBOS application-version routing. Do not reuse a version after changing durable workflow operation order.

Remote operator access

The browser only needs kbbl. Keep DBOS on loopback and expose kbbl on a trusted LAN or tailnet:

export OAKRIDGE_CONTROL_TOKEN="$(openssl rand -hex 32)"
bun run oakridge -- --host=0.0.0.0

Open http://<machine-ip-or-tailnet-name>:8788/#oakridge. For a temporary unauthenticated development bind on a trusted network only:

ALLOW_INSECURE_NON_LOOPBACK_CONTROL=1 bun run oakridge -- --host=0.0.0.0

Separate services

For debugging, first start PostgreSQL and apply migrations, then run:

# Terminal 1 — DBOS backend
cd oakridge-dbos
export DBOS_SYSTEM_DATABASE_URL=postgres://oakridge:oakridge@127.0.0.1:54329/oakridge
export DBOS_APPLICATION_VERSION="$(git rev-parse HEAD)"
export KBBL_BASE_URL=http://127.0.0.1:8788
export OAKRIDGE_DBOS_HOST=127.0.0.1
export PORT=8790
bun run migrate
bun run start

# Terminal 2 — kbbl and the PWA
OAKRIDGE_CORE_BASE_URL=http://127.0.0.1:8790 ./kbbl/scripts/kbbl-start

OAKRIDGE_CORE_BASE_URL is a retained kbbl configuration name; its upstream is now the DBOS backend, not the retired Rust service.

Development

bun install
bun run typecheck
cd oakridge-dbos && bun test
cd ../kbbl && bun run test:all

See the v2 operator runbook for lifecycle, upgrade, recovery, and troubleshooting details. The DBOS replacement decisions are recorded in the backend replacement spec.

Agent-context files

Per-package CLAUDE.md and AGENTS.md files are generated by catagents from .catagents/ sources. Rebuild and check them with:

catagents
catagents --check