Druks

Warning

Druks is under active development. Expect breaking changes and rough edges before 1.0; main and latest are edge builds, not stable releases.

Druks is the self-hosted home for durable agent apps, running on the Claude and Codex subscriptions you already pay for. Build ships out of the box: autonomous software delivery from ticket to reviewed pull request.

An ordinary agent script loses its place when the process dies. A Druks workflow records the result of each completed durable operation in Postgres. After a restart or deploy, Druks replays the workflow and reuses those recorded results instead of repeating completed work. If the process was interrupted inside an operation, that operation may run again, so side effects still need idempotency. Durability and recovery explains the exact boundary.

Install

The installer supports three sandbox profiles backed by Drukbox:

• exe (default) and aws: remote sandbox VMs, with Druks and Drukbox in Compose
• docker: local sandbox containers, with Drukbox running on the host

For a remote install:

bash <(curl -fsSL https://raw.githubusercontent.com/czpython/druks/main/scripts/install.sh)

That command follows the edge channel while Druks has no stable release. Once versioned releases exist, install the script and image from the same tag as described in the release process.

The first run creates ~/druks/.env, generates secrets, and prints any values still required. Re-run the same command after filling them; it pulls images, runs migrations, and starts the stack. Re-running is also the upgrade path. See the deployment runbook for prerequisites, access control, verification, and rollback.

For a laptop-only stack:

DRUKS_PROVIDER=docker bash <(curl -fsSL https://raw.githubusercontent.com/czpython/druks/main/scripts/install.sh)

Then follow full local setup to start Drukbox and connect the agent harnesses. A complete installation needs GitHub Apps because the bundled build extension is installed; a standalone extension may have different integration requirements.

trigger ──> extension workflow ──> durable step ──> agent ──> sandbox
                 │                     │              │
                 │                     │              └─ Claude or Codex harness
                 │                     └─ result checkpointed in Postgres
                 ├─ event ──> feed / extension reaction
                 └─ gate  ──> wait for human or external system ──> resume

Platform and applications stay separate

Druks owns the execution and operating substrate:

• DBOS workflows and queues backed by Postgres
• typed human gates, cancellation, schedules, and observable run state
• Claude and Codex harness dispatch through isolated Drukbox sandboxes
• append-only events, live feeds, webhooks, notifications, MCP servers, and skills
• validated operator settings, encrypted MCP/OAuth secrets, and the dashboard shell
• extension discovery, API namespaces, and independent migration histories

An extension owns the application: its workflows, agents, domain models, routes, events, provider reactions, and optional dashboard pages. It is a normal Python distribution registered through the druks.extensions entry-point group. Installing the distribution registers it; Druks does not need an extension-specific plugin list.

The bundled build extension is a concrete example. It coordinates coding agents through tickets and GitHub pull requests, but GitHub PR orchestration is build behavior—not the definition of Druks.

Documentation

• Evaluating Druks: Concepts and guarantees
• Installing locally: Full local setup
• Operating a remote stack: Deployment runbook
• Configuring integrations and secrets: Configuration
• Building an application: Writing an extension
• Diagnosing a run or service: Troubleshooting
• Contributing to Druks: Contribution guide
• Reporting a vulnerability: Security policy
• All documentation: Documentation index