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.
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 workspace
On 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.
Each service owns a single responsibility
The current production topology aligns with the canonical runtime/domain architecture.
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 tools like Claude Desktop or Cursor 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.
Continue the technical deep-dive
The white paper covers the runtime contract, domain model, context compilation, the delivery and remediation workflows, validation gates, and the deployment model, with measured facts from the platform codebase.