Warren
Turn coding agents from terminal sessions into manageable infrastructure: isolated runs, lifecycle, spend limits, recovery, and Git delivery on compute you control.
- Source repo
- jayminwest/warren
- Stars
- ★ 503
- Last updated
- 2d ago
- License
- MIT
- Primary language
- TypeScript
- FA score
- 76/100 · Good
At a glance
- How it runs
- Works with
- Universal · cross-platformClaude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A solo maintainer of several repositories who wants coding agents working overnight unattended instead of occupying a developer terminal
- Not a fit if
- Teams that need named users, RBAC, or per-user attribution
- Users who want a hosted SaaS rather than self-hosting on their own infrastructure
- Teams whose primary forge is GitLab or Azure DevOps and who won't enable WARREN_FORGE
- Source review
- 76/100 · Good
What does this agent do, and when should you use it?
Warren is a self-hosted control plane that treats coding-agent runs — from harnesses like Claude Code and Pi — as infrastructure workloads rather than one-off terminal sessions. Each run starts from a fresh worktree or clone on its own branch inside a sandbox boundary the operator chooses, while Warren handles dispatch, monitoring, steering, cancellation, recovery, and cleanup. It enforces spend and concurrency caps, persists run state, events, cost, and token usage, and guarantees one core output: a pushed workspace branch, optionally with a PR. Three runtime providers — local (bwrap/sandbox-exec), docker (sibling container), and k8s (pod per run) — implement the same lifecycle. Getting started takes an install script plus warren up; the project is at 0.19.3 under the MIT license and is already used continuously on GKE against its own repository.
Warren takes a repository plus a task and dispatches an isolated agent workload: each run starts from a fresh worktree or clone on its own branch, confined to the sandbox the deployment chooses (bwrap/sandbox-exec, a Docker sibling container, or one Kubernetes pod per run). During execution it streams live events, enforces spend and concurrency limits, and supports steering and cancellation for supported harnesses; watchdogs reconcile lost processes and pods, and finalization salvages work before teardown. Once agents commit changes, Warren manages Git credentials, branch construction, push, and configured PR creation. All run history is exposed through one HTTP API (with an OpenAPI spec), CLI, and web UI, plus a TypeScript SDK. The current distribution ships adapters for Pi and Claude Code harnesses, with roles like planner, healer, and PR fixer composing prompts and policy on top. The default forge is GitHub via a GitHub App or static token; Azure DevOps Repos and GitLab ship behind WARREN_FORGE. Optional out-of-process extensions (audit-log, judge, campaign-controller, tracker-jira, tracker-ado) build on the HTTP surface.
- A solo maintainer of several repositories who wants coding agents working overnight unattended instead of occupying a developer terminal
- A small trusted engineering team sharing one Warren deployment to centrally review each run's duration, cost, and Git delivery inside one trust boundary
- Organizations that must keep code, model credentials, compute, and run history on infrastructure they control
- Ops teams scheduling agent runs in Docker or a Kubernetes cluster with admission control and an incident-response runbook (docs/RUNBOOK-K8S.md)
- Maintainers running scheduled or long-lived contribution activity through the campaign-controller extension under operator-approved policy
How do you install or deploy this agent?
On a fresh macOS or Linux machine, two commands get Warren running:
curl -fsSL https://warren.run/install | sh
warren upThe install script puts Bun and the warren CLI on your PATH when missing. warren up detects the sandbox runtime for your machine, asks for the one credential it still needs, and boots the server; your browser opens already logged in.
For a team deployment on a Linux Docker host, use Compose:
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 mintedOperatorTokenThen open http://localhost:8080, paste the minted token, and connect a GitHub repository.
How do you use this agent?
Once running, connect GitHub in the web UI, pick a repository, and dispatch the prefilled starter run. Typical flow: repository + task → isolated workload (live events, spend and concurrency limits, steering and cancellation, recovery and cleanup) → pushed branch → optional PR. Everything is stored under ~/.warren/; stop with Ctrl-C and restart with warren up. Run history is also queryable via the HTTP API, CLI, or TypeScript SDK. Operator paths include the Docker self-host guide, the Kubernetes runbook (docs/RUNBOOK-K8S.md), and the annotated .env.example environment reference.
What are this agent's strengths and limitations?
- Clear data sovereignty: code, model credentials, compute, and run history all stay on infrastructure the operator controls
- The lifecycle is guaranteed by software: watchdogs reconcile lost processes/pods, finalization salvages work, and the core promise is a pushed workspace branch
- Three runtimes (local/docker/k8s) implement one lifecycle, and
warren upauto-detects — changing topology doesn't change the run model - Full observability surface built in: live event streams, cost and token tracking, HTTP API with OpenAPI, CLI, web UI, and a TypeScript SDK
- The trust model is deliberately limited: one deployment serves one operator or trusted team behind a single bearer credential, with no named users, RBAC, or per-user attribution
- You must provide the infrastructure (a machine, Docker host, or K8s cluster) — it is self-hosted software, not a hosted SaaS; team deployments involve Compose secrets or cluster operations
- Pre-1.0 (0.19.3), and forge support is GitHub-first; GitLab and Azure DevOps require enabling WARREN_FORGE
- Actually running agents requires model credentials (subscription or API key) plus a GitHub App or static token
How does this agent compare with similar options?
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Warren This agent | 76 · Good | Self-hosted serviceFree + model costs | ★ 503 | 2d ago | TypeScript | Claude Code |
| Coder — Self-Hosted Cloud Development Environments and AI Agents | 62 · Some gaps | Self-hosted serviceFreemium | ★ 17k | today | Go | OpenAI API · Claude API |
| Codeg Multi-Agent Coding Workspace | 45 · Major gaps | Desktop appFree + model costs | ★ 4k | today | Rust | Codex · Claude Code · OpenAI API · Claude API |
| Kandev | 74 · Some gaps | CLIFree + model costs | ★ 974 | today | Go | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
SECURITY.md demonstrates thorough least-privilege design: run-scoped callback tokens, sandboxes never receive the operator token, 0600 credential files, repository code excluded from the control plane — full marks. Deducted on dependency security (dependency list shown but no lockfile audit or vulnerability-mitigation evidence) and rollback (only salvage/watchdog described, no mechanism to undo pushed changes); the shared non-expiring token and absent RBAC are self-declared trust-boundary limits.
Docs and config are internally consistent (0.19.3 across README and package.json, version-sync lint scripts) — 3. Dependency availability scored 2: Bun, Postgres, and optional forges are documented but no pinning/lockfile evidence appears. Failure messages scored 2: warren doctor, boot-fails-loud, and 401 handling are documented but error-path coverage is incomplete.
Audience and boundaries are unusually explicit (single operator or trusted team, no RBAC, self-hosted) — 3; the runtime matrix (local/docker/k8s, macOS/Linux) is complete. Trigger precision only 2: runtime auto-detection and harness dispatch selection are described at documentation level only, with no implementation detail in the provided files.
Information architecture (README→docs→runbooks→OpenAPI) and install notes are complete — 3; the known-limits section candidly lists shared tokens, no RBAC, pre-1.0 status. Deducted for: no CHANGELOG file in evidence, dual warren/wr bin naming, maintenance response times being promises from an unverified publisher.
Output usability is strong: pushed branch plus optional PR, multiple access channels (HTTP API, SDK, UI, CLI) — 3. Marginal value is clear (terminal session → observable workload). Cost-benefit 2: spend caps exist but self-hosted operational cost and resource footprint are not quantified.
Documents back-link claims to concrete changes via warren-xxxx identifiers — adequate (2). Cross-source corroboration 1: CI badge, real GKE usage, and the public app.warren.run instance cannot be verified within the provided files. Fact/inference separation is acceptable; test claims are explicitly not executed. This is a static review; confidence stays low.
- The shared operator token has no expiry, scopes, or independent revocation; loss equals full takeover — put an identity-aware proxy in front.
- The docker runtime mounts the Docker socket into the control-plane container, equivalent to root; never expose it to agent containers or untrusted networks.
- WARREN_AUTH=public exposes an unauthenticated projection of run records; enable only when every registered repository and prompt is safe to publish.
- Isolation is not safety: running against untrusted repository code can still combine credentials and network access; review runtime capabilities before dispatch.
- There is no per-user attribution or rollback mechanism; shared deployments leave actions unattributable and mistaken pushes recoverable only by hand via Git.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
The hardening patch. Local runs get a narrowed git-metadata sandbox, the run-scoped API token leaves every sandbox, and a batch of community fixes closes reap, dispatch, and stream gaps. Adds the GitLab forge arm, automatic-run admission limits, and stalled-turn detection. Added - Automatic run admission (#1297). WARREN_AUTOMATIC_MAX_CONCURRENT_RUNS (default 1) caps non-terminal automatic runs per instance: cron, scheduled seeds, the CI fixer, and plan-run coordination. WARREN_AUTOMATIC_RUN_WINDOW (HH:MM-HH:MM@IANA/Zone) limits automatic dispatch and retries to a local …View on GitHub ↗ -
Release notes excerpt
The auto-merge release. A project can now let warren arm GitHub auto-merge on the PRs it opens, with one pr.autoMerge block in .warren/config.yaml and a fail-closed policy that keeps protected paths in front of a human. That replaces the per-repo auto-merge.yml workflow and its secrets. The feature is off until a project opts in. The rest of the release is reliability work from three weeks of dogfood and contributor reports: a poison event can no longer kill a healthy run, harness files stay out of run branches, the judge stops wasting …View on GitHub ↗ -
Release notes excerpt
The upstream-loop release. The campaign controller closes its response loop (Phase 3, pl-096b): it reads review-bot findings, checks, and merge outcomes on the PRs it opened and turns them into bounded follow-up runs, body refreshes, and comment replies, each behind its own policy flag. Warren core learned to dispatch a run onto an existing branch to serve that loop. Azure DevOps arrived on both seams at once as the second in-core forge and the second external tracker. The dogfood deployment moved from Supabase to in-cluster Postgres with …View on GitHub ↗
FAQ
Does Warren itself cost anything?
Which coding agents does it support?
What happens when a run fails or a process is lost?
How do permissions work for a team?
Is GitHub required?
WARREN_FORGE setting.