Deployment

eve deployment is intentionally close to local development: the framework is designed so the same agent can run under eve dev, on Vercel, or on a long-running Node host. The deployment task is therefore less about rewriting application code and more about producing the right host artifact, supplying runtime-only secrets, choosing the expected model route, and verifying that the runtime adapters are available in the target environment. This page explains the production checklist from the source guide and frames each step around what the deployer must decide before shipping an agent.

Sources: docs/guides/deployment.md

Purpose and Scope

Use this page when you are moving an authored eve agent out of local development. An eve agent is built from filesystem conventions such as agent/agent.ts, instructions, tools, channels, schedules, and sandbox configuration; deployment packages that authored surface into host output and runtime manifests. The deployment guide emphasizes that the production path is mostly mechanical because eve keeps the local and hosted execution model aligned. The important production work is to make the environment explicit: build the agent, set secrets outside source control, understand which runtime backend will execute workflows and sandbox work, and decide whether model calls go through Vercel AI Gateway or directly to provider APIs.

The central portability boundary is between the HTTP host layer and the execution adapters. Nitro provides the HTTP host artifact that serves operational routes after the development server is gone. Workflow execution and sandbox execution are separate runtime adapters, which means they are not implicit, hidden dependencies inside Nitro. That separation matters during production planning: a Vercel deployment receives Vercel-specific build output and hosted workflow or sandbox behavior, while a self-hosted Node deployment serves the standard Nitro output and uses local runtime defaults unless the agent config selects a different installed workflow world.

Sources: docs/guides/deployment.md

Relevant Source Files

• docs/guides/deployment.md — First-party deployment checklist covering eve build, Vercel Build Output, .eve/ artifacts, Nitro portability, workflow world selection, sandbox backend selection, environment variables, route-auth secrets, preview-protection bypass, and model routing.

Build Artifacts and Host Output

Start every deployment by running the build command. The documented command is eve build, which compiles the agent and writes the host output. The guide distinguishes between two build modes. When the VERCEL environment variable is set, as it is during hosted Vercel builds, eve writes a Vercel Build Output bundle under .vercel/output. A plain local build skips that Vercel bundle. In both cases, the framework produces compiled eve artifacts under .eve/, including the discovery manifest, compiled manifest, diagnostics, and module map.

eve build

Those generated artifacts are useful operational evidence, not just implementation detail. The discovery manifest and compiled manifest tell you which filesystem-authored surfaces the deployment will actually load. The module map helps connect the production bundle back to authored files. Diagnostics are the first place to inspect when a build succeeds but the resulting deployment does not behave like the local project. Before shipping, open the .eve/ artifacts and confirm that the expected instructions, tools, channels, schedules, and runtime configuration are present in the compiled view.

Sources: docs/guides/deployment.md

Portability Model: Nitro, Workflow, and Sandbox

Nitro is the HTTP host layer in the deployment model. Its job is to produce an artifact capable of serving eve's runtime routes outside the development server. The documented route set includes health, session, stream, channel, callback, and schedule routes. This is the surface your deployed service exposes to clients, channels, scheduled invocations, and callbacks. Nitro does not make workflow execution or sandbox execution Vercel-only; those are selected through separate runtime adapters, which is why the same application model can be run outside Vercel.

On Vercel, eve emits Vercel Build Output, the Workflow SDK runs on Vercel Workflow, and defaultBackend() selects Vercel Sandbox. Outside Vercel, the documented production command is eve start, which serves the standard Nitro Node output. In that mode the Workflow SDK uses its local world by default, and defaultBackend() selects a local sandbox backend in availability order. The guide calls out that the local workflow world persists run state on disk and is not directly coupled to Vercel. Vercel-only features such as latest-deployment routing and dashboard run attributes are additive rather than required for the core runtime model.

For advanced self-hosted environments, the root agent.ts can choose a different installed Workflow world package. That package should read credentials and host-specific options from runtime environment variables, and it should export either a default factory or createWorld() function. This is the extension point for organizations that want eve's authored agent model and Nitro host layer but need to run durable workflow state on their own infrastructure or a separately managed workflow backend.

import { defineAgent } from "eve";
 
export default defineAgent({
  model: "anthropic/claude-opus-4.8",
  experimental: {
    workflow: {
      world: "@acme/eve-workflow-world",
    },
  },
});

Sources: docs/guides/deployment.md

Environment Variables, Secrets, and Auth

Production credentials belong in the deployment environment or a secret manager, never in source and never in compiled artifacts. The guide identifies two core classes of secrets. First, the agent needs a model credential. On Vercel, the lowest-setup path is Vercel AI Gateway: link the Vercel project, use gateway model identifiers such as anthropic/claude-opus-4.8, and authenticate through Vercel OIDC without managing provider keys. Outside Vercel, either set AI_GATEWAY_API_KEY for gateway-routed models or configure a direct AI SDK provider package and provide that provider's key, such as OPENAI_API_KEY or ANTHROPIC_API_KEY. Second, protect externally reachable routes with route-auth secrets appropriate to the channel and deployment. The guide names ROUTE_AUTH_BASIC_PASSWORD as an example and also calls out JWT or OIDC signing keys referenced by a channel's auth configuration. A key operational detail is that route-auth secrets are not serialized into compiled discovery or module-map artifacts. Instead, the runtime re-materializes them from the authored channel definition. That design keeps build artifacts inspectable while preserving the rule that secrets are runtime material, not compile-time material.

Preview protection adds one more local-development consideration. If a deployment sits behind Vercel preview protection and you want to drive it from eve dev, set VERCEL_AUTOMATION_BYPASS_SECRET locally before launching. This is a deployment-to-development bridge rather than a general production credential. Treat it as a local environment value used to exercise a protected preview deployment from the developer workflow.

Sources: docs/guides/deployment.md

Model Routing Decisions

The model value in agent/agent.ts determines whether eve calls the Vercel AI Gateway or a model provider endpoint directly. A string model id is gateway-routed. The guide's example uses defineAgent with model: "anthropic/claude-opus-4.8", which fits the Gateway path described in the environment section. This deployment decision is coupled to credentials: Vercel can use OIDC-backed Gateway authentication for linked projects, while non-Vercel hosts need AI_GATEWAY_API_KEY if they still want to route through the Gateway.

import { defineAgent } from "eve";
 
export default defineAgent({
  model: "anthropic/claude-opus-4.8",
});

Direct provider routing is the alternative when the agent configuration uses a provider integration rather than a plain gateway model id. The provided guide excerpt points deployers to AI SDK provider packages and provider-specific keys. In practice, the production checklist should treat model routing as a build-time configuration review plus a runtime secret review: confirm the authored model shape in agent/agent.ts, then confirm the target environment contains the credential that route requires. Avoid relying on local shell variables or development-only files when validating the production path.

Sources: docs/guides/deployment.md

Production Checklist Reference

Verification Flow and Next Steps

After the build completes, verify deployment readiness in the same order as the checklist. First, inspect .eve/ to confirm the compiled manifest matches the authored project. Second, confirm whether the host will receive .vercel/output or standard Nitro Node output. Third, check all runtime secrets in the target environment and make sure no route-auth or model credential is embedded in source or artifacts. Fourth, confirm the workflow world and sandbox backend that the environment will select. Finally, test the deployed session, stream, channel, callback, and schedule routes through the normal client or channel path rather than only checking that the process starts.

For adjacent documentation, read the CLI reference when you need command-level details for build and start, the auth and route-protection guide before exposing channels or tenant-specific routes, the sandbox guide when production execution isolation matters, and the frontend or Next.js integration pages when the deployed agent is called from an application. If you are composing separately deployed agents, the remote-agents guide is the next step because it explains how one eve deployment can call another with outbound authentication.

Sources: docs/guides/deployment.md