Architecture
From the agent-powered application at the top to the durable Rust engine at the foundation — each layer builds on the one below it.
Application
The application at the top of the stack. Hire agents and coding harnesses, then orchestrate the whole software-development lifecycle — plan, implement, review, test, merge, QA, and run retrospectives — as durable graphs that resume across crashes and reboots.
Application framework
Author Nano apps as code or model. Go code-first and Urban derives the executable model, job types, message correlation, and a generic worker from your code; go model-first and the authored BPMN model is the source of truth. Either way, one source of truth — no hand-wired orchestration.
IDE
The RAAD environment — a polyglot IDE to scaffold, run, and inspect agent applications on your workstation. Model-and-run, live traces, and the web console in one place.
Engine · foundation
The load-bearing runtime, written in Rust and compatible with the Camunda 8 API. Durable by default: on restart a graph resumes at the exact step it left off — completed (journal-committed) steps are never replayed. Delivery is at-least-once, so activities must be idempotent. Small enough to start on a Raspberry Pi.
Nano Workforce isn’t a faster coding agent — it’s a different layer. Here’s where it sits relative to the tools you already know.
| Capability | Interactive coding agentsCopilot CLI, Claude Code, OpenCode, Cursor, Aider | Autonomous SWE agentsDevin & hosted coding agents | Nano Workforce |
|---|---|---|---|
| Primary role | Edit code in a session | Complete one task autonomously | Orchestrate many agents into a delivery workflow |
| Interaction model | Interactive, human-in-the-loop | Fire-and-check, mostly hosted UI | Modelled graph; human only on escalation/approval |
| Unit of work | A prompt / a task | A task / a ticket | An issue → a graph of PRs |
| Multi-agent fan-out | No | Limited | Yes — levelized task graph |
| Durable across restart / failure | Ephemeral session | Vendor-hosted state | Yes — engine journal |
| Review-convergence loop | Manual | Varies | Built-in, multi-round, capped |
| Merge automation | You merge | Opens a PR | CI-aware merge loop |
| Model / provider | Provider-agnostic (mostly) | Proprietary / fixed | Provider-agnostic; agents are pluggable |
| Where it runs | Your workstation | Vendor cloud | Your machine — or across an HA fleet |
| Relationship to the others | Point tools — the hands that write code | Hires the tools on the left as workers | |
Categories blur and vendors move fast — this is an indicative positioning map, not a scorecard. The point is the axis: single-agent tools operate one session at a time; Nano Workforce coordinates many of them durably. For a head-to-head against named orchestrators, see the comparison on the home page.
OpenCode, Claude Code and the Copilot CLI are exactly the kind of worker Nano Workforce hires. Adopting Nano doesn’t replace your coding agent — it puts a durable orchestrator around it.
“The agents are external workers you hire (any coding-agent CLI harness, e.g. the GitHub Copilot CLI). Nano Workforce owns the orchestration; the agents do the work.” — Nano Workforce README
So the question isn’t “Nano or OpenCode?” — it’s “which agent do I want Nano to drive?” Swap the harness without rewriting the workflow; the plan / review / merge graph stays the same.
People ask how Nano relates to Effect, TypeScript’s structured-concurrency and typed-error runtime. They live on different axes — and they compose.
Effect is the best way to make one process robust: fibers, typed errors, and resource safety inside a running program. Nano makes the workflow robust: the same plan → review → merge graph survives the process dying, the machine rebooting, and a redeploy in the middle — then resumes at the exact step it left off. In-memory structured concurrency ends when the memory does; a durable graph doesn’t.
| Concern | Effect in-process | Nano durable |
|---|---|---|
| Unit of execution | Fiber (in one process) | Journalled graph step |
| Survives crash / reboot / redeploy | No — state is in memory | Yes — resumes at the last committed step |
| Retries & timeouts | Per run, in memory | Durable, at-least-once with idempotent recovery |
| Concurrency model | Fibers, first-class | Parallel & multi-instance branches; correlation |
| Error model | Typed error channel | Incidents & boundary events on the graph |
| Time horizon | Milliseconds – minutes | Seconds – weeks (timers, human tasks) |
| Where it runs | Any TS/JS runtime | Rust engine, Camunda 8 API compatible |
So it isn’t “Nano or Effect?” If you love the Effect model, keep it inside your workers — and let Nano carry the run across everything that outlives the process. We love that model enough that Urban’s own glue code uses a tiny, zero-dependency distillation of it:
“effectlite — a tiny, zero-dependency, Effect-like core for Urban glue code … the three Effect ergonomics we actually reach for: typed-errorResultwith generator do-notation, tagged errors with exhaustive matching, andscopedresource release — in ~100 lines with no runtime dependencies.” —@nanobpm/urban,src/effect
Nano is the load-bearing runtime; every layer above is optional and composes on top of it.