--- title: Getting Started description: Install Eve, scaffold your first agent, give it a tool, and run it locally. --- # Getting Started 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. You'll scaffold an app, add a tool, run it locally, then create, stream, and continue a session over HTTP. ## Prerequisites * Node 24 or newer * npm (bundled with Node) * A model credential (see below) The scaffold's default model is `anthropic/claude-sonnet-4.6`, which routes through the Vercel AI Gateway. Set one of these before you run the agent: * A gateway model id needs `AI_GATEWAY_API_KEY`, or a `VERCEL_OIDC_TOKEN` pulled with `vercel link`. * A direct provider id needs that provider's key, derived from the model prefix. For example, `anthropic/claude-...` needs `ANTHROPIC_API_KEY`. If you skip this, the dev TUI flags the missing credential and its `/model` command walks you through pasting a key or linking a project. ## Quick start `npx` runs `eve init` without installing Eve first: ```bash npx eve@latest init my-agent ``` The command: * Creates an npm-managed child directory and uses Eve's default model * Installs dependencies and initializes Git * Starts the development server and opens the interactive [terminal UI](./guides/dev-tui) Type a message and watch the model loop run. Pass `--channel-web-nextjs` to add the Web Chat application. Every app ships the built-in HTTP channel (`agent/channels/eve.ts`) regardless. `eve init` holds the terminal, so stop it with Ctrl+C to get your shell back before editing the generated agent. The command does not create a Vercel project or deploy. To add Eve to an existing project, run `eve init .` from a directory that already has a `package.json` and no `agent/` files yet. Eve adds the missing `eve`, `ai`, and `zod` dependencies without touching anything else the project owns. The Eve dependency and the Node engine come from the same release. Eve pins `engines.node` to the lowest major that release supports (for example `24.x`). It keeps an existing range only when every version that range allows stays within that major; otherwise it replaces the range and prints a warning. ## Manual installation To wire Eve into an existing app by hand instead of using `eve init`, first declare a compatible Node runtime in `package.json`: ```json { "engines": { "node": "24.x" } } ``` Then install the dependencies and author the two files the runtime needs. The `eve init` scaffold adds `ai` and `zod` for you; by hand you install all three: ```bash npm install eve@latest ai zod ``` ### Project files A minimal agent is two files; you add tools as you need them. `agent/instructions.md` is the always-on system prompt: ```md You are a concise assistant. Use tools when they are available. ``` `agent/agent.ts` holds runtime config: ```ts import { defineAgent } from "eve"; export default defineAgent({ model: "anthropic/claude-sonnet-4.6", }); ``` 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](./concepts/default-harness) for the full set and how to override or disable any of them. ### Add your first tool The filename becomes the tool name the model sees, and it must be snake\_case ASCII. Create `agent/tools/get_weather.ts`: ```ts import { defineTool } from "eve/tools"; import { z } from "zod"; // The model sees this tool as `get_weather`, from the filename. 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 A scaffolded app has a `dev` script, so from the app root run: ```bash npm run dev ``` The manual path authors no `dev` script. Run the binary through `npx` instead: ```bash npx eve dev ``` Other commands the eve binary provides (prefix each with `npx`, or add a matching package.json script): * `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](./guides/dev-tui) In the dev TUI, type a message and watch it happen in order. First the `get_weather` call, then its result, then the reply. The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/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//stream ``` The stream is NDJSON, served as `application/x-ndjson; charset=utf-8`. For this run you'll see a handful of lifecycle events: * `session.started` * `actions.requested` (the `get_weather` call) * `action.result` * `message.completed` (the reply) * `session.completed` `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`. The full set covers more lifecycle, human-in-the-loop, and authorization events, including `input.requested`, `turn.failed`, `authorization.required`, and `authorization.completed`. See [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming) for every event and its data shape. ## 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/ \ -H 'content-type: application/json' \ -d '{"continuationToken":"","message":"Now do Queens."}' ``` See [Sessions, runs and streaming](./concepts/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: Set up an Eve agent: read the Eve docs (bundled at node\_modules/eve/docs once eve is installed), scaffold with `npx eve@latest init ` (or `npm install eve@latest ai zod` in an existing app), add a typed tool at agent/tools/get\_weather.ts, run it with `npm run dev`, then create a session, stream it, and send a follow-up. Once `eve` is a dependency, the package bundles the full docs, so the agent can read them locally at `node_modules/eve/docs/` without fetching anything. To add a platform channel after setup, run `eve channels add slack` from an interactive terminal. The init flags are covered in [Quick start](#quick-start). ## 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](./guides/frontend/overview): browser chat with `useEveAgent` * [TypeScript SDK](./guides/client/overview): call the agent from scripts or server-side code * [Sessions, runs and streaming](./concepts/sessions-runs-and-streaming): the durable session model * [Build an agent](./tutorial/first-agent): the full end-to-end walkthrough --- 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)