Vercel Eve — The Filesystem-First Framework for Durable AI Agents (Complete Guide)
Vercel Eve — The Filesystem-First Framework for Durable AI Agents
Eve is a filesystem-first framework for building durable backend AI agents that run anywhere. Developed by Vercel (the company behind Next.js and the Vercel AI SDK), Eve takes a radically simple approach: every part of your agent is a file in a well-known directory structure. Your agent's instructions, tools, skills, channels, and schedules each live in their own conventional locations — no configuration objects, no registries, no boilerplate.
Since its release on June 16, 2026, Eve has gained over 3,100 GitHub stars. It represents a shift from "agent framework as a library" to "agent framework as a filesystem," where the project tree itself is the authoring interface.
Why It's Trending
The AI agent space is crowded with frameworks, but Eve stands out for three reasons:
- Filesystem-first design — Add a file, and Eve discovers it. Rename or move it, and its identity moves with it. There is no separate registry to maintain.
- Durable by default — Sessions survive crashes, network failures, and restarts. Eve uses the Workflow SDK to make sessions resumable without extra code.
- Built-in channels — HTTP, Slack, Discord, and more are first-class citizens. Your agent can serve a web API or respond in a chat room with the same code.
- HMR development — Hot Module Replacement means you edit a file and the agent reloads instantly. No rebuilds, no restarts.
Prerequisites
- Node.js 24 or newer
- npm (bundled with Node)
- An API key for your preferred LLM provider (Anthropic, OpenAI, Google, etc.)
- Basic familiarity with TypeScript
Quick Start
Scaffold your first agent in one command:
npx eve@latest init my-agentThis creates a new my-agent directory, installs dependencies, initializes Git, and starts the interactive terminal UI. Type a message and the model loop runs immediately.
To add Eve to an existing project:
cd myapp
npx eve@latest init .The scaffold's default model is anthropic/claude-sonnet-5. Set your API key as an environment variable:
export ANTHROPIC_API_KEY="sk-ant-..."Then start the dev server:
cd my-agent
npm run devProject Structure
An Eve agent is a TypeScript project with a conventional layout:
my-agent/
package.json
agent/
agent.ts # Model and runtime config
instructions.md # Always-on system prompt (identity, rules)
tools/
get_weather.ts # Typed functions the model can call
search_docs.ts
skills/
plan_trip.md # On-demand procedures loaded when useful
channels/
slack.ts # Communication platforms
discord.ts
schedules/
weekly_report.ts # Recurring cron jobsagent.ts — Runtime Configuration
Set the model, reasoning effort, and compaction settings:
import { defineAgent } from "eve";
export default defineAgent({
model: "anthropic/claude-sonnet-5",
reasoning: "high",
compaction: {
thresholdPercent: 0.75, // Compact context when 75% full
},
});instructions.md — The System Prompt
Your agent's permanent identity. This is prepended to every model call:
You are a concise assistant. Use tools when they are available.
Always verify critical information before reporting it.
Keep responses brief and actionable.tools/ — Typed Functions
Each tool is a file that exports a defineTool call:
import { defineTool } from "eve/tools";
import { z } from "zod";
export default defineTool({
description: "Get the current weather for a city.",
inputSchema: z.object({ city: z.string().min(1) }),
async execute({ city }) {
const res = await fetch(
`https://api.weather.com/current?city=${encodeURIComponent(city)}`
);
return res.json();
},
});skills/ — On-Demand Procedures
Longer procedures that only load when the model calls load_skill:
# plan_trip
When asked to plan a trip:
1. Ask for destination, dates, and budget
2. Search for flights using search_flights tool
3. Search for hotels using search_hotels tool
4. Compile an itinerary with suggestions
5. Ask for confirmation before bookingchannels/ — Platform Integrations
Eve ships with built-in HTTP handling. Add Slack or Discord by creating a channel file:
import { defineChannel } from "eve/channels";
export default defineChannel({
platform: "slack",
token: process.env.SLACK_BOT_TOKEN,
// Eve handles the message routing automatically
});schedules/ — Cron Jobs
Recurring tasks run on a cron schedule:
import { defineSchedule } from "eve/schedules";
export default defineSchedule({
cron: "0 9 * * 1", // Every Monday at 9 AM
async execute() {
// Generate weekly report
return { summary: "Report generated" };
},
});Architecture Overview
Eve's architecture follows a clean layered design. At the top, Platform Channels (HTTP, Slack, Discord, Terminal UI) receive messages from users. The Eve Runtime orchestrates the agent loop: it loads the Filesystem Manifest (instructions, tools, skills, schedules), manages session persistence via the Workflow SDK, and streams results back through channels.
The LLM Provider (Anthropic, OpenAI, Google, etc.) handles inference through the Vercel AI Gateway or directly via AI SDK provider packages. Compaction automatically summarizes older turns as the context window fills, keeping agents running in long sessions without manual tuning.
Installation & Setup
1. Install Node.js 24
Eve requires Node 24 or newer. Install using nvm:
nvm install 24
nvm use 242. Scaffold an Agent
npx eve@latest init my-first-agent
cd my-first-agent3. Configure the Model
Edit agent/agent.ts to set your preferred model:
import { defineAgent } from "eve";
export default defineAgent({
model: "openai/gpt-5.5",
});Install the provider SDK if using a direct provider model:
npm install @ai-sdk/openai4. Set API Keys
export OPENAI_API_KEY="sk-..."Or for the Vercel AI Gateway:
export AI_GATEWAY_API_KEY="gwk-..."5. Run the Agent
npm run devThe terminal UI opens. Type a message and watch the model loop execute, call tools, and respond.
Creating Custom Tools
Tools are the primary way your agent interacts with the outside world. Here are practical examples:
Web Search Tool
import { defineTool } from "eve/tools";
import { z } from "zod";
export default defineTool({
description: "Search the web for recent information.",
inputSchema: z.object({
query: z.string().min(1),
maxResults: z.number().max(10).default(5),
}),
async execute({ query, maxResults }) {
// Call your search API here
return { results: [] };
},
});Database Query Tool
import { defineTool } from "eve/tools";
import { z } from "zod";
export default defineTool({
description: "Query the PostgreSQL database.",
inputSchema: z.object({
sql: z.string().min(1),
}),
async execute({ sql }) {
// Sanitize and execute query
return { rows: [] };
},
});Adding Slack Integration
Create agent/channels/slack.ts:
import { defineChannel } from "eve/channels";
export default defineChannel({
platform: "slack",
signingSecret: process.env.SLACK_SIGNING_SECRET,
botToken: process.env.SLACK_BOT_TOKEN,
});Set the environment variables and restart. Eve handles Slack event subscription, message parsing, and response delivery automatically.
Production Deployment
Eve supports several deployment targets:
Docker
Eve provides a sandbox Docker image. Create a Dockerfile:
FROM ghcr.io/vercel/eve-sandbox:latest
WORKDIR /app
COPY package.json ./
RUN npm install
COPY . .
CMD ["npx", "eve", "start"]Vercel Deployment
npx eve deployThis links your project to Vercel and deploys the agent as a serverless function with HTTP and scheduled task support.
Self-Hosted (Node)
Run the built agent behind a process manager:
npm run build
pm2 start dist/index.js --name my-agentVerification Checklist
npx eve@latest init test-agentcreates a working scaffoldnpm run devstarts the terminal UI without errors- Typing a message produces a valid model response
- Adding a
.tsfile toagent/tools/is auto-discovered (no restart needed with HMR) - Adding
agent/slack.tsenables Slack message handling - Session state persists after an agent crash (durability check)
eve deployproduces a working production endpoint
Resources
- GitHub Repository: github.com/vercel/eve
- Official Documentation: eve.dev/docs
- NPM Package: npmjs.com/package/eve
- Getting Started Tutorial: eve.dev/docs/tutorial/first-agent
- Vercel AI Gateway: vercel.com/docs/ai-gateway
- Workflow SDK: workflow-sdk.dev
- Discord Community: discord.gg/zPQJrNGuFB