eve 0.89.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -0,0 +1,99 @@
1
+ ---
2
+ title: "Operate a Self-Hosted Agent"
3
+ description: "Upgrade, scale, and troubleshoot an eve agent that runs on your own infrastructure."
4
+ ---
5
+
6
+ Use this guide after your agent runs with [`eve start`](./self-hosting). It covers upgrades, replicas, schedules, workspace members, run data, and common failures.
7
+
8
+ ## Upgrade a self-hosted agent
9
+
10
+ A self-hosted Workflow world serves one eve version at a time. Deploying a new build of your agent on the same eve release keeps existing sessions running. Upgrading eve strands sessions started by the previous version: their recorded history remains readable, but they cannot resume. See [Recover a stranded session](#recover-a-stranded-session) for how a new channel message starts a replacement.
11
+
12
+ To deploy a new build:
13
+
14
+ 1. Stop the processes running the previous build.
15
+ 2. With the Postgres world, run `bootstrap` if the build upgrades `@workflow/world-postgres`; see [Use the Postgres world](./workflow-worlds#use-the-postgres-world).
16
+ 3. Start the new build with `eve start`.
17
+
18
+ When the eve version is unchanged, the new build resumes runs that were active when the previous processes stopped.
19
+
20
+ ### Recover a stranded session
21
+
22
+ A session is **stranded** when another eve version built its workflow run, so the current deployment cannot replay it. Its history stays readable, but it cannot process new work. A new message to its channel address starts a replacement session, and `ctx.session.predecessor` names the stranded one. See [Stranded sessions](../../concepts/execution-model-and-durability#stranded-sessions) for behavior in each world and how the replacement reads the earlier conversation.
23
+
24
+ ## Run replicas
25
+
26
+ Use the [Postgres world](./workflow-worlds#use-the-postgres-world) to serve an agent from several `eve start` processes. Every process connected to the database runs queued work, so any replica can continue any session. The local world serves one process.
27
+
28
+ Configure each replica the same way, with two differences:
29
+
30
+ - Run schedules on one replica only; see [Run schedules](#run-schedules).
31
+ - Give every replica access to the same sandboxes. A session records its sandbox, and the next replica to run the session resumes it. A Docker sandbox lives on the Docker daemon of the host that created it. A replica that can't find it starts a fresh sandbox without the earlier files if its own daemon has the build's sandbox image, and fails with `SandboxTemplateNotProvisionedError` otherwise. For replicas on several hosts, use a provider every replica can reach, such as [Vercel Sandbox](../../sandbox/vercel) or a [custom provider](../../sandbox/custom-providers).
32
+
33
+ ## Run schedules
34
+
35
+ `eve start` runs every authored schedule. On a custom HTTP-only host or preset, run Nitro scheduled tasks or invoke the same work from your scheduler.
36
+
37
+ When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
38
+
39
+ ## Run workspace members
40
+
41
+ An [agent workspace](../../concepts/project-structure#several-root-agents) needs neither Vercel nor a frontend at runtime. Build each member from its own directory, because a root `eve build` produces a Vercel workspace deployment.
42
+
43
+ For a workspace containing `support` and `research`, run these from the workspace root, outside a Vercel build environment:
44
+
45
+ ```bash
46
+ (cd agents/support && npx eve build)
47
+ (cd agents/research && npx eve build)
48
+ ```
49
+
50
+ Start each built agent in a separate terminal, or configure these commands in your process manager:
51
+
52
+ ```bash
53
+ (cd agents/support && npx eve start --host 127.0.0.1 --port 3001)
54
+ (cd agents/research && npx eve start --host 127.0.0.1 --port 3002)
55
+ ```
56
+
57
+ This Caddy configuration gives each agent its own origin and forwards all paths unchanged. Point the hostnames at your server and run Caddy on the same machine:
58
+
59
+ ```text
60
+ support.example.com {
61
+ reverse_proxy 127.0.0.1:3001
62
+ }
63
+
64
+ research.example.com {
65
+ reverse_proxy 127.0.0.1:3002
66
+ }
67
+ ```
68
+
69
+ Apply the [authentication, Workflow world, and sandbox configuration](./self-hosting) to each member. With the default local Workflow world, persist each member's own `.eve/.workflow-data` directory.
70
+
71
+ If agents delegate to one another, configure an explicit [workspace-peer transport](../../subagents#vercel-workspace-peers) with the peer's URL and credentials, because the default transport requires Vercel. Remote agent callbacks must reach a public address. Outside `eve dev`, eve refuses callback hosts that are, or resolve to, loopback, private, link-local, or reserved addresses. So callbacks between services over a private network or `127.0.0.1` don't work. See [How remote dispatch and callbacks work](../remote-agents#how-remote-dispatch-and-callbacks-work) and [Set the public callback origin](./self-hosting#set-the-public-callback-origin).
72
+
73
+ ### Add a peer frontend
74
+
75
+ A frontend under `apps/web/` is a separate service that runs with its framework commands, not `eve start`. A browser client can call an agent origin directly with `useEveAgent({ baseUrl: "https://support.example.com" })`. Configure [CORS](../../channels/eve#cors) and browser credentials for that deployment. Alternatively, mount each agent on the frontend's origin through your reverse proxy.
76
+
77
+ For path-based mounts, strip the public prefix before forwarding to the agent. Set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.
78
+
79
+ To have Next.js start the built agent processes and provide the browser-facing proxy routes, use [`eve/next`](../frontend/nextjs#self-host). A self-hosted process manager ignores `eve/vercel` configuration.
80
+
81
+ ## Manage run data
82
+
83
+ The Workflow world holds every session's history. Back it up with the rest of your application data:
84
+
85
+ - **Local world:** back up the `.eve/.workflow-data` directory.
86
+ - **Postgres world:** back up the database. The Postgres world keeps the records of finished runs until you delete them.
87
+
88
+ eve can ask the world to delete a run's inputs, outputs, and stream contents when the run ends. See [Run data retention](../../agent-config#run-data-retention) for the default policy and the override.
89
+
90
+ ## Troubleshoot a self-hosted agent
91
+
92
+ | Symptom | Check | Next action |
93
+ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
94
+ | Sandbox tools fail with `DefaultSandbox has no sandbox provider for this build` | Whether `eve build` could reach a Docker daemon, for example inside a Dockerfile `RUN` step | Rebuild where Docker is reachable, or [select a provider explicitly](./self-hosting#build-inside-a-container-image) |
95
+ | Workflow deliveries fail with HTTP 401 with the local world | Whether `WORKFLOW_LOCAL_BASE_URL` reaches a load balancer in front of several processes | Serve the agent from one process, or use the [Postgres world](./workflow-worlds#use-the-postgres-world) for replicas |
96
+ | Sign-in links or remote agent callbacks point at `localhost` | Whether `WORKFLOW_LOCAL_BASE_URL` is set | [Set the public callback origin](./self-hosting#set-the-public-callback-origin) |
97
+ | A session starts but never responds behind a proxy | With `WORKFLOW_LOCAL_BASE_URL` pointing at the proxy, whether the proxy forwards `/.well-known/workflow/` without rewriting the path | Forward both [proxy route prefixes](./self-hosting#configure-proxy-routes) |
98
+ | Requests return `409` with `code: "session_stranded"` after an upgrade | The eve version in the response | End the session, or send a new message to its channel address; see [Recover a stranded session](#recover-a-stranded-session) |
99
+ | Schedules run more than once | How many replicas run without `--no-schedules` | [Run schedules](#run-schedules) on one replica |
@@ -1,145 +1,128 @@
1
1
  ---
2
2
  title: "Self-Host eve"
3
- description: "Run an eve agent as a Node service with your own workflow storage, sandbox provider, and routing."
3
+ description: "Run an eve agent as a Node service on your own infrastructure, and choose the Workflow world and sandbox it uses."
4
4
  ---
5
5
 
6
- 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.
6
+ Self-host eve by running the Node server that `eve build` produces on your own servers, container platform, or behind your own reverse proxy. The server runs every session as a durable workflow, so conversations, human approvals, and subagent work survive process restarts. eve backs that durability with a [Workflow world](./workflow-worlds) and runs shell and file tools in a [sandbox](../../sandbox). Both have self-hosted defaults, and you can replace either one without changing your agent's behavior.
7
7
 
8
- ## Build and start the Node service
8
+ ## What a self-hosted deployment needs
9
9
 
10
- Build the agent, then start the generated server:
10
+ Every self-hosted deployment needs:
11
11
 
12
- ```bash
13
- eve build
14
- PORT=3000 eve start --host 0.0.0.0
15
- ```
12
+ - A model credential and a production route policy; see [Configure model access and route auth](#configure-model-access-and-route-auth)
13
+ - Persistent storage for the Workflow world; see [Choose a Workflow world](#choose-a-workflow-world)
14
+ - A Node process serving the build; see [Build and start the server](#build-and-start-the-server)
15
+ - A reverse proxy that forwards both runtime route prefixes; see [Configure proxy routes](#configure-proxy-routes)
16
16
 
17
- The build writes the Nitro server under `.output/`. `eve start` serves that output and accepts either `PORT` or the `--port` flag.
18
-
19
- 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.
17
+ The sections below follow that order and end by verifying a real turn. Configure [additional features](#configure-additional-features) as your agent needs them.
20
18
 
21
19
  ## Configure model access and route auth
22
20
 
23
- 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.
24
-
25
- 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 [Authentication](../auth-and-route-protection).
21
+ Set `AI_GATEWAY_API_KEY` to use a string model ID through the Vercel AI Gateway. To call a provider directly, install its [AI SDK provider package](https://ai-sdk.dev/docs/foundations/providers-and-models), pass its model object in `agent.ts`, and set its API key. See [Agent configuration](../../agent-config#set-the-model) for examples.
26
22
 
27
- ## Persist workflow state
23
+ Outside Vercel, use an authenticator your host can validate as the production route policy, such as Basic auth, JSON Web Token (JWT) verification, generic OpenID Connect (OIDC), or a custom verifier, rather than `vercelOidc()` alone. See [Authentication](../auth-and-route-protection).
28
24
 
29
- 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.
25
+ ## Choose a Workflow world
30
26
 
31
- With the default local world, each `eve start` process accepts workflow queue deliveries only from its own queue. Keep deliveries on the process that enqueued them. Do not point `WORKFLOW_LOCAL_BASE_URL` at a load balancer that can forward deliveries to another replica; that replica rejects them with HTTP 401. Use a custom world designed for shared queue delivery when scaling across replicas.
27
+ For one process, use the default local world. It needs no configuration and stores session state under `.eve/.workflow-data`; mount that directory on persistent storage so sessions survive process and container replacement. For replicas or hosts without persistent disk, configure the [Postgres world](./workflow-worlds#use-the-postgres-world). To use your own world implementation, see [Use another world](./workflow-worlds#use-another-world).
32
28
 
33
- On startup, eve re-enqueues pending and running local workflow runs with a new per-process delivery proof. Local recovery always runs; `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS=0` or `false` does not disable it in `eve start`.
29
+ See [Workflow worlds](./workflow-worlds) to compare and configure the available worlds.
34
30
 
35
- You can instead select an installed Workflow world package in the root `agent.ts`:
31
+ ## Build and start the server
36
32
 
37
- ```typescript
38
- import { defineAgent } from "eve";
33
+ If your agent uses sandbox tools or file attachments, make Docker available during the build and at runtime, or [select a sandbox provider explicitly](#run-the-sandbox). For Dockerfile builds, see [Build inside a container image](#build-inside-a-container-image) below.
39
34
 
40
- export default defineAgent({
41
- model: "anthropic/claude-opus-5.5",
42
- experimental: {
43
- workflow: {
44
- world: "@acme/eve-workflow-world",
45
- },
46
- },
47
- });
35
+ ```bash
36
+ eve build
37
+ PORT=3000 eve start --host 0.0.0.0
48
38
  ```
49
39
 
50
- 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.
51
-
52
- See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the underlying Workflow software development kit (SDK) abstraction.
53
-
54
- ## Recover a stranded session
40
+ The build writes the eve server under `.output/`. `eve start` serves that output and accepts either `PORT` or the `--port` flag. To run the server from another directory, copy the app source, `.output/`, and installed dependencies together.
55
41
 
56
- A session is **stranded** when another eve version built the workflow run that owns it, so the current deployment cannot replay it. Its recorded history stays readable, but it cannot process new work. A new message to its channel address starts a replacement session whose `ctx.session.predecessor` names the stranded one.
42
+ The output is a standard [Nitro](https://nitro.build) Node server. If you adapt it to a host or preset instead of running `eve start`, see [Run schedules](./self-hosted-operations#run-schedules).
57
43
 
58
- See [Stranded sessions](../../concepts/execution-model-and-durability#stranded-sessions) for when a session is stranded in each world, how it ends, and how a replacement session can read the earlier conversation.
44
+ Run the process under the same process manager or container platform you use for other Node web services, and configure Transport Layer Security (TLS), restarts, and log collection there.
59
45
 
60
- ## Select a sandbox provider
46
+ ### Build inside a container image
61
47
 
62
- The default sandbox environment selects Docker when `eve build` can reach a Docker daemon and records that choice in the build. A production build never falls back to just-bash: when Docker is unreachable during the build, the build succeeds, but each session fails when it opens the sandbox. Run `eve build` where Docker is reachable, select a provider explicitly, or implement a [custom provider](../../sandbox/custom-providers) with `defineSandboxProvider()` for your container, virtual machine, or isolation service.
48
+ A `RUN eve build` step in a Dockerfile usually has no Docker daemon, so the build records no sandbox provider, even when the running container later mounts `/var/run/docker.sock`. Select `DockerSandbox.environment()` explicitly in that setup:
63
49
 
64
- A `RUN eve build` step in a Dockerfile usually has no Docker daemon, so the build records no provider even when the running container later mounts `/var/run/docker.sock`. In that setup, select `DockerSandbox.environment()` from `eve/sandbox/docker` explicitly in your sandbox module, or run `eve build` in an environment where Docker is reachable and copy the output into the image.
50
+ ```typescript title="agent/sandbox.ts"
51
+ import { defineSandbox } from "eve/sandbox";
52
+ import { DockerSandbox } from "eve/sandbox/docker";
65
53
 
66
- Don’t select `VercelSandbox.environment()` unless the self-hosted process should create hosted Vercel sandboxes. See [Sandbox](../../sandbox) for provider configuration and selection order.
54
+ export const environment = DockerSandbox.environment();
55
+ export default defineSandbox(() => environment.open());
56
+ ```
67
57
 
68
- Self-hosted deployments don’t support deployed self-modification. The [`eve/extensions/self-modification/remote`](../self-modification#propose-changes-from-a-deployed-agent) subagent requires deploying on Vercel, where Vercel Sandbox provides its runtime credential transforms. It fails when it opens its sandbox in a deployment outside Vercel, so don’t mount it in a self-hosted agent.
58
+ You can instead run `eve build` where Docker is reachable and copy the output into the image. See [Run the sandbox](#run-the-sandbox) for the other providers.
69
59
 
70
60
  ## Configure proxy routes
71
61
 
72
- Forward both runtime route prefixes through your reverse proxy or ingress:
62
+ Forward both runtime route prefixes through your reverse proxy or ingress without rewriting their paths:
73
63
 
74
64
  - `/eve/` serves health, sessions, streams, channels, tools, and subagents
75
65
  - `/.well-known/workflow/` receives workflow callbacks
76
66
 
77
- 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.
78
-
79
- ## Run workspace members
67
+ If the proxy forwards only `/eve/`, a session starts but the run stalls because its workflow callback can’t reach eve.
80
68
 
81
- An [agent workspace](../../concepts/project-structure#several-root-agents) does not require Vercel or a frontend at runtime. Build each member from its own directory: root `eve build` produces a Vercel workspace deployment, not a group of self-hosted Node servers.
69
+ ## Verify the service
82
70
 
83
- For a workspace containing `support` and `research`, run these from the workspace root, outside a Vercel build environment:
71
+ After your proxy and authentication are active, check the health route:
84
72
 
85
73
  ```bash
86
- (cd agents/support && npx eve build)
87
- (cd agents/research && npx eve build)
74
+ curl https://your_agent.example.com/eve/v1/health
88
75
  ```
89
76
 
90
- Start each built agent in a separate terminal, or configure these commands in your process manager:
77
+ Then connect the development TUI and complete a real turn:
91
78
 
92
79
  ```bash
93
- (cd agents/support && npx eve start --host 127.0.0.1 --port 3001)
94
- (cd agents/research && npx eve start --host 127.0.0.1 --port 3002)
80
+ eve remote connect --url https://your_agent.example.com
95
81
  ```
96
82
 
97
- For example, this Caddy configuration gives each agent its own origin and forwards both `/eve/` and `/.well-known/workflow/` without changing their paths. Point the example hostnames at your server and run Caddy on the same machine:
83
+ ## Configure additional features
98
84
 
99
- ```text
100
- support.example.com {
101
- reverse_proxy 127.0.0.1:3001
102
- }
85
+ | Feature | Configuration |
86
+ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
87
+ | Sandbox tools, file attachments, and skill supporting files | [Run the sandbox](#run-the-sandbox) with Docker or another provider |
88
+ | [Schedules](../../schedules) | Keep schedules enabled on [one `eve start` process](./self-hosted-operations#run-schedules) |
89
+ | Slack, Microsoft Teams, and other [channels](../../channels/overview) | Expose `/eve/` over public HTTPS through your [proxy](#configure-proxy-routes) |
90
+ | Connection sign-in and [remote agents](../remote-agents) | Set a [public callback origin](#set-the-public-callback-origin) |
91
+ | Agents in a workspace that call each other | Configure a [workspace-peer transport](../../subagents#vercel-workspace-peers) |
92
+ | Traces | Configure an [OpenTelemetry](../../observability/otel) destination |
103
93
 
104
- research.example.com {
105
- reverse_proxy 127.0.0.1:3002
106
- }
107
- ```
94
+ ## Run the sandbox
108
95
 
109
- Apply the authentication, persistent storage, and sandbox configuration above to each member. With the default local Workflow world, persist each member's own `.eve/.workflow-data` directory. If agents delegate to one another, configure an explicit [workspace-peer transport](../../subagents#vercel-workspace-peers) with the peer's URL and credentials; the default transport requires Vercel. Ensure callback URLs are reachable from the services that call them. Remote agent callbacks must reach a public address: outside `eve dev`, eve refuses callback hosts that are loopback, private, link-local, or reserved addresses, or that resolve to one. Callbacks between services over a private network or `127.0.0.1` don't work. See [How remote dispatch and callbacks work](../remote-agents#how-remote-dispatch-and-callbacks-work).
96
+ eve runs the sandbox in Docker when `eve build` can reach a Docker daemon, and records that choice in the build.
110
97
 
111
- ### Add a peer frontend
98
+ A session starts its sandbox when a tool, a file attachment, or a skill's supporting files need it, and early when a client [prewarms](../frontend/use-eve-agent#prewarming) the session. Sessions, approvals, subagents, schedules, and authored tools that don't call `ctx.getSandbox()` work without a sandbox. Without one, a file attachment reaches the model as a text note instead of a file.
112
99
 
113
- A frontend under `apps/web/` is another service managed by your host, not by `eve start`. Build and start it using its framework commands. A browser client can use `useEveAgent({ baseUrl: "https://support.example.com" })`; configure [CORS](../../channels/eve#cors) and browser credentials for that deployment. Alternatively, mount each agent on the frontend's origin through your reverse proxy.
100
+ To run sandboxes elsewhere, or when the build cannot reach Docker, select a provider in your sandbox module:
114
101
 
115
- For path-based mounts, strip the public prefix before forwarding requests to the agent and set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.
102
+ - `VercelSandbox.environment()` creates hosted [Vercel Sandbox](../../sandbox/vercel) sessions from any host. Outside Vercel and without a linked project, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`.
103
+ - `DockerSandbox.environment()` from `eve/sandbox/docker` selects [Docker](../../sandbox/docker) regardless of what the build can reach.
104
+ - `defineSandboxProvider()` connects a [custom provider](../../sandbox/custom-providers), such as your own container, virtual machine, or isolation service.
116
105
 
117
- You can instead use [`eve/next`](../frontend/nextjs#self-host) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager.
106
+ See [Sandbox](../../sandbox) for provider configuration and selection order.
118
107
 
119
- ## Run schedules
108
+ ## Set the public callback origin
120
109
 
121
- 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.
122
-
123
- Each `eve start` process runs every authored schedule. When you run several replicas, start one normally and start the others with `eve start --no-schedules`, or set `EVE_SCHEDULES_DISABLED=1` in their environment. See [`eve start`](../../reference/cli#eve-start).
124
-
125
- ## Verify the service
126
-
127
- Check the health route after your proxy and authentication configuration are active:
110
+ Connection sign-in links and the callback URLs a parent passes to [remote agents](../remote-agents) start from the server's own address, which is `http://localhost:<port>` outside Vercel. Set `WORKFLOW_LOCAL_BASE_URL` to the agent's public origin, such as `https://support.example.com`, when your agent uses either feature:
128
111
 
129
112
  ```bash
130
- curl https://your_agent.example.com/eve/v1/health
113
+ WORKFLOW_LOCAL_BASE_URL=https://support.example.com eve start --host 0.0.0.0
131
114
  ```
132
115
 
133
- Then connect the development TUI and complete a real turn:
116
+ With the local world, queued work is also delivered to that origin, so those deliveries pass through your proxy. Forward both [proxy route prefixes](#configure-proxy-routes), and keep a single process behind that origin; see [Use the local world](./workflow-worlds#use-the-local-world). The Postgres world delivers queued work inside each process, so its deliveries don't use this origin.
134
117
 
135
- ```bash
136
- eve remote connect --url https://your_agent.example.com
137
- ```
118
+ For an agent mounted under a path prefix, also set `EVE_PUBLIC_ROUTE_PREFIX`; see [Run workspace members](./self-hosted-operations#run-workspace-members).
138
119
 
139
120
  ## Continue configuring production
140
121
 
141
- Use these guides to secure and observe the deployed agent:
122
+ Use these guides to scale, secure, and observe the deployed agent:
142
123
 
124
+ - [Workflow worlds](./workflow-worlds): configure the local, Postgres, or another world
125
+ - [Operate a self-hosted agent](./self-hosted-operations): upgrade builds, run replicas and schedules, and troubleshoot
143
126
  - [Authentication](../auth-and-route-protection): configure the host’s route policy
144
127
  - [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
145
128
  - [Sandbox](../../sandbox): select and secure a sandbox provider
@@ -3,33 +3,33 @@ title: "Deploy to Vercel"
3
3
  description: "Deploy an eve agent with Vercel Workflow, Sandbox, Cron, and project credentials."
4
4
  ---
5
5
 
6
- 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.
6
+ On Vercel, eve builds to Vercel Build Output, and Vercel runs the agent’s web service, workflows, sandboxes, schedules, and observability.
7
7
 
8
8
  ## Prepare the Vercel project
9
9
 
10
- 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:
10
+ Link the project from its root, or from the workspace root for an eve agent workspace:
11
11
 
12
12
  ```bash
13
13
  eve link
14
14
  ```
15
15
 
16
- 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:
16
+ `eve link` links an existing project or creates one, then pulls its environment variables. For non-interactive use, name the project:
17
17
 
18
18
  ```bash
19
19
  eve link --project your_project_name --non-interactive
20
20
  ```
21
21
 
22
- 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.
22
+ Add `--team` when the account has access to more than one team.
23
23
 
24
24
  ## Configure credentials and auth
25
25
 
26
- 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.
26
+ A string model ID routes requests through the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway). The deployment authenticates to it through project OpenID Connect (OIDC), so it needs no provider API key.
27
27
 
28
- 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.
28
+ Add credentials for direct model providers, tools, and connections to the Vercel project environment. Also add any signing keys or passwords your [route authentication policy](../auth-and-route-protection) requires. Replace `placeholderAuth()` before a browser sends a production request.
29
29
 
30
30
  ## Select the sandbox environment
31
31
 
32
- The default environment selects Vercel Sandbox on Vercel. To select it explicitly:
32
+ On Vercel, the default sandbox environment selects Vercel Sandbox. To select it explicitly:
33
33
 
34
34
  ```typescript
35
35
  import { defineSandbox } from "eve/sandbox";
@@ -39,25 +39,25 @@ export const environment = VercelSandbox.environment();
39
39
  export default defineSandbox(() => environment.open());
40
40
  ```
41
41
 
42
- See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and lifecycle.
42
+ See [Sandbox](../../sandbox) for preparation, resource limits, network policy, and sandbox lifetime.
43
43
 
44
44
  <Callout type="info" title="Sandbox prewarming">
45
45
  During a Vercel build, eve creates or reuses a snapshot-backed template when an environment uses
46
46
  `VercelSandbox.environment({prepare})` or has seed files. A prewarm failure stops the deployment.
47
- See the [sandbox lifecycle](../../sandbox#lifecycle).
47
+ See [how long a sandbox lasts](../../sandbox#lifecycle).
48
48
  </Callout>
49
49
 
50
50
  ## Deploy the agent
51
51
 
52
- 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.
52
+ For a single-agent project without a frontend, use `eve build`. For an agent-only workspace, run it from the workspace root. Each member gets a separately built service and an `/eve/<name>/v1/*` transport route, and all members deploy together in one Vercel project. See [Project Structure](../../concepts/project-structure) for workspace layout rules.
53
53
 
54
- 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.
54
+ A Next.js-centered project uses [`withEve` in `next.config.ts`](../frontend/nextjs) and its Next.js build command. To author the project's service graph in `vercel.ts`, use the configuration below instead.
55
55
 
56
56
  ### Compose agents with other Vercel services
57
57
 
58
- 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.
58
+ `withEve` from `eve/vercel` adds eve agents to a Vercel service graph as peers of your other applications, with no frontend framework required. Unlike `eve/next`, it doesn't depend on a Next.js build. Both deploy the agent services together in one Vercel project.
59
59
 
60
- 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`:
60
+ 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 keeps an ordinary Next.js config without `eve/next`:
61
61
 
62
62
  ```typescript title="vercel.ts"
63
63
  import { withEve } from "eve/vercel";
@@ -79,15 +79,21 @@ export default await withEve({
79
79
  });
80
80
  ```
81
81
 
82
- 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.
82
+ `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 builds the frontend and each agent separately, so the frontend needs neither `withEve` in its framework configuration nor a script that builds the agents.
83
83
 
84
- 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](./self-hosting#run-workspace-members).
84
+ 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](./self-hosted-operations#run-workspace-members).
85
85
 
86
- 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. Import the experimental helper from `eve/experimental/workspace`; see [Vercel workspace peers](../../subagents#vercel-workspace-peers). The workspace layout and `eve/vercel` integration are not experimental.
86
+ Run `vercel dev --local` with Vercel CLI 59.16.0 or newer to start the whole service graph locally without linking a project. A linked directory also loads its development environment and settings. A generated Vercel Web Chat project exposes the scripts below. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials. Import that helper from `eve/experimental/workspace`; see [Vercel workspace peers](../../subagents#vercel-workspace-peers). The workspace layout and `eve/vercel` integration are not experimental.
87
87
 
88
- 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`.
88
+ | Script | Starts |
89
+ | ---------------------------- | ------------------------------------------------- |
90
+ | `pnpm dev:all` | The whole service graph, via `vercel dev --local` |
91
+ | `pnpm dev` or `pnpm dev:eve` | One agent and the eve terminal UI |
92
+ | `pnpm dev:web` | The frontend without its agent services |
89
93
 
90
- Custom agent channel endpoints are not published automatically. Expose one explicitly by routing it to the generated service:
94
+ Generated transport routes go before a filesystem handler, or before authored routes when there is none. `withEve` throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove that route, and remove or rename that service, because `withEve` adds both. Names in the array form of `services` must be unique. Other services, routes, bindings, and Cron Jobs stay authored in `vercel.ts`.
95
+
96
+ Custom agent channel endpoints aren’t published automatically. Route each one to the generated service:
91
97
 
92
98
  ```typescript title="vercel.ts"
93
99
  import { withEve } from "eve/vercel";
@@ -109,9 +115,9 @@ export default await withEve({
109
115
  });
110
116
  ```
111
117
 
112
- 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.
118
+ A Vercel project uses 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`. `withEve` discovers the workspace containing its evaluation directory; pass `{ root: "/absolute/workspace/path" }` as the second argument to select a different workspace root.
113
119
 
114
- 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/*`.
120
+ Callbacks follow the mount: a root agent at `/eve/v1` receives them at `/eve/v1/callback/*`, and a named mount such as `/eve/support` at `/eve/support/v1/callback/*`.
115
121
 
116
122
  ### Deploy the project
117
123
 
@@ -121,9 +127,9 @@ Deploy the linked project to production from its root:
121
127
  eve deploy
122
128
  ```
123
129
 
124
- `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`.
130
+ `eve deploy` installs dependencies, runs `vercel deploy --prod --logs`, and pulls the project environment afterward. 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`.
125
131
 
126
- When `eve deploy` creates a new Vercel project, it configures trace sampling so traces appear in Agent Runs automatically. See [Agent Runs](../../observability/agent-runs) for details. Pass `--no-trace-sampling` to skip this setting.
132
+ When `eve deploy` creates a new Vercel project, it configures trace sampling so traces appear in [Agent Runs](../../observability/agent-runs). Pass `--no-trace-sampling` to skip this.
127
133
 
128
134
  For non-interactive use, confirm the production deploy up front. `--project` links first, so a new project needs no separate `eve link`:
129
135
 
@@ -131,10 +137,10 @@ For non-interactive use, confirm the production deploy up front. `--project` lin
131
137
  eve deploy --project your_project_name --non-interactive --yes
132
138
  ```
133
139
 
134
- Vercel uses the generated output to configure these services:
140
+ Vercel configures these services from the build output:
135
141
 
136
142
  - **Web runtime**: serves health, session, stream, channel, callback, and schedule routes
137
- - **Vercel Workflow**: persists and resumes durable runs, with optimistic replay preconditions enabled so stale event-log snapshots reload before they can commit
143
+ - **Vercel Workflow**: stores and resumes agent runs
138
144
  - **Vercel Cron**: invokes authored schedules
139
145
  - **Vercel Sandbox**: runs sandbox sessions selected by the default sandbox environment
140
146
 
@@ -147,7 +153,7 @@ curl https://your_agent.vercel.app/eve/v1/health
147
153
  eve remote connect --url https://your_agent.vercel.app
148
154
  ```
149
155
 
150
- For a workspace agent, include its public `/eve/<name>` mount. For example:
156
+ For a workspace agent, include its `/eve/<name>` mount:
151
157
 
152
158
  ```bash
153
159
  curl https://your_agent.vercel.app/eve/support/v1/health
@@ -164,8 +170,6 @@ for beta access, pricing, retention, and tracing setup.
164
170
 
165
171
  ## Continue configuring production
166
172
 
167
- Use these guides to secure and observe the deployed agent:
168
-
169
173
  - [Authentication](../auth-and-route-protection): configure who can call the deployed agent
170
174
  - [Instrumentation](../../observability/instrumentation): export traces and diagnose runtime failures
171
175
  - [Sandbox](../../sandbox): configure resources, isolation, and network access
@@ -0,0 +1,100 @@
1
+ ---
2
+ title: "Workflow Worlds"
3
+ description: "Choose and configure the Workflow world that stores and resumes eve sessions on a self-hosted deployment."
4
+ ---
5
+
6
+ A Workflow world is the backend that stores eve sessions so they survive restarts and redeploys. eve runs every session as a [Workflow SDK](https://workflow-sdk.dev/) workflow. The world stores each run's event log, step results, pending input, and streams, and queues the work that resumes it. eve uses Vercel Workflow on Vercel and the local world for `eve start`. A self-hosted deployment can select another world package without changing the agent.
7
+
8
+ ## Compare worlds
9
+
10
+ | World | Storage | Processes | After an eve version upgrade |
11
+ | ----------------------------------- | --------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------- |
12
+ | [Local](#use-the-local-world) | Files under `.eve/.workflow-data` | One | Existing sessions cannot resume |
13
+ | [Postgres](#use-the-postgres-world) | A PostgreSQL database | Any number of replicas | Existing sessions cannot resume |
14
+ | [Vercel Workflow](./vercel) | Managed by Vercel | Managed by Vercel | Runs continue on their original deployments; eligible idle sessions can move to the new deployment |
15
+
16
+ On the local and Postgres worlds, a new build on the same eve version resumes existing sessions. See [Upgrade a self-hosted agent](./self-hosted-operations#upgrade-a-self-hosted-agent) for what happens when the eve version changes.
17
+
18
+ All three support compaction handoff, which moves a session to a fresh run while keeping its ID, event stream, and addresses; the Postgres world needs `@workflow/world-postgres` 5.0.4 or later. Vercel Workflow also supports moving eligible idle sessions between deployments. See [Execution model and durability](../../concepts/execution-model-and-durability#compaction-handoff).
19
+
20
+ ## Use the local world
21
+
22
+ The local world is the default for `eve start` and needs no configuration. It stores run state under `.eve/.workflow-data` in the app directory. Mount that directory on persistent storage so runs survive process and container replacement.
23
+
24
+ Each `eve start` process accepts queue messages only from its own queue. Don't point `WORKFLOW_LOCAL_BASE_URL` at a load balancer, because another replica rejects forwarded messages with HTTP 401. To serve an agent from several replicas, use the [Postgres world](#use-the-postgres-world).
25
+
26
+ On startup, `eve start` queues pending and running local workflow runs again. Runs that were active when the previous process stopped continue when the eve version is unchanged. `WORKFLOW_LOCAL_RECOVER_ACTIVE_RUNS=0` or `false` doesn't disable this recovery.
27
+
28
+ ## Use the Postgres world
29
+
30
+ The [`@workflow/world-postgres`](https://www.npmjs.com/package/@workflow/world-postgres) package stores runs in PostgreSQL and queues their work with Graphile Worker. Every `eve start` process connected to the same database processes queued work, so you can run several replicas behind a load balancer.
31
+
32
+ 1. Install the package in your app:
33
+
34
+ ```bash
35
+ pnpm add @workflow/world-postgres
36
+ ```
37
+
38
+ 2. Select it in the root `agent.ts`:
39
+
40
+ ```typescript title="agent/agent.ts"
41
+ import { defineAgent } from "eve";
42
+
43
+ export default defineAgent({
44
+ model: "anthropic/claude-opus-5.5",
45
+ experimental: {
46
+ workflow: {
47
+ world: "@workflow/world-postgres",
48
+ },
49
+ },
50
+ });
51
+ ```
52
+
53
+ 3. Set the connection string in the runtime environment with `WORKFLOW_POSTGRES_URL`. The package also reads `DATABASE_URL`. When neither is set, it connects to `postgres://world:world@localhost:5432/world`.
54
+
55
+ 4. Create the schema before the first start:
56
+
57
+ ```bash
58
+ pnpm exec bootstrap
59
+ ```
60
+
61
+ With npm, run `npx --package @workflow/world-postgres bootstrap`. The command reads the same connection variables. Run it again before you start a build that upgrades `@workflow/world-postgres`, so the database has the new version's migrations.
62
+
63
+ 5. Build and start the server as usual with `eve build` and `eve start`.
64
+
65
+ ### Tune the Postgres world
66
+
67
+ The package reads these optional variables:
68
+
69
+ | Variable | Default | Description |
70
+ | -------------------------------------- | ------- | ------------------------------------------------ |
71
+ | `WORKFLOW_POSTGRES_WORKER_CONCURRENCY` | `50` | Queued jobs each process runs at once |
72
+ | `WORKFLOW_POSTGRES_MAX_POOL_SIZE` | `10` | Connections in each process's database pool |
73
+ | `WORKFLOW_POSTGRES_POLL_INTERVAL_MS` | `500` | Milliseconds between idle job fetches per worker |
74
+
75
+ Graphile Worker recommends a pool size of at least the worker concurrency plus 2. With the default concurrency, set `WORKFLOW_POSTGRES_MAX_POOL_SIZE=52`, and size the database's connection limit for every replica's pool. See the [package README](https://www.npmjs.com/package/@workflow/world-postgres) for the full list.
76
+
77
+ The Postgres world stores workflow inputs, outputs, and stream contents in the database without encryption, and it keeps the records of finished runs until you delete them. Protect database access and backups, and see [Manage run data](./self-hosted-operations#manage-run-data) for retention.
78
+
79
+ ## Use another world
80
+
81
+ Select any installed Workflow world package in the root `agent.ts`:
82
+
83
+ ```typescript title="agent/agent.ts"
84
+ import { defineAgent } from "eve";
85
+
86
+ export default defineAgent({
87
+ model: "anthropic/claude-opus-5.5",
88
+ experimental: {
89
+ workflow: {
90
+ world: "@acme/eve-workflow-world",
91
+ },
92
+ },
93
+ });
94
+ ```
95
+
96
+ The package must export a default factory or `createWorld()` function. It reads credentials and host options from runtime environment variables, not `agent.ts`. If the package must stay external in hosted output, list it in `build.externalDependencies`.
97
+
98
+ Install a world built against the same `@workflow/*` major version as your eve release, currently `5.x`. eve checks the world's `@workflow/core` or `@workflow/world` dependency at startup, and fails with the version to install when the major versions differ.
99
+
100
+ See [Workflow Worlds](https://workflow-sdk.dev/worlds) for the Workflow SDK abstraction, and [agent.ts](../../agent-config#workflow-world) for the configuration field.