# Installation

> Node 24+ prerequisites, npm/pnpm install paths, eve package binary, model credential options (gateway OIDC or direct provider keys), and environment file loading from the app root.

- Repository: vercel/eve
- GitHub: https://github.com/vercel/eve
- Human docs: https://www.grok-wiki.com/public/docs/vercel-eve-759e1d74a10f
- Complete Markdown: https://www.grok-wiki.com/public/docs/vercel-eve-759e1d74a10f/llms-full.txt

## Source Files

- `docs/getting-started.mdx`
- `packages/eve/package.json`
- `packages/eve/bin/eve.js`
- `.nvmrc`
- `packages/eve/src/cli/run.ts`

---

---
title: "Installation"
description: "Node 24+ prerequisites, npm/pnpm install paths, eve package binary, model credential options (gateway OIDC or direct provider keys), and environment file loading from the app root."
---

Install Eve as the `eve` npm package. The published binary scaffolds agents, compiles authored files under `agent/`, and runs a local development server. Before your first session, you need a compatible Node.js runtime, the package on disk, and a model credential.

## Prerequisites

Eve requires **Node.js 24 or newer**. The `eve` package declares `engines.node` as `>=24`, and the repository pins `.nvmrc` to `24`. The CLI binary checks your Node version on every invocation and exits with an error if the running version is outside the supported range.

<Tabs>
<Tab title="nvm">

```bash
nvm install 24
nvm use 24
node --version
```

</Tab>
<Tab title="fnm">

```bash
fnm install 24
fnm use 24
node --version
```

</Tab>
<Tab title="Direct install">

Download Node 24+ from [nodejs.org](https://nodejs.org/) or use your system package manager, then verify:

```bash
node --version
```

</Tab>
</Tabs>

You also need a **model credential** before the agent can call a model. Eve supports gateway credentials (API key or Vercel OIDC) and direct provider API keys. See [Model credentials](#model-credentials) below.

## Install paths

Pick the path that matches your starting point: a greenfield agent, an existing Node project, or a manual wiring.

<Steps>
<Step title="Scaffold a new agent (recommended)">

`npx` runs `eve init` without installing Eve globally first:

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

The command creates a new directory, writes `agent/agent.ts` and `agent/instructions.md`, installs dependencies, initializes Git, and starts `eve dev`. Press **Ctrl+C** to stop the dev server and return to your shell before editing files.

Fresh scaffolds use the package manager that launched the CLI (`npx` → npm, `pnpm dlx` → pnpm). When you run the `eve` binary directly with no package-runner context, Eve defaults to **pnpm**.

</Step>
<Step title="Add Eve to an existing project">

From a directory that already has `package.json` and no `agent/` tree yet:

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

Eve adds the `agent/` files and missing dependencies (`eve`, `ai`, `zod`) without modifying unrelated project configuration. It detects the project's existing package manager from `package.json#packageManager` or lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lock`).

If the project's `engines.node` is incompatible with Eve's required major, Eve replaces it with a pinned range such as `24.x` and prints a warning.

</Step>
<Step title="Install dependencies manually">

For full control, declare a compatible Node runtime and install the runtime dependencies yourself:

```json title="package.json"
{
  "engines": {
    "node": "24.x"
  }
}
```

<CodeGroup>
```bash title="npm"
npm install eve@latest ai zod
```

```bash title="pnpm"
pnpm add eve@latest ai zod
```

```bash title="yarn"
yarn add eve@latest ai zod
```

```bash title="bun"
bun add eve@latest ai zod
```
</CodeGroup>

Then author the two files the runtime needs:

```md title="agent/instructions.md"
You are a concise assistant. Use tools when they are available.
```

```ts title="agent/agent.ts"
import { defineAgent } from "eve";

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

Run the dev server with `npx eve dev` or add a `"dev": "eve dev"` script to `package.json`.

</Step>
</Steps>

### What gets installed

A scaffolded agent declares these runtime dependencies:

| Package | Role |
| --- | --- |
| `eve` | Framework, CLI binary, compiled runtime |
| `ai` | AI SDK model calls and streaming |
| `zod` | Tool and schema validation |
| `@vercel/connect` | Connection helpers (scaffold only) |

The `eve` package ships with a single runtime dependency (`nitro`). Peer dependencies such as framework plugins (`next`, `nuxt`, `sveltekit`) and optional integrations are installed only when you add them.

Once `eve` is installed, the full documentation bundle is available locally at `node_modules/eve/docs/`.

## The `eve` binary

The npm package exposes a CLI binary mapped to `bin/eve.js`:

<ParamField body="bin" type="string">
Maps to `./bin/eve.js` in the published `eve` package.
</ParamField>

<ParamField body="default command" type="string">
Running `eve` with no subcommand runs `eve dev`.
</ParamField>

The bootstrap script validates Node.js compatibility, ensures the compiled CLI entrypoint exists (rebuilding from source when developing inside the Eve monorepo), and delegates to `dist/src/cli/run.js`. Available commands include `init`, `info`, `build`, `start`, `dev`, `link`, `deploy`, `eval`, and `channels`.

Scaffolded projects wire the binary into `package.json` scripts:

```json
{
  "scripts": {
    "build": "eve build",
    "dev": "eve dev",
    "start": "eve start"
  }
}
```

Every CLI command resolves the **application root** from the current working directory. Run commands from your agent project root so discovery, env loading, and artifact paths resolve correctly.

## Model credentials

Eve routes models through the **Vercel AI Gateway** by default. A bare string model id such as `anthropic/claude-sonnet-4.6` (the `eve init` default) is classified as gateway-routed. Alternatively, you can use a direct AI SDK provider instance that bypasses the gateway.

### Gateway credentials

Gateway-routed models need one of two credentials:

| Credential | Environment variable | How to obtain |
| --- | --- | --- |
| API key | `AI_GATEWAY_API_KEY` | Create a key in the [Vercel AI Gateway dashboard](https://vercel.com/dashboard/ai/api-keys), or paste one in the dev TUI `/model` flow |
| OIDC token | `VERCEL_OIDC_TOKEN` | Run `eve link` to link a Vercel project and pull preview environment variables into `.env.local` |

When both are present, **`AI_GATEWAY_API_KEY` takes precedence** over `VERCEL_OIDC_TOKEN`, matching the AI SDK gateway provider behavior.

<Tabs>
<Tab title="API key">

Create or copy an AI Gateway API key, then add it to `.env.local` at the app root:

```bash title=".env.local"
AI_GATEWAY_API_KEY=your-gateway-key
```

</Tab>
<Tab title="Vercel OIDC">

From an interactive terminal in your agent project:

```bash
eve link
```

The command walks you through team and project selection, runs `vercel link`, and pulls environment variables so a gateway credential lands in `.env.local`. A running `eve dev` reloads env files automatically — no restart needed.

In CI, use `vercel link --project <name> --yes` instead; `eve link` requires an interactive terminal.

</Tab>
</Tabs>

The dev TUI surfaces credential status in its status bar and gates the "provider required" prompt when neither credential is detectable. Use `/model` to walk through provider setup interactively.

### Direct provider keys

For models that bypass the gateway, set the provider's own API key. The environment variable name follows the model id prefix:

| Model id pattern | Environment variable |
| --- | --- |
| `anthropic/claude-...` | `ANTHROPIC_API_KEY` |
| `openai/gpt-...` | `OPENAI_API_KEY` |
| `google/gemini-...` | `GOOGLE_API_KEY` |

The prefix before the first `/` determines the variable name: uppercase slug with `_API_KEY` appended (for example, `anthropic/claude-sonnet-4.6` → `ANTHROPIC_API_KEY`).

To use a direct provider SDK model instead of a gateway string id, change `agent/agent.ts`:

```ts title="agent/agent.ts"
import { anthropic } from "@ai-sdk/anthropic";
import { defineAgent } from "eve";

export default defineAgent({
  model: anthropic("claude-sonnet-4.6"),
});
```

Direct provider instances are classified as `external` routing. Gateway credentials do not apply; the provider key must be present in the environment. Eve makes no connectedness claim for external providers on `/eve/v1/info`.

### Bring-your-own-key through the gateway

The scaffold can also wire a provider key through the gateway's `byok` block in `modelOptions.providerOptions.gateway.byok`. This passes your provider API key to the gateway explicitly while keeping a gateway model id string in `model`.

## Environment file loading

Local CLI commands load environment files from the **application root** (the directory where you run `eve`). Commands that load env files include `eve dev`, `eve build`, `eve start`, and `eve eval`.

### File precedence

Eve reads up to four files, listed here from **highest to lowest** precedence:

1. `.env.development.local`
2. `.env.local`
3. `.env.development`
4. `.env`

Later files in this list override earlier ones for the same key. Values from `.env.local` typically hold secrets such as `AI_GATEWAY_API_KEY` or `VERCEL_OIDC_TOKEN`.

### Shell precedence

Variables already set in the parent process (your shell) are **protected**. Env files never overwrite shell-exported values. This lets you override project secrets temporarily without editing files.

### Hot reload

During `eve dev`, Eve watches env files for changes and reloads them without restarting the server. After `eve link` pulls new credentials or you edit `.env.local`, the running dev server picks up the updated values automatically.

Missing env files are silently skipped; only files that exist on disk are parsed.

## Verify installation

<Steps>
<Step title="Check Node version">

```bash
node --version
```

Expect v24.x or newer.

</Step>
<Step title="Confirm the binary">

```bash
npx eve --version
```

Prints the installed `eve` package version.

</Step>
<Step title="Inspect discovery">

From your agent project root:

```bash
npx eve info
```

Confirms Eve discovered `agent/agent.ts`, tools, channels, and routes. Use `--json` for machine-readable output.

</Step>
<Step title="Start the dev server">

```bash
npm run dev
```

Or, without a `dev` script:

```bash
npx eve dev
```

If credentials are missing, the dev TUI flags the gap and `/model` walks you through setup. With credentials in place, type a message to confirm the model loop runs.

</Step>
</Steps>

### Common issues

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `Eve requires Node.js >=24` | Node version too old | Install Node 24+ and retry |
| Gateway "no credentials" error | Missing `AI_GATEWAY_API_KEY` and `VERCEL_OIDC_TOKEN` | Run `eve link` or set `AI_GATEWAY_API_KEY` in `.env.local` |
| Stale gateway key shadows OIDC | Shell exports an old `AI_GATEWAY_API_KEY` | Unset the shell variable or update the key |
| Provider key missing for direct model | External provider without env var | Set the provider's `*_API_KEY` in `.env.local` |
| Env changes not picked up | Running outside `eve dev` | Restart the process, or use `eve dev` which hot-reloads env files |

For deeper diagnostics, see [Troubleshooting](/troubleshooting).

## Next

<CardGroup>
<Card title="Quickstart" href="/quickstart">
Scaffold with `eve init`, verify with `eve info`, iterate with `eve dev`, and exercise the HTTP session API.
</Card>
<Card title="Project layout" href="/project-layout">
Where authored files live under `agent/` and what compiles into `.eve/` artifacts.
</Card>
<Card title="Agent configuration" href="/agent-configuration">
Configure `defineAgent` model, compaction, and build options in `agent/agent.ts`.
</Card>
<Card title="Auth and deployment" href="/auth-and-deployment">
Route auth, Vercel secrets, `eve link`/`eve deploy`, and production verification.
</Card>
<Card title="CLI reference" href="/cli-reference">
Full command reference for `init`, `info`, `build`, `start`, `dev`, `link`, `deploy`, and `eval`.
</Card>
</CardGroup>