Getting Started

flue-eve has two moving parts:

A browser-facing Eve contract: /eve/v1/*, NDJSON streams, Client, and useEveAgent.
An Eve-style authoring surface: agent/instructions.md, agent/tools/*, and agent/connections/* scaffolded into Flue runtime files.
A Flue backend: the agent runtime that owns models, tools, durability, and deployment.

Getting started means wiring those two pieces together. Pick the path that matches the code you already have.

Prerequisites

Node.js 22.19.0 or later for Flue.
pnpm 9.x for this repository, or your package manager in an app project.
An LLM provider key only when you want real model calls. Mock admission works without secrets.

Choose your path

Path	Use it when	Result
New project	You want Eve-style authoring plus a Vite + React app	`agent/` files, same-origin `/eve/v1/*`, React UI, Flue runtime
From Eve	You already have Eve code	Eve-style files and aliased client/hook imports backed by Flue
Frontend only	The server already exists	Browser code talks to a remote compat server
React	You are building a chat UI	`useEveAgent` with streaming state
Client	You are writing scripts or tests	`Client` and `ClientSession` over HTTP
Cloudflare Worker	You want edge deployment	Worker app with KV/DO-backed persistence

What the quickstarts produce

A browser UI that talks to same-origin /eve/v1/* routes during development.
A compat server mounted in the Flue app, not in Vite middleware.
Eve-shaped session responses and NDJSON stream events.
Mock admission by default, so setup works before provider keys are configured.
A path to real Flue execution by setting FLUE_BASE_URL=http://127.0.0.1:3583.

Terms you will see

Term	Meaning
Eve contract	The HTTP routes, stream format, client SDK, and hook that browser code uses
Compat server	The Hono middleware that translates Eve requests/events to and from Flue
Admission	How a user turn is submitted to Flue: mock, loopback HTTP, or runtime integration
Journal	The server-owned event log that makes Eve `startIndex` replay stable
Flue agent	The actual runtime agent that handles models, tools, and durable execution

How it works

React hook or TypeScript client
  -> /eve/v1/session, /stream
  -> compat-server journal + mapper
  -> Flue agent instance

Vite handles integration: proxying, generated sidecar files, aliases, and health checks. The compat server handles runtime translation: session tokens, event mapping, NDJSON, auth, and journal replay.

Need help?

Troubleshooting — common issues and fixes
Eve and Flue — which project owns which layer
Architecture — the data flow and invariants
Migration tiers — what can be automated