@wardby/cli 0.1.0

package/.env.example

@@ -0,0 +1,131 @@
+# Copy to `.env` for defaults everyone shares (still gitignored — this repo
+# has none actually safe to commit), or `.env.local` for personal overrides.
+# Runtime commands use dotenv-flow's standard cascade. Vitest explicitly loads
+# .env -> .env.local -> .env.test -> .env.test.local, while preserving shell/CI
+# variables as highest priority. Direct `npx prisma ...` commands read only a
+# plain `.env`, which is why DATABASE_URL belongs there as well.
+#
+# Portable Phase 1 defaults: OpenAI + local Postgres (deploy/local).
+DATABASE_URL="postgresql://wardby:wardby@localhost:55432/wardby"
+OPENAI_API_KEY=
+# Set LLM_PROVIDER=anthropic to select the Claude adapter (default: openai).
+LLM_PROVIDER=openai
+ANTHROPIC_API_KEY=
+
+# Phase 4: MCP server (`wardby mcp`). stdio is the local/no-OAuth default.
+MCP_TRANSPORT=stdio
+# host:port — required when MCP_TRANSPORT=http.
+MCP_HTTP_BIND=127.0.0.1:8080
+# wardby's own canonical URI — required when MCP_TRANSPORT=http (used as the
+# OAuth resource identifier and, in self-hosted mode, the AS issuer/audience).
+MCP_CANONICAL_URI=
+# Optional exact additional MCP browser origins, comma-separated. No paths/wildcards.
+# Login, consent, and logout always require the canonical origin.
+MCP_ALLOWED_ORIGINS=
+# stdio-mode owner identity (no token to derive one from).
+LOCAL_PRINCIPAL=local
+
+# AUTH_PROVIDER=delegating (default): wardby is resource-server-only and an
+# external IdP issues tokens. Use self-hosted for provisioned-user login,
+# consent, and public S256 PKCE clients. See docs/security-deployment.md.
+AUTH_PROVIDER=delegating
+# delegating mode:
+AUTH_ISSUER=
+AUTH_JWKS_URI=
+AUTH_AUDIENCE=
+# Must exactly match the normalized MCP_CANONICAL_URI for HTTP.
+# Self-hosted keys: independently generated 32-byte keys, each encoded as 64 hex chars.
+# Generate each with openssl rand -hex 32; supply via a secret manager in production.
+AUTH_SIGNING_KEY=
+AUTH_CREDENTIAL_HASH_KEY=
+AUTH_MAX_CLIENTS=1000
+
+# Exact normalized hosts only. Allowlisting private hosts bypasses network isolation.
+# Only takes effect for a tool attachment whose allowedHosts includes the "*"
+# wildcard (attach_tool / CLI `tool attach`) — a tool with an explicit host
+# list ignores this and is restricted to exactly what it declared.
+WARDBY_FETCH_ALLOWED_HOSTS=
+
+# SECRET_CIPHER=app-key (default): AES-256-GCM with a local master key.
+# kms is reserved (no adapter yet).
+SECRET_CIPHER=app-key
+# 32 bytes of hex (64 hex chars) — e.g. `openssl rand -hex 32`.
+SECRET_APP_KEY=
+
+# Local browser-backed security tests can reuse an installed Chrome instead of
+# downloading Playwright Chromium. CI should install Playwright's pinned browser.
+SECURITY_BROWSER_CHANNEL=
+
+# Required only for a multi-instance HTTP deployment: shares the MCP
+# requestState HMAC key across instances, so a secret-elicitation token
+# minted on one instance verifies on another. 32 bytes of hex (64 hex
+# chars) — e.g. `openssl rand -hex 32`. Leave unset for stdio or a
+# single-instance HTTP deployment (each process falls back to its own
+# random key, which is fine when only one process ever sees a given token).
+REQUEST_STATE_KEY=
+
+# Phase 5 containerized coding executor. The native executor remains the
+# default; all values below are used only when JOB_LAUNCHER=docker.
+JOB_LAUNCHER=local
+# Required: immutable repository digest or Docker local image ID, never a mutable tag.
+CODING_WORKER_IMAGE=
+# Required: dedicated proxy container already attached to its external network.
+CODING_PROXY_CONTAINER=
+# Trusted host roots. VCS_WORK_ROOT is also the Docker launcher's seed/materialize root.
+VCS_WORK_ROOT=
+CODING_JOB_STATE_ROOT=
+CODING_ARTIFACT_ROOT=
+# Reference resolved only by the trusted proxy process; never passed to the worker.
+CODING_OPENAI_CREDENTIAL_REF=env:OPENAI_API_KEY
+CODING_CPUS=1
+CODING_MEMORY_MB=2048
+CODING_PIDS=128
+CODING_DISK_MB=2048
+# Operator ceiling (MiB) on a coding profile's per-agent workspaceDiskMb; must be >= CODING_DISK_MB.
+# Defaults to CODING_DISK_MB, so raising it is a deliberate opt-in (on Docker the workspace is tmpfs,
+# i.e. RAM, and every concurrent run can claim this much).
+CODING_MAX_DISK_MB=2048
+# Coding runs holding a slot at once, across all control-plane replicas
+# (enforced in Postgres). Runs over the cap wait in a FIFO queue.
+CODING_MAX_CONCURRENT=4
+# Seconds a coding run may wait for a slot before failing (coding_queue_timeout).
+CODING_QUEUE_TIMEOUT_SEC=3600
+
+# JOB_LAUNCHER=kubernetes: coding runs as pods (see deploy/kind-coding/ locally).
+# Namespace holding coding-run pods and the in-cluster coding proxy.
+KUBERNETES_NAMESPACE=wardby-coding
+# kubeconfig context to use; unset = current context, or in-cluster credentials.
+KUBERNETES_CONTEXT=
+KUBERNETES_PROXY_SERVICE=wardby-coding-proxy
+# Required RuntimeClass for coding pods (e.g. gvisor on GKE). Unset = development
+# cluster: the launcher logs a warning on every launch.
+KUBERNETES_RUNTIME_CLASS=
+
+# Phase 7 observability. Disabled unless an explicit bind is supplied. Keep
+# production on loopback; the local Grafana Compose profile uses its private
+# network and explicitly enables 0.0.0.0 without publishing this port.
+METRICS_BIND=
+METRICS_ALLOW_NON_LOOPBACK=false
+
+# GitHub App installation used for scoped clone, branch push, and draft PR creation.
+GITHUB_APP_ID=
+GITHUB_APP_PRIVATE_KEY=
+GITHUB_API_VERSION=2026-03-10
+VCS_MAX_CHANGED_FILES=1000
+VCS_MAX_DIFF_BYTES=1048576
+
+# EXECUTOR=in-process (default): heartbeat + reconciler durability; a run whose
+# process dies is reconciled to `lost`. EXECUTOR=dbos: each run is a DBOS
+# durable workflow that resumes from its last completed LLM turn / tool call
+# after a crash or redeploy, and `stop` is a real cancellation.
+EXECUTOR=in-process
+# DBOS keeps its workflow tables in schema DBOS_SCHEMA of this database.
+# Defaults to DATABASE_URL; point elsewhere to keep them in a separate DB.
+DBOS_SYSTEM_DATABASE_URL=
+DBOS_SCHEMA=dbos
+# REQUIRED when EXECUTOR=dbos (no default — EXECUTOR=dbos refuses to start
+# without it). A restarted process with the same id re-drives its own
+# interrupted runs at launch, so two processes sharing an id each re-drive the
+# other's live workflows: the scheduler and the MCP server need DIFFERENT
+# values (e.g. scheduler-1 and mcp-1).
+DBOS_EXECUTOR_ID=

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Wardby
+Copyright 2026 Christopher Fields

package/README.md

@@ -0,0 +1,282 @@
+<div>
+  <img align="left" hspace="24" src="docs/assets/brand/wardby-mascot.png" alt="Wardby guardian robot protecting an agent budget" width="280">
+  <h3><big><big>Wardby</big></big> <small><em>(pronounced&nbsp;“WARD&#8209;bee”)</em></small></h3>
+  <h3>Autonomous agents, bounded by design.</h3>
+  <p><strong>Most agent runners focus on helping a model complete a task. Wardby is the self-hosted control plane that decides whether the task should run, limits what it can access, and returns a reviewable outcome governed by explicit policy.</strong></p>
+  <br clear="left">
+  <p><strong>Budgets are enforced before spend: every model request must fit within a hard run limit before it reaches the provider.</strong></p>
+  <p>
+    <a href="#why-wardby">Why Wardby</a> ·
+    <a href="#why-wardby-instead-of-another-agent-runner">Why it is different</a> ·
+    <a href="#a-full-cycle-agent-from-one-conversation">Full-cycle example</a> ·
+    <a href="#host-it-in-your-cloud">Deployments</a> ·
+    <a href="#bring-your-own-observability">Observability</a> ·
+    <a href="#quickstart">Quickstart</a> ·
+    <a href="#security-boundaries">Security</a>
+  </p>
+</div>
+<br clear="left">
+
+<!-- GitHub does not expose live Actions badge images for private repositories. These capability badges link authenticated readers to the authoritative workflow. -->
+
+[![Security CI](https://img.shields.io/badge/security%20CI-GitHub%20Actions-2088FF?logo=githubactions&logoColor=white)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
+[![Dependency audit](https://img.shields.io/badge/dependencies-audit%20policy-0f766e.svg)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
+[![Container scan](https://img.shields.io/badge/container%20images-Trivy%20CRITICAL%20gate-0f766e.svg)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
+[![SBOM](https://img.shields.io/badge/SBOM-SPDX%20JSON-0f766e.svg)](https://github.com/wardby/wardby/actions/workflows/security.yml?query=branch%3Amain)
+[![License](https://img.shields.io/badge/license-Apache--2.0-0f766e.svg)](LICENSE)
+
+> **Project status:** the control plane, scheduler, budget groups, MCP server,
+> native agents, isolated Codex and Claude Code workers, GitHub draft-PR flow,
+> and local observability stack are implemented and tested. Production
+> readiness and cloud deployment coverage are still being expanded.
+
+## Why Wardby
+
+AI agents are easy to demo and harder to operate. Once an agent can spend
+money, use credentials, change a repository, or run without a person watching,
+teams need more than a prompt and a cron job.
+
+Wardby provides the control plane around the model:
+
+| For engineering leaders                                                     | For developers                                                                             |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| Put explicit cost, ownership, and approval boundaries around agent work.    | Create and manage agents from Claude or Codex through MCP.                                 |
+| Keep execution, data, and credentials in infrastructure your team controls. | Choose OpenAI, Anthropic, or Bedrock-backed models per agent.                              |
+| Turn one-off experiments into scheduled, observable operating processes.    | Attach scoped tools, secrets, schedules, memory, and sub-agents.                           |
+| Keep approval and action authority explicit for consequential outcomes.     | Run optional coding tasks in isolated Codex or Claude Code workers that produce draft PRs. |
+
+The result is not another autonomous black box. It is a way to make agent work
+repeatable, bounded, inspectable, and reviewable.
+
+## Why Wardby instead of another agent runner?
+
+Agent tools solve different layers of the problem. Wardby does not need to
+replace them: it provides the self-hosted operating boundary around agents and
+the work they perform.
+
+| Category                   | What it primarily helps you do                              | What Wardby adds                                                                           |
+| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| **Agent frameworks**       | Build reasoning loops, tool calls, and multi-agent logic.   | Persistent ownership, schedules, budgets, credentials, run history, and lifecycle control. |
+| **Coding agents**          | Plan, edit, and test code for an interactive task.          | Isolated managed workers, admission-time budgets, scoped access, and optional draft PRs.   |
+| **Hosted agent platforms** | Start quickly on infrastructure operated by another vendor. | A control plane, data, credentials, and execution boundary you can host in your own cloud. |
+| **Workflow orchestrators** | Make application jobs durable, retryable, and observable.   | Agent-specific policy, model usage, capabilities, budgets, and MCP-native operations.      |
+
+The distinction is control, not just execution. Wardby reserves spend before a
+run starts, grants only assigned capabilities, records what happened, and
+keeps downstream action authority separate from the worker that produced the
+result.
+
+## One control plane, the full lifecycle
+
+![Wardby workflow: ask in Claude or Codex, define an agent through MCP, govern it in Wardby, execute it in isolation, and apply review policy to its outcome](docs/assets/wardby-workflow.svg)
+
+Claude and Codex are the operator experience. Wardby is the durable system
+behind them: it stores agent definitions, triggers work, reserves budget,
+mediates tools and credentials, records outcomes, and exposes run state through
+MCP.
+
+## A full-cycle agent from one conversation
+
+Ask your MCP client:
+
+> Create a weekly dependency-maintenance agent for this repository. Use Claude
+> Code, put it in a $5 weekly budget group, run it Thursday at 2:00 AM, execute
+> the test suite, and open a draft pull request when a safe update is ready.
+> Never merge automatically.
+
+Claude or Codex can translate that request into Wardby MCP operations such as
+`create_budget_group`, `create_agent`, `attach_tool`, `trigger_agent`, and
+`get_run`. After that:
+
+1. The scheduler or an event creates an owned run.
+2. Wardby reserves budget and resolves only the capabilities assigned to that
+   agent.
+3. An isolated coding worker receives the task without receiving the GitHub App
+   credential or provider API key.
+4. The worker changes the checkout and runs its approved checks.
+5. Trusted finalization validates the diff, pushes a unique branch, and opens at
+   most one draft pull request.
+6. A person reviews and decides whether anything merges.
+
+The same agent can be updated, paused, triggered, inspected, or deleted from an
+MCP conversation. The CLI remains available as the bootstrap and operations
+floor.
+
+## Agent ecosystems you can compose
+
+Wardby provides lifecycle primitives rather than prescribing one fixed catalog.
+These are example systems a team can build and manage through MCP:
+
+| Agent system             | Typical cycle                                                      | Governed outcome                     |
+| ------------------------ | ------------------------------------------------------------------ | ------------------------------------ |
+| **Delivery pipeline**    | Work request → plan → implementation → tests → review              | Optional draft feature or bug-fix PR |
+| **Security maintenance** | Scheduled scan → assess → patch → verify                           | Report or optional remediation PR    |
+| **Architecture review**  | Inspect codebase → score risks → prioritize findings               | Architecture and risk report         |
+| **QA coverage**          | Map journeys → rank gaps → add tests → run suite                   | Coverage report or optional test PR  |
+| **System monitoring**    | Receive signal → investigate → correlate → escalate                | Actionable defect or incident report |
+| **Project tracking**     | Read delivery data → compare plan, cost, and progress → flag drift | Portfolio or program update          |
+
+Agents can stand alone or be connected as bounded sub-agents. Shared budget
+groups can cap the combined spend of an ecosystem, while each agent retains its
+own model, tools, schedule, and run history.
+
+## Host it in your cloud
+
+The core does not import a cloud SDK. Jobs, model access, email, secrets,
+authentication, and object storage sit behind provider interfaces so operators
+can choose the infrastructure boundary that fits their environment.
+
+| Target                               | Current support                                                                                                                                 |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Local Docker, VM, or on-premises** | Portable PostgreSQL and container workflow for development and self-hosting.                                                                    |
+| **Production container baseline**    | Separate runtime and migration images plus a Compose/Caddy reference boundary.                                                                  |
+| **GCP**                              | Terraform reference for the control plane on Cloud Run and Cloud SQL. Cloud-native coding jobs and production observability are follow-on work. |
+| **AWS**                              | The portable runtime and Bedrock model adapter are available; a native AWS deployment module is planned.                                        |
+| **Other clouds**                     | Run the production image and provide equivalent PostgreSQL, secrets, ingress, egress, and monitoring controls.                                  |
+
+Start with [deployment targets](deploy/README.md), the
+[portable production boundary](deploy/production/README.md), or the
+[GCP setup guide](deploy/gcp/SETUP.md). Reference deployments are examples,
+not a requirement to use one vendor.
+
+**A complete deployment runs more than `wardby mcp`.** `mcp` serves the MCP
+surface; the scheduler that fires due agents and the reconciler that recovers
+orphaned runs live in `wardby scheduler`. Run **`wardby serve`** to get all three
+in one process. It is the container image's default command and what a
+single-container deployment (Cloud Run, a lone VM) should run. Alternatively,
+run `mcp` and `scheduler` as two processes, as `deploy/production/compose.yml`
+does. Running `mcp` alone logs a startup warning if enabled schedules exist
+that nothing will fire.
+
+## Bring your own observability
+
+The coding proxy can expose standard Prometheus metrics at `/metrics` when
+`METRICS_BIND` is configured. Collection is pull-based: keep the endpoint on a
+private network and give only your chosen collector access to it.
+
+| Destination                      | Integration path                                                                                                                                                                                                                                   |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Local Prometheus and Grafana** | The included Compose profile provisions Prometheus, Grafana, and dashboards for requests, errors, latency, cost, budgets, runs, and actual spend.                                                                                                  |
+| **AWS CloudWatch**               | Configure the [CloudWatch Agent's Prometheus collector](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Agent-PrometheusEC2.html) to scrape Wardby over private EC2, ECS, or EKS networking and import selected metrics. |
+| **Google Cloud Monitoring**      | Configure the [Google Cloud Ops Agent Prometheus receiver](https://cloud.google.com/stackdriver/docs/managed-prometheus/setup-opsagent), or a Managed Service for Prometheus collector, to scrape the private endpoint.                            |
+| **Other monitoring platforms**   | Use any collector or hosted service that accepts the Prometheus exposition format.                                                                                                                                                                 |
+
+Run the local proof without making a paid model request:
+
+```sh
+npm run observability:up
+npm run observability:smoke
+npm run observability:down
+```
+
+The included cloud deployments do not yet provision AWS or GCP collectors.
+Current metrics primarily cover the coding proxy; application/MCP metrics,
+production alerts, and SLOs remain operator responsibilities. See the
+[observability guide](docs/observability.md) for boundaries and retention.
+
+## Security boundaries
+
+- **Hard budget enforcement:** per-agent limits and shared daily, weekly, or
+  monthly budget groups stop additional model work when the cap is reached.
+- **Scoped capabilities:** tools, secrets, datastores, and sub-agents are
+  attached explicitly and checked against the authenticated owner.
+- **Sandboxed tools:** native agent tools execute inside a constrained QuickJS
+  environment with controlled fetch and secret bindings.
+- **Isolated coding workers:** Codex and Claude Code run in hardened containers
+  with resource limits, protected paths, bounded output, and reviewed network
+  access.
+- **Credential separation:** workers do not receive provider credentials or the
+  GitHub App private key; trusted components proxy model use and finalize Git.
+- **Explicit action authority:** the worker that produces an outcome does not
+  implicitly gain authority to apply it. Current coding finalization creates a
+  draft pull request and does not auto-merge it.
+- **Protected remote MCP:** HTTP transport is an OAuth 2.1 resource server;
+  local stdio mode trusts the local operator.
+- **Sanitized operations:** lifecycle events and metrics exclude prompts,
+  repository content, credentials, diffs, and raw worker output.
+
+Read the [runtime architecture](docs/architecture-runtime.md),
+[coding-worker isolation model](docs/coding-worker-isolation.md), and
+[security deployment guide](docs/security-deployment.md) before enabling a
+production repository.
+
+Review policy is designed to support designated agents as well as people.
+Agent approvals will be recorded as workflow evidence; operators will decide
+whether that evidence permits an automated action or still requires a person.
+
+## Quickstart
+
+Requirements: Node.js 24 or newer, Docker, and one supported model-provider
+credential.
+
+```sh
+git clone https://github.com/wardby/wardby.git
+cd wardby
+npm ci
+cp .env.example .env
+```
+
+Edit `.env` and set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`. Generate a local
+secret-encryption key with `openssl rand -hex 32` and use it as
+`SECRET_APP_KEY`. Then initialize the local database and start the stdio MCP
+server:
+
+```sh
+npm run db:up
+npm run prisma:generate
+npm run prisma:migrate
+npm run cli -- mcp
+```
+
+Point Claude or Codex at `npm run cli -- mcp` with the repository as its working
+directory. The exact client configuration format differs, but both use Wardby's
+stdio transport locally. For shared or remote access, use Streamable HTTP with
+OAuth and the production boundary documented above.
+
+Once connected, ask the client to list the available Wardby tools, create an
+agent with a small budget, trigger it, and inspect the run. Coding-agent setup
+additionally requires a dedicated GitHub App, immutable worker images, and the
+proxy boundary described in the [local coding-agent setup guide](docs/coding-agent-setup.md).
+
+## What is implemented
+
+- MCP-first agent, tool, schedule, budget-group, secret, datastore, webhook,
+  run, and sub-agent management.
+- Scheduled and event-triggered native agents with OpenAI, direct Anthropic,
+  and Bedrock-Claude model routing.
+- Per-run budgets, shared budget groups, usage accounting, and cancellation.
+- QuickJS tool isolation with host allowlists and secret bindings.
+- Containerized Codex and Claude Code executors with trusted GitHub draft-PR
+  finalization.
+- In-process reconciliation and optional DBOS durable workflows.
+- Self-hosted or delegated OAuth for remote MCP access.
+- Prometheus metrics and provisioned Grafana dashboards for local operations.
+- Portable production images, a Compose/Caddy boundary, and a GCP control-plane
+  Terraform reference.
+
+This project is under active development. Run the
+[release verification](docs/release-verification.md) checks and review the
+[security deployment guide](docs/security-deployment.md) before production use.
+
+## Repository map
+
+```text
+src/core/       Agents, runner, scheduler, triggers, budgets, and sandbox
+src/mcp/        MCP transports, authentication, and management tools
+src/providers/  Swappable model, job, VCS, email, auth, secret, and storage seams
+src/coding-worker/ and src/claude-coding-worker/
+                Isolated Codex and Claude Code execution
+deploy/         Local, production-reference, observability, and cloud deployment
+prisma/         Schema and reviewed migrations
+docs/           Architecture, security, setup, and operator guidance
+```
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) for the license terms and
+[NOTICE](NOTICE) for attribution.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute and [SECURITY.md](SECURITY.md)
+to report a vulnerability privately.
+
+Built as an independent reimplementation. See [CLEANROOM.md](CLEANROOM.md).

package/bin/wardby.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+await import("../dist/wardby-bin.js");

package/deploy/local/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: wardby
+      POSTGRES_PASSWORD: wardby
+      POSTGRES_DB: wardby
+    ports:
+      - "55432:5432"
+    volumes:
+      - wardby-postgres-data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U wardby -d wardby"]
+      interval: 5s
+      timeout: 5s
+      retries: 12
+
+volumes:
+  wardby-postgres-data: