---
title: Getting Started
description: Create an eve project, configure model credentials, and run your first agent.
url: "https://eve.dev/docs/getting-started"
docs_index: /llms.txt
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

## 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/`:

```bash
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:

```bash
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`:

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

## Run the agent

The [terminal UI](/docs/guides/dev-tui) opens after interactive initialization. To return later, enter the project and run:

```bash
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](./guides/self-modification).

<span id="project-layout" />

<span id="agent-directory-layout" />

<span id="naming-from-paths" />

<span id="recommended-layout" />

<span id="nested-layout" />

<span id="agent-files-and-directories" />

<span id="files-available-in-the-sandbox" />

<span id="local-subagents" />

<span id="flat-layout" />

<span id="debug-file-discovery" />

## Organize your project

See [Project Structure](/docs/concepts/project-structure) when adding another root agent or deciding where a frontend belongs. The [Agent Files reference](/docs/reference/agent-files) lists supported files and discovery rules.

## Install manually

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

```bash
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](./guides/upgrade). It covers the deploy order, the v27 session stream, renamed APIs, and saved history.

## Continue with the tutorial

The [Tutorial](/docs/tutorial/first-agent) 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:

| Goal                                                               | Read                                                                                                 |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Give the model some code it can run                                | [Tools](/docs/tools)                                                                                 |
| Connect the agent to an external MCP or OpenAPI service            | [Connections](/docs/connections)                                                                     |
| Communicate with users through Slack, Discord, or another platform | [Channels](/docs/channels)                                                                           |
| Build a browser interface                                          | [Frontend Frameworks](/docs/guides/frontend)                                                         |
| Test agent behavior                                                | [Evals](/docs/evals)                                                                                 |
| Secure and deploy the agent                                        | [Authentication](/docs/guides/auth-and-route-protection), then [Deployment](/docs/guides/deployment) |

Read [Execution Model and Durability](/docs/concepts/execution-model-and-durability) to learn how sessions, turns, and steps run, and how waiting work survives restarts.

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)