flue-eve

flue-eve is an adapter that lets apps written for Eve's browser-facing API run against a Flue backend.

In practical terms: you keep the Eve authoring and frontend experience — agent/instructions.md, agent/tools/*, /eve/v1/*, NDJSON streams, Client, and useEveAgent — while your agent actually runs on Flue's open runtime.

It exists for teams that like Eve's file-based agent authoring and browser ergonomics but want runtime control: normal Flue agents, Flue tools, Flue deployment targets, and no dependency on Eve's hosted/runtime layer.

How to think about it

flue-eve is not a fork of Eve and not a replacement for Flue. It is the translation layer between the two:

• Eve shape at the edge: HTTP routes, stream events, client SDK, React hook.
• Flue execution inside: agent harness, tools, model configuration, durability, sandboxing, and deployment.
• A compat server in the middle: session tokens, event journal, NDJSON, and Flue-to-Eve event mapping.

What stays familiar

• Eve-style agent files: agent/instructions.md, agent/tools/*, and agent/connections/*.
• GET /eve/v1/health, POST /eve/v1/session, and session streams.
• Client and ClientSession from eve/client-compatible imports.
• useEveAgent with session state, reducer output, reconnects, and HITL events.
• sessionId, continuationToken, and streamIndex as the browser-facing handles.
• One JSON event per line over application/x-ndjson.

What changes

• You can author with Eve-style agent/ files or Flue-native agents. Eve-style files are imported by the scaffold into Flue runtime files.
• The Vite plugin wires development: aliases, proxying, sidecar scaffold, and the flue dev integration.
• @flue-eve/compat-server translates at runtime and owns the Eve event journal.
• Production deploys use normal Flue-compatible targets such as Node, split origin Node, Nitro, or Cloudflare Workers.

A project at a glance

my-app/
├── src/
│   ├── agents/assistant.ts       # Flue agent
│   ├── app.ts                    # Flue app routes
│   ├── flue-eve-shim.ts          # mounts /eve/v1
│   └── ui/App.tsx                # React UI using useEveAgent
├── vite.config.ts                # flueEve() plugin
└── package.json

Start with the Vite plugin and a single agent. Add persistence, auth, connections, and deployment-specific configuration only when the app needs them.

Request flow

Browser or script
  -> /eve/v1/session and /stream     Eve HTTP contract
  -> @flue-eve/compat-server         tokens, journal, NDJSON, mapping
  -> @flue/runtime                   agent harness, tools, durable stream

The journal is the important boundary: Eve clients reconnect with startIndex, and the compat server replays journaled Eve events instead of exposing Flue stream offsets.

Get started

1. Install flue-eve.
2. Add flueEve() to Vite for same-origin development proxying.
3. Run npx flue-eve init to scaffold the compat sidecar and app mount.
4. Render a UI with useEveAgent() or call the API with Client.

Start with New project for a complete walkthrough, or From Eve if you already have an Eve app.

Quick links

AI-assisted migration

A migration skill is bundled for coding agents that understand skills:

npx skills add doeixd/flue-eve