Durable agents with eve

eve is Vercel's open-source (Apache-2.0) framework for durable backend agents. An agent is a folder of files: instructions, tools, skills, connections and schedules. eve runs it as checkpointed steps, so a session can wait for an approval or a timer and pick up again after a restart. The durable-agent exercises use it to build agents that survive crashes and long waits. This page gets one running on your machine.

Before you start

• Node.js 24 or newer, with npm. Check with node --version; see Node.js, pnpm and TypeScript.
• One model credential. eve's built-in connections are a Vercel account, a Vercel AI Gateway key, an OpenAI or Anthropic API key, or a ChatGPT subscription, and agent.ts also accepts any AI SDK model. For these courses, use your personal OpenRouter key through OpenRouter's AI SDK provider (step 2), or a local Ollama model. A Claude subscription isn't one of the connections eve offers.
• No Vercel account or project is needed to run locally. You only need one to deploy to Vercel.
• Docker is optional. Without it, local development uses eve's built-in pure-JavaScript sandbox (just-bash). The first eve dev installs the just-bash package into your project if it isn't there; add it to devDependencies yourself so installs stay reproducible.

1. Create a project

npx eve@latest init my-agent

This scaffolds the project with one agent in agent/, installs dependencies, initialises git and opens the terminal UI. To scaffold without starting the UI, add --non-interactive.

The parts you'll edit most:

2. Connect a model through OpenRouter

The model is set in agent/agent.ts, and it can be a model string or a model instance:

• No agent.ts: eve uses the AI Gateway model openai/gpt-6-luna-fast. eve init also starts from an AI Gateway model unless you pass --model.
• A model string, such as "anthropic/claude-opus-5.5", routes through the Vercel AI Gateway, which needs a Vercel account connection or an AI Gateway key.
• A model instance calls the provider directly. eve accepts any AI SDK language model, so OpenRouter's official AI SDK provider works.

Install the provider in the project:

npm install @openrouter/ai-sdk-provider

import { createOpenRouter } from "@openrouter/ai-sdk-provider";
import { defineAgent } from "eve";
 
const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
 
export default defineAgent({
  model: openrouter(process.env.MODEL ?? "anthropic/claude-sonnet-5.5"),
  modelContextWindowTokens: 1_000_000,
});

eve dev loads .env, .env.local, .env.development and .env.development.local, so put the key in .env.local and make sure git ignores it:

OPENROUTER_API_KEY=sk-or-...
MODEL=anthropic/claude-sonnet-5.5

MODEL is any OpenRouter slug. eve calls tools on most turns, so Anthropic models are the most reliable choice; a cheap one such as anthropic/claude-haiku-5.5 is fine while you build. Set modelContextWindowTokens to the model's context length (the OpenRouter model page lists it), because eve uses it to decide when to compact: 1,000,000 for Sonnet 5.5 and Haiku 5.5.

/login and /model manage eve's built-in connections only. With a custom provider like this one, change the model in .env.local or agent.ts.

3. Other ways to connect

If you already have a direct OpenAI or Anthropic API key, eve's own helpers (openai() from eve/models/openai, anthropic() from eve/models/anthropic) read OPENAI_API_KEY or ANTHROPIC_API_KEY, or a key saved through /login. /login offers a Vercel account, an AI Gateway key, a ChatGPT subscription, an OpenAI key or an Anthropic key, and saves keys in your OS secret store, never in project files. For these courses, OpenRouter or a local model is enough.

Use a local model instead

eve works with any OpenAI-compatible server through the AI SDK provider. With Ollama:

npm install @ai-sdk/openai-compatible
ollama pull gpt-oss:20b
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
import { defineAgent } from "eve";
 
const ollama = createOpenAICompatible({
  name: "ollama",
  baseURL: "http://localhost:11434/v1",
  includeUsage: true,
});
 
export default defineAgent({
  model: ollama("gpt-oss:20b"),
  modelContextWindowTokens: 64_000,
});

Set modelContextWindowTokens to the context your server actually allocates, because eve uses it to decide when to compact. eve calls tools on most turns, so pick a model with native tool calling; the eve docs suggest gpt-oss:20b, qwen3 or gemma4. Expect weaker results than with Claude.

4. Run it locally

cd my-agent
npm run dev

This starts the agent with eve dev: a local server on 127.0.0.1:2000 and the terminal UI. Type a message and press Enter. eve reloads as you edit agent/ files. Commands you'll use:

Durability locally. By default, local runs use eve's built-in local Workflow World. A new eve dev process leaves unfinished runs from earlier processes dormant. To try to recover them, start with eve dev --resume.

Telemetry. The eve CLI collects telemetry by default. Turn it off with npx eve telemetry disable, or set EVE_TELEMETRY_DISABLED=1 for one command.

Check it works

Start the server without the UI, then call its public health route from another terminal:

npx eve dev --no-ui

curl http://127.0.0.1:2000/eve/v1/health

Expected output (your ID differs):

{"ok":true,"status":"ready","workflowId":"…"}

Then run npm run dev and send Say hello in five words. A reply means the model connection works too.

Troubleshooting

npx eve init fails with an engine or syntax error. Your Node is older than 24. Run node --version, then install a newer LTS with fnm install 26.

The UI keeps opening /login, or a Vercel login says Gateway access is unavailable. agent.ts still uses a Gateway model string, or there is no agent.ts. Switch it to the OpenRouter model instance from step 2. A Vercel account isn't required for local runs.

OpenRouter returns 401 or 402. The key didn't reach the process (check that OPENROUTER_API_KEY is in .env.local in the project root), or your balance or the key's credit limit is used up; see Get an OpenRouter key.

Messages to an old conversation fail after a restart. That run is dormant (see step 4). Run /new, or restart with npx eve dev --resume.

A local model ignores tools or forgets earlier turns. The context is too small or the model lacks tool calling. Raise OLLAMA_CONTEXT_LENGTH, match modelContextWindowTokens, and pick a tool-capable model.

Going further

• Get an OpenRouter key
• Local models with Ollama
• OpenRouter or a local model?