# Eve deployment

> Build `.eve/` artifacts, configure Vercel env and sandbox backends, prewarm templates, deploy, and verify production routes.

- Repository: withastro/flue-with-vercel-eve
- GitHub: https://github.com/withastro/flue
- Human docs: https://grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6
- Complete Markdown: https://grok-wiki.com/public/docs/withastro-flue-with-vercel-eve-f4b79875fff6/llms-full.txt

## Source Files

- `vercel-eve:docs/guides/deployment.md`
- `vercel-eve:docs/reference/cli.md`
- `vercel-eve:Dockerfile`
- `vercel-eve:docs/guides/instrumentation.md`
- `vercel-eve:docs/guides/auth-and-route-protection.md`
- `vercel-eve:packages/eve/package.json`
- `vercel-eve:turbo.json`

---

---
title: "Eve deployment"
description: "Build `.eve/` artifacts, configure Vercel env and sandbox backends, prewarm templates, deploy, and verify production routes."
---

`eve build` compiles authored files under `agent/` into inspectable `.eve/` artifacts and a Nitro host bundle under `.output/`. When `VERCEL` is set during a hosted build, the same command also emits `.vercel/output`, runs sandbox template prewarm, and bundles Vercel Workflow functions. Production deploys use `eve link` (or `vercel link` in CI), then `eve deploy` or `vercel deploy`, and expose the same `/eve/v1/*` routes as local `eve dev`.

## Deployment lifecycle

```mermaid
flowchart TB
  subgraph Authoring["Authoring layer"]
    Agent["agent/ slots"]
  end

  subgraph Build["eve build"]
    EveArtifacts[".eve/ discovery + compile"]
    NitroOut[".output/ Nitro server"]
    VercelOut[".vercel/output/ (when VERCEL set)"]
    Prewarm["Sandbox template prewarm"]
    WorkflowFns["Workflow function emit"]
  end

  subgraph Vercel["Vercel platform"]
    Env["Project env vars"]
    Sandbox["Vercel Sandbox"]
    Runs["Agent Runs / Workflow tags"]
  end

  subgraph Runtime["Production HTTP"]
    Health["GET /eve/v1/health"]
    Session["POST /eve/v1/session"]
    Stream["GET /eve/v1/session/:id/stream"]
  end

  Agent --> EveArtifacts
  EveArtifacts --> NitroOut
  NitroOut --> VercelOut
  VercelOut --> Prewarm
  Prewarm --> WorkflowFns
  WorkflowFns --> Env
  Env --> Runtime
  Prewarm --> Sandbox
  Runtime --> Runs
```

<Note>
Eve requires Node `>=24` (`packages/eve/package.json`). The workspace also contains **withastro/flue**, which ships agents via `flue build` to Node or Cloudflare targets — a different deploy surface documented on the Flue deploy page.
</Note>

## Build output

`eve build` has no flags. It loads `.env` and `.env.local` from the app root, compiles discovery and runtime artifacts, builds the host output, and prints the output directory path.

<CodeGroup>
```bash title="Local build"
eve build
```

```bash title="Expected success line"
built output at .output
```
</CodeGroup>

### `.eve/` artifacts

These files are preserved even on partial discovery failure and are the fastest way to see what a deployment will load.

| Artifact | Purpose |
| --- | --- |
| `.eve/discovery/agent-discovery-manifest.json` | Files Eve discovered on disk |
| `.eve/discovery/diagnostics.json` | Authored-shape errors and warnings |
| `.eve/compile/compiled-agent-manifest.json` | Serialized surface loaded at runtime |
| `.eve/compile/compile-metadata.json` | Build-time metadata and paths |
| `.eve/compile/module-map.mjs` | Compiled module entrypoints imported at runtime |

When discovery errors cause `eve build` to fail, the CLI prints the full diagnostics report (severity, message, source path) and the diagnostics artifact path.

### Host output directories

| Condition | Output |
| --- | --- |
| `VERCEL` unset (local build) | `.output/` Nitro server bundle only |
| `VERCEL` set (Vercel build) | `.output/` plus `.vercel/output/` Build Output API bundle |

On Vercel builds, sandbox prewarm runs **before** workflow function emission so a prewarm failure aborts the build before bundling deploy artifacts that would never ship.

`eve start` serves the previously built `.output/server/index.mjs` bundle. Run `eve build` first; `eve start` errors when that entry is missing.

## Environment variables and secrets

Set credentials in the Vercel project environment — never in source or compiled artifacts. Route-auth secrets are not serialized into discovery or module-map artifacts; the runtime re-materializes them from the authored channel definition at boot.

### Model credentials

<ParamField body="AI Gateway (recommended)" type="env">
Link a Vercel project with `eve link`. Gateway model ids such as `anthropic/claude-opus-4.8` authenticate through Vercel OIDC with no provider API keys to manage. `eve link` pulls `VERCEL_OIDC_TOKEN` or `AI_GATEWAY_API_KEY` into `.env.local` and verifies one is present.
</ParamField>

<ParamField body="Direct provider" type="env">
Set the provider key directly, for example `OPENAI_API_KEY`, when not routing through AI Gateway.
</ParamField>

### Route auth secrets

Route-auth values such as `ROUTE_AUTH_BASIC_PASSWORD` and JWT/OIDC signing keys referenced by `agent/channels/eve.ts` must live in Vercel env vars. Replace scaffolded `placeholderAuth()` before the first production browser request — both the placeholder and the framework default reject production browser traffic (fail closed).

### Preview protection bypass

When a deployment sits behind Vercel preview protection and you want to drive it with `eve dev`, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching:

```bash
eve dev https://<your-app>
```

## Sandbox backend

On Vercel, sandboxes run on [Vercel Sandbox](https://vercel.com/docs/sandbox) infrastructure. Pin the backend explicitly or rely on environment-aware defaults.

<CodeGroup>
```ts title="Explicit Vercel backend"
import { defineSandbox } from "eve/sandbox";
import { vercel } from "eve/sandbox/vercel";

export default defineSandbox({
  backend: vercel(),
});
```

```ts title="Environment-aware default"
import { defaultBackend, defineSandbox } from "eve/sandbox";

export default defineSandbox({
  backend: defaultBackend(),
});
```
</CodeGroup>

`defaultBackend()` selects backends in priority order: **Vercel Sandbox** when `process.env.VERCEL` is set, then Docker, microsandbox, then just-bash locally. One sandbox definition can serve both local `eve dev` and hosted Vercel without branching on `VERCEL` in authored code.

The repository `Dockerfile` defines the Ubuntu 26.04 base image Eve agents use inside Vercel Sandbox (Node 24, git, ripgrep, python3, jq, sudo).

## Build-time sandbox prewarm

During hosted builds, Eve prewarms reusable Vercel sandbox templates so the first session avoids cold-start template construction.

| Rule | Behavior |
| --- | --- |
| Activation | Runs only when **both** `VERCEL` and `VERCEL_DEPLOYMENT_ID` are set |
| Skip | Sandboxes with no `bootstrap()` and no workspace seed files (`templatePlan.kind === "none"`) |
| Seed-only templates | Keyed by skills and workspace file contents; unchanged seeds reuse across deploys |
| `bootstrap()` templates | Keyed by optional `revalidationKey()`, authored sandbox source hash, and seed contents |
| Build log | Summary line reports reused vs built counts; per-template progress is logged |
| Runtime | `onSession()` still runs once per session; prewarm covers template construction only |
| Failure | **Build fails** — prewarm errors are treated as build failures |

<Warning>
If build-time prewarm fails, the Vercel build fails. Fix sandbox bootstrap or seed configuration before retrying deploy.
</Warning>

## Link and deploy

### Link the Vercel project

<Steps>
<Step title="Link interactively">

```bash
eve link
```

Select a team and project. Eve runs `vercel link`, pulls project environment into `.env.local`, and verifies an AI Gateway credential landed. Re-running `eve link` always shows the pickers again; the new choice wins. A running `eve dev` reloads env files automatically.

</Step>

<Step title="Link in CI">

`eve link` requires an interactive terminal. In CI, use:

```bash
vercel link --project <name> --yes
```

</Step>
</Steps>

### Deploy to production

<Tabs>
<Tab title="eve deploy">

```bash
eve deploy
```

`eve deploy` runs the shared deploy flow: install dependencies if needed, `vercel deploy --prod --yes`, pull env into `.env.local`, and probe the production URL. An unlinked directory prompts through the same team/project pickers when a TTY is present; non-interactive runs without a link exit with guidance to run `eve link` first. `eve deploy` sets `VERCEL_USE_EXPERIMENTAL_FRAMEWORKS=1` during deploy.

</Tab>

<Tab title="vercel deploy">

```bash
vercel deploy
# or
vercel deploy --prod
```

Push to a Git-connected Vercel project or deploy with the Vercel CLI directly. The deployed app serves the same health, session, and stream routes as local dev.

</Tab>
</Tabs>

## Auth before first production traffic

Route auth on `agent/channels/eve.ts` guards:

| Route | Auth |
| --- | --- |
| `POST /eve/v1/session` | Required |
| `POST /eve/v1/session/:sessionId` | Required |
| `GET /eve/v1/session/:sessionId/stream` | Required |
| `GET /eve/v1/health` | Public (no auth walk) |

`eve init` scaffolds `[localDev(), vercelOidc(), placeholderAuth()]`. Swap `placeholderAuth()` for your real policy — or delete the authored channel file to fall back to `[localDev(), vercelOidc()]`, which also rejects production browser traffic.

## Verify production routes

<Steps>
<Step title="Health check">

```bash
curl https://<your-app>/eve/v1/health
```

Expect a successful response suitable for load balancers and uptime monitors.

</Step>

<Step title="Start a session">

<RequestExample>
```bash
curl -X POST https://<your-app>/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"Hello from production"}'
```
</RequestExample>

<ResponseExample>
```json
{
  "sessionId": "<session-id>"
}
```
</ResponseExample>

The JSON body includes `sessionId` for the new session.

</Step>

<Step title="Attach to the stream">

```bash
curl https://<your-app>/eve/v1/session/<sessionId>/stream
```

Returns NDJSON session events. For authenticated deployments, include the same credentials your route-auth policy expects.

</Step>

<Step title="Interactive smoke test">

```bash
eve dev https://<your-app>
```

Connects the dev TUI to a remote deployment — useful for preview and production smoke tests. Set `VERCEL_AUTOMATION_BYPASS_SECRET` first when preview protection is enabled.

</Step>

<Step title="Run evals against production">

```bash
eve eval --url https://<your-app>
```

Runs discovered evals against the remote target without starting a local server.

</Step>
</Steps>

## Observability after deploy

Once deployed, Vercel auto-detects `eve` as the framework and surfaces an **Agent Runs** tab under the project's **Observability** view. Browse sessions and drill into conversation traces powered by framework-owned `$eve.*` workflow run tags — no `agent/instrumentation.ts` required.

<Info>
The Agent Runs tab is currently gated per Vercel team. If it does not appear, contact your Vercel representative for enablement.
</Info>

OpenTelemetry export configured in `agent/instrumentation.ts` is separate from Agent Runs. Use OTel when you want spans in Braintrust, Datadog, or another third-party backend.

## Host framework co-deploy

An Eve agent can deploy standalone or mount inside a host web framework (Next.js via `withEve`, Nuxt, SvelteKit) that owns marketing pages, dashboards, and other API routes. The host keeps its own routing; Eve's HTTP contract and session routes stay identical either way.

## Pre-deploy checklist

- [ ] `eve build` succeeds locally; on Vercel, `.vercel/output` is written when `VERCEL` is set
- [ ] `eve info` shows the expected tools, skills, channels, and routes with no blocking diagnostics
- [ ] Model credentials and route-auth secrets are set in Vercel env vars (not in repo)
- [ ] Sandbox backend matches the target (`vercel()` or `defaultBackend()`)
- [ ] Build-time prewarm completed without failure (check Vercel build logs)
- [ ] `placeholderAuth()` is replaced with production route auth
- [ ] `eve deploy` or `vercel deploy` succeeds
- [ ] Health, session POST, and stream GET respond on the deployment URL

## Troubleshooting

| Symptom | Likely cause and fix |
| --- | --- |
| `eve build` fails with discovery errors | Read printed diagnostics and `.eve/discovery/diagnostics.json`; fix authored-shape errors under `agent/` |
| Build fails during sandbox prewarm | Fix `bootstrap()` or workspace seeds; prewarm failures abort the Vercel build |
| `401` on session routes in production | Expected fail-closed behavior; replace `placeholderAuth()`, configure `vercelOidc()` or your `AuthFn`, set `VERCEL_PROJECT_ID` |
| `eve deploy` exits before deploy | Directory not linked; run `eve link` or `vercel link --project <name> --yes` in CI |
| `eve start` missing build output | Run `eve build` first; expects `.output/server/index.mjs` |
| Tool not visible to the model | Run `eve info`; confirm file is in the correct slot and default-exports `defineTool(...)` |
| Stuck on `session.waiting` | Turn parked on approval, question, or connection sign-in; answer or POST follow-up with valid `continuationToken` |

## Related pages

<CardGroup>
<Card title="Eve CLI reference" href="/eve-cli-reference">
Commands, flags, and exit behavior for `eve build`, `link`, `deploy`, `start`, and `dev`.
</Card>

<Card title="Eve HTTP protocol reference" href="/eve-http-protocol-reference">
Session routes, NDJSON event types, `continuationToken` follow-ups, and stream reconnect rules.
</Card>

<Card title="Eve authoring surfaces" href="/eve-authoring-surfaces">
Configure `agent.ts`, sandbox overrides, channels, and route auth before shipping.
</Card>

<Card title="Eve sessions and streaming" href="/eve-sessions-streaming">
Start sessions, stream events, and handle HITL and subagent events in production clients.
</Card>

<Card title="Flue deploy" href="/flue-deploy">
Compare Eve's Vercel-centric deploy path with Flue's Node and Cloudflare build targets.
</Card>
</CardGroup>