Warren runs agent harnesses as isolated, observable workloads on infrastructure you control. It owns the workspace, run lifecycle, spend limits, live events, intervention, recovery, and Git delivery.
Warren becomes useful when an agent run stops being a terminal session and starts being a workload. The run may need to continue unattended, repeat on a schedule, survive failure, or become visible to someone besides the person who started it.
You can run warren alone. A small, trusted engineering team can share one deployment and one trust boundary today.
repository + task
│
▼
isolated agent workload
│
├── live events
├── spend and concurrency limits
├── steering and cancellation
└── recovery and cleanup
│
▼
pushed branch ──► optional pull request
- Workspace. Each run starts from a fresh worktree or clone on its own branch.
- Isolation. Runs operate under
bwrap, in a sibling Docker container, or in a Kubernetes pod. - Lifecycle. Warren dispatches, monitors, cancels, finalizes, and cleans up each run.
- Control. Streams stay live, steering reaches supported harnesses, and spend caps hold during execution.
- Recovery. Watchdogs reconcile lost processes and pods. Finalization salvages work before teardown when possible.
- Git delivery. Agents commit their changes. Warren manages Git credentials, branch construction, push, and configured PR creation.
- History. Run state, events, cost, token use, and outcomes persist behind one HTTP API, CLI, and UI.
The core guarantee is a pushed workspace branch. Project settings can add PR creation, tracker updates, previews, and other reactions.
A harness is the coding-agent process warren drives. A runtime is the place where that workload runs.
Warren's run model supports any harness with a Warren runtime adapter. The current distribution includes adapters for Pi and Claude Code. Agent roles such as planner, healer, and PR fixer compose prompts and policy on top of those harnesses.
Three runtime providers implement the same lifecycle:
| Runtime | Isolation boundary | Best fit |
|---|---|---|
local |
bwrap on Linux, sandbox-exec on macOS |
One host |
docker |
Sibling container | Docker hosts and custom agent images |
k8s |
Pod per run | Cluster scheduling and admission control |
Warren fits individual operators and small, trusted teams that already use coding agents and want the runs off a developer terminal. It is especially useful when code, model credentials, compute, and run history must remain on infrastructure the operator controls.
The current boundary is explicit:
- One deployment serves one operator or trusted team.
- One bearer credential guards the operator surface.
- Warren has no named users, RBAC, or per-user attribution.
- The shipped forge supports GitHub PAT and GitHub App credentials.
- Warren is self-hosted software, not a hosted SaaS.
See Security for the full threat model and Roadmap for future work.
The shortest complete path uses the shipped Compose file and the local runtime on a Linux Docker host. Compose includes the security flags that nested bwrap needs.
git clone https://github.com/jayminwest/warren
cd warren
cp .env.example .env
$EDITOR .env # set two secrets plus WARREN_GIT_AUTHOR_NAME/EMAIL
docker compose up -d
docker compose logs warren | grep mintedOperatorTokenOpen http://localhost:8080, paste the minted token, add a GitHub repository, and dispatch a run. Warren streams the events and pushes the result branch.
For the sibling-container topology, custom agent images, persistent paths, and macOS Docker Desktop requirements, use the Docker self-host guide. For Kubernetes, use the Kubernetes runbook.
A fresh install needs no other os-eco tool. Projects can opt into persistent Mulch memory or the Seeds issue tracker by committing their data directories.
The audit log and judge are optional, out-of-process extensions. They do not run in a base warren installation:
extensions/audit-log/exports append-only JSONL run activity.extensions/judge/scores finished runs against a versioned rubric and stores verdicts separately.
See Extensions for their contracts and current packaging limits.
- First run
- Docker self-hosting
- Kubernetes operations
- Operations and observability
- Architecture
- Project configuration
- Preview environments
- PR templates
- CLI reference
- HTTP API and OpenAPI
- TypeScript SDK
- Contributing
ROADMAP.md owns warren's direction and sequencing. It tracks what is in flight, what comes next, what has shipped, and what stays out of core.
Stable (0.18.0). The run lifecycle is in continuous use on GKE. It operates against real repositories, including this one. app.warren.run exposes the read-only run history and event streams without a login.
Warren is pre-1.0. Unit, integration, and scenario tests exercise the run lifecycle. The current shared-token trust model remains a deliberate limit.
MIT. See LICENSE.