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.
Get started
Run locally in five minutes
Requirements: Node.js 24 or newer, Docker, and an OpenAI or Anthropic API key. You do not need to clone Wardby or install PostgreSQL.
-
From the project where you want to use Wardby, run:
npx --yes @wardby/cli@latest quickstart -
Follow the prompts to choose a provider, start PostgreSQL, create a
$1demo agent, optionally set up a coding agent and a review agent against a local git repository (no GitHub App needed), and optionally connect Codex or Claude Code through MCP. -
Verify the installation:
npx --yes @wardby/cli@latest doctor
Quickstart keeps credentials and local state under .wardby/ in the current
project. Read the local getting-started guide
for unattended setup, lifecycle commands, MCP configuration, and cleanup.
Develop Wardby from source
Clone the repository only when you want to contribute to Wardby, inspect its deployment assets, or build images yourself:
git clone https://github.com/wardby/wardby.git
cd wardby
npm ci
npm run build
npm test
Continue with CONTRIBUTING.md for the development database, migrations, required checks, and contribution expectations.
Deploy for a team
- Follow the GKE guide for the supported Google Cloud reference deployment.
- Start from the self-hosted container deployment reference for Docker Compose on a VM or on-premises host. Supply the surrounding production infrastructure and controls yourself.
- Follow Bring your own identity provider to protect remote MCP with your existing OAuth/OIDC provider.
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.
One control plane instead of scattered automation
Teams often begin with Claude Code or Codex on developer machines, repository-specific automation, and separate provider dashboards. As adoption grows, agent definitions, ownership, credentials, budgets, schedules, and run history become fragmented across tools and repositories.
Wardby gives every Wardby-managed agent one durable operational identity: who owns it, why it exists, what it may access, when it runs, what it may spend, and what outcome it produced.
Wardby provides the control plane around the model:
The result is not another autonomous black box. It is a way to make agent work repeatable, bounded, inspectable, and reviewable.
Where Wardby fits
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.
The distinction is governed work, not just model calls or execution. Rather than assembling a gateway, scheduler, agent catalog, budget service, capability registry, and run database, Wardby provides one operating boundary. It 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.
Scope: Wardby's inventory and budget views cover work managed through Wardby. Provider reconciliation and unmanaged-agent discovery are required before those views can represent every AI agent or expense in an organization.
One operational contract, the full lifecycle
Claude and Codex are the operator experience. Wardby is the durable operating boundary between intent and agent execution: it stores agent definitions, triggers work, reserves budget, mediates tools and credentials, records outcomes, and exposes run state through MCP. Nothing runs until identity, policy, and available budget agree.
Governed shared state for agent teams
Named Wardby datastores let related agents exchange persistent structured data without sharing an unrestricted database credential. Datastores are owned and attached to agents explicitly; each sandboxed tool can reach only approved bound names and key prefixes.
A planner can publish a feature plan, a builder can record implementation state, and a reviewer or QA agent can add findings to the same governed workspace. Datastores provide bounded coordination state, not a replacement for authoritative source systems or searchable agent memory.
Real services for real tests
A coding run can have the services its tests need. The repository declares them on its base branch:
services:
postgres: "16"
Every run then gets its own fresh database next to it, on the Kubernetes or
Docker launcher, with DATABASE_URL set in the agent's shells. Images come from an
admin-managed catalog pinned by digest, each agent is allowed only the services
its owner lists, and the run's network policy does not change. See
coding services.
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:
- The scheduler or an event creates an owned run.
- Wardby reserves budget and resolves only the capabilities assigned to that agent.
- An isolated coding worker receives the task without receiving the GitHub App credential or provider API key.
- The worker changes the checkout and runs its approved checks.
- Trusted finalization validates the diff, pushes a unique branch, and opens at most one draft pull request.
- A person reviews and decides whether anything merges.
The same agent can be updated, paused, triggered, inspected, or deleted from an
MCP conversation, and so can its sandboxed tools: update_tool fixes a tool's
code in place for the next run, and delete_tool removes one you no longer
need. The CLI remains available as the bootstrap and operations
floor. The result is autonomy with a receipt: an owned run with bounded spend,
assigned capabilities, durable status, and a reviewable outcome.
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:
Builders can vary. The controls do not. Each system inherits the same budget, capability, identity, evidence, and review contract.
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
Bring your providers. Keep your infrastructure. Govern agents in one place.
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. Models, coding executors, cloud platforms, and observability systems can change independently instead of defining the agent architecture. This reduces control-plane lock-in without pretending that source control, model providers, or monitoring systems disappear.
The kind harness
is for local Kubernetes testing, not production deployment.
Start with deployment targets, the self-hosted container deployment reference, or the GKE getting-started guide. Reference deployments are examples, not a requirement to use one vendor.
For a single-container deployment, run wardby serve to start MCP, the
scheduler, and reconciliation together. Split deployments can run wardby mcp
and wardby scheduler separately; mcp alone does not fire schedules. See the
deployment guides above for the complete process boundary.
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.
Run the local proof without making a paid model request:
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 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.
Group caps apply to native and coding runs alike, whether scheduled,
webhook-, MCP-, host-event- or sub-agent-triggered: a coding run reserves at
most what its group has left and is refused (
budget_group_exhausted:<period>) when nothing is left. A live run still in flight holds its unspent reservation against the group, so concurrent top-level runs cannot each claim the same remainder (native runs are served first come, first served). Known limit: within one sub-agent run tree, a parent's in-progress spend is not yet visible to its child's budget. - Scoped capabilities: tools, secrets, datastores, and sub-agents are
attached explicitly and checked against the authenticated owner. Agents are
private until their owner shares them (
grant_accessat read, execute or write), and one owner's secrets, datastores, repositories and sub-agents never reach another owner's agent without a grant on that exact resource. - 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, and bounded output. Egress is limited to the coding proxy; runs can also reach explicitly declared services inside their isolated run environment.
- Allowlisted package installs: a coding agent's
npm/pipinstalls are limited to an approved dependency graph, served through the same proxy with a minimum release age, an OSV vulnerability audit, and every package recorded, for Codex and Claude Code runs alike (pip on thenode-pythontoolchain). - 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, coding-worker isolation model, native sandbox guide (0.5.4+), and security deployment guide 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.
Optional npm installation
The npx quickstart above requires no installation. To pin Wardby as a local
project dependency instead:
npm install @wardby/cli
That install is audit-clean: the published package carries no Prisma CLI,
@prisma/config, deepmerge-ts, or mysql2, so npm audit reports nothing
and no overrides entry is needed in your own package.json.
wardby quickstart and wardby doctor separately fetch the pinned Prisma CLI
([email protected]) on demand via npx to run migrations, so the machine running
them needs npm registry access at that moment. See
Images and dependencies
for the repository's own dependency-override policy.
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, priced and routed from an admin-editable
model catalog (
list_models,get_model,set_model,disable_model,reset_model). - Per-run budgets, shared budget groups, usage accounting, and cancellation.
- QuickJS tool isolation with host allowlists, secret bindings, and brokered secrets (0.6.0+) that tools send to chosen hosts without reading (guide).
- Containerized Codex and Claude Code executors with trusted GitHub draft-PR finalization.
- Optional, outbound-only Slack workflow notifications (0.6.0+): link a channel to a Jira project or an agent to follow a card from pickup to merge.
- Per-run PostgreSQL, Redis and MySQL services for coding runs, declared in the repository and allowed per agent, for Codex and Claude Code runs on the Kubernetes and Docker launchers.
- 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 GKE Autopilot Terraform reference deployment.
This project is under active development. Run the release verification checks and review the security deployment guide before production use.
Repository map
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 for the license terms and NOTICE for attribution.
See CONTRIBUTING.md to contribute and SECURITY.md to report a vulnerability privately.
Built as an independent reimplementation. See CLEANROOM.md.
