vercel-labs/open-agents: a forkable reference app for background coding agents on Vercel

The problem: an agent that outlives the request

Most chat-with-your-code demos die when the HTTP request ends. The browser tab closes, the stream drops, and the work in progress is gone. Open Agents is aimed at that failure mode. The README describes it as an "open-source reference app for building and running background coding agents on Vercel", and the operative word is background: a run is expected to continue while nobody is watching.

The audience is narrower than the phrasing suggests. This is not a tool for a developer who wants an agent on their laptop. It is for teams building an agent product, or an internal agent, who want a working skeleton of the whole loop: authentication, a chat UI, a durable run, a virtual machine that clones a repository, and an optional pull request at the end. The repository is meant to be forked and adapted, not treated as a black box, so the value is in the shape of the system rather than in a polished binary.

Why the agent does not run inside the sandbox

The architecture is three layers, and the README states them directly: web, then agent workflow, then sandbox VM. The web app owns auth, sessions, chat and the streaming UI. The agent runs as a durable workflow on Vercel. The sandbox is the execution environment, holding the filesystem, a shell, git, dev servers and preview ports.

The design decision that matters is that the agent sits outside the VM and reaches in through tools: file reads, edits, search and shell commands. The README lists the consequences it is after. Agent execution is not tied to a single request lifecycle. The sandbox can hibernate and resume on its own schedule. Model and provider choices can change without touching the sandbox implementation, and the VM stays a plain execution environment instead of becoming the control plane.

That separation is also where the complexity lives. A tool call is now a round trip across a boundary, and the workflow has to persist enough state to reconstruct its position after a resume. The README notes that chat requests start a workflow run rather than executing the agent inline, that each turn can continue across many persisted workflow steps, and that an active run can be resumed by reconnecting to the stream for the existing workflow. Sandboxes expose ports 3000, 5173, 4321 and 8000, can optionally start from a configured base snapshot, and hibernate after inactivity. If your dev server listens somewhere else, the preview port list is a constraint you have to work around.

Running it locally with pnpm and a Vercel project

The repository is a pnpm workspace driven by turbo, and the root package.json pins the toolchain: node 24.x and pnpm 11.5.1. The README's local path is short. Enable corepack, install, copy the env example, fill it in, and start the web app.

corepack enable
pnpm install
cp apps/web/.env.example apps/web/.env
pnpm web

The root script `web` runs `pnpm --dir apps/web dev`, so `pnpm web` starts the Next.js app in apps/web. The minimum runtime is two variables, and the README gives them in env syntax:

POSTGRES_URL=
BETTER_AUTH_SECRET=

Generate the session secret with `openssl rand -base64 32` as the README suggests. Postgres is not optional here; the app expects a database before it will do anything useful. If you already have a linked Vercel project, `vc env pull` is the documented shortcut for pulling those values down instead of typing them.

Sign-in is a separate step. Authentication is handled by Better Auth with Vercel and GitHub as social providers, and all auth routes are served from the `/api/auth/[...all]` catchall. To sign in with Vercel you create a Vercel OAuth app whose callback URL is `https://YOUR_DOMAIN/api/auth/callback/vercel`, then add the client ID and secret and redeploy. Until those two variables exist, the app deploys but you cannot get past the login screen.

The GitHub App is the real setup cost

The minimum runtime gets you a chat UI. The coding-agent flow, the part where the agent clones a repo, works on a branch, commits and opens a pull request, needs a GitHub App with four URLs and six environment variables. The README specifies the homepage URL as `https://YOUR_DOMAIN`, the callback URL as `https://YOUR_DOMAIN/api/auth/callback/github`, and the setup URL as `https://YOUR_DOMAIN/api/github/app/callback`. The App's client ID and client secret fill `NEXT_PUBLIC_GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`; the App ID, private key and webhook secret fill the rest.

NEXT_PUBLIC_GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
NEXT_PUBLIC_GITHUB_APP_SLUG=
GITHUB_WEBHOOK_SECRET=

One detail in the README is easy to miss and will cost an afternoon: make the GitHub App public if you want org installs to work cleanly. A private App installed on an organization behaves differently, and the symptom shows up at install time rather than at deploy time. The README also notes that auto-commit and auto-PR are preference-driven, not always-on behavior, so a successful run does not imply a branch was pushed. Check the session preferences before assuming the agent failed.

Optional variables round out the picture. `REDIS_URL` or `KV_URL` enables a skills metadata cache that otherwise falls back to in-memory. `OPEN_AGENTS_RESOURCE_PROFILE` set to `hobby` switches chat and sandbox resources to Hobby-compatible defaults. `VERCEL_SANDBOX_BASE_SNAPSHOT_ID` lets fresh sandboxes start from your own snapshot instead of Vercel's standard Sandbox runtime, and the README warns that the snapshot must be created in, or accessible to, your own Vercel scope. `ELEVENLABS_API_KEY` turns on voice transcription.

Where the template pushes work back onto you

The in-memory fallback for the skills cache is the clearest example of a default that will not survive production. With no `REDIS_URL` or `KV_URL`, metadata lives in process memory. On a single long-lived server that is fine. On a serverless deployment that scales to multiple instances, each instance has its own cache and behavior can differ between requests that look identical to the user. The README presents the fallback as a convenience, and it is, but it is a local-development convenience.

There is a second, larger gap: the repository has no releases. Nothing in the repository describes a versioned artifact, a changelog or a migration path, and the README does not document rollback. If you fork this, your upgrade unit is a diff against main. That is a defensible choice for a reference app whose whole purpose is to be adapted, but it means the cost of staying current grows with every local change you make. Teams that need a version number to pin should treat that absence as a decision, not an oversight.

Finally, the deployment targets are not neutral. The agent runs as a durable workflow on Vercel, the sandboxes are Vercel sandboxes, and the deploy button provisions Neon Postgres and Upstash KV. The three-layer split is genuinely portable in principle, since the agent talks to the sandbox through tools, but the shipped implementation is wired to one platform's primitives. If your infrastructure is elsewhere, you are rewriting the runtime layer, not configuring it.

Compared with a self-hosted agent runner

The obvious alternative is a self-hosted agent runner such as OpenHands, which executes the agent loop inside the same container as the workspace. The difference is not cosmetic. In that model the agent process and the filesystem share a lifetime: when the container stops, the run stops with it, and resuming means restarting the container and the loop together. Resource limits apply to both at once, and the model-facing code sits next to the code being edited.

Open Agents inverts that. The workflow is durable and the sandbox is disposable, which is what makes hibernation and snapshot-based resume possible, and what lets you change the model without rebuilding the execution image. The trade is a network hop on every tool call and a persistence layer you have to operate. If you want a single process you can `docker run` and inspect with a shell, the self-hosted runner is the simpler object. If you want runs that survive a closed laptop and sandboxes that wake up where they left off, the split is the point.

Licence and what you inherit

Open Agents is MIT-licensed, with the licence text in LICENSE.md at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained, and it disclaims warranty. For a template that is explicitly meant to be forked, that is the permissive end of the spectrum, and it means your fork can be closed if you want it to be.

The licence does not cover the services the template depends on. Vercel, Neon, Upstash, GitHub and ElevenLabs each have their own terms, quotas and pricing, and the README's `OPEN_AGENTS_RESOURCE_PROFILE=hobby` variable exists precisely because resource defaults differ between plans. A fork that runs cheaply on one plan can fail to deploy on another. Read the terms of the services you actually enable, and treat the MIT grant as covering the code only. This is a description of the licence text, not legal advice.

Editorial conclusion

Fork Open Agents if you want a working reference for a chat-driven coding agent that survives page reloads and edits a repo in an isolated VM, and if you are willing to own the Vercel OAuth app, the GitHub App and the Postgres database that the template expects you to create. Do not fork it if you need a drop-in product with a documented upgrade path: there are no releases in the repository, so you track main, and the README does not document rollback. Before you commit, verify that the sandbox ports 3000, 5173, 4321 and 8000 cover your dev server, and that your Vercel plan can run the resource profile you configure.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. vercel-labs/open-agents on GitHub