Getting Started

Prerequisites

You need:

• Node.js 24 or newer
• npm, which Node.js includes
• A credential for the model your agent uses

Connect a ChatGPT subscription, a Vercel account, or an AI Gateway, OpenAI, or Anthropic API key in the terminal UI. You do not need a Vercel project to start chatting.

Choose a model, provider, and channel that meet your data-processing and compliance requirements.

Create a project

Run eve init with a project name to create a project with one agent in agent/:

npx eve@latest init my-agent

The command creates the project, installs dependencies, initializes Git, and opens the terminal UI. eve reuses an available model connection or opens /login. Once connected, type your first message. Channel and integration setup is optional; use /add when you need it.

In /add, search by name or by what an item does, such as iMessage or SMS. Select an item to install it and complete its setup.

During startup, the status line shows what eve is waiting for. If you choose a Vercel account, finish signing in in your browser and select a team when prompted. eve checks that team's AI Gateway access before returning to the composer. Changing the account, team, or key needs no rebuild or restart.

To add eve to a project that already has a package.json, run this command from its root before you create any agent/ files:

npx eve@latest init .

eve adds the missing eve, ai, and zod dependencies without changing files the project already owns.

Customize initialization

To initialize the agent with a different AI Gateway model or reasoning effort, pass --model or --reasoning:

npx eve@latest init my-agent --model openai/gpt-6-luna --reasoning high

Run the agent

The terminal UI opens after interactive initialization. To return later, enter the project and run:

cd my-agent
npm run dev

This starts an interactive session where you can send messages to your agent. Edit agent/instructions.md to change its behavior and agent/agent.ts to configure its model. eve reloads your changes as you work. You can also ask the agent to update its own instructions, tools, or skills; see Self-Modification.

Organize your project

See Project Structure when adding another root agent or deciding where a frontend belongs. The Agent Files reference lists supported files and discovery rules.

Install manually

If you do not want to use the scaffold, install the runtime dependencies:

npm install eve@latest ai zod

Declare Node.js 24 in package.json, then create agent/instructions.md and, when you need runtime configuration, agent/agent.ts.

The installed package's node_modules/eve/CHANGELOG.md contains that version's release notes and a link to the full changelog through that version. For an upgrade across multiple releases, review each version between the installed and target versions in the target version's changelog at https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%40<version>/packages/eve/CHANGELOG.md.

Upgrade an existing project

To move a project from eve 0.83 or earlier, follow Upgrade to 1.0. It covers the deploy order, the v27 session stream, renamed APIs, and saved history.

Next steps

Continue with the task you need:

Read Execution Model and Durability to learn how sessions, turns, and steps run, and how waiting work survives restarts.