eve/docs/guides/deployment/vercel.mdx

Filesystem-first framework for durable backend AI agents that run anywhere.

---
title: "Deploy to Vercel"
description: "Deploy an eve agent with Vercel Workflow, Sandbox, Cron, and project credentials."
---

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:

```bash
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:

```bash
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](https://vercel.com/docs/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](../auth-and-route-protection). 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:

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

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

See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and lifecycle.

<Callout type="info" title="Sandbox prewarming">
  During a Vercel build, eve creates or reuses a snapshot-backed template when an environment uses
  `VercelSandbox.environment({prepare})` or has seed files. A prewarm failure stops the deployment.
  See the [sandbox lifecycle](../../sandbox#lifecycle).
</Callout>

## 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](../../concepts/project-structure) for workspace membership and layout rules.

A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/nextjs) 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.

`eve/vercel` currently requires an `agents/` workspace, even if it has only one member. It does not support a standalone root `agent/`.

For a 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`:

```typescript title="vercel.ts"
import { withEve } from "eve/vercel";

export default await withEve({
  services: {
    web: {
      framework: "nextjs",
      root: "apps/web",
    },
  },
  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 does not support agent workspaces. Create the frontend using the [React chat example](../frontend/overview#basic-chat-react), and configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosting#run-workspace-members).

Run Vercel CLI 59.16.0 or newer with `vercel dev --local` to start the complete service graph locally. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials. Run `eve dev` instead when you only need one agent and the eve terminal UI.

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:

```typescript title="vercel.ts"
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:

```bash
eve deploy
```

`eve deploy` installs dependencies, runs `vercel deploy --prod`, 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`.

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

```bash
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:

```bash
curl https://your_agent.vercel.app/eve/v1/health
eve dev https://your_agent.vercel.app
```

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

```bash
curl https://your_agent.vercel.app/eve/support/v1/health
eve dev https://your_agent.vercel.app/eve/support
```

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

## Continue configuring production

Use these guides to secure and observe the deployed agent:

- [Authentication](../auth-and-route-protection): configure who can call the deployed agent
- [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
- [Sandbox](../../sandbox): configure resources, isolation, and network access