Expected Behavior
The README "Local development" section lists every local prerequisite and gives copy-pasteable steps. It currently says: "Configure the variables in .env.example, then: pnpm install && pnpm dev" and "there is no separate local-only runtime."
Current Behavior
Two things bite on a fresh clone:
1. Docker is silently required. agent/agent.ts sets experimental.tasks: true, so the first chat message that starts a task runs in an eve sandbox. On Vercel that is Vercel Sandbox; locally it is Docker — the dev log shows [eve:dev] eve: opening sandbox session "root" on backend "docker"... and a container eve-sbx-ses-docker-… appears. Nothing in the README, .env.example, or AGENTS.md mentions Docker, so on a machine without Docker running the first agent turn fails with no setup hint.
2. Which env file? Editing .env.example in place does nothing — Next.js / @next/env only load .env, .env.local, etc. .gitignore ignores .env* except .env.example, so the intended file is implied but never stated. KERNEL_API_KEY is required by lib/env.ts but is only mentioned indirectly via the Deployment section's marketplace note.
Possible Solution
- Add a prerequisites list to "Local development": Node 24, pnpm, Docker running (local eve task sandbox), a Neon database (see the related issue on the Neon-only driver), and a Kernel API key.
- Change the steps to
cp .env.example .env.local, then fill in BETTER_AUTH_SECRET, BETTER_AUTH_URL=http://localhost:3000, DATABASE_URL, DATABASE_URL_UNPOOLED, SECRET_ENCRYPTION_KEY, KERNEL_API_KEY, and run pnpm db:migrate before pnpm dev.
- Optionally have
pnpm dev check docker info up front and print a clear message.
Minimal Reproducible Example
- Fresh clone; follow the README literally (edit
.env.example, pnpm install, pnpm dev) → lib/env.ts throws on missing BETTER_AUTH_SECRET.
- Fix the env file, stop Docker,
pnpm dev, sign in, send any message that starts a task → sandbox open fails.
Context
First-run setup on 2026-08-27. Both were solvable by reading code, but each cost time that a two-line README change would save every new contributor.
Expected Behavior
The README "Local development" section lists every local prerequisite and gives copy-pasteable steps. It currently says: "Configure the variables in
.env.example, then:pnpm install && pnpm dev" and "there is no separate local-only runtime."Current Behavior
Two things bite on a fresh clone:
1. Docker is silently required.
agent/agent.tssetsexperimental.tasks: true, so the first chat message that starts a task runs in an eve sandbox. On Vercel that is Vercel Sandbox; locally it is Docker — the dev log shows[eve:dev] eve: opening sandbox session "root" on backend "docker"...and a containereve-sbx-ses-docker-…appears. Nothing in the README,.env.example, orAGENTS.mdmentions Docker, so on a machine without Docker running the first agent turn fails with no setup hint.2. Which env file? Editing
.env.examplein place does nothing — Next.js /@next/envonly load.env,.env.local, etc..gitignoreignores.env*except.env.example, so the intended file is implied but never stated.KERNEL_API_KEYis required bylib/env.tsbut is only mentioned indirectly via the Deployment section's marketplace note.Possible Solution
cp .env.example .env.local, then fill inBETTER_AUTH_SECRET,BETTER_AUTH_URL=http://localhost:3000,DATABASE_URL,DATABASE_URL_UNPOOLED,SECRET_ENCRYPTION_KEY,KERNEL_API_KEY, and runpnpm db:migratebeforepnpm dev.pnpm devcheckdocker infoup front and print a clear message.Minimal Reproducible Example
.env.example,pnpm install,pnpm dev) →lib/env.tsthrows on missingBETTER_AUTH_SECRET.pnpm dev, sign in, send any message that starts a task → sandbox open fails.Context
First-run setup on 2026-08-27. Both were solvable by reading code, but each cost time that a two-line README change would save every new contributor.