Nuxt

The eve/nuxt module runs a Nuxt frontend and an eve agent as one project, with one dev server and one Vercel deploy. The auto-imported useEveAgent composable finds the mounted routes on its own, so you configure no CORS or URL env vars.

Prerequisites

  • The eve package installed in your project (npm install eve@latest).
  • An existing eve agent directory. If you don't have one, start from Getting started.
  • A Nuxt app to mount the agent in.

Register the module

nuxt.config.ts
export default defineNuxtConfig({
  modules: ["eve/nuxt"],
});

The module looks for an agent/ folder in the Nuxt project root, mounted at /eve/v1/*. An agents/ workspace mounts each member at /eve/<name>/v1/* instead. Pass eveRoot when the agent lives elsewhere:

export default defineNuxtConfig({
  modules: ["eve/nuxt"],
  eve: {
    eveRoot: "../my-agent",
  },
});

eve/nuxt options

All fields are optional.

OptionTypeDefaultPurpose
eveRootstringNuxt project rooteve project root, relative to the Nuxt project root unless absolute.
eveBuildCommandstringgeneratedBuild command for the generated eve Vercel service.
devServerTimeoutMsnumber180000Maximum time to wait for the eve development server to start, including when another Nuxt process is starting it.

For slow cold starts, increase the development timeout:

export default defineNuxtConfig({
  modules: ["eve/nuxt"],
  eve: {
    devServerTimeoutMs: 300_000,
  },
});

Call the composable

useEveAgent (eve/vue) is auto-imported, so a component calls it without an explicit import and without passing baseUrl:

<script setup lang="ts">
const { status, send } = useEveAgent();

const isBusy = computed(() => status.value === "busy");
const isInputDisabled = computed(() => isBusy.value || status.value === "resuming");

const message = ref("");

async function handleSubmit() {
  const text = message.value.trim();
  if (!text || isInputDisabled.value) return;
  message.value = "";
  await send(text);
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input v-model="message" :disabled="isInputDisabled" />
    <button type="submit" :disabled="isInputDisabled">Send</button>
  </form>
</template>

The browser still needs a production authentication policy. See Authenticate browser requests for the default policy, which rejects unverified requests, and for channel configuration.

Dev vs deploy topology

  • Local dev. npm run dev starts an eve dev server for each agent beside nuxt dev and proxies the eve routes to it. The browser talks only to the Nuxt origin. Set EVE_BASE_URL to proxy to an eve dev server you already run instead.

  • Vercel. The web app and the eve runtime deploy as a single project. On Vercel builds, the module adds an eve service per agent and routes its transport requests to it before filesystem routing. The Nuxt app serves everything else, and no vercel.json is required. When vercel.json declares services, or a vercel.ts composes them with withEve from eve/vercel, the module generates nothing and that configuration controls routing. By default, each generated service runs the installed eve binary from its agent root, so agent directories don't need their own package.json. When the agents need their own build step, set eveBuildCommand:

    export default defineNuxtConfig({
      modules: ["eve/nuxt"],
      eve: {
        eveBuildCommand: "npm run build:eve",
      },
    });
  • Non-Vercel hosts. The module doesn't start eve in production; run the eve service yourself. nuxt build writes proxy rules that send the eve routes to EVE_NUXT_PRODUCTION_ORIGIN, or to http://127.0.0.1:4274 when that variable is unset. With EVE_NUXT_PRODUCTION_ORIGIN, each agents/ workspace member keeps its own path on that host (/eve/<name>/v1). Without it, each member runs as its own server serving /eve/v1, on consecutive ports from 4274 in alphabetical order of member name (4274, 4275, ...). Override the first port with EVE_NUXT_PRODUCTION_PORT. Set these variables when you run nuxt build, because the destination is fixed in the build output:

    EVE_NUXT_PRODUCTION_ORIGIN=https://agent.example.com npm run build

    eve build and nuxt build both write .output/. When the agent lives in the Nuxt project root, the two outputs overwrite each other. Build and serve eve from a separate directory instead, and set eveRoot to it. See Self-host eve for running the eve service.

Managing vercel.json yourself

When vercel.json declares services, the module generates nothing, and your configuration controls routing. It must include the eve service (framework: "eve") and a rewrite that sends /eve/v1/* requests to it, or the module fails the build:

vercel.json
{
  "services": {
    "web": { "root": ".", "framework": "nuxtjs" },
    "eve": { "root": "agent", "framework": "eve", "buildCommand": "eve build" }
  },
  "rewrites": [{ "source": "/eve/v1/(.*)", "destination": { "service": "eve" } }]
}

Remove experimentalServices

Vercel doesn't route the experimentalServices field in vercel.json: both services build, but every /eve/v1/* request returns NOT_FOUND. The module ignores the field and warns that vercel.json defines experimentalServices. Remove it in one of two ways:

  • Generated (default). Delete vercel.json (or its experimentalServices block) and set the project's Framework Preset to Nuxt.js. The module generates the eve service and its routing on every Vercel build.
  • Hand-maintained. Replace experimentalServices with the services and rewrites shown above, and keep the "Services" Framework Preset.