nap
Describe an app. Step away. Come back to a project with evidence behind it.
nap is an open-source AI app builder for software work that needs more than a model response. You
describe an app in chat. An agent writes it into an isolated sandbox, serves a live preview, commits
the workspace, and runs the project's own checks before nap calls the work verified.
Use nap as an app, a local runtime, or a reference implementation for long-running coding-agent
systems.
A model saying "done" is a claim. A passing checkpoint is evidence.
Live demo · Docs ·
Architecture ·
NapBench
The GIF is a 22-second cut from a real two-minute session. It shows the prompt, sandbox tool calls,
project checks, verification, and the resulting app. The full session is on the docs page.
What nap does
- Builds in an isolated workspace. The agent reads and edits files in an E2B sandbox. A Vite
server exposes the project through a live preview while the turn runs.
- Keeps work after the browser goes away. The API admits a turn to a durable Postgres queue. A
worker executes it, so closing a tab or deploying the API does not cancel the work.
- Streams from a durable event log. Events are appended before they are published. A reconnect
asks for everything after its last sequence number, so it can catch up without duplicates or gaps.
- Separates commits from checkpoints. Every file-changing turn creates a commit. Only a commit
that passes the discovered checks becomes a checkpoint, which is nap's last known-good state.
- Repairs bounded failures. A failed check opens another turn with the failure in its context.
The repair budget has a hard limit.
- Puts idle projects away. nap stores the Git repository, destroys the idle sandbox, and restores
the project when you return.
How a prompt becomes a verified project
prompt
↓
durable job → worker → agent in sandbox → commit
↓
project checks
↙ ↘
pass fail
↓ ↓
checkpoint bounded repair turn
The job and its transcript come from the same append-only event log. That gives nap one answer to
what happened, what was verified, and where to continue. The full event model, job lifecycle, and
verification rules are in the technical docs.
Evidence, with scope
These are historical measurements, not a promise about every deployment. The load test used fake
model and sandbox providers, so it measured nap's queue, event log, workers, and WebSocket path. The
real-model measurements tested the verification path and did not establish a model-score improvement.
| Result | Measurement |
|---|
| Concurrent turns in the latest cluster run | 100 |
| Turns completed in that run | 2,422 |
| Job, turn, and verification completion | 100% |
| Sequence gaps, duplicate events, WebSocket failures | 0 |
| Event delivery at 100 concurrent turns | 20 ms p95 |
| Fast local suite at this revision | 3,982 tests in 288 files |
The latest cluster run included 231 mid-turn reconnects. It ran on 24 August 2026 after an earlier
run on 23 August. Read the cluster report and the single-process baseline
for the test profile, caveats, and comparison.
The verification measurements covered 12 real runs and cost $0.15 in total. They found and fixed a
real verifier blind spot, but the sample was too small to support a claim about score improvement.
See the first measurement and the
re-measurement.
Run bun run test:fast to reproduce the local-suite result. The cluster numbers use fake model and
sandbox providers. They describe the deployment path, not production model or sandbox capacity.
Try it without credentials
The runtime has fakes for external services, so you can exercise the core loop locally without
Docker, API keys, network access, or spend.
bun install
bun run test:fast
bun run harness "build a todo list"
bun run ws:smoke
The harness prints the event stream for one complete turn. The smoke test drives the WebSocket path
over a real socket. test:fast runs the unit, type, and web suites without Postgres.
Run the full app locally
You need Bun, Docker, an E2B key, a model-provider key, and a
Cloudflare R2 bucket for snapshot storage.
bun install
docker compose -f infra/docker-compose.yml up -d
cp apps/api/.env.example apps/api/.env
Fill in the required values in apps/api/.env. For a local worker setup, also set:
NAP_EVENT_BUS=postgres
The example file documents each variable. The API validates its configuration at startup, including
the database, model provider, authentication, key encryption, and snapshot storage settings.
Start the processes in separate terminals:
bun run db:migrate
bun run dev # web: http://localhost:3000, API: http://localhost:3001
bun run dev:worker # claims queued turns and runs them
# bun run dev:reaper # optional locally; puts idle projects away
Open http://localhost:3000, describe the app you want, and watch the agent
work. The worker is required for a turn to execute. The reaper is optional in development.
Every real turn uses a model call and a sandbox. Use the fake harness for a free local run. Use
--real only when you intend to spend money:
bun run harness --real "build a todo list"
bun run napbench --real --suite=all
Run the checks
bun run test:fast # unit, type, and web suites; no Docker
bun run test # all TypeScript suites; the db suite needs Docker
bun run typecheck # workspace and root TypeScript checks
bun run lint # Biome
bun run build # production builds
The Python benchmark harness has its own gates:
bun run lint:py
bun run test:py
Use bun run test, not bun test. Bun treats test as its own built-in command and skips the
repository's Vitest project configuration.
Repository map
| Path | Role |
|---|
apps/web | Next.js interface: chat, transcript, and live preview |
apps/api | Hono API, WebSocket streaming, authentication, admission, worker, and reaper processes |
apps/napbench | CLI that runs NapBench against the agent and real or fake infrastructure |
packages/runtime | Turn lifecycle, jobs, commits, verification, checkpoints, and continuation |
packages/agent | Model loop, its sandbox-backed tools, and the helpers it can hand a search to |
packages/context | Prompt assembly, token budgets, and truncation |
packages/sandbox | Sandbox, filesystem, command, and preview ports plus the E2B adapter |
packages/db and packages/storage | Postgres event data and Git bundle snapshots in R2 |
packages/verify and |
Architecture in one picture
Browser
│ HTTP + WebSocket
▼
API process ──► Postgres queue ──► Worker process ──► Runtime ──► E2B sandbox
▲ │ │ │
└──── event log ◄──┴──────────────────┴───────────────┘
Reaper process: snapshots idle projects, reconciles capacity, and closes orphaned turns.
The API serves and admits work. The worker executes turns. The reaper handles cleanup. They share
one composition but have separate responsibilities, which lets a deployment scale and drain them
independently. The architecture docs explain the
package boundaries and invariants. The ADRs explain decisions that are expensive to
reverse.
Current scope
The durable job loop, worker queue, verification and repair, checkpoints, project continuation,
NapBench, and the multi-process deployment are implemented. nap is still deliberately focused:
- No multi-agent orchestration.
- No built-in billing.
- No Monaco editor or terminal in the web app.
- User sandboxes still run through E2B rather than Kubernetes pods.
- Long-term memory is an interface with a no-op implementation.
Those boundaries have extension points in the code. See the full docs,
docs/DEPLOY.md, and docs/NAPBENCH.md for operational and
benchmark details.
Read next
License
MIT © 2026 Manas Raghuwanshi
