Skip to main content
Vercel is the recommended platform for deploying ZapDev. This guide covers the complete deployment process including Convex backend, Inngest Cloud integration, and all required services.

​
Prerequisites

Before deploying, ensure you have accounts for:
  • Vercel - Hosting platform
  • Convex - Real-time database backend
  • Inngest Cloud - Background job processing
  • Clerk - Authentication (or Stack Auth)
  • E2B - Code sandbox environment
  • Polar.sh - Billing and subscriptions
  • OpenRouter - AI model gateway
  • Cerebras - Ultra-fast AI inference (optional)

​
Step 1: Set Up Inngest Cloud

Inngest Cloud handles background AI code generation workflows.
1

Create an Inngest Account

Go to Inngest Cloud and sign up or log in
2

Create a New App

  • Click “Create App” in the dashboard
  • Name your app (e.g., zapdev-production)
3

Get Your Keys

Navigate to your app settings and copy:
  • Event Key (starts with ac9_)
  • Signing Key (starts with signkey-)
You’ll need these for Vercel environment variables.

​
Step 2: Deploy Convex Backend

Convex provides the real-time database for ZapDev.
1

Install Convex CLI

bun install -g convex
2

Login to Convex

bunx convex login
3

Create Production Deployment

bunx convex deploy
This will:
  • Create a production deployment
  • Provide your NEXT_PUBLIC_CONVEX_URL
  • Deploy your database schema and functions
4

Copy Convex URL

Save the NEXT_PUBLIC_CONVEX_URL from the deployment output - you’ll need it for Vercel.

​
Step 3: Build E2B Sandbox Template

This step is required before deployment. The E2B template must be built with Docker running.
1

Install E2B CLI

bun install -g @e2b/cli
# or
brew install e2b
2

Login to E2B

e2b auth login
3

Build the Template

cd sandbox-templates/nextjs
e2b template build --name zapdev-production --cmd "/compile_page.sh"
Important: Docker must be installed and running for this command.
4

Update Template Name

After building, update the template name in your codebase:
// src/inngest/functions.ts (line ~22)
const sandbox = await Sandbox.create("zapdev-production");
Commit this change before deploying to Vercel.

​
Step 4: Deploy to Vercel

1

Push to GitHub

git add .
git commit -m "chore: prepare for production deployment"
git push origin main
2

Import to Vercel

  • Go to Vercel Dashboard
  • Click “New Project”
  • Import your GitHub repository
  • Select the repository containing ZapDev
3

Configure Build Settings

Vercel should auto-detect Next.js. Verify:
  • Framework Preset: Next.js
  • Build Command: bun run build
  • Install Command: bun install
  • Output Directory: .next (default)
4

Add Environment Variables

In the Vercel project settings, add all environment variables (see below).
Copy from your local .env file, but replace development URLs with production values.
5

Deploy

Click “Deploy” and wait for the build to complete (typically 2-3 minutes).

​
Step 5: Configure Environment Variables

Add these environment variables in your Vercel project settings:

​
Application

NEXT_PUBLIC_APP_URL="https://your-app.vercel.app"

​
Convex Database

NEXT_PUBLIC_CONVEX_URL="https://your-deployment.convex.cloud"
NEXT_PUBLIC_CONVEX_SITE_URL="https://your-app.vercel.app"

​
Clerk Authentication

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_live_..."
CLERK_SECRET_KEY="sk_live_..."
CLERK_JWT_ISSUER_DOMAIN="clerk.your-domain.com"
CLERK_JWT_TEMPLATE_NAME="convex"
Create a JWT template named “convex” in Clerk Dashboard → JWT Templates for Convex integration.

​
Polar.sh Billing

POLAR_ACCESS_TOKEN="polar_at_..."
POLAR_WEBHOOK_SECRET="whsec_..."
NEXT_PUBLIC_POLAR_ORGANIZATION_ID="org_..."
NEXT_PUBLIC_POLAR_PRO_PRODUCT_ID="prod_..."
NEXT_PUBLIC_POLAR_PRO_PRICE_ID="price_..."
NEXT_PUBLIC_POLAR_PRO_YEARLY_PRICE_ID="price_..."
NEXT_PUBLIC_POLAR_UNLIMITED_PRODUCT_ID="prod_..."
NEXT_PUBLIC_POLAR_UNLIMITED_PRICE_ID="price_..."
NEXT_PUBLIC_POLAR_SERVER="production"

​
AI Services

# OpenRouter (AI Gateway)
OPENROUTER_API_KEY="sk-or-..."
OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"

# Cerebras (Ultra-fast inference)
CEREBRAS_API_KEY="csk-..."

# Vercel AI Gateway (fallback)
VERCEL_AI_GATEWAY_API_KEY="..."

​
E2B Sandboxes

E2B_API_KEY="e2b_..."

​
Inngest (Background Jobs)

INNGEST_EVENT_KEY="ac9_..."
INNGEST_SIGNING_KEY="signkey-..."

​
Optional Services

# Brave Search (web research)
BRAVE_SEARCH_API_KEY="..."

# Firecrawl (web scraping)
FIRECRAWL_API_KEY="..."

# UploadThing (file uploads)
UPLOADTHING_TOKEN="..."

# Sentry (error monitoring)
NEXT_PUBLIC_SENTRY_DSN="https://..."
SENTRY_DSN="https://..."

​
Step 6: Sync with Inngest Cloud

After Vercel deployment completes, connect Inngest to your app:
1

Get Your Vercel URL

Copy your deployed app URL (e.g., https://your-app.vercel.app)
2

Sync with Inngest

  • Go to Inngest Dashboard
  • Navigate to your app
  • Click “Sync App”
  • Add URL: https://your-app.vercel.app/api/inngest
  • Click “Sync”
3

Verify Connection

Inngest will connect to your endpoint. You should see:
  • Status: “Connected”
  • Functions listed: codeAgentFunction, auto-pause-sandboxes
  • No error messages

​
Step 7: Configure Webhooks

​
Clerk Webhooks

1

Update Webhook URL

  • Go to Clerk Dashboard → Webhooks
  • Update webhook URL to: https://your-app.vercel.app/api/webhooks/clerk
2

Enable Events

Ensure these events are enabled:
  • user.created
  • user.updated
  • session.created

​
Polar.sh Webhooks

1

Configure Webhook

  • Go to Polar.sh Dashboard → Webhooks
  • Add endpoint: https://your-app.vercel.app/api/webhooks/polar
  • Copy the webhook secret to POLAR_WEBHOOK_SECRET

​
Step 8: Set Up Cron Jobs

ZapDev includes a cron job for sandbox cleanup defined in vercel.json: 
{
  "crons": [
    {
      "path": "/api/cron/cleanup-sandboxes",
      "schedule": "0 0 * * *"
    }
  ]
}
This runs daily at midnight UTC. Vercel automatically registers this cron job on deployment.
View cron job execution logs in Vercel Dashboard → Logs → Filter by /api/cron/cleanup-sandboxes

​
Monitoring Your Deployment

​
Vercel Dashboard

  • Deployments: Track build status and history
  • Logs: Real-time function logs and errors
  • Analytics: Performance metrics and Web Vitals
  • Speed Insights: Core Web Vitals monitoring

​
Convex Dashboard

Monitor at dashboard.convex.dev:
  • Data: View database tables and documents
  • Functions: Query and mutation execution logs
  • Logs: Real-time backend logs
  • Deployments: Schema change history

​
Inngest Dashboard

Monitor at app.inngest.com:
  • Functions: View all registered functions
  • Runs: Execution history and status
  • Errors: Failed runs with replay capability
  • Crons: Scheduled job execution times

​
E2B Dashboard

Monitor at e2b.dev/account:
  • Sandboxes: Active and paused sandboxes
  • Usage: API calls and compute time
  • Costs: Real-time cost tracking
Auto-pause should reduce E2B costs by 30-50% by pausing inactive sandboxes every 5 minutes.

​
Troubleshooting

​
Deployment Fails

Issue: Build fails with TypeScript errors Solution: 
# Test build locally first
bun run build

# Fix any TypeScript errors
bun run lint

​
Inngest Not Syncing

Issue: Inngest shows “Failed to sync” error Solution:
  1. Verify INNGEST_EVENT_KEY and INNGEST_SIGNING_KEY are correct
  2. Check Vercel function logs for /api/inngest errors
  3. Ensure endpoint is publicly accessible
  4. Re-deploy and try syncing again

​
AI Generation Not Working

Issue: Code generation fails or hangs Solutions:
  1. Verify E2B Template: 
    # Check template exists
e2b template list
  2. Check API Keys:
    • Verify E2B_API_KEY is valid
    • Test CEREBRAS_API_KEY or OPENROUTER_API_KEY
  3. Review Inngest Logs:
    • Check for sandbox creation errors
    • Look for API timeout issues

​
Database Connection Issues

Issue: Convex queries failing Solution:
  1. Verify NEXT_PUBLIC_CONVEX_URL is correct
  2. Check Convex dashboard for deployment status
  3. Ensure JWT template is configured in Clerk
  4. Re-deploy Convex: bunx convex deploy

​
Webhook Failures

Issue: Clerk or Polar webhooks not received Solution:
  1. Check webhook URLs are correct
  2. Verify webhook secrets match environment variables
  3. Review Vercel function logs for webhook endpoints
  4. Test webhook delivery in service dashboard

​
Production Checklist

Before launching to production:
  • All environment variables configured in Vercel
  • Convex backend deployed (bunx convex deploy)
  • E2B template built with production name
  • Inngest Cloud synced successfully
  • Clerk webhooks configured with production URL
  • Polar.sh webhooks configured
  • Test user registration flow
  • Test AI code generation end-to-end
  • Verify cron job execution in logs
  • Monitor first few Inngest function runs
  • Check E2B sandbox creation and auto-pause
  • Configure custom domain (optional)
  • Enable Vercel Speed Insights
  • Set up Sentry error tracking (optional)

​
Updating Your Deployment

​
Code Changes

# Push to main branch
git push origin main

# Vercel auto-deploys from main

​
Schema Changes

# Deploy Convex schema updates
bunx convex deploy

# Then deploy to Vercel (auto-triggers on push)
git push origin main

​
Environment Variables

  1. Update in Vercel Dashboard → Settings → Environment Variables
  2. Redeploy: Vercel Dashboard → Deployments → Redeploy

​
Next Steps

Docker Deployment

Alternative deployment using Docker containers

Self-Hosted

Deploy on your own infrastructure

Build docs developers (and LLMs) love

Get started for freeTalk to us