Deploy to Vercel

Deploy eve to Vercel when you want the framework’s managed build and runtime integrations. Vercel runs the web service, workflows, sandboxes, schedules, and deployment observability.

Prepare the Vercel project

Run this from the project root to link it to a Vercel project. For an eve agent workspace, use the workspace root, not a member directory:

eve link

The command links an existing project or creates one, then pulls its environment variables. For non-interactive use, name the project instead of picking it:

eve link --project your_project_name --non-interactive

Use --team as well when the account has access to more than one team. eve link creates the project if it doesn't exist yet.

Configure credentials and auth

A string model ID routes requests through the Vercel AI Gateway. The deployment authenticates through project OpenID Connect (OIDC), so you don’t need a provider API key for that path.

Add credentials for direct model providers, tools, and connections to the Vercel project environment. Add any signing keys or passwords required by your route authentication policy. Replace placeholderAuth() before a browser sends a production request.

Select the sandbox environment

The default environment selects Vercel Sandbox on Vercel. To select it explicitly:

import { defineSandbox } from "eve/sandbox";
import { VercelSandbox } from "eve/sandbox/vercel";

export const environment = VercelSandbox.environment();
export default defineSandbox(() => environment.open());

See Sandbox for preparation, resource limits, network policy, and lifecycle.

Deploy the agent

For a single-agent project without a frontend, use eve build. For an agent-only workspace, run it from the workspace root: eve generates a separately built service and a /<name>/eve/v1/* transport route for each member. All members deploy together in one Vercel project. See Project Structure for workspace membership and layout rules.

A Next.js-centered project uses withEve in next.config.ts and its Next.js build command. If you author the project's broader service graph in vercel.ts, use the configuration below instead.

Compose agents with other Vercel services

Use withEve from eve/vercel when the agents and other applications are peer services. The helper contributes workspace agents to a Vercel service graph; it does not manage or require a particular frontend framework. Unlike eve/next, this keeps the project lifecycle separate from Next.js. Both integrations deploy the agent services together in one Vercel project.

For a standalone agent or workspace with a peer Next.js frontend under apps/web/, replace vercel.json with a root vercel.ts. The frontend uses an ordinary Next.js config without eve/next:

import { withEve } from "eve/vercel";

export default await withEve({
  services: {
    web: {
      framework: "nextjs",
      root: "apps/web",
      buildCommand: "node ../../node_modules/next/dist/bin/next build",
    },
  },
  routes: [
    {
      src: "^(.*)$",
      destination: { type: "service", service: "web" },
    },
  ],
});

Vercel evaluates vercel.ts before resolving the service graph. withEve adds the root agent, or every direct workspace member, as an independently built service and returns a plain Vercel configuration. Named workspace agents mount at /eve/<name>/v1/*; a root agent mounts at /eve/v1/*. Vercel then builds the frontend and each eve agent separately. The frontend does not need withEve in its framework configuration or a build script that builds the agents.

The Web Chat installer can generate this composition for a standalone agent or a selected workspace agent. Configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own process and proxy configuration.

Run Vercel CLI 59.16.0 or newer with vercel dev --local to start the complete service graph locally without linking a Vercel project. A generated Vercel Web Chat project exposes this as pnpm dev:all. When the directory is linked, Vercel also loads its development environment and settings. Use pnpm dev or pnpm dev:eve when you want one agent and the eve terminal UI, or pnpm dev:web when you want the frontend without its agent services. Named agents use the same /eve/<name>/v1/* routes in development, and default defineWorkspaceAgent transports can call peers without deployment credentials.

Generated transport routes are inserted before a filesystem handler or, when no filesystem handler exists, before authored routes. withEve throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove the authored route, and remove or rename the authored service; withEve adds both automatically. Names in the array form of services must also be unique. Other service names, routes, bindings, and Cron Jobs remain authored in vercel.ts.

Custom agent channel endpoints are not published automatically. Expose one explicitly by routing it to the generated service:

import { withEve } from "eve/vercel";

export default await withEve({
  services: {
    web: { framework: "nextjs", root: "apps/web" },
  },
  routes: [
    {
      src: "^/webhooks/github$",
      destination: { type: "service", service: "eve-triage" },
    },
    {
      src: "^(.*)$",
      destination: { type: "service", service: "web" },
    },
  ],
});

A Vercel project can use only one configuration source, so remove vercel.json when adopting vercel.ts. Keep eve in the root package dependencies so Vercel can import eve/vercel while evaluating the configuration. withEve discovers the workspace containing its evaluation directory, including Vercel's temporary .vercel configuration directory. Pass { root: "/absolute/workspace/path" } as the second argument only when you need to select a specific workspace root.

An authored eve service routed at /eve/v1 already uses the protocol path; callbacks remain at /eve/v1/callback/*. A named mount such as /eve/support adds that mount before the protocol path, giving /eve/support/v1/callback/*.

Deploy the project

Deploy the linked project to production from its root:

eve deploy

eve deploy installs dependencies, runs vercel deploy --prod --logs to show build logs, and pulls the project environment after deployment. You can also push to a Git-connected Vercel project. Hosted Vercel builds set VERCEL, so eve build writes the deployment bundle under .vercel/output.

When eve deploy creates a new Vercel project, it configures trace sampling so traces appear in Agent Runs automatically. See Agent Runs for details. Pass --no-trace-sampling to skip this setting.

For non-interactive use, confirm the production deploy up front. --project links first, so a new project needs no separate eve link:

eve deploy --project your_project_name --non-interactive --yes

Vercel uses the generated output to configure these services:

• Web runtime: serves health, session, stream, channel, callback, and schedule routes
• Vercel Workflow: persists and resumes durable runs, with optimistic replay preconditions enabled so stale event-log snapshots reload before they can commit
• Vercel Cron: invokes authored schedules
• Vercel Sandbox: runs sandbox sessions selected by the default sandbox environment

Verify the deployment

For a single unnamed agent, check the health route and connect the development TUI:

curl https://your_agent.vercel.app/eve/v1/health
eve remote connect --url https://your_agent.vercel.app

For a workspace agent, include its public /eve/<name> mount. For example:

curl https://your_agent.vercel.app/eve/support/v1/health
eve remote connect --url https://your_agent.vercel.app/eve/support

Set VERCEL_AUTOMATION_BYPASS_SECRET locally before connecting if the deployment uses Deployment Protection.

Inspect agent runs

Use the Agent Runs tab under Observability to browse sessions and inspect conversation traces. See Agent Runs for beta access, pricing, retention, and tracing setup.

Continue configuring production

Use these guides to secure and observe the deployed agent:

• Authentication: configure who can call the deployed agent
• Instrumentation: export traces and diagnose runtime failures
• Sandbox: configure resources, isolation, and network access