Local DevOps Workbench

Evidence-based discovery → standard config you own.

Quick start · Features · Supported workflows · Documentation · CI · Contribute

LDW discovers your repository from evidence and records the setup you approve. Run it with ldw up, the managed path, or export a Tiltfile or mise tasks that you own and can run without LDW. Coordinate native processes, Docker Compose, DDEV, and Kubernetes; add isolated VMs, observability, backups, and SSH deployment when you need them.

Keep your existing tools. LDW works with your package scripts, Makefile, Compose files, and DDEV configuration, adding a consistent lifecycle around them.

Public preview: Install from source. APIs may change before v1.0.0.

The everyday workflow

cd /path/to/your/project

ldw init .    # Discover and review
ldw plan      # Preview the run
ldw up        # Start the accepted mode

# In another terminal:
ldw status    # Health and endpoints
ldw logs api  # Logs for your api resource
ldw down      # Stop and preserve data

Review once, run consistently. Every ldw up uses the accepted manifest and lock; it never rescans the repository or calls AI.

Or export and leave

ldw export tiltfile   # A standalone Tiltfile for `tilt up`
ldw export mise       # mise tasks for `mise run dev`
ldw export tiltfile --check   # Fail CI when the export is stale or edited

Exported files come from the same accepted manifest and list what they cannot do without LDW. See Export and eject and Compared with other tools.

What you can do

Supported workflows

Select another declared mode with ldw up my-project:kubernetes. Kubernetes setup and VM operations are explicit; ldw up never creates a VM.

Quick start

1. Install LDW

Requirements: macOS or Linux, Git, uv, and your project's native tools. Python 3.12–3.14 is supported; the commands below install 3.12. Container workflows need Docker Desktop, Docker Engine, or a supported compatible Docker context.

git clone https://github.com/openplanr/ldw.git
cd ldw
uv python install 3.12
uv tool install --force --python 3.12 .
uv tool update-shell
export PATH="$HOME/.local/bin:$PATH"

ldw bootstrap --apply
ldw doctor

bootstrap --apply installs Workbench tooling; doctor checks prerequisites. This install includes every first-party plugin: VMs, SSH deployment, failure labs, observability, and coding-agent analysis. Install ./packages/ldw-core instead for the core alone. For a fresh Mac, follow the complete installation guide.

uv tool install --force --python 3.12 '.[ansible]'

2. Connect your project

cd /path/to/your/project
ldw init .

Review the detected resources, commands, ports, and managed files. Accepting saves the setup, links the project, and validates it. Discovery uses no AI by default. Use ldw init . --local-only to keep the integration entirely on your machine.

Try the Compose tutorial for a runnable frontend, API, PostgreSQL, and Redis example.

3. Start developing

ldw plan
ldw up

If Docker is stopped, use ldw runtime start or ldw up --start-runtime. Add --wait to require resource readiness, or --no-ui for CLI-only startup. With Tilt available, ldw up provides an attached resource UI.

Press Ctrl-C in the attached session or run ldw down to stop it. Normal shutdown preserves data and retains Compose containers. Full lifecycle behavior.

Go beyond startup

How LDW keeps the setup predictable

1. Discover repository facts and evidence.
2. Review and save the manifest and lock atomically.
3. Run the accepted setup with locks and port checks.
4. Reconcile repository changes before updating the integration.

In team mode, commit these files:

.devops-workbench/
├── project.toml       # Accepted resources, modes, and commands
└── workbench.lock     # Integration ownership and hashes

Ignore machine overrides in .devops-workbench/project.local.toml. Operational state stays in local user directories. Secrets stay in project-owned environment files or an external store; manifests declare variable names only.

Use ldw integration diff and ldw review to review changes, then ldw resolve 1 and ldw apply. ldw review shows what LDW will write; ldw plan shows how ldw up will start. LDW refuses to overwrite drifted managed content and removes only artifacts it can prove it owns. Follow the reconciliation guide to apply changes.

Optional AI, bounded authority

Request analysis during initialization with --agent codex, --agent claude, or --agent auto. After per-project consent, eligible analyzers receive a restricted mirror of eligible tracked files. Credentials, environment files, Git data, and ignored or untracked files are excluded. Proposals must pass schema and evidence validation; agents have no direct infrastructure authority.

Codex requires a passing native sandbox self-test; Claude Code uses restricted file tools. Unsupported environments fail closed. --agent none keeps onboarding deterministic. ldw context --json supplies redacted, read-only operational facts for coding tools. See the threat model.

Find your next step

Browse the full documentation for all guides and references.

Contributing

LDW is licensed under Apache 2.0. Bug reports, documentation improvements, integration packs, and code contributions are welcome. Start with CONTRIBUTING.md and the Code of Conduct, or use GitHub Discussions for setup and design questions.

Report vulnerabilities through the security policy, and keep secrets and private project data out of public issues.