Metadata-Version: 2.5
Name: local-devops-workbench
Version: 0.2.1
Summary: A safe local DevOps control plane for native, Compose, DDEV, Kubernetes, and OrbStack VM projects.
Project-URL: Homepage, https://github.com/openplanr/ldw
Project-URL: Documentation, https://github.com/openplanr/ldw/tree/main/docs
Project-URL: Issues, https://github.com/openplanr/ldw/issues
Project-URL: Source, https://github.com/openplanr/ldw
Author: AsemDevs
Maintainer: OpenPlanr
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ddev,developer-experience,devops,docker-compose,kind,orbstack,tilt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: <3.15,>=3.12
Requires-Dist: ldw-agent==0.2.1
Requires-Dist: ldw-core==0.2.1
Requires-Dist: ldw-deploy==0.2.1
Requires-Dist: ldw-labs==0.2.1
Requires-Dist: ldw-observability==0.2.1
Requires-Dist: ldw-vm==0.2.1
Provides-Extra: ansible
Requires-Dist: ldw-vm[ansible]==0.2.1; extra == 'ansible'
Provides-Extra: dev
Requires-Dist: ldw-core[dev]==0.2.1; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/readme-hero.svg" alt="Local DevOps Workbench — Your stack. One workbench. Discover and review with ldw init, preview with ldw plan, and start with ldw up." width="1000">
</p>

<h1 align="center">Local DevOps Workbench</h1>

<p align="center">
  <strong>Evidence-based discovery → standard config you own.</strong>
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-2563eb" alt="License: Apache 2.0"></a>
  <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.12%E2%80%933.14-2563eb" alt="Python 3.12–3.14"></a>
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/status-public_preview-e9a45c" alt="Status: public preview"></a>
</p>

<p align="center">
  <a href="#quick-start">Quick start</a> ·
  <a href="#what-you-can-do">Features</a> ·
  <a href="#supported-workflows">Supported workflows</a> ·
  <a href="docs/index.md">Documentation</a> ·
  <a href="https://github.com/openplanr/ldw/actions/workflows/quality.yml">CI</a> ·
  <a href="CONTRIBUTING.md">Contribute</a>
</p>

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

```bash
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

```bash
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](docs/how-to/export-and-eject.md) and
[Compared with other tools](docs/explanation/compared-with.md).

## What you can do

| Capability | What it gives you |
| --- | --- |
| **Discover an existing stack** | Find package scripts, workspaces, Compose, DDEV, Helm, ports, and required environment variable names, with evidence for each proposed resource. |
| **Use one daily workflow** | Plan, start, inspect, log, test, and stop linked projects through the same CLI. Select another declared mode when you need it. |
| **Run several projects** | Check fixed-port conflicts and acquire project locks before startup, with ownership tracking and bounded rollback. |
| **Keep integrations current** | Review changes, detect drift, apply plans atomically, and repair, upgrade, or remove files with proven ownership. |
| **Export standard config** | Generate a Tiltfile or mise tasks from the accepted manifest, check them in CI, or eject them to the team. |
| **Share a portable setup** | Commit the manifest and lock for your team, or integrate locally without changing the repository. |
| **Ask for optional AI analysis** | Let Codex or Claude Code propose a setup for ambiguous repositories through a consent-based, restricted analysis workflow. |

## Supported workflows

| Your project uses | LDW coordinates |
| --- | --- |
| **Native tools** | Existing package scripts, Make targets, and local application processes. |
| **Docker Compose** | Project-owned services, dependencies, logs, and container-retaining shutdown. |
| **DDEV** | The existing DDEV project and its service lifecycle. |
| **Native + containers** | Accepted infrastructure startup, provider health checks, then native applications. |
| **Kubernetes / kind** | Declared Helm charts, local images, namespaces, and resources in Workbench-owned kind contexts. |
| **OrbStack VMs** | Explicit machine creation, provisioning, deployment, health checks, and rollback on macOS. |

Select another declared mode with `ldw up my-project:kubernetes`.
[Kubernetes setup](docs/how-to/use-kubernetes.md) and
[VM operations](docs/how-to/use-orbstack-vms.md) are explicit; `ldw up` never creates a VM.

## Quick start

### 1. Install LDW

**Requirements:** macOS or Linux, Git, [uv](https://docs.astral.sh/uv/getting-started/installation/),
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.

```bash
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](docs/how-to/install-on-a-new-mac.md).

<details>
<summary><strong>Optional: OrbStack VMs and Ansible-based labs</strong></summary>

Local VMs require OrbStack on macOS. From the LDW checkout, install the extra dependencies:

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

Then follow the [VM guide](docs/how-to/use-orbstack-vms.md).

</details>

### 2. Connect your project

```bash
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](docs/tutorials/quick-start.md) for a runnable frontend, API,
PostgreSQL, and Redis example.

### 3. Start developing

```bash
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](docs/reference/cli.md#runtime-planning-and-lifecycle).

<details>
<summary><strong>Automating onboarding or choosing a project identity?</strong></summary>

`ldw init . --json` returns a plan without applying it. Noninteractive plain `ldw init` leaves
the plan unapplied, prints the next command, and exits nonzero. Unresolved plans cannot be applied.

Use `--project-id my-project` for a stable identity; DDEV uses the accepted DDEV name.
See the [integration reference](docs/reference/integration.md) for resolve/apply commands.

</details>

## Go beyond startup

| When you need to… | Use |
| --- | --- |
| **See metrics, logs, and traces** | [Local observability](docs/how-to/use-observability.md) with Grafana, Prometheus, Loki, Tempo, and OpenTelemetry. |
| **Protect and restore project data** | [Checksummed backups and guarded resets](docs/how-to/backup-and-restore.md), with a mandatory snapshot before reset. |
| **Rehearse a release in isolation** | [OrbStack VMs](docs/how-to/use-orbstack-vms.md) with verified artifacts, local tunnels, and health-gated releases. |
| **Deploy to an existing server** | [SSH deployment](docs/how-to/deploy-over-ssh.md) to one Ubuntu LTS host, with pinned identity and health-gated rollback. Server provisioning, DNS, TLS, and public ingress stay external. |
| **Practice recovering from failure** | [Bounded failure labs](docs/how-to/run-failure-labs.md) that verify a healthy baseline, inject a fault, and report recovery. |
| **Prepare for offline work** | [Verified cache warming](docs/how-to/work-offline.md) for supported tools, images, charts, and dependencies. |
| **Add custom integrations** | [Declarative packs and trusted Python extensions](docs/how-to/write-a-provider.md) for organization-specific behavior. |

## 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:

```text
.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](docs/how-to/reconcile-an-integration.md) 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](docs/explanation/threat-model.md).

## Find your next step

| I want to… | Start here |
| --- | --- |
| Install on a fresh machine | [New-Mac guide](docs/how-to/install-on-a-new-mac.md) |
| Try a working example | [Compose tutorial](docs/tutorials/quick-start.md) |
| Onboard my own repository | [Add a project](docs/how-to/add-a-project.md) |
| Export a Tiltfile or mise tasks | [Export and eject](docs/how-to/export-and-eject.md) |
| Run several projects together | [Multi-project guide](docs/how-to/run-multiple-projects.md) |
| Look up a command or config field | [CLI reference](docs/reference/cli.md) · [Manifest reference](docs/reference/project-manifest.md) |
| Understand the design | [Architecture](docs/explanation/architecture.md) · [Environment boundaries](docs/explanation/environment-boundaries.md) · [Compared with other tools](docs/explanation/compared-with.md) |
| Diagnose a problem | [Troubleshooting](docs/how-to/troubleshoot.md) · [Support](SUPPORT.md) |

Browse the [full documentation](docs/index.md) for all guides and references.

## Contributing

LDW is licensed under [Apache 2.0](LICENSE). Bug reports, documentation improvements, integration
packs, and code contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and the
[Code of Conduct](CODE_OF_CONDUCT.md), or use
[GitHub Discussions](https://github.com/openplanr/ldw/discussions) for setup and design questions.

Report vulnerabilities through the [security policy](SECURITY.md), and keep secrets and private
project data out of public issues.
