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

Start with one agent in agent/.

Run eve init with a project name:

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 capability, such as iMessage or SMS. The picker matches item names, addresses, titles, and descriptions. Select an item to install it and complete its required 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 and applies the connection before returning to the composer. Changing only the account, team, or key does not rebuild your agent. Once connected, you can send your first message while the agent information refreshes in the background; no restart is required.

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-5.6-terra --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.

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.

Continue with the tutorial

The Tutorial builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result.

After the tutorial, continue with the task you need:

Read Execution Model and Durability for the mental model behind sessions, turns, durable steps, and parked work.