Ductum

Ductum is a local-first factory control plane for agentic software work. It tracks Projects, Repositories, Components, Specs, Tasks, Attempts, Factory Settings, and Repair items so agent work can be assigned, audited, approved, retried, and closed without losing the operator trail.

The current wedge is governed execution for real agent work: read before edit, verify before push, approval before risky transitions, no push to protected branches, and no done state before required evidence is present. Ductum coordinates the work; Edictum enforces the process boundaries.

Install

npm install -g ductum

Requirements:

• Node.js 22+
• Git
• Provider auth for the agents you enable:
  • Anthropic subscription auth: ductum login
  • Codex auth: install the Codex CLI and run codex login

Ductum uses better-sqlite3 for the local factory database. A normal npm install builds or fetches that native binding. Installing with lifecycle scripts disabled can leave the API unable to start.

Quick Start

Create a factory directory:

ductum init --dir ~/ductum --name factory

Start or reopen the local control plane:

ductum start --dir ~/ductum

Check readiness and the next operator action:

ductum repair list
ductum operator brief
ductum operator next

Attach a repository to a Project:

ductum project create my-project --repo /absolute/path/to/repo --merge-mode human
ductum repository list my-project

Import work and start an Attempt:

ductum spec intake my-project path/to/spec.yaml --import
ductum queue
ductum attempt start <taskId> --agent codex --project my-project
ductum watch <attemptId>

When an Attempt reaches an operator decision:

ductum approve <attemptId>
ductum deny <attemptId> --reason "Needs a smaller patch"
ductum retry <attemptId>

Operator Model

• Factory: the local control plane.
• Project: the daily product or system boundary.
• Repository: a local Git checkout attached to a Project.
• Component: optional subdirectory scope inside a Repository.
• Spec: an operator work request.
• Task: a concrete repository-scoped unit of work.
• Attempt: one execution try for a Task.
• Factory Settings: Providers, Models, Harnesses, Workflows, Agents, sandboxes, notifications, budgets, and app settings.
• Repair: actionable readiness and recovery blockers.

Legacy Target, Run, and resource commands still exist for migration and debug paths. The normal path is Project, Repository, Spec, Task, Attempt, and Factory Settings.

Configuration And Secrets

Use the CLI as the supported write path:

ductum config validate --file ductum.yaml
ductum config apply --file ductum.yaml
ductum factory settings

Literal secrets do not belong in config files, logs, evidence, exports, or public JSON. Use environment-variable references such as ${ANTHROPIC_API_KEY} for provider credentials and notification settings.

What Ships

The npm package includes:

• the ductum CLI
• the local API server runtime
• dashboard static assets
• workflow templates
• sample specs used by the bootstrap demo

Source and issue tracker: https://github.com/acartag7/ductum