---
title: Workflow Worlds
description: Choose and configure the Workflow world that stores and resumes eve sessions on a self-hosted deployment.
url: "https://eve.dev/docs/guides/deployment/workflow-worlds"
docs_index: /llms.txt
---

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

A Workflow world is the backend that stores eve sessions so they survive restarts and redeploys. eve runs every session as a [Workflow SDK](https://workflow-sdk.dev/) workflow. The world stores each run's event log, step results, pending input, and streams, and queues the work that resumes it. eve uses Vercel Workflow on Vercel and the local world for `eve start`. A self-hosted deployment can select another world package without changing the agent.

## Compare worlds

| World                               | Storage                            | Processes              | After an eve version upgrade                                                                       |
| ----------------------------------- | ---------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
| [Local](#use-the-local-world)       | SQLite under `.eve/.workflow-data` | One                    | Existing sessions cannot resume                                                                    |
| [Postgres](#use-the-postgres-world) | A PostgreSQL database              | Any number of replicas | Existing sessions cannot resume                                                                    |
| [Vercel Workflow](./vercel)         | Managed by Vercel                  | Managed by Vercel      | Runs continue on their original deployments; eligible idle sessions can move to the new deployment |

On the local and Postgres worlds, a new build on the same eve version resumes existing sessions. See [Upgrade a self-hosted agent](./self-hosted-operations#upgrade-a-self-hosted-agent) for what happens when the eve version changes.

All three support compaction handoff, which moves a session to a fresh run while keeping its ID, event stream, and addresses; the Postgres world needs `@workflow/world-postgres` 5.0.4 or later. Vercel Workflow also supports moving eligible idle sessions between deployments. See [Execution model and durability](../../concepts/execution-model-and-durability#compaction-handoff).

eve needs a world with atomic start hooks, so a new session takes its channel address as it starts. All three worlds provide them; the Postgres world needs `@workflow/world-postgres` 5.1.1 or later. On a world without them, starting a session fails with an error that names this requirement.

## Use the local world

The local world is the default for `eve start` and needs no configuration. It stores run state under `.eve/.workflow-data` in the app directory. Mount that directory on persistent storage so runs survive process and container replacement.

Each `eve start` process accepts queue messages only from its own queue. Don't point `WORKFLOW_LOCAL_BASE_URL` at a load balancer, because another replica rejects forwarded messages with HTTP 401. `eve start` refuses to start with `WORKFLOW_QUEUE_AUTH=off`, which would turn that check off. To serve an agent from several replicas, use the [Postgres world](#use-the-postgres-world).

On startup, `eve start` queues pending and running local workflow runs again. Runs that were active when the previous process stopped continue when the eve version is unchanged. A step that was running when the previous process stopped, such as a model call, runs again right away. In a [spec 8 run](#set-the-workflow-spec-version), that interrupted attempt counts toward the step's retries, so a step that allows no retries fails instead. `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS=0` or `false` doesn't disable this recovery.

Run one eve process, `eve start` or `eve dev`, per `.eve/.workflow-data` directory. Both use `.eve` in the app directory. Recovery treats steps started before it booted as abandoned, so a second live process on the same directory runs them twice.

## Use the Postgres world

The [`@workflow/world-postgres`](https://www.npmjs.com/package/@workflow/world-postgres) package stores runs in PostgreSQL and queues their work with Graphile Worker. Every `eve start` process connected to the same database processes queued work, so you can run several replicas behind a load balancer.

1. Install the package in your app:

   ```bash
   pnpm add @workflow/world-postgres
   ```

2. Select it in the root `agent.ts`:

   ```typescript title="agent/agent.ts"
   import { defineAgent } from "eve";

   export default defineAgent({
     model: "anthropic/claude-opus-5.5",
     experimental: {
       workflow: {
         world: "@workflow/world-postgres",
       },
     },
   });
   ```

3. Set the connection string in the runtime environment with `WORKFLOW_POSTGRES_URL`. The package also reads `DATABASE_URL`. When neither is set, it connects to `postgres://world:world@localhost:5432/world`.

4. Create the schema before the first start:

   ```bash
   pnpm exec bootstrap
   ```

   With npm, run `npx --package @workflow/world-postgres bootstrap`. The command reads the same connection variables. Run it again before you start a build that upgrades `@workflow/world-postgres`, so the database has the new version's migrations.

5. Build and start the server as usual with `eve build` and `eve start`.

### Tune the Postgres world

The package reads these optional variables:

| Variable                               | Default | Description                                      |
| -------------------------------------- | ------- | ------------------------------------------------ |
| `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | `50`    | Queued jobs each process runs at once            |
| `WORKFLOW_POSTGRES_MAX_POOL_SIZE`      | `10`    | Connections in each process's database pool      |
| `WORKFLOW_POSTGRES_POLL_INTERVAL_MS`   | `500`   | Milliseconds between idle job fetches per worker |

Graphile Worker recommends a pool size of at least the worker concurrency plus 2. With the default concurrency, set `WORKFLOW_POSTGRES_MAX_POOL_SIZE=52`, and size the database's connection limit for every replica's pool. See the [package README](https://www.npmjs.com/package/@workflow/world-postgres) for the full list.

The Postgres world stores workflow inputs, outputs, and stream contents in the database without encryption, and it keeps the records of finished runs until you delete them. Protect database access and backups, and see [Manage run data](./self-hosted-operations#manage-run-data) for retention.

## Use another world

Select any installed Workflow world package in the root `agent.ts`:

```typescript title="agent/agent.ts"
import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-opus-5.5",
  experimental: {
    workflow: {
      world: "@acme/eve-workflow-world",
    },
  },
});
```

The package must export a default factory or `createWorld()` function. It reads credentials and host options from runtime environment variables, not `agent.ts`. If the package must stay external in hosted output, list it in `build.externalDependencies`.

Install a world built against the same `@workflow/*` major version as your eve release, currently `5.x`. eve checks the world's `@workflow/core` or `@workflow/world` dependency at startup, and fails with the version to install when the major versions differ.

See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the Workflow SDK abstraction, and [agent.ts](../../agent-config#workflow-world) for the configuration field.

## Set the Workflow spec version

eve creates new runs with Workflow spec version 9, which drives each run from one orchestrator. eve sets `WORKFLOW_SPEC_VERSION=9` before it creates a world, unless `WORKFLOW_SPEC_VERSION` or `WORKFLOW_SEALED_LOG` is already set. To create spec 8 runs, set `WORKFLOW_SPEC_VERSION=8` in the runtime environment.

The setting applies only to new runs. Existing runs keep the version they started with. The local world, Vercel Workflow, and `@workflow/world-postgres` 5.1.0 or later create spec 9 runs. A world without spec 9 support, such as an earlier Postgres world, logs a warning and creates spec 8 runs. `eve dev` always creates spec 9 runs on the local world.

---

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)