# Installation

> Prerequisites, package managers, Node engine requirements, and first-install commands for Flue and Eve projects.

- Repository: withastro/flue-with-vercel-eve
- GitHub: https://github.com/withastro/flue
- Human docs: https://www.grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6
- Complete Markdown: https://www.grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6/llms-full.txt

## Source Files

- `withastro-flue:package.json`
- `withastro-flue:pnpm-workspace.yaml`
- `withastro-flue:packages/cli/package.json`
- `vercel-eve:package.json`
- `vercel-eve:pnpm-workspace.yaml`
- `vercel-eve:packages/eve/package.json`
- `vercel-eve:.nvmrc`

---

---
title: "Installation"
description: "Prerequisites, package managers, Node engine requirements, and first-install commands for Flue and Eve projects."
---

Flue and Eve ship as npm packages (`@flue/runtime`, `@flue/cli`, `eve`) with distinct Node floors, scaffold contracts, and CLI entrypoints. Flue separates runtime (`@flue/runtime`) from build/dev tooling (`@flue/cli`); `flue init` writes `flue.config.ts` only. Eve scaffolds a full agent app through `eve init`, installs dependencies, optionally initializes Git, and starts `eve dev`.

## Prerequisites

Both frameworks are TypeScript-first and provider-neutral: you bring your own model credentials and choose any supported provider prefix (for example `anthropic/...`, `openai/...`, or gateway-routed ids). Neither framework requires a specific hosted connector at install time.

| Requirement | Flue | Eve |
| --- | --- | --- |
| Node.js | `>=22.19.0` on published `@flue/runtime` and `@flue/cli` | `>=24` on published `eve` and the Eve monorepo |
| Package manager (application projects) | npm, pnpm, yarn, or bun — docs use npm | npm, pnpm, yarn, or bun — `eve init` detects the invoking manager |
| Model credentials | At least one provider API key or Cloudflare Workers AI binding | Gateway key (`AI_GATEWAY_API_KEY`), Vercel OIDC (`vercel link`), or direct provider key |
| Git | Optional | `eve init` runs `git init` on fresh scaffolds when Git is available |

<Warning>
The Flue CLI bin rejects Bun and enforces Node `>=22.18` on Node 22, or `>=23.6` on Node 23, for native TypeScript config loading. Published packages still declare `engines.node: ">=22.19.0"`.
</Warning>

### Flue-specific prerequisites

- **LLM access** — A model specifier (for example `anthropic/claude-sonnet-4-6`) and matching provider credentials, or Cloudflare `cloudflare/*` models without API keys when targeting Workers.
- **Target selection** — `flue init` requires `--target node` or `--target cloudflare` before `flue dev`, `flue build`, or `flue run`.

### Eve-specific prerequisites

- **Companion packages** — Application projects depend on `eve`, `ai`, and `zod`. Fresh scaffolds also include `@vercel/connect` for later channel additions.
- **Scaffolded Node pin** — Generated apps declare a single major in `engines.node` (for example `24.x`) derived from the installed Eve release, so deployment platforms resolve a stable major.

## Node engine requirements

```text
Application install                Monorepo development
─────────────────────────────────────────────────────────────
Flue   Node >=22.19.0 (packages)   Node >=22, pnpm >=11 <12
       CLI bin: >=22.18 or >=23.6   packageManager: pnpm@11.1.1

Eve    Node >=24 (eve package)      Node >=24 (.nvmrc: 24)
       Scaffold pins e.g. 24.x     packageManager: pnpm@11.5.2
```

<Note>
Eve reconciles `engines.node` when adding to an existing project: compatible ranges are preserved; incompatible ranges are replaced with the Eve-selected major and a warning is printed.
</Note>

## Install a Flue application

Flue publishes `@flue/runtime` (harness, sessions, tools) and `@flue/cli` (the `flue` binary and `defineConfig`). Install both in a new project directory, add credentials, then initialize the deployment target.

<Steps>
<Step title="Install packages">

<CodeGroup>
```bash title="npm"
npm install @flue/runtime
npm install --save-dev @flue/cli
```

```bash title="pnpm"
pnpm add @flue/runtime
pnpm add -D @flue/cli
```

```bash title="yarn"
yarn add @flue/runtime
yarn add -D @flue/cli
```

```bash title="bun"
bun add @flue/runtime
bun add -D @flue/cli
```
</CodeGroup>

</Step>

<Step title="Add environment variables">

Create `.env` at the project root with provider credentials. Add `.env` to `.gitignore`.

```bash
echo 'ANTHROPIC_API_KEY="your-api-key"' > .env
```

Flue CLI commands load `<project>/.env` when present; shell-exported values take precedence.

</Step>

<Step title="Initialize configuration">

`flue init` writes `flue.config.ts` and does not scaffold agents, workflows, or `app.ts`.

```bash
npx flue init --target node
# or: npx flue init --target cloudflare
```

<ParamField body="--target" type="'node' | 'cloudflare'" required>
Selects the value written to `flue.config.ts`. Required on first init.
</ParamField>

<ParamField body="--root" type="string">
Directory that receives `flue.config.ts`. Defaults to the current working directory.
</ParamField>

<ParamField body="--force" type="boolean">
Overwrite an existing `flue.config.*` file. Without it, any discovered config blocks generation.
</ParamField>

Generated file:

```ts title="flue.config.ts"
import { defineConfig } from '@flue/cli/config';

export default defineConfig({
  target: 'node',
});
```

</Step>

<Step title="Verify">

```bash
node -v    # expect >=22.19.0 per package engines
npx flue docs
```

After authoring an agent module under `agents/` or `.flue/agents/`, run `npx flue connect <agent> local --target node` or `npx flue dev --target node`.

</Step>
</Steps>

### Optional Flue packages

| Package | When to install |
| --- | --- |
| `@flue/sdk` | HTTP client for deployed agents and workflows |
| `@flue/postgres`, `@flue/redis`, … | Persistence or channel adapters via `flue add` blueprints |

## Install an Eve application

Eve publishes a single package `eve` with the `eve` CLI binary. The fastest path is `npx eve@latest init`, which scaffolds the project, installs dependencies, initializes Git on fresh projects, and starts the dev server.

<Steps>
<Step title="Scaffold with eve init">

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

For an empty directory you already created:

```bash
cd my-empty-dir
npx eve@latest init .
```

`eve init` holds the terminal while `eve dev` runs. Press Ctrl+C to regain the shell before editing files. The command does not create or link a Vercel project.

<ParamField body="target" type="string">
Project name (`my-agent`) creates a child directory. `.`, `./`, or an existing directory with `package.json` adds an agent to that project.
</ParamField>

<ParamField body="--channel-web-nextjs" type="flag">
Adds the Web Chat Next.js application on fresh scaffolds. Rejected when adding to an existing project — use `eve channels add web` instead.
</ParamField>

</Step>

<Step title="Understand scaffold output">

Fresh projects receive:

```text
my-agent/
├── package.json          # scripts: dev, build, start, typecheck
├── tsconfig.json
├── pnpm-workspace.yaml   # when scaffolded with pnpm
└── agent/
    ├── agent.ts
    ├── instructions.md
    └── channels/eve.ts
```

`package.json` dependencies include `eve`, `ai`, `zod`, and `@vercel/connect`. `engines.node` is pinned to the Eve release major (for example `24.x`).

Package manager selection on fresh scaffolds:

1. Manager that launched the CLI (`npx` → npm, `pnpm dlx` → pnpm, `yarn dlx` → yarn)
2. Default `pnpm` when the `eve` binary runs directly with no user-agent hint

Existing projects keep their detected manager (`packageManager` field, then lockfile, then `pnpm` default).

</Step>

<Step title="Configure model credentials">

Default model is `anthropic/claude-sonnet-4.6`. Set one of:

- `AI_GATEWAY_API_KEY` for gateway-routed models
- `VERCEL_OIDC_TOKEN` after `vercel link`
- Direct provider key (for example `ANTHROPIC_API_KEY` for `anthropic/...`)

</Step>

<Step title="Verify">

```bash
node -v           # expect >=24
cd my-agent
npm run dev       # or: npx eve dev
# in another shell:
npx eve info
```

`eve info` confirms discovery, routes, and compiled artifact paths without booting the full dev TUI.

</Step>
</Steps>

### Manual Eve installation

To add Eve without `eve init`, declare Node and install dependencies:

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

```bash
npm install eve@latest ai zod
```

Author `agent/agent.ts` and `agent/instructions.md`, then run `npx eve dev` (no `dev` script is created automatically on the manual path).

### Add Eve to an existing application

From a directory with `package.json` and no `agent/` tree:

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

Eve writes `agent/` files, adds missing `eve`, `ai`, and `zod` dependencies, reconciles `engines.node`, and leaves unrelated project configuration untouched. `--channel-web-nextjs` is not supported in this mode.

## Monorepo development

Clone either upstream repository to work on the frameworks themselves. Application installs above do not require monorepo checkout.

<Tabs>
<Tab title="Flue (withastro/flue)">

| Setting | Value |
| --- | --- |
| Node | `>=22` |
| pnpm | `>=11 <12` (pinned `pnpm@11.1.1`) |
| Workspace | `packages/*`, `examples/*`, `apps/*` |

```bash
git clone https://github.com/withastro/flue.git
cd flue
corepack enable
pnpm install
pnpm run build
```

Build order for local CLI work: `packages/runtime` then `packages/cli`. CI builds with:

```bash
pnpm --filter @flue/runtime --filter @flue/sdk --filter @flue/cli build
```

</Tab>

<Tab title="Eve (vercel/eve)">

| Setting | Value |
| --- | --- |
| Node | `>=24` (`.nvmrc` pins `24`) |
| pnpm | pinned `pnpm@11.5.2` via `packageManager` |
| Workspace | `packages/*`, `apps/*`, `e2e/fixtures/*` |

```bash
git clone https://github.com/vercel/eve.git
cd eve
nvm use    # or: fnm use
corepack enable
pnpm install
pnpm build
pnpm dev
```

`pnpm dev` watches the `eve` package build and runs the `weather-agent` fixture on an available localhost port.

</Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
<Accordion title="Flue: Node version rejected at CLI startup">

Upgrade to Node `>=22.19.0` to satisfy package `engines`. If you are on Node 23, use `>=23.6` for the CLI bin guard. Bun is not supported as a Node replacement for the `flue` binary.

</Accordion>

<Accordion title="Flue: flue init refuses to overwrite config">

An existing `flue.config.*` (`.ts`, `.mts`, `.mjs`, `.js`, `.cjs`, `.cts`) blocks generation. Pass `--force` to write `flue.config.ts`; the new `.ts` file takes precedence in discovery.

</Accordion>

<Accordion title="Eve: dependency install fails during eve init">

`eve init` runs the detected package manager with release-age bypass for pinned scaffold versions. On failure, the manager's stderr is replayed. Retry install manually from the project root (`npm install`, `pnpm install`, etc.), then run `npx eve dev`.

</Accordion>

<Accordion title="Eve: cannot add agent to existing project">

`eve init .` requires `package.json`, no pre-existing `agent/` files, and no conflicting paths. For Web Chat on existing apps, run `eve channels add web` after init.

</Accordion>

<Accordion title="Eve: engines.node overridden warning">

When adding Eve to a project whose `engines.node` spans multiple majors, Eve replaces the range with the pinned major for the installed release (for example `24.x`) and prints a warning. Update CI and deployment Node versions to match.

</Accordion>
</AccordionGroup>

## Next

<CardGroup>
<Card title="Flue quickstart" href="/flue-quickstart">
Scaffold agents, run `flue dev`, invoke workflows, and connect to agent instances.
</Card>
<Card title="Eve quickstart" href="/eve-quickstart">
Run `eve init`, start `eve dev`, inspect discovery, and send the first HTTP session message.
</Card>
<Card title="Flue configuration reference" href="/flue-configuration-reference">
`flue.config.*` keys, source-root precedence, and CLI overrides.
</Card>
<Card title="Eve CLI reference" href="/eve-cli-reference">
Full `eve` command surface including `info`, `build`, `deploy`, and `channels`.
</Card>
</CardGroup>