| name | devbox-preview |
| description | Project knowledge for making this repo preview correctly from Vercel Devbox/Sandbox. Use when configuring Next.js dev settings, explaining how users preview the app from Devbox, or responding to localhost, Sandbox URL, port 3000, or cross-origin dev-resource issues. |
Devbox Preview
This starter is used in a workshop where some users run the app inside Vercel Devbox instead of on their laptop. Preserve this setup so preview works without users debugging Devbox internals.
Required app configuration
The frontend must allow Vercel Sandbox preview origins during Next.js development. Keep this in frontend/next.config.js:
allowedDevOrigins: ["*.vercel.run"]
Without this, Next.js can serve the page but block dev-only resources such as HMR from https://sb-...vercel.run, causing confusing preview failures.
Preview model
- In Devbox,
localhost means the remote box, not the user's laptop.
- Users should open the published Sandbox URL for port 3000, usually
https://sb-...vercel.run.
- Do not tell Devbox users to open their laptop's
http://localhost:3000.
- The frontend and backend are both reached through Vercel dev on port 3000:
- frontend:
/
- backend:
/api/*
User-facing guidance
When explaining how to preview from Devbox, tell the user:
- In the Devbox SSH session, run Vercel dev bound to port 3000:
vercel dev -L --listen 0.0.0.0:3000
- From a local terminal outside the Devbox SSH session, publish port 3000:
SANDBOX_ID=$(devbox get --output json | python3 -c 'import json, sys; print(json.load(sys.stdin)["response"]["devboxes"][0]["sandboxId"])')
sandbox config ports "$SANDBOX_ID" -p 3000
- Open the
https://sb-...vercel.run URL printed by the sandbox config ports command.
Troubleshooting context
- If
curl -i http://127.0.0.1:3000/ works inside Devbox but the browser fails, suspect Sandbox port publishing or allowedDevOrigins.
- If the browser shows a cross-origin dev-resource warning, check
frontend/next.config.js and restart vercel dev.
- If curl inside Devbox returns 500, inspect the app error in the
vercel dev terminal logs.
