Deploy config and serverless schedules

deploy writes your platform's own deploy files from main.yaml, wakes schedules through one tick route, checks the build before it ships and diffs two environments.

deploy:
  target: vercel
  regions: [fra1]
  port: 3000
  tick:
    secret: secret:CRON_SECRET
    late: 10m
  vercel: { plan: pro }
  docker: { base: node:24-slim }
jobs:
  schedules:
    nightly-report: "0 3 * * *"
seal:
  mode: warn
  exclude: ["**/*.map"]
  publish: { sbom: false }

// Hono on Vercel: the platform cron calls this route with the bearer secret
import { Hono } from "hono";
import { createTick } from "mainsdk/deploy";
import { app } from "mainsdk";

const tick = createTick(app());
const router = new Hono();
router.all("/_mainsdk/jobs/tick", (c) => tick.handle(c.req.raw));

// Cloudflare Workers: the same code, in process, for a cron trigger
export default { fetch: router.fetch, scheduled: (e) => tick.scheduled(e) };

deploy:
  driver: vercel

Quick start

deploy:
  target: vercel
  regions: [fra1]
  port: 3000
  tick:
    secret: secret:CRON_SECRET
    late: 10m
  vercel: { plan: pro }
  docker: { base: node:24-slim }
jobs:
  schedules:
    nightly-report: "0 3 * * *"

// The platform cron calls this route with the bearer secret; Workers calls scheduled in process
import { createTick, type ScheduledEvent } from "mainsdk/deploy";
import { app } from "mainsdk";

const tick = createTick(app());

export default {
  fetch: (req: Request) => {
    const { pathname } = new URL(req.url);
    return tick.match(pathname) ? tick.handle(req) : new Response("Not found", { status: 404 });
  },
  scheduled: (e: ScheduledEvent) => tick.scheduled(e),
};

Configuration

The Quick start shows the whole deploy section.

What you get

Write the platform's own deploy files from main.yaml for Vercel, Cloudflare Workers, Fly.io and Docker, wake schedules through one tick route, check the build before it ships and diff two environments.

Calls

What mainsdk deploy config writes

Every target also writes deploy/env.<env>.example, which lists each required env var name with where it is used and no value, and mainsdk.deploy.json, which records each file and a hash of the part MainSDK owns. Commit both.

MainSDK owns the lines between # mainsdk:generated:begin and # mainsdk:generated:end and, in vercel.json, the three keys above. Everything else in the file is yours and is kept byte for byte. A key that you define outside the block wins and the block leaves it out. mainsdk check reports a stale or hand-edited block as MAIN-DEPLOY-0010 with the command that rewrites it.

Regions and plan limits

The function or machine region follows the data regions of db.regions and files.regions.

A deploy.regions entry outside the data regions is MAIN-DEPLOY-0002. With deploy.vercel.plan: hobby, a cron more often than once a day, more than two cron entries or more than one region is MAIN-DEPLOY-0004.

Schedules on serverless targets

On vercel and cloudflare there is no process to keep a timer, so the in-process scheduler of jobs.schedule is off and each schedule becomes a platform cron entry. The platform calls POST /_mainsdk/jobs/tick?schedule=<name> with Authorization: Bearer <deploy.tick.secret>. The tick answers as soon as the job is queued and runs each schedule once per slot, so a duplicate call answers ran: false. A tick later than deploy.tick.late after its slot still runs and logs MAIN-DEPLOY-0008. The tick is left out of the SLO request counts.

Schedules are the jobs.schedules of main.yaml plus every jobs.schedule("name", "expr", …) call whose name and expression are string literals. A computed one can't be deployed to a serverless target: MAIN-DEPLOY-0001, with its file and line.

Preflight and environment diff

mainsdk deploy preflight --env prod runs inside the platform build, where the secrets are. It checks that each required env var name is present and non-empty, the region and plan rules, and mainsdk check --env prod, and fails the build before anything is served. It prints names, never values.

mainsdk deploy diff --from staging --to prod lists what changes between two environments. With --fail-on widen it fails on a new allowed host, a new secret, a new region or a looser grant. MainSDK never pushes a deploy, holds a platform token or hosts your app; the platform's Git integration or CLI does that.

What it always does

• MainSDK writes and checks deploy files; it never pushes a deploy, holds a platform token or hosts the app
• Generated blocks are owned and checked; every other key and line of the file is kept byte for byte
• Regions follow the data regions, and a region outside them is a finding
• A schedule runs once per slot, however many times the platform calls the tick
• The build fails before anything is served when a required env var name is missing
• deploy config, preflight and diff make no network call and read no platform credential

Errors and checks

Each code's cause and fix is in check codes.

Swapping drivers

deploy:
  target: fly   # was vercel

Then run mainsdk deploy config again. Your app code stays the same; the files it owns change to the new platform's. The drivers are:

Testing

The tick, the file writers and the preflight run against fake platforms, with no network call (packages/sdk/test/deploy-tick.test.ts, packages/cli/test/deploy.test.ts). Check your own files in CI with mainsdk deploy config --check and mainsdk deploy preflight --env <env>.

Next

• Seal your build
• Jobs and schedules
• Check codes