Workflow Worlds

A Workflow world is the backend that stores eve sessions so they survive restarts and redeploys. eve runs every session as a Workflow SDK 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

WorldStorageProcessesAfter an eve version upgrade
LocalFiles under .eve/.workflow-dataOneExisting sessions cannot resume
PostgresA PostgreSQL databaseAny number of replicasExisting sessions cannot resume
Vercel WorkflowManaged by VercelManaged by VercelRuns 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 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.

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. To serve an agent from several replicas, 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, 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 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:

    pnpm add @workflow/world-postgres
  2. Select it in the root agent.ts:

    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:

    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:

VariableDefaultDescription
WORKFLOW_POSTGRES_WORKER_CONCURRENCY50Queued jobs each process runs at once
WORKFLOW_POSTGRES_MAX_POOL_SIZE10Connections in each process's database pool
WORKFLOW_POSTGRES_POLL_INTERVAL_MS500Milliseconds 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 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 for retention.

Use another world

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

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 for the Workflow SDK abstraction, and agent.ts 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.