---
title: "Getting Started"
description: "Install Eve, scaffold your first agent, give it a tool, and run it locally."
---

Eve is a filesystem-first framework for durable agents: you write capabilities under `agent/`, and Eve runs the model loop, persists every session, and serves the agent over HTTP and platform channels. This guide gets a small app running locally and walks the current request loop end to end: build, run, message, stream, and follow up.

## Prerequisites

- Node `24.x`
- `pnpm`

You also need a model credential. Set the provider or gateway key your model string requires (gateway ids like `anthropic/claude-opus-4.8` route through the Vercel AI Gateway), or link a Vercel project that supplies one.

## Create Your Agent

The fastest path is the `create` CLI. It scaffolds the project, prompts for a model, and wires up an optional channel:

```bash
pnpm create eve@beta
```

The wizard first asks how much to set up: a complete setup, or a one-shot scaffold (also available as `--one-shot`) that just writes the project files with the default model. The complete path describes the agent first — a model, the channels you'll chat through (Web Chat or Slack; the CLI REPL is always available), and the connections it can reach — and only then asks where it should run: on Vercel, or locally for now. Picking Slack or a Connect-backed connection settles that question automatically, since both need a Vercel project, and scaffolding into a directory that is already linked to one (with a logged-in Vercel CLI) skips it too: the AI Gateway authenticates through your Vercel login. Every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless of what you pick. For a local chat it installs dependencies and starts the dev server for you.

To add Eve to an existing app instead:

```bash
pnpm add eve@beta
```

## What's In Your Project

The scaffold writes two files; you add tools as you need them.

`agent/instructions.md` (generated) is the always-on system prompt:

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

`agent/agent.ts` (generated; model comes from the wizard) holds runtime config:

```ts
import { defineAgent } from "eve";

export default defineAgent({
  model: "anthropic/claude-opus-4.8",
});
```

Even at this size the agent can already do real work. The default harness gives it file, shell, web, and delegation tools out of the box. See [Default harness](./advanced/default-harness) for the full set and how to override or disable any of them.

### Add Your First Tool

Whatever you name the file becomes the tool name the model sees. Create `agent/tools/get_weather.ts`:

```ts
import { defineTool } from "eve/tools";
import { z } from "zod";

// The runtime tool name comes from the filename, so the model sees this as
// `get_weather`. Tool filenames must be snake_case ASCII.
export default defineTool({
  description: "Get the current weather for a city.",
  inputSchema: z.object({ city: z.string().min(1) }),
  async execute({ city }) {
    return { city, condition: "Sunny", temperatureF: 72 };
  },
});
```

Tools run in your app runtime with full `process.env`, not inside the [sandbox](./sandbox). More in [Tools](./tools).

## Run The App

From the app root:

```bash
pnpm dev
```

Useful commands:

- `eve info`: show the active routes and compiled artifacts
- `eve build`: compile the agent into `.eve/` and build the host output
- `eve start`: serve the built output
- `eve dev`: start the local runtime and open the interactive [terminal UI](./advanced/dev-tui)

In the dev TUI, type a message and watch it happen in order: the `get_weather` call, its result, then the reply.

The same CLI can point at a deployment. `eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./advanced/deployment).

## Send A Message

Every Eve app exposes the same stable HTTP API. Start a durable session:

```bash
curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"What is the weather in Brooklyn?"}'
```

The response comes back with two things you'll reuse:

- a `continuationToken` in the JSON body, to resume this conversation
- an `x-eve-session-id` header that identifies the run to stream

## Stream The Session

Attach to the session stream:

```bash
curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream
```

The stream is NDJSON. Expect lifecycle events such as:

- `session.started`
- `turn.started`
- `message.received`
- `step.started`
- `actions.requested`
- `action.result`
- `subagent.called`
- `subagent.completed`
- `reasoning.appended`
- `reasoning.completed`
- `message.appended`
- `message.completed`
- `step.completed`
- `turn.completed`
- `session.waiting`
- `session.completed`
- `session.failed`

`reasoning.appended` and `message.appended` are optional live-streaming events. Clients that can't surface incremental output can ignore them and rely on `reasoning.completed` and `message.completed`.

`message.completed.data.finishReason` tells you whether assistant text is interim tool-call narration or a terminal reply, and `step.completed.data.usage` carries token usage. When a parent delegates to a subagent, `subagent.called.data.childSessionId` gives you the child session id, so you can subscribe to that child stream and watch the delegated work.

## Send A Follow-Up Message

When the session is waiting for the next user message, post a follow-up with the token:

```bash
curl -X POST http://127.0.0.1:3000/eve/v1/session/<sessionId> \
  -H 'content-type: application/json' \
  -d '{"continuationToken":"<token>","message":"Now do Queens."}'
```

See [Sessions, runs & streaming](./advanced/sessions-runs-and-streaming) for the full contract.

## Setting up with a coding agent

If a coding agent (Claude Code, Cursor, and the like) is doing the setup, hand it this prompt:

<CopyPrompt text="Set up an Eve agent for the user. Eve is a filesystem-first TypeScript framework for durable agents, published as the npm package eve. Read its docs: once eve is installed they are bundled in the package at node_modules/eve/dist/docs/public; before eve is installed, read the published Introduction and Getting Started pages. If the project has no Eve app, scaffold one with `pnpm create eve@beta`; to add Eve to an existing app, run `pnpm add eve@beta`. Make sure agent/agent.ts (which sets the model) and agent/instructions.md exist, then add a first typed tool at agent/tools/get_weather.ts using defineTool from eve/tools with a Zod inputSchema and an inline execute. Run it locally with `pnpm dev` (or `eve dev`), then exercise the HTTP API: create a session with POST /eve/v1/session, attach to GET /eve/v1/session/:id/stream, and send a follow-up with the returned continuationToken. Verify with the project's typecheck, adapt model and provider choices to the project, and do not commit unless the user asks.">
  Set up an Eve agent: read the Eve docs (bundled at node_modules/eve/dist/docs/public once eve is
  installed), scaffold with `pnpm create eve@beta` (or `pnpm add eve@beta` in an existing app), add
  a typed tool at agent/tools/get_weather.ts, run it with `pnpm dev`, then create a session, stream
  it, and send a follow-up.
</CopyPrompt>

Once `eve` is a dependency, the full docs are bundled in the package, so the agent can read them locally without fetching anything:

- Docs: `node_modules/eve/dist/docs/public/`

To scaffold a project end to end, `pnpm create eve@beta` collects the decisions (name, setup mode, model, channels), runs setup, adds Slack interactively with `eve channels add slack`, and verifies the result with `eve info --json`.

## What to read next

- [Instructions](./instructions) and [Tools](./tools): the core building blocks
- [Channels](./channels/overview): reach the agent from Slack, Discord, or a web UI
- [Frontend](./frontend/overview): browser chat with `useEveAgent`
- [TypeScript Client](./client/overview): call the agent from scripts or server-side code
- [Sessions, runs & streaming](./advanced/sessions-runs-and-streaming): the durable session model
- [Build an agent](./tutorial/first-agent): the full end-to-end walkthrough
