---
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

- Node.js 24 or newer, which includes npm
- Access to an AI model: a ChatGPT subscription, a Vercel account, or an [AI Gateway](https://vercel.com/docs/ai-gateway/authentication-and-byok), OpenAI, or Anthropic API key. You don't need a Vercel project to start chatting.

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

## Create a project

#### New project

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

```bash
npx eve@latest init my-agent
```

The command creates the project, installs dependencies, initializes Git, and opens the terminal UI.

#### Existing project

From the root of a project that has a `package.json` and no `agent/` directory, run:

```bash
npx eve@latest init .
```

The command adds an agent in `agent/`, installs dependencies, and opens the terminal UI.

eve connects with credentials you already have, or opens `/login` to set one up.

Once connected, you can start chatting with your agent. Use `/model` to switch models or reasoning effort.

## Run the agent

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

```bash
npx eve dev
```

eve reloads your changes as you work.

<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`.

## Next steps

Try these from the eve terminal UI:

1. **Change your agent's behavior.** Edit `agent/instructions.md`, or ask the agent to update its own instructions. See [Self-Modification](/docs/guides/self-modification).
2. **Give your agent a new capability.** Ask the agent to build one, such as "Add a tool that looks up the weather for a city" or "Connect to Linear."
3. **Let your agent communicate on another channel.** Run `/add` and choose a platform such as Slack or iMessage.
4. **Deploy it.** Run `/deploy` to ship the agent to Vercel, or see [Self-Hosting](/docs/guides/deployment/self-hosting).

For examples of what to build, see [Use Cases](/docs/use-cases). Then continue with the task you need:

| Goal                                                               | Read                                                                                                 |
| ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
| Give the model some code it can run                                | [Tools](/docs/tools)                                                                                 |
| Teach the agent a reusable procedure                               | [Skills](/docs/skills)                                                                               |
| Require human approval before a tool runs                          | [Human-in-the-Loop](/docs/human-in-the-loop)                                                         |
| 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)