An architecture that makes autonomous coding reliable and inspectable
CrewWork centers on a canonical Core runtime and independent domain services. It separates chat from non-chat execution, routes model calls through local or configured inference infrastructure, and projects all run state through explicit event contracts.
work item
- submit a domain plans and submits a canonical work item
- admit the runtime applies policy, lease, and budget
- execute the inner runner works in its sandbox
- validate tests run against the changed workspace
- record results and artifacts persist with the run
- review a person reviews the change in the workbench
Every domain executes through one runtime contract
Domains submit canonical work items to the runtime. Runtime owns policy checks, retries, budgets, persistence, and artifact publication. The lifecycle of one work item:
- plan
- Domain trigger → Domain planner → Canonical work item → Runtime policies
- execute
- Lease and workspace lock → Budget and retry policy → Inner runner: delegated backend by default, in-process loop as fallback → Model transport to the configured host
- validate
- Repository diff in the git worktree → Validation and tests against the changed workspaceOn failure, a diagnostics packet feeds a guided repair-and-retry loop.
- land
- Persist result and artifacts → Execution events to the Redis stream → Domain projections → Workbench surfaces over WebSocket
Hotfix and repair share one runtime contract
Error ingestion, remediation generation, and validation use the same runtime contract. Project fixes land on an isolated delivery branch; platform self-repair opens a draft pull request instead, so every fix stays inspectable and policy-governed.
diagrams/error-triage.svgExpand
Each service owns a single responsibility
The current production topology aligns with the canonical runtime/domain architecture.
| Service | Responsibility | Built on |
|---|---|---|
| Core API | Transport layer for auth, repos, runs, Infinite Coder, hotfix, search, diagnostics, suggestions, preview, and event projection APIs, plus a spec-compliant MCP server endpoint so external MCP clients can read files, search code, and inspect git status on a connected project. | Python 3.12, FastAPI, async SQLAlchemy |
| Core Runtime | Canonical execution authority for work items: leases, budgets, retries, persistence, artifacts, and canonical event envelopes, plus a durable outbox that reliably delivers on-call escalation and webhook notifications across restarts. | core/runtime/* |
| Model Transport and Routing | Execution, chat, and structured-output clients behind provider-neutral transport contracts, with workload-aware routing across configured local or OpenAI-compatible endpoints for code generation, chat, embeddings, and extraction. | core/runtime/* + core/engine/* |
| Domain Services | 19 independent domain packages acting as planners and projectors over the shared runtime: Infinite Coder delivery, hotfix, platform self-repair, search, suggestions, diagnostics, action items, preview, projects, git, users, webhooks, realtime, secret management, organizations, releases, runs, CrewMate, and console. | core/domains/* |
| Task Queue Workers | Three dedicated worker pools claim and execute durable tasks through canonical runtime paths: an indexing pool for code intelligence and provisioned test runs, an autonomous pool for Infinite Coder, PR review, and release builds, and a single isolated pool reserved for platform self-repair. | Postgres-backed queue + 3 worker pools (indexing, autonomous, self-repair) |
| Events Service | Internal Redis Streams event bus for service-to-service fanout and replay, with consumer groups and dead-letter handling. Browser activity streams are served separately through the authenticated /ws endpoint on the Core API. | HTTP + Redis Streams |
| Container Orchestrator | Single Docker control plane for the platform: preview lifecycle (framework detection, start/stop, logs, failure handoff), isolated validation jobs and matrix runs (a provisioned multi-stack test engine and the security scanner suite, both network-isolated), agent runner container sessions, and container maintenance. The only service with Docker socket access, guarded by its own service token. | Docker API + orchestration service |
| PostgreSQL | Primary persistence for domain state, runtime attempts, context artifacts metadata, and the symbol-relationship graph. | PostgreSQL 15 (asyncpg + SQLAlchemy) |
| Qdrant | Schema-versioned vector store for code intelligence retrieval, with on-disk vectors and payload, cosine distance, and stable point IDs for idempotent reindexing. | Qdrant |
| Redis | Event streams, transient coordination, counters, and cache primitives. | Redis 7 |
| Artifact Storage | Durable storage for logs, diffs, summaries, and validation outputs with retention and redaction policies. | Filesystem volume + core APIs |
| Release Pipeline | Builds a release OCI image from your exact source commit inside embedded gVisor BuildKit, signs the provenance attestation, and pushes it to an opt-in, intranet-only private registry. An outbound-only mutual-TLS release agent on each target host polls for jobs and deploys the signed image, with no inbound connectivity to the target. | gVisor BuildKit (runsc) + private OCI registry + mTLS release agent |
Design decisions favor reliability over speed
Each one also keeps the system inspectable, even at some cost to development speed.
- Core Runtime Execution All non-chat work executes through one Core runtime contract. Chat runs on a separate transport, so a conversational surface can never become a second completion authority.
- Evidence-Based Completion Completion is decided on platform-sourced evidence only. A model’s own claim of success or failure is never admissible, and missing evidence defaults to not-success rather than a pass. Implementation and repair steps must produce a real, non-empty change set, and HTTP and browser-flow acceptance probes against the live preview add an independent signal alongside test and validation results before anything is marked done.
- Delegated Inner-Runner Execution Behind the engine facade, eligible implementation and repair steps are dispatched by default to a delegated inner-runner execution backend. An operator kill switch and a per-step eligibility check both have to agree before that dispatch happens; either one falls the step back to the in-process execution loop, so ineligible work never silently loses its safety behavior.
- Durable Same-Reason Breaker A durable breaker tracks the most recent unbroken run of same-reason failed attempts straight from the persisted attempt history rather than an in-memory counter. Because the count lives in the database, it survives lineage replacement, plan resynthesis, and process restarts, so a stuck step cannot loop forever just because the process running it restarted.
- One Kernel Isolation Boundary Every untrusted or candidate execution path, whether preview containers, validation and matrix jobs, agent runner sessions, or release image builds, runs inside a gVisor (runsc) kernel-isolated sandbox with hard CPU, memory, and process-count caps. One isolation boundary covers the whole platform instead of a patchwork of per-workload controls.
- Postgres-backed Task Queue Leases, retries, and task state live in Postgres and survive worker restarts, without a separate queue broker.
Scaling stays operational, not architectural
CrewWork runs as a local-first platform and scales operationally: increase worker concurrency, route model traffic across configured model hosts and workload pools, and isolate heavy workloads by domain, without duplicating execution semantics.
See whether CrewWork fits your work.
CrewWork is built and running, and not yet generally available.
- worth discussing
- The errors and backlog you would hand off
- Where your source has to stay
- The evidence you would need to trust a change