Deploy to Vercel

Vercel runs your code as functions and gives every deploy its own URL. Exercises use it to deploy eve agents, to run untrusted code in Vercel Sandbox microVMs and to test Vercel Queues consumers. Everything here runs on the free Hobby plan, which can't bill you: when you use up an allowance, that feature pauses instead.

Before you start

• macOS, Linux or Windows, with Node.js and pnpm. The CLI is an npm package.
• A personal GitHub, GitLab, Bitbucket or email login to sign up with. Hobby is for personal, non-commercial projects, so don't use it for an employer's or client's work.
• Python exercises (Sandbox, Queues) also need Python with uv.

1. Create a Hobby account

Sign up at vercel.com/signup and choose Hobby. No payment method is needed. Each month Hobby includes, among other things, 1,000,000 function invocations, 4 hours of active CPU, 5 hours of Sandbox active CPU and the first 1,000,000 Queue operations. For limits that reset monthly, going over pauses that feature until 30 days after you first used it.

2. Install the CLI and log in

pnpm i -g vercel
vercel --version

npm i -g vercel works too. To update later, run the install command again with vercel@latest, or vercel upgrade.

vercel login
vercel whoami

vercel login opens a browser to approve the CLI; vercel whoami prints your username. If you belong to any team (for example through work), vercel switch lets you choose your personal Hobby scope, and every exercise should run there.

3. Link a project

From the root of an exercise project:

vercel link

Answer the prompts: your personal scope, then link to an existing project or create one named after the folder. This writes a .vercel/ folder holding the project and team IDs. The CLI adds it to .gitignore; check that it did, because the folder is specific to your account.

4. Add secrets as Sensitive variables

Environment variables belong to an environment: production, preview or development. Variables you add to Production and Preview are stored as Secret (Sensitive) by default: nobody can read the value back, not even you. Pass --sensitive anyway, so the choice is explicit:

vercel env add OPENROUTER_API_KEY preview --sensitive
vercel env add OPENROUTER_API_KEY production --sensitive
vercel env ls

Each command asks for the value, so the key never appears in your shell history. Don't use echo sk-... | vercel env add, which does. Use an OpenRouter key with its own credit limit (see Get an OpenRouter key), not one you use elsewhere.

5. Pull variables for local runs

vercel env pull

This writes the Development variables to .env.local. It merges into an existing file and keeps entries that exist only locally. Two things to know:

• It also writes VERCEL_OIDC_TOKEN, which the Sandbox and Queues SDKs use to authenticate from your laptop. The token expires after 12 hours; run vercel env pull again when you see authentication errors.
• Sensitive values can't be downloaded. If you set a Development secret, the CLI keeps the value already in your file, or writes a placeholder for you to fill in.

Keep .env.local out of git (echo ".env.local" >> .gitignore). To run one command with the project's variables without writing a file, use vercel env run -- pnpm test.

6. Make a preview deployment

vercel deploy

Plain vercel does the same. It uploads the folder, builds it on Vercel and prints the deployment URL on stdout. A preview gets its own URL and never touches your production domain; vercel deploy --prod is how you deploy to production. The first deployment of a new project is always production, so make that first deploy something harmless.

Previews are protected by Vercel Authentication by default, so only you, logged in, can open them in a browser. To call a protected deployment from a script, use vercel curl /api/health --deployment <url>, which adds the bypass for you.

7. Keep spending at zero

On Hobby there's nothing to cap: you get notifications as you approach a limit, then the feature pauses. For Sandbox, Hobby also caps a session at 45 minutes and 10 concurrent sandboxes; call sandbox.stop() when you're done so the sandbox doesn't sit idle until its timeout. Check usage on your dashboard's Usage page, or run vercel usage.

If you ever upgrade to Pro ($20 a month, including $20 of usage credit), metered usage beyond the credit is billed. Turn on Spend Management straight away:

1. Settings → Billing → Spend Management: enable it and set an On-Demand Budget, such as $10.
2. Enable Pause Production Deployments. A budget on its own only sends alerts (at 50%, 75% and 100%); pausing is what stops the spending.

The CLI equivalent is vercel budgets set --amount 10 --pause. Vercel checks spend every few minutes, so set the budget a little below your real limit. Pausing doesn't stop AI Gateway usage, so give any Gateway key its own budget too.

Check it works

vercel whoami && vercel ls

Expected: your username, then a table of your project's deployments, with the preview from step 6 showing as Ready.

Troubleshooting

vercel: command not found after installing. pnpm's global bin folder isn't on your PATH. Run pnpm setup, open a new terminal, and install again.

A preview URL shows a Vercel login page. That's Deployment Protection doing its job. Open it in a browser where you're logged in, or use vercel curl.

Sandbox or Queues calls fail with an authentication error locally. The OIDC token has expired, or the folder isn't linked. Run vercel link, then vercel env pull.

A feature stops working mid-month on Hobby. You've used that month's allowance. Wait for it to reset, or move that experiment somewhere local.

Going further

• Durable agents with eve, the framework the deploy exercises use
• Get an OpenRouter key for the model key you store in step 4