From Eve

The safest migration starts by separating the Eve surface from the Eve runtime. Browser and client code usually move first because eve/client and eve/react map directly to flue-eve/client and flue-eve/react. Server-side agent authoring can keep the familiar Eve-style agent/ file layout; the scaffold imports those declarations into Flue agents and tools.

What usually stays unchanged

• Browser code that calls /eve/v1/*.
• Client-side session cursors: sessionId, continuationToken, streamIndex.
• NDJSON stream consumption and reconnect behavior.
• React UI state based on useEveAgent.
• Tool, HITL, authorization, and result events that are already in the supported compatibility set.

What moves to Flue

• Agent execution and model configuration.
• Tool implementation and sandbox behavior.
• Deployment topology.
• Any platform channels outside the Eve HTTP channel.

1. Scan the project

The scanner classifies imports, filesystem layout, and unsupported surfaces:

npx flue-eve scan

Most browser-first Eve chat apps are Tier 0/1. See migration tiers for the detailed rules.

Use --strict in CI to fail on Tier 2/3 findings:

npx flue-eve scan --strict

2. Initialize the bridge

npx flue-eve init

This creates Flue runtime files, the Eve compat sidecar, and any generated adapters that the scanner can produce safely.

3. Keep browser imports or switch explicitly

The Vite plugin can alias browser imports:

eve/client -> flue-eve/client
eve/react  -> flue-eve/react

That lets a UI migrate without touching every component. If you prefer explicit imports, change them directly:

- import { Client } from 'eve/client'
+ import { Client } from 'flue-eve/client'

- import { useEveAgent } from 'eve/react'
+ import { useEveAgent } from 'flue-eve/react'

For server code:

- import { createEveServer } from 'eve/server';
+ import { eveCompat } from '@flue-eve/compat-server';

4. Replace the Vite integration

- import eve from 'eve/vite';
+ import { flueEve } from 'flue-eve/vite';

  export default defineConfig({
    plugins: [
-     eve(),
+     flueEve(),
    ],
  });

5. Run locally

pnpm dev

Mock admission lets you verify the Eve HTTP contract before provider keys or real Flue admission are configured:

curl -X POST http://localhost:5173/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"Hello"}'

For real LLM responses, run Flue and set FLUE_BASE_URL:

FLUE_BASE_URL=http://127.0.0.1:3583 pnpm dev

What stays the same

• All /eve/v1/* routes
• NDJSON streaming format
• sessionId and continuationToken semantics
• useEveAgent reducer and event types
• Client reconnect and startIndex behavior

What to review manually

• Eve filesystem discovery: agent/instructions.md, agent/tools/*, and agent/connections/* are supported through scaffold/import. Flue still owns runtime discovery, so review generated files when you change the layout.
• Platform channels: use Flue channel integrations or @flue-eve/channels instead of assuming Eve Slack/Discord channels are present.
• Production auth: the compat server fails closed unless auth: 'none' is configured intentionally.

AI-assisted migration

Install the bundled migration skill and ask your AI coding agent to handle it:

npx skills add doeixd/flue-eve

"Migrate this Eve project to flue-eve"

The agent will scan, scaffold, configure, connect the frontend, and verify.

See migrate an existing Eve agent for a detailed step-by-step guide.