--- title: Worlds description: Configure the Workflow backend that stores runs and delivers queue messages. type: reference summary: Select and configure Local, Postgres, Vercel, or custom Worlds. related: - /worlds/local - /worlds/postgres - /worlds/vercel --- # Worlds A [World](/docs/deploying) stores workflow state and delivers queue messages. ## Selecting a World ### `WORKFLOW_TARGET_WORLD` * Surface: environment variable * Default: `local` outside Vercel; automatic Vercel World inside Vercel deployments * Selects a non-default World module. Outside Vercel, Workflow defaults to the Local World. On Vercel, leave `WORKFLOW_TARGET_WORLD` unset for the normal case; Workflow detects the Vercel deployment and selects the Vercel World automatically. The World is selected when your app **runs**, from the environment of the process serving it, so changing `WORKFLOW_TARGET_WORLD` takes effect on the next start without a rebuild. Detection keys off `VERCEL_DEPLOYMENT_ID`, which Vercel sets in every deployed function and nothing else sets: with it, the Vercel World; without it, the Local World. Broader signals are deliberately ignored. `vercel env pull` writes `VERCEL=1` into `.env.local`, so a dev server or a production server started on your own machine sees it while running against a writable filesystem, where the Local World is the right choice. Set `WORKFLOW_TARGET_WORLD=vercel` explicitly if you want such a process to talk to the Vercel World; starting a run then fails with an error naming the missing `VERCEL_DEPLOYMENT_ID`. A deployment that pins `WORKFLOW_TARGET_WORLD=local` warns at startup and fails on its first write, because a Vercel deployment's filesystem is read-only. A deployment can land on the Local World without pinning anything, and without that warning, if the project has cleared **Enable access to System Environment Variables** under **Settings**, then **Environment Variables**. That checkbox is what makes Vercel expose `VERCEL_DEPLOYMENT_ID` to your build and your functions; with it off, there is no signal to detect, so detection and the warning both see an ordinary non-Vercel process. See [System environment variables](/worlds/vercel#system-environment-variables) for how to confirm and fix it. Set `WORKFLOW_TARGET_WORLD` only when you want to use a custom or self-hosted World: * `local`: Alias for `@workflow/world-local`. * `@workflow/world-postgres`: Postgres World package. * `./my-world.ts`: Local module exporting a World, `createWorld()`, or a default factory. * Any package specifier: Custom World package. The `vercel` alias exists for manual selection and tooling, but deployed Vercel apps do not need to set it. Export a configured World from a module when you need factory options instead of pure environment configuration: ```typescript title="my-world.ts" lineNumbers import { createWorld } from "@workflow/world-postgres"; export default createWorld({ connectionString: process.env.DATABASE_URL!, jobPrefix: "myapp_", }); ``` ```bash title=".env" WORKFLOW_TARGET_WORLD="./my-world.ts" ``` ## Local World The Local World is the default outside Vercel and is intended for development. ### `dataDir` * Environment variable: `WORKFLOW_LOCAL_DATA_DIR` * Default: `.workflow-data` * Directory where runs, steps, events, hooks, streams, and the local manifest are written. ### `baseUrl` * Environment variable: `WORKFLOW_LOCAL_BASE_URL` * Default: inferred from the app port * Full base URL used when queue messages call back into the app. * Overrides `port` and `PORT`. ### `port` * Environment variable: `PORT` * Default: auto-detected * Local app port used to build the callback URL when `baseUrl` is unset. ### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY` * Factory option: none * Default: `1000` * Maximum number of concurrent local queue message handlers. ### `WORKFLOW_LOCAL_QUEUE_MAX_VISIBILITY` * Factory option: none * Default: unlimited * Maximum seconds a local queue message stays hidden before the handler rechecks the run. ### `WORKFLOW_LOCAL_HEADERS_TIMEOUT_MS` * Factory option: none * Default: `0` (no deadline) * Maximum milliseconds to wait for a local queue handler to begin responding before the durable message is redelivered. A value below your longest inline step re-executes that step while it is still running. ### `WORKFLOW_LOCAL_BODY_TIMEOUT_MS` * Factory option: none * Default: `0` (no deadline) * Maximum gap in milliseconds between response body chunks from a local queue handler before the durable message is redelivered. ### `recoverActiveRuns` * Environment variable: `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS` * Default: `true` * Re-enqueues pending and running local runs when the World starts. Set the environment variable to `0` or `false` to skip recovery; the factory option wins when both are set. ### `WORKFLOW_LOCAL_HOOK_RETENTION_LIMIT_DAYS` * Factory option: none * Default: `30` * Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Local World, in days. * Set this to the same limit as your production World so oversized values fail during local development. ### `tag` * Environment variable: none * Default: unset * Scopes local storage files to a tag, mainly for test isolation. ### `streamFlushIntervalMs` * Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` * Default: `0` (dispatch the leading chunk of an idle stream immediately) * Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the first chunk. ### `WORKFLOW_MAX_EVENTS` * Default: `25000` * Per-run event ceiling reported to the runtime. A run whose event log reaches it fails with `MAX_EVENTS_EXCEEDED`, bounding a runaway loop. See [`WORKFLOW_MAX_EVENTS_OVERRIDE`](/docs/configuration/runtime-tuning#workflow_max_events_override) for the runtime-side clamp. ## Postgres World The Postgres World is a self-hosted durable backend for long-running server processes. ### `connectionString` * Environment variable: `WORKFLOW_POSTGRES_URL`, then `DATABASE_URL` * Default: `postgres://world:world@localhost:5432/world` * PostgreSQL connection string used by the runtime World. * The `bootstrap` migration command uses the same precedence. ### `pool` * Environment variable: none * Default: new `pg.Pool` * Existing `pg.Pool` to use instead of constructing one from `connectionString`. ### `jobPrefix` * Environment variable: `WORKFLOW_POSTGRES_JOB_PREFIX` * Default: `workflow_` * Prefix for Graphile Worker job names. ### `queueConcurrency` * Environment variable: `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` * Default: `50` * Number of concurrent workers polling for jobs. * Also bounds concurrent parent-to-child workflow return-value polls. ### `applicationManagedShutdown` * Environment variable: `WORKFLOW_POSTGRES_APPLICATION_MANAGED_SHUTDOWN` (`1` enables) * Default: `false` * Whether the application coordinates shutdown instead of Graphile Worker responding automatically. * Set to `true` only when the application awaits `world.close()` before closing its workflow HTTP server and caller-owned pool. * Prevents Graphile Worker's default handler from terminating the process before the application's remaining cleanup finishes. ### `maxPoolSize` * Environment variable: `WORKFLOW_POSTGRES_MAX_POOL_SIZE` * Default: `pg` default * Maximum size of the internal `pg.Pool` when the World creates the pool. ### `WORKFLOW_POSTGRES_HOOK_RETENTION_LIMIT_DAYS` * Factory option: none * Default: `30` * Maximum [`experimental_minRetention`](/docs/api-reference/workflow/create-hook#keep-a-token-unavailable-after-the-run-ends) accepted by the Postgres World, in days. * Set this to the same limit as your production World so oversized values fail during development. ### `namespace` * Environment variable fallback: `WORKFLOW_QUEUE_NAMESPACE` * Default: none * Queue topic namespace. For example, `custom` changes `__wkf_*` topics to `__custom_wkf_*`. ### `streamFlushIntervalMs` * Environment variable fallback: `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` * Default: `0` (dispatch the leading chunk of an idle stream immediately) * Group-commit window for the leading chunk of an idle stream; a positive value trades first-chunk latency for larger groups. The `WORKFLOW_STREAM_FLUSH_INTERVAL_MS` environment variable, when set, overrides this option; otherwise the World option governs, including the first chunk. ## Vercel World The Vercel World is configured automatically inside Vercel deployments. The platform provides the deployment ID, project ID, request authentication, queue integration, storage, and encryption material. Most applications should not set `WORKFLOW_VERCEL_*` variables on Vercel. They configure tooling that talks to a Vercel Workflow project from outside a deployment, such as the Workflow CLI, the web user interface (UI), continuous integration (CI), or tests. The runtime warns if these variables are set in a deployed Vercel Function because they do not control runtime configuration there. Platform-provided values such as `VERCEL_DEPLOYMENT_ID`, `VERCEL_PROJECT_ID`, and `VERCEL_DEPLOYMENT_KEY` are read by the runtime inside Vercel deployments. Do not set them yourself; keep [system environment variables](/worlds/vercel#system-environment-variables) enabled for the project so that Vercel provides them. ### `token` * Environment variable: `WORKFLOW_VERCEL_AUTH_TOKEN`, then `VERCEL_TOKEN`, then Vercel CLI login * CLI flag: `--authToken` * Default: inferred when possible * Vercel API token for external tooling. Keep it secret. ### `projectConfig.environment` * Environment variable: `WORKFLOW_VERCEL_ENV` * CLI flag: `--env` or `-e` * Default: `production` * Vercel environment targeted by tooling. Accepts `production` or `preview`. ### `projectConfig.projectId` * Environment variable: `WORKFLOW_VERCEL_PROJECT` * CLI flag: `--project` * Default: inferred from `.vercel/project.json` when possible * Vercel project ID. ### `projectConfig.teamId` * Environment variable: `WORKFLOW_VERCEL_TEAM` * CLI flag: `--team` * Default: inferred from `.vercel/project.json` when possible * Vercel team ID. ### `WORKFLOW_VERCEL_PROJECT_NAME` * Factory option: none * CLI flag: none * Default: inferred when possible * Project slug used for dashboard links. ### `WORKFLOW_VERCEL_BACKEND_URL` * Factory option: none * CLI flag: none * Default: `https://api.vercel.com/v1/workflow` * Workflow API proxy URL for external tooling. ### `WORKFLOW_SEQUENTIAL_REPLAYS` * Default: disabled * Set `1` to serialize orchestrator (flow) invocations per run: each run's replays get their own queue topic and the flow trigger is generated with `maxConcurrency: 1`. Inline step executions get per-step topics and keep full parallelism. * Read at **both build time and runtime**: set it as a project-level environment variable so the generated trigger and the runtime queue routing agree. * Routing each run through a dedicated `maxConcurrency: 1` topic might lead to higher queue performance overhead. See [Vercel World](/worlds/vercel#workflow_sequential_replays) for details. ### `VERCEL_WORKFLOW_SERVER_URL` * Factory option: none * CLI flag: none * Default: unset * Direct workflow-server URL override for testing or custom infrastructure. Normal deployments do not need it. ### `VERCEL_QUEUE_MAX_DELAY_SECONDS` * Factory option: none * CLI flag: none * Default: `82800` (23 hours) * Maximum delay for one Vercel Queues continuation message when implementing `sleep()`. * Longer sleeps schedule another continuation when the first one fires. `VERCEL_QUEUE_MAX_DELAY_SECONDS` defaults to 23 hours because Vercel Queues message delays are capped by the message TTL, and the default TTL is 24 hours. Workflow stays inside that default and chains continuation messages for longer sleeps. ### `WORKFLOW_REQUEST_TIMEOUT_MS` * Factory option: none * CLI flag: none * Default: `60000` * Clamp: `10000` to `120000` (values outside are clamped, with a warning) * Per-request timeout for Vercel World HTTP calls to workflow-server. * At the `10000` floor the run-status long poll disables itself, because its budget is this value minus 10s of headroom. ### `WORKFLOW_MAX_CHUNKS_PER_REQUEST` * Factory option: none * CLI flag: none * Default: `1000` * Maximum stream chunks written in one Vercel World request. Larger batches are split. ### `WORKFLOW_STREAMS_TRANSPORT` * Factory option: none * CLI flag: none * Default: `http` * Experimental stream-write transport capability. Set to exactly `ws` to attempt `workflow-stream-ws/v1`. The server authoritatively accepts or declines each upgrade; a decline uses HTTP directly for that writer lifetime. Stream reads remain HTTP and demand-driven. * This is not tenant rollout policy or a package-version check. HTTP remains the compatibility path. `/websockets/v1` is independent of REST v2/v4 and persisted workflow `specVersion` values. * A throttled (429) socket write or close is retried after the server's `Retry-After`, as over HTTP. It moves to HTTP if the connection ends during the wait or the cumulative wait passes 30 seconds. ### `WORKFLOW_DISABLE_ANALYTICS_READS` * Factory option: none * CLI flag: none * Default: disabled * Set `1` to turn off the World's metadata-only `analytics` read namespace, forcing `workflow inspect` and web UI list views onto strongly consistent primary storage. Intended for tests and tooling that read entities immediately after writing them. ### `WORKFLOW_BATCH_TRANSITIONS` * Surface: environment variable * Default: on * Set to `0` (or `false`) to **disable** batched event writes, the escape hatch that restores the exact prior one-write-per-event path. When enabled (the default), a suspension's eager `step_created` and `wait_created` writes fold into batched `events.createBatch` calls (one durable write with per-event outcomes) on Worlds that implement the optional batch API. The fold only engages when the World implements `events.createBatch` (the Vercel World does; Local and Postgres do not), the run's spec version supports slot identity (≥ 6), and the suspension carries no attribute writes or resilient step dispatch. Hook writes in the same suspension go through the single-event path concurrently with the batch. Everything else keeps the single-event path unchanged, so disabling is only needed as an operational escape hatch. Batches are capped at 32 events; larger fan-outs commit in successive batches. See the [batched event writes changelog](/docs/changelog/batched-event-writes) for the World API contract. ### `WORKFLOW_EVENTS_TRANSPORT` * Factory option: none * CLI flag: none * Default: `http` * Set to `ws` to ship workflow run events to the Vercel World over a WebSocket instead of one HTTP request each. Only `ws` (case-insensitive) opts in; any other value, including unset, empty, or `http`, keeps HTTP. * Ignored when the World is configured with `projectConfig` and routes through the `api-workflow` proxy: that endpoint is an HTTP-only REST gateway and does not forward a WebSocket upgrade, so events stay on HTTP. ### `WORKFLOW_WS_MAX_MESSAGE_BYTES` * Factory option: none * CLI flag: none * Default: `12582912` (12 MiB) * Clamp: `2097152` to `16777216` (values outside are clamped, with a warning) * Largest events WebSocket message, header included. A larger frame is sent as several messages and rebuilt on the other side. The ceiling is the 16 MiB WebSocket message limit. --- 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)