GitHub

eve is a filesystem-first framework for durable agents. You write capabilities under agent/, and eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. You'll scaffold an app, add a tool, run it locally, then create, stream, and continue a session over HTTP.

Prerequisites

Node 24 or newer
npm (bundled with Node)
A model credential (see below)

The scaffold's default model is anthropic/claude-sonnet-5, which routes through the Vercel AI Gateway. Set one of these before you run the agent:

A gateway model id needs AI_GATEWAY_API_KEY, or a VERCEL_OIDC_TOKEN pulled with vercel link.
A direct provider model uses that provider's AI SDK package and API key. For example, anthropic("claude-...") from @ai-sdk/anthropic needs ANTHROPIC_API_KEY.

You are responsible for selecting a model, provider, and channel appropriate for your data and use case, and for complying with each provider's terms (as listed per model) and data-processing requirements.

If you skip this, the dev TUI flags the missing credential and its /model command walks you through pasting a key or linking a project.

Quick start

npx runs eve init without installing eve first:

npx eve@latest init my-agent

The command:

Creates a child directory using the current workspace or launcher package manager, and uses eve's default model
Installs dependencies and initializes Git
When a supported coding-agent REPL (Claude Code, Codex, Cursor, Droid, Gemini CLI, opencode, or Pi) is on PATH, asks whether to open an available REPL or start the development server; otherwise starts the server and opens the interactive terminal UI

Type a message and watch the model loop run. Pass --channel-web-nextjs to add the Web Chat application. Every app ships the built-in HTTP channel (agent/channels/eve.ts) regardless.

When you choose one of those REPLs, eve starts it with a project-specific prompt that guides the setup. The prompt distinguishes eve dev, which starts eve's HMR server and the agent's terminal REPL, from eve dev --no-ui, which is the controllable background mode for verification.

eve init holds the terminal, so stop it with Ctrl+C to get your shell back before editing the generated agent. The command does not create a Vercel project or deploy.

To add eve to an existing project, run eve init . from a directory that already has a package.json and no agent/ files yet. eve adds the missing eve, ai, and zod dependencies without touching anything else the project owns. The eve dependency and the Node engine come from the same release. eve pins engines.node to the lowest major that release supports (for example 24.x). It keeps an existing range only when every version that range allows stays within that major; otherwise it replaces the range and prints a warning.

Manual installation

To wire eve into an existing app by hand instead of using eve init, first declare a compatible Node runtime in package.json:

{
  "engines": {
    "node": "24.x"
  }
}

Then install the dependencies and author the two files the runtime needs. The eve init scaffold adds ai and zod for you; by hand you install all three:

npm install eve@latest ai zod

Project files

A minimal agent is two files; you add tools as you need them.

agent/instructions.md is the always-on system prompt:

You are a concise assistant. Use tools when they are available.

agent/agent.ts holds runtime config:

import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-sonnet-5",
});

Before using real customer data, confirm the selected model provider's terms, routing path, and retention settings are appropriate for that data.

Even at this size the agent can already do real work. The default harness gives it file, shell, web, and delegation tools out of the box. See Default harness for the full set and how to override or disable any of them.

Add your first tool

The filename becomes the tool name the model sees, and it must be snake_case ASCII. Create agent/tools/get_weather.ts:

import { defineTool } from "eve/tools";
import { z } from "zod";

// The model sees this tool as `get_weather`, from the filename.
export default defineTool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});

Tools run in your app runtime with full process.env, not inside the sandbox. More in Tools.

Run the app

A scaffolded app has a dev script, so from the app root run:

npm run dev

The manual path authors no dev script. Run the binary through npx instead:

npx eve dev

Other commands the eve binary provides (prefix each with npx, or add a matching package.json script):

eve info: show the active routes and compiled artifacts
eve build: compile the agent into .eve/ and build the host output
eve start: serve the built output
eve dev: start the local runtime and open the interactive terminal UI

In the dev TUI, type a message and watch it happen in order. First the get_weather call, then its result, then the reply.

The same CLI can point at a deployment. npx eve dev https://your-app.vercel.app drives a deployed app, which is handy for preview and production smoke tests. See Deployment.

Send a message

Every eve app exposes the same stable HTTP API. Start a durable session:

curl -X POST http://127.0.0.1:2000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"What is the weather in Brooklyn?"}'

The response comes back with two things you'll reuse:

a continuationToken in the JSON body, to resume this conversation
an x-eve-session-id header that identifies the run to stream

Stream the session

Attach to the session stream:

curl http://127.0.0.1:2000/eve/v1/session/<sessionId>/stream

The stream is NDJSON, served as application/x-ndjson; charset=utf-8. For this run you'll see a handful of lifecycle events:

session.started
actions.requested (the get_weather call)
action.result
message.completed (the reply)
session.completed

reasoning.appended and message.appended are optional live-streaming events. Clients that can't surface incremental output can ignore them and rely on reasoning.completed and message.completed.

Note: consider the privacy, confidentiality, and user-experience implications for displaying, storing, or transmitting reasoning events in your application.

The full set covers more lifecycle, human-in-the-loop, and authorization events, including input.requested, turn.failed, authorization.required, and authorization.completed. See Sessions, runs and streaming for every event and its data shape.

Send a follow-up message

When the session is waiting for the next user message, post a follow-up with the token:

curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId> \
  -H 'content-type: application/json' \
  -d '{"continuationToken":"<token>","message":"Now do Queens."}'

See Sessions, runs and streaming for the full contract.

Setting up with a coding agent

If a coding agent (Claude Code, Cursor, and the like) is doing the setup, hand it this prompt:

Prompt for coding agents

Set up an eve agent: read the eve docs (bundled at node_modules/eve/docs once eve is installed), scaffold with npx eve@latest init <name> (or npm install eve@latest ai zod in an existing app), add a typed tool at agent/tools/get_weather.ts, run it with npx eve dev --no-ui, then create a session, stream it, and send a follow-up.

Once eve is a dependency, the package bundles the full docs, so the agent can read them locally at node_modules/eve/docs/ without fetching anything.

To add a platform channel after setup, run eve channels add slack from an interactive terminal. The init flags are covered in Quick start.

Getting Started