Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs: organize deployment guidance by strategy (#971)

Colton Padden2079cdf33150
diff --git a/docs/concepts/execution-model-and-durability.md b/docs/concepts/execution-model-and-durability.md
index 648dade39..47d119223 100644
--- a/docs/concepts/execution-model-and-durability.md
+++ b/docs/concepts/execution-model-and-durability.md
@@ -36,7 +36,7 @@ export default defineAgent({
});
```
-The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. Custom worlds must implement the runtime protocol expected by eve's vendored `@workflow/*` packages (currently the `5.0.0-beta` line); the Workflow SDK rejects incompatible protocol versions during initialization. See the [deployment guide](../guides/deployment#8-deploy-without-vercel) for the install command, plus [agent.ts](../agent-config#workflow-world) and [Workflow Worlds](https://workflow-sdk.dev/worlds).
+The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. Custom worlds must implement the runtime protocol expected by eve's vendored `@workflow/*` packages (currently the `5.0.0-beta` line); the Workflow SDK rejects incompatible protocol versions during initialization. See [Self-host eve](../guides/deployment/self-hosting#persist-workflow-state), [agent.ts](../agent-config#workflow-world), and [Workflow Worlds](https://workflow-sdk.dev/worlds).
## Resuming after a crash
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
index 31924b8e2..7cb35355d 100644
--- a/docs/getting-started.mdx
+++ b/docs/getting-started.mdx
@@ -130,7 +130,7 @@ Other commands the eve binary provides (prefix each with `npx`, or add a matchin
In the dev TUI, type a message and watch it happen in order. First the `get_weather` call, then its result, then the reply.
-The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment).
+The same CLI can point at a deployment. `npx eve dev https://your-app.vercel.app` drives a deployed app, which is handy for preview and production smoke tests. See [Deployment](./guides/deployment/overview).
## Send a message
diff --git a/docs/guides/auth-and-route-protection.md b/docs/guides/auth-and-route-protection.md
index 4737e28f8..5599ca506 100644
--- a/docs/guides/auth-and-route-protection.md
+++ b/docs/guides/auth-and-route-protection.md
@@ -373,4 +373,4 @@ Inline providers derive a stable tool-qualified auth key from Vercel Connect met
- [Security model](../concepts/security-model): trust boundaries and the pre-production checklist
- [Connections](../connections): connection auth shapes (`connect()` vs static token)
-- [Deployment](./deployment): where route-auth secrets live in production
+- [Deployment](./deployment/overview): where route-auth secrets live in production
diff --git a/docs/guides/deployment.md b/docs/guides/deployment.md
deleted file mode 100644
index 9a5500e23..000000000
--- a/docs/guides/deployment.md
+++ /dev/null
@@ -1,210 +0,0 @@
----
-title: "Deployment"
-description: "A production checklist for shipping an eve agent on Vercel or your own host, covering build output, env and secrets, sandbox backend, auth, deploy, and verify."
----
-
-eve runs the same way locally, on Vercel, and on a long-running Node host, so taking an agent from `eve dev` to production is mostly mechanical. Work through this checklist in order.
-
-## 1. Build
-
-`eve build` compiles the agent and writes the host output:
-
-```bash
-eve build
-```
-
-When `VERCEL` is set (every hosted Vercel build sets it), `eve build` writes the [Vercel Build Output](https://vercel.com/docs/build-output-api) bundle under `.vercel/output`. A plain local `eve build` skips that bundle. Either way you get eve's compiled framework artifacts under `.eve/`, including the discovery manifest, compiled manifest, diagnostics, and module map. Open those to see which authored surface a deployment will load. For the artifact guide and what to do when `eve build` fails, see [Observability](./instrumentation).
-
-### How portability works
-
-Nitro is the HTTP host layer. It gives eve a build artifact that can serve the health, session, stream, channel, callback, and schedule routes outside the dev server. Workflow execution and sandbox execution are separate runtime adapters; they are not hidden Vercel dependencies inside Nitro.
-
-On Vercel, eve emits Vercel Build Output, the Workflow SDK runs on Vercel Workflow, and `defaultBackend()` selects Vercel Sandbox. Outside Vercel, `eve start` serves the standard Nitro Node output, the Workflow SDK uses its local world by default, and `defaultBackend()` selects a local sandbox backend in availability order. That local workflow world persists run state on disk and has no direct coupling to Vercel; Vercel-only behavior such as latest-deployment routing and dashboard run attributes is additive.
-
-Advanced self-hosted deployments can select a different installed Workflow world package in the root `agent.ts`:
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
- model: "anthropic/claude-opus-4.8",
- experimental: {
- workflow: {
- world: "@acme/eve-workflow-world",
- },
- },
-});
-```
-
-The world package should read credentials and host-specific options from runtime environment variables. It should export a default factory or `createWorld()` function. See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying SDK abstraction.
-
-## 2. Environment variables and secrets
-
-Set these in your deployment environment or secret manager, never in source or compiled artifacts:
-
-- **A model credential.** The lowest-setup Vercel option is the Vercel AI Gateway. Link a Vercel project, and gateway model ids like `anthropic/claude-opus-4.8` authenticate through Vercel OIDC, with no provider keys to manage. Outside Vercel, either set `AI_GATEWAY_API_KEY` for gateway-routed models or configure a direct provider model with an [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models) and set that provider's key, for example `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
-- **Route-auth secrets**, for example `ROUTE_AUTH_BASIC_PASSWORD` and any JWT/OIDC signing keys referenced by your channel's `auth` (see [Auth and route protection](./auth-and-route-protection)).
-
-Route-auth secrets are never serialized into the compiled discovery or module-map artifacts. The runtime re-materializes them from the authored channel definition instead. If your deployment sits behind Vercel preview protection and you want to drive it with `eve dev`, set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before launching.
-
-## 3. Model routing
-
-The shape of `model` in `agent/agent.ts` decides whether eve calls the Vercel AI Gateway or a provider endpoint directly.
-
-A string model id is gateway-routed:
-
-```ts title="agent/agent.ts"
-import { defineAgent } from "eve";
-
-export default defineAgent({
- model: "anthropic/claude-opus-4.8",
-});
-```
-
-That works on Vercel with project OIDC or anywhere else with `AI_GATEWAY_API_KEY`. Passing a provider key through `modelOptions.providerOptions.gateway.byok` also still sends the request through the Gateway; it only changes which upstream key the Gateway uses.
-
-To avoid the Gateway entirely, install the [AI SDK package](https://ai-sdk.dev/docs/foundations/providers-and-models) for the provider you want to call, pass that provider's model object, and set that provider's normal environment variable:
-
-```bash
-npm install @ai-sdk/anthropic
-```
-
-```ts title="agent/agent.ts"
-import { anthropic } from "@ai-sdk/anthropic";
-import { defineAgent } from "eve";
-
-export default defineAgent({
- model: anthropic("claude-opus-4-8"),
-});
-```
-
-With that shape, the model call goes directly to Anthropic and the runtime reads `ANTHROPIC_API_KEY`. Direct Anthropic model ids use hyphens (`claude-opus-4-8`), unlike the dotted Gateway id (`anthropic/claude-opus-4.8`). The same pattern works for OpenAI after installing `@ai-sdk/openai`, using `openai("...")`, and setting `OPENAI_API_KEY`. This is the usual choice when self-deploying without any Vercel-managed services.
-
-## 4. Sandbox backend
-
-On Vercel, the [sandbox](../sandbox) runs on hosted [Vercel Sandbox](https://vercel.com/docs/sandbox) infrastructure. Attach the backend on the sandbox definition:
-
-```ts title="agent/sandbox/sandbox.ts"
-import { defineSandbox } from "eve/sandbox";
-import { vercel } from "eve/sandbox/vercel";
-
-export default defineSandbox({
- backend: vercel(),
-});
-```
-
-Leave `backend` off and eve falls back to `defaultBackend()`, which picks the Vercel backend on hosted builds and the local backend everywhere else. One definition, both environments.
-
-For a self-deployed process, leave `defaultBackend()` in place or choose an explicit non-Vercel backend such as Docker or microsandbox. If those do not match your infrastructure, write a custom `SandboxBackend` adapter that creates sessions in your own container, VM, or isolation service. Do not pin `vercel()` unless that process should create hosted Vercel sandboxes.
-
-## 5. Build-time sandbox prewarm
-
-During Vercel-targeted builds, eve prewarms reusable Vercel sandbox templates so the first session doesn't pay the cold-start cost. This includes hosted builds and local `vercel build` runs:
-
-- Prewarm runs for hosted Vercel builds and linked local `vercel build` runs.
-- A sandbox with no `bootstrap()` and no workspace seed files gets skipped.
-- Seed-only templates are keyed by skills and workspace file contents, so unchanged seeds reuse a template across deploys.
-- Templates with a `bootstrap()` are keyed by the optional resolved `revalidationKey()` plus the authored sandbox source and seed contents, so matching inputs reuse a template across deploys.
-- Each template shows up in the build log as either `reused cached` or `built`.
-- Prewarming only covers template construction. `onSession()` still runs at runtime, once per session.
-- **If build-time prewarm fails, the build fails.**
-
-Local builds must be linked to a Vercel project with credentials that can provision Vercel Sandbox templates. If authentication or template provisioning fails, eve fails the build rather than emitting output that would fail after deployment.
-
-## 6. Auth
-
-Swap any scaffolded `placeholderAuth()` for your real policy before the first production browser request hits the app. Both the framework default and the placeholder reject production browser traffic, so an unconfigured app fails closed rather than serving open routes. The production policy can be a shipped helper (`httpBasic()`, `jwtHmac()`, `jwtEcdsa()`, `oidc()`, `vercelOidc()`) or a custom `AuthFn` that validates your own sessions, API keys, or identity provider. See [Auth and route protection](./auth-and-route-protection) for the ordered auth walk and the fail-closed guarantee.
-
-If you self-deploy outside Vercel, do not rely on `vercelOidc()` as the only production authenticator. Use your own route policy, such as Basic auth, JWT/OIDC verification for your identity provider, or a custom verifier.
-
-## 7. Deploy on Vercel
-
-Deploy with the [Vercel CLI](https://vercel.com/docs/cli) or by pushing to a Git-connected project:
-
-```bash
-vercel deploy
-```
-
-The deployed app serves the same stable health, session, and stream routes you've been hitting locally.
-
-## 8. Deploy without Vercel
-
-eve can also run as a normal Node service behind your own process manager, container platform, or reverse proxy:
-
-```bash
-eve build
-PORT=3000 eve start --host 0.0.0.0
-```
-
-Eve writes the standard Nitro output under `.output/` instead of Vercel Build Output. `eve start` serves that built app and respects `PORT`, or the `--port` flag. Put TLS, routing, autoscaling, and log collection around that process the same way you would for any other Node HTTP service.
-
-Self-deployed agents should make the Vercel-specific choices explicit:
-
-- Let the Workflow SDK use its default local world, which stores workflow state under `.eve/.workflow-data`; configure your host so that directory is on persistent storage, or select another world with `experimental.workflow.world` in the root `agent.ts`. When you select a custom world, install a world package built against the same `@workflow/*` line as your eve release (currently the `5.0.0-beta` line). The npm `latest` tag may lag, so pin the version explicitly, for example `pnpm add @workflow/[email protected]`. The Workflow SDK rejects worlds with an incompatible runtime protocol during initialization.
-- If you put a reverse proxy or ingress in front of eve, forward **both** `/eve/` and `/.well-known/workflow/`. The workflow world delivers run callbacks to `/.well-known/workflow/v1/flow`; a proxy restricted to `/eve/` lets sessions start but silently stalls runs forever, because the callbacks never reach eve.
-- Install the AI SDK package for your provider, then use a direct provider model object and `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` when you want no Gateway dependency.
-- Use `AI_GATEWAY_API_KEY` if you still want Gateway routing from a non-Vercel host.
-- Replace `vercelOidc()` with auth that your host can verify.
-- Use `defaultBackend()`, a pinned non-Vercel sandbox backend such as Docker or microsandbox, or your own `SandboxBackend` adapter.
-- If the agent defines schedules, the default `eve build && eve start` path starts Nitro's schedule runner, and Vercel wires schedules to Vercel Cron automatically. If you adapt the output to a custom HTTP-only host or preset, make sure it also runs Nitro scheduled tasks, or trigger the same work from your own scheduler.
-- Treat Vercel Cron, Vercel Sandbox prewarm, Vercel Deployment Protection bypass, and the Agent Runs dashboard as Vercel-only conveniences.
-
-The HTTP contract is unchanged: health, session creation, streaming, channels, tools, and subagents use the same routes under `/eve/`, and the workflow dispatch route lives under `/.well-known/workflow/`. A reverse proxy must preserve both prefixes. Any client that can reach and authenticate to those routes can talk to the agent.
-
-## 9. Verify the deployment
-
-Smoke-test the live routes. Health first:
-
-```bash
-curl https://<your-app>/eve/v1/health
-```
-
-Then a real turn:
-
-```bash
-curl -X POST https://<your-app>/eve/v1/session \
- -H 'content-type: application/json' \
- -d '{"message":"Hello from production"}'
-```
-
-The POST returns a JSON body whose `sessionId` identifies the new session. Attach to that session's stream with it:
-
-```bash
-curl https://<your-app>/eve/v1/session/<sessionId>/stream
-```
-
-Or drive the deployment interactively with the dev TUI, which is handy for preview and production smoke tests:
-
-```bash
-eve dev https://<your-app>
-```
-
-(Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if the deployment uses preview protection.)
-
-## View runs in the dashboard
-
-Once the agent is deployed, the platform auto-detects `eve` as the framework and surfaces an **Agent Runs** tab under your project's **Observability** view in the Vercel dashboard. From there you can browse sessions and drill into each conversation's trace.
-
-> The Agent Runs tab is currently gated. Your Vercel team needs the feature enabled before it appears. If you don't see it, reach out to your Vercel contact to get your team enabled.
-
-Agent Runs is separate from the OpenTelemetry exporters configured in [Observability](./instrumentation). Those still work and are the recommended path if you want spans in Braintrust, Datadog, or another third-party backend.
-
-## How eve sits behind a host framework
-
-You can deploy an eve app on its own, or mount it inside a host web framework that owns the rest of the site (marketing pages, a dashboard, other API routes). The host keeps its own routing and serves eve's routes through the framework integration. Either way, the agent surface and HTTP contract are identical. For mounting eve in Next.js (`withEve`) and the other supported frameworks, see [Frontend](./frontend/nextjs).
-
-## Checklist
-
-- [ ] `eve build` succeeds, and writes `.vercel/output` when `VERCEL` is set.
-- [ ] Provider keys and route-auth secrets are set in the deployment environment.
-- [ ] The sandbox backend matches the environment (`vercel()` or `defaultBackend()`).
-- [ ] On Vercel, build-time prewarm reused or built templates without failing.
-- [ ] `placeholderAuth()` is replaced with your real policy.
-- [ ] `vercel deploy` succeeds, or your self-hosted process starts with `eve start`.
-- [ ] The health, session, and stream routes respond on the deployment URL.
-
-## What to read next
-
-- [Auth and route protection](./auth-and-route-protection): secure the routes you deployed
-- [Observability](./instrumentation): tracing, run tags, and common failures
-- [Sandbox](../sandbox): backends, lifecycle, and credential brokering
diff --git a/docs/guides/deployment/meta.json b/docs/guides/deployment/meta.json
new file mode 100644
index 000000000..75483dedf
--- /dev/null
+++ b/docs/guides/deployment/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Deployment",
+ "pages": ["overview", "vercel", "self-hosting"]
+}
diff --git a/docs/guides/deployment/overview.md b/docs/guides/deployment/overview.md
new file mode 100644
index 000000000..30b65cba2
--- /dev/null
+++ b/docs/guides/deployment/overview.md
@@ -0,0 +1,61 @@
+---
+title: "Overview"
+description: "Choose a deployment strategy and prepare an eve agent for production."
+---
+
+Deploy eve to Vercel or run it as a Node service on your own infrastructure. Your deployment strategy determines the build output, workflow storage, sandbox backend, and routing. The agent’s filesystem-based configuration remains portable across these strategies.
+
+## Choose a deployment strategy
+
+Choose where the eve runtime will run:
+
+| Strategy | Build output | Workflows | Sandbox | Choose it when |
+| ------------------------------ | ---------------------- | ------------------------------ | ------------------------------- | ----------------------------------------------------- |
+| [Vercel](./vercel) | `.vercel/output` | Vercel Workflow | Vercel Sandbox | You want Vercel to operate the runtime services |
+| [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker, microsandbox, or custom | You operate your own Node or container infrastructure |
+
+eve is frontend agnostic and can be deployed within Next.js, Nuxt, or SvelteKit applications. See [Frontend integrations](../frontend/overview) for more details.
+
+## Prepare for production
+
+Every production deployment must satisfy the same runtime requirements:
+
+1. Run `eve build` to compile the agent and create host output.
+2. Provide a model credential and any secrets required by tools, connections, and route authentication.
+3. Replace `placeholderAuth()` with a production route policy before accepting browser traffic.
+4. Select workflow and sandbox implementations that match the host.
+5. Verify the health route and complete a real agent turn.
+
+`eve build` always writes compiler artifacts under `.eve/`. A Vercel build also writes `.vercel/output`. A build for another host writes the standard Nitro server under `.output/`.
+
+## Configure credentials
+
+Keep credentials in your deployment environment or secret manager. Don’t include them in source or compiled artifacts.
+
+Your model configuration determines the required credential. A string model ID uses the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) and requires Vercel project OpenID Connect (OIDC) or `AI_GATEWAY_API_KEY`. A provider-authored model uses that provider’s package and API key. See [Agent configuration](../../agent-config#set-the-model) for both forms.
+
+Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Auth and route protection](../auth-and-route-protection) for the available policies and secret requirements.
+
+## Verify the deployment
+
+Check the public health route first:
+
+```bash
+curl https://your_agent.example.com/eve/v1/health
+```
+
+Then connect the development terminal user interface (TUI) to the deployment and send a real message:
+
+```bash
+eve dev https://your_agent.example.com
+```
+
+Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if a Vercel deployment uses Deployment Protection.
+
+## Continue with a platform guide
+
+Follow the guide for your deployment platform or application topology:
+
+- [Deploy to Vercel](./vercel): use Vercel Build Output, Workflow, Sandbox, Cron, and observability
+- [Self-host eve](./self-hosting): run the Nitro Node server with infrastructure you manage
+- [Frontend integrations](../frontend/overview): mount eve alongside Next.js, Nuxt, or SvelteKit
diff --git a/docs/guides/deployment/self-hosting.md b/docs/guides/deployment/self-hosting.md
new file mode 100644
index 000000000..c470f57ee
--- /dev/null
+++ b/docs/guides/deployment/self-hosting.md
@@ -0,0 +1,88 @@
+---
+title: "Self-host eve"
+description: "Run an eve agent as a Node service with your own workflow storage, sandbox backend, and routing."
+---
+
+Self-host eve when you operate a Node service, container platform, or reverse proxy. You run eve’s Nitro server and choose the infrastructure that stores workflows and executes sandbox sessions.
+
+## Build and start the Node service
+
+Build the agent, then start the generated server:
+
+```bash
+eve build
+PORT=3000 eve start --host 0.0.0.0
+```
+
+The build writes the Nitro server under `.output/`. `eve start` serves that output and accepts either `PORT` or the `--port` flag.
+
+Run this process under the same process manager or container platform you use for other Node web services. Configure Transport Layer Security (TLS), scaling, restarts, and log collection in that platform.
+
+## Configure model access and route auth
+
+Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway from a non-Vercel host. To call a provider directly, install its [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models). Then pass its model object in `agent.ts` and set its API key. See [Agent configuration](../../agent-config#set-the-model) for examples.
+
+Don’t rely on `vercelOidc()` as the only production authenticator outside Vercel. Configure Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier that your host can validate. See [Auth and route protection](../auth-and-route-protection).
+
+## Persist workflow state
+
+The default local Workflow world stores run state under `.eve/.workflow-data`. Mount that directory on persistent storage so runs survive process and container replacement.
+
+You can instead select an installed Workflow world package in the root `agent.ts`:
+
+```typescript
+import { defineAgent } from "eve";
+
+export default defineAgent({
+ experimental: {
+ workflow: {
+ world: "@acme/eve-workflow-world",
+ },
+ },
+});
+```
+
+The package must export a default factory or `createWorld()` function. Read credentials and host options from runtime environment variables. Install a world built against the same `@workflow/*` line as your eve release. The current line is `5.0.0-beta`, and the runtime rejects incompatible protocol versions.
+
+See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
+
+## Select a sandbox backend
+
+`defaultBackend()` selects a local sandbox backend in availability order. You can instead select Docker, microsandbox, or a custom `SandboxBackend` adapter for your container, virtual machine, or isolation service.
+
+Don’t select `vercel()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for backend configuration and selection order.
+
+## Configure proxy routes
+
+Forward both runtime route prefixes through your reverse proxy or ingress:
+
+- `/eve/` serves health, sessions, streams, channels, tools, and subagents
+- `/.well-known/workflow/` receives workflow callbacks
+
+A proxy restricted to `/eve/` lets a session start, but the run stalls when its callback can’t reach eve. Preserve both prefixes without rewriting their paths.
+
+## Run schedules
+
+The standard `eve build && eve start` path starts Nitro’s schedule runner. If you adapt the output to a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
+
+## Verify the service
+
+Check the health route after your proxy and authentication configuration are active:
+
+```bash
+curl https://your_agent.example.com/eve/v1/health
+```
+
+Then connect the development TUI and complete a real turn:
+
+```bash
+eve dev https://your_agent.example.com
+```
+
+## Continue configuring production
+
+Use these guides to secure and observe the deployed agent:
+
+- [Auth and route protection](../auth-and-route-protection): configure the host’s route policy
+- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Sandbox](../../sandbox): select and secure a sandbox backend
diff --git a/docs/guides/deployment/vercel.mdx b/docs/guides/deployment/vercel.mdx
new file mode 100644
index 000000000..7a42f8244
--- /dev/null
+++ b/docs/guides/deployment/vercel.mdx
@@ -0,0 +1,90 @@
+---
+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
+
+Link the agent directory to a Vercel project:
+
+```bash
+eve link
+```
+
+The command links an existing project or creates one, then pulls its environment variables. In continuous integration (CI) environments, use the non-interactive Vercel command instead:
+
+```bash
+vercel link --project your_project_name --yes --non-interactive
+```
+
+## 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 backend
+
+Leave the sandbox `backend` unset to use `defaultBackend()`. On Vercel, it selects Vercel Sandbox. You can also select the backend explicitly:
+
+```typescript
+import { defineSandbox } from "eve/sandbox";
+import { vercel } from "eve/sandbox/vercel";
+
+export default defineSandbox({
+ backend: vercel(),
+});
+```
+
+See [Sandbox](../../sandbox) for resource limits, network policy, and lifecycle hooks.
+
+<Callout type="info" title="Sandbox prewarming">
+ During a Vercel build, eve automatically creates or reuses a sandbox template when your sandbox
+ has `bootstrap()` or seed files. The build needs permission to create Vercel Sandbox templates,
+ and a prewarm failure stops the deployment. See the [sandbox lifecycle](../../sandbox#lifecycle)
+ for template and session setup.
+</Callout>
+
+## Deploy the agent
+
+Deploy the linked project to production:
+
+```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`.
+
+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
+- **Vercel Cron**: invokes authored schedules
+- **Vercel Sandbox**: runs sandbox sessions selected by `defaultBackend()`
+
+## Verify the deployment
+
+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
+```
+
+Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally before connecting if the deployment uses Deployment Protection.
+
+## Inspect agent runs
+
+Vercel detects eve and can add an **Agent Runs** tab under the project’s **Observability** view. Use it to browse sessions and inspect each conversation trace.
+
+The Agent Runs tab requires enablement for your Vercel team. Contact your Vercel representative if the tab doesn’t appear. For third-party tracing backends, configure [OpenTelemetry instrumentation](../instrumentation).
+
+## Continue configuring production
+
+Use these guides to secure and observe the deployed agent:
+
+- [Auth and route protection](../auth-and-route-protection): configure who can call the deployed agent
+- [Observability](../instrumentation): export traces and diagnose runtime failures
+- [Sandbox](../../sandbox): configure resources, isolation, and network access
diff --git a/docs/guides/dev-tui.md b/docs/guides/dev-tui.md
index 655d34bee..b97f6aab5 100644
--- a/docs/guides/dev-tui.md
+++ b/docs/guides/dev-tui.md
@@ -150,7 +150,7 @@ In a remote session, `/vc:login` first resolves the deployment's Vercel project
The project-scoped token represents the resolved project's Development environment. Vercel already allows a project's Development environment to call its own Preview deployments by default. For a Production or custom-environment target, `/vc:login` shows the exact Development-to-target rule before changing that project's Trusted Sources. Eve preserves existing entries. When it creates an explicit rule, it also carries Vercel's default self-access rows forward because saved rules replace those defaults. See Vercel's [Trusted Sources guide](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources), [error reference](https://vercel.com/docs/errors/trusted_sources_environment_mismatch), and [OIDC token anatomy](https://vercel.com/docs/oidc/reference#oidc-token-anatomy).
-`VERCEL_AUTOMATION_BYPASS_SECRET` remains available for a Protection Bypass for Automation token. See [Deployment](./deployment) for the smoke-test flow.
+`VERCEL_AUTOMATION_BYPASS_SECRET` remains available for a Protection Bypass for Automation token. See [Deploy to Vercel](./deployment/vercel#verify-the-deployment) for the smoke-test flow.
## What to read next
diff --git a/docs/guides/frontend/nextjs.mdx b/docs/guides/frontend/nextjs.mdx
index c26371884..9277207f8 100644
--- a/docs/guides/frontend/nextjs.mdx
+++ b/docs/guides/frontend/nextjs.mdx
@@ -124,4 +124,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
- [Frontend overview](./overview): the `useEveAgent` API
- [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)
diff --git a/docs/guides/frontend/nuxt.mdx b/docs/guides/frontend/nuxt.mdx
index b8a67f31b..e0622129b 100644
--- a/docs/guides/frontend/nuxt.mdx
+++ b/docs/guides/frontend/nuxt.mdx
@@ -96,4 +96,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
- [`useEveAgent` (Vue)](./use-eve-agent-vue): the composable API
- [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)
diff --git a/docs/guides/frontend/sveltekit.mdx b/docs/guides/frontend/sveltekit.mdx
index c4a3774b0..ad322f5ac 100644
--- a/docs/guides/frontend/sveltekit.mdx
+++ b/docs/guides/frontend/sveltekit.mdx
@@ -108,4 +108,4 @@ For a public demo, use `none()` (also from `eve/channels/auth`) to skip authenti
- [`useEveAgent` (Svelte)](./use-eve-agent-svelte): the binding API
- [Auth & route protection](../auth-and-route-protection)
-- [Deployment](../deployment)
+- [Deployment](../deployment/overview)
diff --git a/docs/guides/instrumentation.md b/docs/guides/instrumentation.md
index b036cb36a..f9d9df9c8 100644
--- a/docs/guides/instrumentation.md
+++ b/docs/guides/instrumentation.md
@@ -138,7 +138,7 @@ Per-turn usage tags are written on each step of a turn, accumulating cumulative
Tag writes are best-effort: a failure is logged once per process and then swallowed, so a broken tag emit never breaks the agent.
-These tags power the **Agent Runs** tab in the Vercel dashboard. When you deploy on Vercel, the platform auto-detects `eve` as the framework and surfaces an Agent Runs view under your project's **Observability** tab, where you can browse sessions and drill into each conversation's trace, with no `instrumentation.ts` required. The tab is currently gated per team. See [Deployment](./deployment#view-runs-in-the-dashboard) for enablement. Agent Runs is separate from the OpenTelemetry export above. Use OTel when you want spans in Braintrust, Datadog, or another third-party backend.
+These tags power the **Agent Runs** tab in the Vercel dashboard. When you deploy on Vercel, the platform auto-detects `eve` as the framework and surfaces an Agent Runs view under your project's **Observability** tab, where you can browse sessions and drill into each conversation's trace, with no `instrumentation.ts` required. The tab is currently gated per team. See [Deploy to Vercel](./deployment/vercel#inspect-agent-runs) for enablement. Agent Runs is separate from the OpenTelemetry export above. Use OTel when you want spans in Braintrust, Datadog, or another third-party backend.
Note: By default, telemetry records full message history and model outputs You may need to disclose these data flows in your privacy materials if utilized.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index c7729130b..808dfcba0 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -273,4 +273,4 @@ Related: [Project layout](./project-layout) · [instrumentation.ts](../guides/in
- [Project layout](./project-layout): what `eve info` discovers
- [instrumentation.ts](../guides/instrumentation): tracing and the error catalog
-- [Deployment](../guides/deployment): `eve build` and `eve start` in production
+- [Deployment](../guides/deployment/overview): `eve build` and `eve start` in production
diff --git a/docs/tutorial/ship-it.mdx b/docs/tutorial/ship-it.mdx
index 8c557061d..2db857152 100644
--- a/docs/tutorial/ship-it.mdx
+++ b/docs/tutorial/ship-it.mdx
@@ -153,4 +153,4 @@ Across the nine steps you built and shipped one agent, and along the way you use
- [Dynamic capabilities](../guides/dynamic-capabilities) for schema-derived dynamic tools, a read-only analyst subagent, and model-authored report workflows on this same example.
- [Auth and route protection](../guides/auth-and-route-protection) for production auth patterns.
-Learn more: [Frontend](../guides/frontend/overview) · [Auth and route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment)
+Learn more: [Frontend](../guides/frontend/overview) · [Auth and route protection](../guides/auth-and-route-protection) · [Deployment](../guides/deployment/overview)