Getting Started

Purpose and Scope

Use this page when you are installing eve for the first time, creating a new agent project, or adding eve to an existing Node application. The getting-started flow is intentionally practical: prepare the runtime, make sure a model credential is available, run the scaffold, then interact with the local development experience before editing the generated files. eve is described here as a filesystem-first framework for durable agents, which means the files you place under the agent directory define the agent’s behavior while eve owns the model loop, session persistence, HTTP serving, and platform channel plumbing.

Sources: docs/getting-started.mdx

The first decision is whether you want eve to create a new project directory or initialize a project you already own. New users usually start with the scaffold command because it creates the child app, installs dependencies, initializes Git, chooses the default model, and launches the local experience. Existing application owners can run initialization in place, as long as the directory already has package metadata and does not already contain authored eve agent files. In both cases, the result is a project whose capabilities are expressed by filesystem convention rather than a large handwritten registry.

Sources: docs/getting-started.mdx

Relevant Source Files

• docs/getting-started.mdx — Primary user-facing guide for prerequisites, scaffold behavior, manual installation, minimal project files, credential requirements, and the first local run.

Prerequisites

Before running the scaffold, install Node 24 or newer and use npm, which ships with Node. The starter agent uses the model id anthropic/claude-sonnet-5 by default. That default routes through the Vercel AI Gateway, so the local runtime needs either an AI Gateway key or a Vercel identity token obtained through project linking. If you choose a direct model provider instead, install and configure that provider’s AI SDK package and set the provider-specific API key. The guide calls out Anthropic as an example of that direct-provider path.

Sources: docs/getting-started.mdx

Credential setup is not just a mechanical prerequisite. The documentation places responsibility on the application developer to choose a model, provider, and channel that fit the data being processed and the use case being served. That includes checking provider terms and data-processing requirements before sending sensitive or customer-owned information through the runtime. If you skip the credential step during early exploration, local development still helps: the dev terminal UI detects the missing credential and offers a model command that can walk you through pasting a key or linking a Vercel project.

Sources: docs/getting-started.mdx

Quick Start Flow

Run the scaffold through npx when you do not want to install eve globally first. The command creates a new project folder, installs the required packages, initializes Git, and then chooses the best available local development path. If a supported coding-agent REPL is on the shell path, eve asks whether to open that REPL or start the development server. Supported REPLs include Claude Code, Codex, Cursor, Droid, Gemini CLI, opencode, and Pi. If none is available, eve starts the development server and opens the interactive terminal UI.

npx eve@latest init my-agent

Sources: docs/getting-started.mdx

After the scaffold starts, type a message in the terminal UI and watch the model loop run. This first interaction matters because it validates several moving parts at once: Node is compatible, the package installation completed, the model credential resolves, the default channel is available, and the local runtime can create a session. The generated project always includes the built-in HTTP channel at agent/channels/eve.ts. You can also pass the channel-web-nextjs flag during initialization when you want the Web Chat application added alongside the backend agent.

Sources: docs/getting-started.mdx

The init command holds the terminal while the local experience is running. Stop it with Ctrl+C before editing generated files or running follow-up commands in the same shell. The docs are explicit that initialization does not create a Vercel project and does not deploy anything; it is a local scaffold and development flow. When eve launches a supported coding-agent REPL, it supplies a project-specific prompt that distinguishes the normal dev command, which starts the hot-module-reloading server and terminal REPL, from the no-UI mode used for controllable background verification.

Sources: docs/getting-started.mdx

Core Primitives

The generated app revolves around a small set of primitives. The agent directory is the authoring boundary. Instructions are the always-on system prompt that shapes the agent’s identity and standing behavior. The agent configuration file selects the model and runtime options. Tools are typed functions the model can call when it needs application-specific actions or data access. Channels expose the agent to callers; every scaffold includes the built-in HTTP channel, and the optional Web Chat flag adds a frontend-oriented channel experience. Sessions are persisted conversations served by the runtime, so clients can create, stream, and continue work over HTTP.

Sources: docs/getting-started.mdx

This mental model is important before adding complexity. Instead of registering everything in one central file, you add capabilities in conventional places, and eve discovers them. That is why the first manual project contains only two essential files: an instructions file and an agent configuration file. Tools, skills, connections, schedules, subagents, and additional channels can be added later as the use case demands. Getting a tiny agent running first gives you a known-good baseline before you introduce external data, provider-specific models, approvals, sandboxed execution, or production deployment wiring.

Sources: docs/getting-started.mdx

Existing Projects and Manual Installation

To add eve to an existing project, run initialization with the current directory as the target. The documented constraint is that the directory already has a package file and does not yet contain agent files. In that mode, eve adds the missing dependencies it needs, including eve, ai, and zod, without taking ownership of unrelated project code. The dependency version and Node engine are tied to the same eve release. When necessary, initialization pins the Node engine to the lowest supported major version for that release and warns if it must replace an incompatible existing range.

cd myapp
npx eve@latest init .

Sources: docs/getting-started.mdx

Manual installation is the alternative when you want to wire the project yourself. First declare a compatible Node runtime in package metadata, then install eve with ai and zod. After that, author the minimal runtime files under the agent directory. The instructions file supplies the standing prompt. The agent configuration file imports defineAgent from eve and exports a configuration object with the selected model. Even at this size, the project can run locally, but the docs again recommend confirming provider terms, routing, and retention settings before using real customer data.

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

npm install eve@latest ai zod

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

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

Sources: docs/getting-started.mdx

First Local Run and Next Steps

For a newly scaffolded project, the first local run is usually the fastest confirmation that the agent is healthy. Start the development script created by the scaffold, open the terminal UI if it is not already running, and ask a simple question. If the runtime reports a missing credential, use the model setup path rather than editing random environment variables until the provider can be reached. If the model answers, you have verified the durable session loop, the selected model route, and the built-in HTTP-facing agent surface.

npm run dev

Sources: docs/getting-started.mdx

Once the baseline works, make one deliberate change at a time. Edit the instructions to give the agent a clearer role, add a tool when it needs deterministic application data or actions, and consider the Web Chat option when you want a browser-facing frontend during development. Keep the generated HTTP channel in mind even if you are using a frontend or platform channel, because it is the common path for creating, streaming, and continuing sessions programmatically. From here, continue to the first-agent tutorial for a guided end-to-end build, or use the project layout reference before adding more authored slots.

Sources: docs/getting-started.mdx