---
title: Vercel World
description: Fully-managed world for Vercel deployments with automatic storage, queuing, and authentication.
type: integration
summary: Deploy workflows to Vercel with fully-managed storage, queuing, and authentication.
prerequisites:
  - /docs/deploying
related:
  - /docs/how-it-works/encryption
  - /worlds/local
  - /worlds/postgres
---

# Vercel World



The Vercel World is a fully-managed workflow backend for applications deployed on Vercel. It provides scalable storage, distributed queuing, and automatic authentication with zero configuration.

When you deploy to Vercel, workflows automatically use the Vercel World - no setup required.

## Usage

Deploy your application to Vercel:

```bash
vercel deploy
```

That's it. Vercel automatically:

* Selects the Vercel World backend
* Configures authentication using OIDC tokens
* Provisions storage and queuing infrastructure
* Isolates data per environment (production, preview, development)

<FluidComputeCallout />

## Vercel platform documentation

For complete details on pricing, usage limits, and included allotments on Vercel, see the official Vercel documentation:

* **[Vercel Workflow](https://vercel.com/docs/workflows)** — Pricing details, concepts, and observability for Workflow on Vercel
* **[Vercel limits](https://vercel.com/docs/limits)** — Platform-wide limits including Workflow-specific constraints
* **[Vercel Hobby plan](https://vercel.com/docs/plans/hobby)** — Free tier included usage for Workflow and other resources

For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local).

## Limitations

<Callout type="info">
  **Multi-region support is available starting with `workflow` version
  5.0.0-beta.33.** On 5.x, workflow runs are pinned to the region that creates them —
  storage, queuing, and streams are served region-locally instead of routing
  through `iad1`. See [Multi-region on the v5 version of this
  page](/v5/worlds/vercel#multi-region). The limitations
  below apply to the 4.x release line, which will not support multi-region.
</Callout>

* **Single-region deployment** - On the 4.x release line, the backend infrastructure is used only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1` — or upgrade to `workflow` 5.0.0-beta.33+ for multi-region support.

* **Data residency** - On the 4.x release line, independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region.

## Observability

Workflow observability is built into the Vercel dashboard on your project page. It respects your existing authentication and project permission settings.

The `workflow` CLI commands open a browser window deeplinked to the Vercel dashboard:

```bash
# List workflow runs (opens Vercel dashboard)
npx workflow inspect runs --backend vercel

# Launch the web UI (opens Vercel dashboard)
npx workflow web --backend vercel
```

The CLI automatically retrieves authentication from the Vercel CLI (`vercel login`) and infers project/team IDs from your local Vercel project linking.

To use the local observability UI instead of the Vercel dashboard:

```bash
npx workflow web --backend vercel --localUi
```

To override the automatic configuration:

```bash
npx workflow inspect runs \
  --backend vercel \
  --env production \
  --project my-project \
  --team my-team \
  --authToken <your-token>
```

Learn more in the [Observability](/docs/observability) documentation.

## Testing & Compatibility

<WorldTestingPerformance worldId="vercel" />

## Configuration

The Vercel World requires no configuration when deployed to Vercel. For advanced use cases, you can override settings programmatically via `createVercelWorld()`.

### `WORKFLOW_VERCEL_ENV`

The Vercel environment to use. Options: `production`, `preview`, `development`. Automatically detected.

### `WORKFLOW_VERCEL_AUTH_TOKEN`

Authentication token for API requests. Automatically detected.

### `WORKFLOW_VERCEL_PROJECT`

Vercel project ID for API requests. Automatically detected.

### `WORKFLOW_VERCEL_TEAM`

Vercel team ID for API requests. Automatically detected.

### `WORKFLOW_VERCEL_BACKEND_URL`

Custom base URL for the Vercel workflow API. Automatically detected.

### `WORKFLOW_SEQUENTIAL_REPLAYS`

Set `WORKFLOW_SEQUENTIAL_REPLAYS=1` to guarantee that **at most one orchestrator (flow) invocation runs at a time per workflow run**. This behavior is off by default; without it, the runtime relies on idempotency and the event log to tolerate concurrent flow invocations of the same run.

When enabled, each run is given its own queue topic and the flow route is configured with `maxConcurrency: 1`, so [Vercel Queues](https://vercel.com/docs/queues) processes flow messages for a given run strictly one at a time. Step routes are unaffected and continue to run with full concurrency.

<Callout type="warn">
  This variable is read at **both build time and runtime**, so it must be set as a project-level environment variable that applies to your build and your deployed functions. Setting it for only one will produce an inconsistent configuration. The same applies to framework integrations that write their own queue trigger configuration instead of using `getWorkflowQueueTrigger()` from `@workflow/builders`: they only get the runtime half (per-run topics) unless they also emit `maxConcurrency: 1` on their flow trigger.
</Callout>

Because it routes each run's flow invocations through a dedicated `maxConcurrency: 1` queue topic, enabling this might lead to higher queue performance overhead.

### Programmatic configuration

{/*@skip-typecheck: incomplete code sample*/}

```typescript title="workflow.config.ts" lineNumbers
import { createVercelWorld } from "@workflow/world-vercel";

const world = createVercelWorld({
  token: process.env.WORKFLOW_VERCEL_AUTH_TOKEN,
  baseUrl: "https://api.vercel.com/v1/workflow",
  projectConfig: {
    projectId: "my-project",
    teamId: "my-team",
    environment: "production",
  },
});
```

## Versioning

On Vercel, workflow runs are pegged to the deployment that started them. This means:

* Existing workflow runs continue executing on their original deployment, even as new code is deployed
* New workflow runs start on the latest deployment
* Code changes won't break in-flight workflows

This ensures long-running workflows complete reliably without being affected by subsequent deployments.

For the full model, including rerunning on latest and explicit upgrade boundaries, see [Versioning](/docs/foundations/versioning).

## Security

### Consumer function security

Workflow handler functions on Vercel are not accessible through public endpoints. During the build step, the Workflow SDK registers each handler as only reachable by [Vercel Queue](https://vercel.com/docs/queues), by using the `experimentalTriggers` configuration in `.vc-config.json`:

```json title=".vc-config.json (step handler)"
{
  "experimentalTriggers": [
    {
      "type": "queue/v2beta",
      "topic": "__wkf_step_*",
      "consumer": "default",
    }
  ]
}
```

Practically, this means:

* You don't need to add authentication or authorization logic to workflow handlers
* Unauthorized requests can never reach the step or workflow functions
* Only messages delivered through Vercel Queues can trigger execution
* Handlers receive only a message ID that must be retrieved from Vercel's backend, making it impossible to craft custom payloads

<Callout>
  This configuration is managed entirely by the Workflow SDK build step. You should not need to write this yourself. If you are writing a custom integration, see [Framework Integrations — Security](/docs/how-it-works/framework-integrations#security) for more details.
</Callout>

## How It Works

The Vercel World uses Vercel's infrastructure for workflow execution:

* **Storage** - Workflow data is stored in Vercel's cloud with automatic replication and [end-to-end encryption](/docs/how-it-works/encryption)
* **Queuing** - Steps are distributed across serverless functions via [Vercel Queues](https://vercel.com/docs/queues) with automatic retries and [consumer function security](#consumer-function-security)
* **Authentication** - OIDC tokens provide secure, automatic authentication

For more details, see the [Vercel Workflow documentation](https://vercel.com/docs/workflows).


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)