Build an app that turns a prompt into a working Next.js application, then lets you refine the result through chat. Forma is a single-user app builder with saved projects, a conversation history, and a live preview you can pause and reopen later.

The OpenAI Agents API manages the coding agent's session and streams updates as it works. In this project, the agent connects to an executor in your own compute environment to edit files, install packages, and run commands.

Vercel Sandbox provides that environment: an isolated Linux workspace for each generated app. Its persistent file system lets you return to a project and continue editing the same code after its compute has stopped. It also provides a stable preview URL for the running app.

In this guide, you’ll learn how to make your own app builder like v0, understand its architecture, and deploy it to Vercel for everyone to use.

Deploy the template now, or follow the steps below to build it.

Deploy Template

A Next.js app builder with chat-based editing, live previews, and saved projects you can return to.

Quick start with an AI coding agent

The builder and each generated app are separate Next.js applications. The builder is deployed on Vercel; the generated apps run inside Sandbox.

Integration walkthrough

1. Set up the Next.js app

Start with an App Router project using TypeScript and Tailwind CSS:

pnpm create next-app@16.3.4 forma --ts--tailwind--eslint--app --use-pnpm --no-src-dir --import-alias

cd forma

pnpmadd @vercel/sandbox@3.2.1 @vercel/queue@0.5.1 openai@7.15.0 undici@7.29.1 pg zod lucide-react react-markdown

pnpmadd-D @types/pg tsx

The template implements the builder interface as a Client Component with a prompt composer, saved project list, conversation, and preview panel. Route Handlers under app/api handle sign-in, project reads, and requests to edit, pause, or resume a project.

Keep the handlers small: validate the request and ownership, save a job, and return its identifier. Put database operations in lib/projects.ts, background execution in lib/worker.ts, and external service calls in their own modules. This lets the deployed Queue consumer and the local worker use the same execution logic.

The template also includes shared-password authentication and same-origin checks for browser mutations. Everyone who signs in shares the same workspace. For production workflows, you should set up sign-up and sign-in flows for individual users.

2. Configure the OpenAI Agents API

Create a saved agent with instructions to build Next.js apps in /workspace, preserve the managed preview server, and check its changes before finishing. The template's creation script selects gpt-5.6 and saves the returned identifier as OPENAI_AGENT_ID.

The application uses client.beta.agents from the OpenAI TypeScript SDK, which adds the OpenAI-Beta: agents=v1 header automatically. For a new project, client.beta.agents.sessions.create() sends the following body to POST https://api.openai.com/v1/agents/sessions:

{

"agent_id":"",

"environment":{

"type":"self_hosted",

"workspace_directory":"/workspace"

}

}

Save the returned session ID against the project. Start the Codex executor in that project's sandbox with --environment-id set to session.environment.id and --remote set to session.environment.remote_url. Save both values and reuse the returned URL unchanged when reconnecting. Subsequent prompts go to the same session, so the agent can continue working on the existing app.

Subscribe to the session's event stream before submitting a prompt, then save assistant text and progress as events arrive. Give each submission a stable job ID as its idempotency key so a retried request can refer to the same input.

3. Give each project a persistent sandbox

The agent needs a place to write source files, install dependencies, and run the generated app. Create a named Vercel Sandbox for each project so that those operations happen in an isolated workspace, and later edits can retrieve the same files.

For a project without an existing agent session, lib/sandbox.ts uses the following sandbox configuration:

On first use, prepare /workspace, install the executor, write the starter Next.js app, and install its packages. For a project with an existing agent session, use Sandbox.get({ name }). A missing saved workspace must surface an error instead of silently creating an empty replacement.

Persistent sandboxes snapshot their file system on stop and restore it on resume. Forma retains two snapshots without automatic expiration, so Save & pause stops compute while retained storage can still incur charges. Running processes are restarted when the project reopens.

Only the restricted executor key is passed into the sandbox. The application's OpenAI key, database connection string, and authentication secrets stay in the builder backend.

4. Store projects and jobs with Postgres

Connect a Neon Postgres database and use its pooled connection string as DATABASE_URL. The template uses pg for database access and keeps its repeatable schema in db/schema.sql.

The following four tables cover the application's state:

When accepting an edit, lock the project and create its job, user message, and active-job pointer in one transaction. A repeated request ID returns the existing job. So, a new edit is rejected while another operation is active.

The worker claims a job with a time-limited lease. This gives duplicate queue deliveries a way to detect work already in progress. The database also preserves unfinished jobs if publishing to the queue fails.

5. Process background work with Vercel Queues

Configure two topics using Vercel Queues: studio-jobs for project operations and studio-provision for session reconciliation. The private consumers are declared in vercel.json:

OpenAI lifecycle notifications enter through /api/webhook. Verify the signature against the raw request body, then send the relevant session ID to studio-provision. Its consumer checks that the session belongs to a saved project before reconnecting an executor or handling a failed session.

6. Add recovery and idle cleanup with Vercel Cron

Add the Cron schedule alongside the Queue configuration in vercel.json:

{

"crons":[{"path":"/api/cron","schedule":"*/5 * * * *"}]

}

docs.

Every five minutes, /api/cron republishes unfinished jobs whose leases are absent or expired. It also enqueues stop operations for inactive projects with no active job and removes expired login-throttling records. The route checks the bearer token supplied through CRON_SECRET.

Projects become eligible for an idle shutdown after 10 minutes of inactivity. Shutdown happens after the next cron run and queue delivery. An active sandbox also has its own compute timeout.

7. Connect progress and previews to the UI

Start the generated Next.js development server on 0.0.0.0:3000 inside the sandbox. Wait for a successful HTTP response before saving sandbox.domain(3000) as the project's preview URL. The studio loads that URL in an iframe, and the development server updates the preview as source files change.

After the agent finishes, the worker runs a separate production build. The starter uses BUILD_CHECK=1 to write verification output to .next-build, leaving the live server's .next directory separate. A successful build and preview readiness check mark the project ready; a failed build appears in chat so the user can request a fix.

The browser connects to an SSE endpoint that reads saved project state and messages from Neon. Refreshing or closing the page leaves the background job running. Reconnecting restores the saved conversation and status.

The iframe restricts navigation and runs on a separate origin. Its URL is accessible to anyone who has it; the builder's password does not protect generated previews.

8. Journey of a request

The complete request flow is:

You can generate a random secret with openssl rand -hex 32; run it separately for each secret. Keep .env.local out of version control. Leave APP_URL unset locally so requests use the local origin.

For the webhook, subscribe to agent.session.action_required and agent.session.failed. OpenAI provides the signing secret when you register the endpoint. If you don't have a deployed URL yet, complete the initial deployment below, then save the returned secret locally before starting generation.

The local worker can establish executor connections directly. A production webhook only reconciles sessions present in its own database; it does not process projects stored exclusively in a development branch.

Run the app

Once the environment is configured, create the saved agent, apply the schema, and start development:

pnpm agent:create

pnpm db:migrate

pnpm dev

The agent script keeps an existing OPENAI_AGENT_ID. The development command starts both Next.js and the database worker; running Next.js by itself leaves local jobs unprocessed.

Open localhost:3000, sign in with APP_PASSWORD, and try:

Build a reading list app with book cards, a form to add a book, and filters for books I want to read and books I've finished.

Wait for the build check, then request a change such as adding a rating control. Refresh to confirm the conversation returns. Use Save & pause, reopen the project, and check that the generated code is still there. Data entered into the generated app needs its own storage if it should survive reloads.

If local Sandbox authentication expires, pull fresh variables into a separate temporary file and copy the new VERCEL_OIDC_TOKEN into .env.local, preserving your other settings. Restart pnpm dev after changing credentials.

Deploy the app

Before proceeding with production deployment, create a production database or Neon branch and a separate set of production credentials. Within each environment, the OpenAI application and executor keys must belong to the same organization and project. Use an agent accessible to that production OpenAI project and a webhook registered for the production endpoint.

Generation remains unconfigured until the webhook secret is installed. In the production OpenAI project's webhook settings, register https://your-domain.example/api/webhook for agent.session.action_required and agent.session.failed. Add the returned OPENAI_WEBHOOK_SECRET to the Vercel project’s environment variables and redeploy.

Finally, sign in and verify a new project, a follow-up edit, and pause/resume. Inspect OpenAI's webhook delivery history and the provision consumer logs to confirm actual lifecycle events arrive.

Next steps