eve 0.90.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 (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,7 +3,13 @@ title: "Sandbox Troubleshooting"
3
3
  description: "Causes and fixes for common eve sandbox errors in the sandbox file, after a build, when a session resumes, and during eve dev."
4
4
  ---
5
5
 
6
- Sections whose heading is in code format start with the beginning of an error message, so you can search this page for the text you see. Most sandbox errors come from one of three mismatches: the sandbox file does not match what eve expects, the build output does not match the runtime, or a session's recorded sandbox does not match the current agent.
6
+ Most sandbox errors come from one of three mismatches:
7
+
8
+ - The sandbox file doesn't match what eve expects.
9
+ - The build output doesn't match the runtime.
10
+ - A session's recorded sandbox doesn't match the current agent.
11
+
12
+ Headings in code format start with the error text, so search this page for the message you see.
7
13
 
8
14
  ## Errors in the sandbox file
9
15
 
@@ -13,7 +19,7 @@ Sections whose heading is in code format start with the beginning of an error me
13
19
  Sandbox "sandbox.ts" must export an environment.
14
20
  ```
15
21
 
16
- eve compiles the sandbox file during `eve build` and `eve dev`, and it needs the environment as a named `environment` export so it can prepare it before any session exists. Export the environment that the selector opens:
22
+ eve needs a named `environment` export so `eve build` and `eve dev` can prepare it before any session exists. Export the environment that the selector opens:
17
23
 
18
24
  ```ts title="agent/sandbox.ts"
19
25
  import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -28,7 +34,7 @@ export default defineSandbox(() => environment.open());
28
34
  Sandbox "sandbox.ts" opened an environment other than the one it exports as `environment`.
29
35
  ```
30
36
 
31
- The selector called `open()` on a different environment object than the exported `environment`. This happens when the selector creates an environment inline, such as `DefaultSandbox.environment().open()`, or imports another sandbox file's environment. Create the environment once at module scope, export it, and call `environment.open()` on that export.
37
+ The selector called `open()` on an environment object other than the exported `environment`. For example, it created one inline with `DefaultSandbox.environment().open()` or imported one from another sandbox file. Create the environment once at the top level of the module, export it, and call `environment.open()` on that export.
32
38
 
33
39
  ### `can open only one sandbox`
34
40
 
@@ -36,7 +42,7 @@ The selector called `open()` on a different environment object than the exported
36
42
  A sandbox definition can open only one sandbox.
37
43
  ```
38
44
 
39
- The selector called `environment.open()` more than once. Call `environment.open()` once in the `defineSandbox()` selector and return that sandbox.
45
+ The selector called `environment.open()` more than once. Call it once and return that sandbox.
40
46
 
41
47
  ### `can only open sandboxes inside defineSandbox()`
42
48
 
@@ -44,7 +50,7 @@ The selector called `environment.open()` more than once. Call `environment.open(
44
50
  Sandbox environments can only open sandboxes inside defineSandbox().
45
51
  ```
46
52
 
47
- Code outside the `defineSandbox()` selector called `environment.open()`, for example a tool or a module's top level. Only the selector opens the sandbox. From tools and other runtime code, use `ctx.getSandbox()` to reach the session's sandbox, or `ctx.getSandbox(environment)` to keep the provider-specific session type.
53
+ Code outside the `defineSandbox()` selector, such as a tool or a module's top level, called `environment.open()`. From tools and other runtime code, use `ctx.getSandbox()`, or `ctx.getSandbox(environment)` to also get the provider-specific methods.
48
54
 
49
55
  ### `selects parent.sandbox but agent node ... has no parent`
50
56
 
@@ -52,11 +58,11 @@ Code outside the `defineSandbox()` selector called `environment.open()`, for exa
52
58
  Sandbox "sandbox.ts" selects parent.sandbox but agent node "..." has no parent.
53
59
  ```
54
60
 
55
- The sandbox file uses `defineParentSandbox()`, but the agent is not a declared subagent, so it has no parent sandbox to share. eve reports this when it loads the agent graph. Only a declared subagent can [share its parent's sandbox](/docs/sandbox#share-a-parent-sandbox). Give this agent its own sandbox file with `defineSandbox()` and an exported environment.
61
+ The sandbox file uses `defineParentSandbox()`, but the agent isn't a declared subagent. Only a declared subagent can [share its parent's sandbox](/docs/sandbox#share-a-parent-sandbox). Give this agent its own sandbox file with `defineSandbox()` and an exported environment.
56
62
 
57
63
  ## Errors after a build or deploy
58
64
 
59
- Production never prepares sandbox environments. `eve build` prepares them and records one artifact for each agent sandbox, such as a Docker image, a Vercel snapshot, or a just-bash template, and the runtime only uses those recorded artifacts.
65
+ Production never prepares sandbox environments. `eve build` records one artifact for each agent sandbox, such as a Docker image, a Vercel snapshot, or a just-bash template. The runtime uses only those.
60
66
 
61
67
  ### `No prepared ... sandbox environment is recorded`
62
68
 
@@ -64,7 +70,7 @@ Production never prepares sandbox environments. `eve build` prepares them and re
64
70
  No prepared "docker" sandbox environment is recorded for agent node "...".
65
71
  ```
66
72
 
67
- The deployed build output has no prepared artifact for this agent. This usually means the output came from `eve build --skip-sandbox-prewarm`, which [the CLI reference](/docs/reference/cli) marks as not deployable. Run `eve build` without that flag and deploy its output together with the runtime.
73
+ The deployed build output has no prepared artifact for this agent. Usually the output came from `eve build --skip-sandbox-prewarm`, which [the CLI reference](/docs/reference/cli) marks as not deployable. Run `eve build` without that flag and deploy its output.
68
74
 
69
75
  ### `The prepared sandbox artifact ... was created with provider`
70
76
 
@@ -72,7 +78,7 @@ The deployed build output has no prepared artifact for this agent. This usually
72
78
  The prepared sandbox artifact for agent node "..." was created with provider "vercel", but this process selects provider "docker".
73
79
  ```
74
80
 
75
- The sandbox file selected one provider when eve prepared the sandbox and a different one in the process that uses it. This happens when the sandbox file chooses a provider by reading the host, for example with `process.env.VERCEL ? VercelSandbox.environment() : DockerSandbox.environment()`, and the build and runtime hosts differ. `DefaultSandbox.environment()` does not cause this, because it [records its choice when it prepares the sandbox](/docs/sandbox/default#the-build-records-the-choice). Select one provider explicitly, or use `DefaultSandbox.environment()`, then rebuild with `eve build`, or restart `eve dev` locally.
81
+ The sandbox file selected different providers at build time and at runtime, because it checks the host and the hosts differ. For example, it uses `process.env.VERCEL ? VercelSandbox.environment() : DockerSandbox.environment()`. Select one provider explicitly, or use `DefaultSandbox.environment()`, which [records its choice at build time](/docs/sandbox/default#the-build-records-the-choice). Then rebuild with `eve build`, or restart `eve dev` locally.
76
82
 
77
83
  ### `DefaultSandbox has no sandbox provider for this build`
78
84
 
@@ -80,7 +86,7 @@ The sandbox file selected one provider when eve prepared the sandbox and a diffe
80
86
  DefaultSandbox has no sandbox provider for this build: it did not run on Vercel, no Docker daemon was reachable, and production builds do not fall back to just-bash.
81
87
  ```
82
88
 
83
- The production `eve build` ran outside Vercel without a reachable Docker daemon, so `DefaultSandbox` recorded no provider, and the first session that opens the sandbox fails. A `RUN eve build` step in a Dockerfile usually has no Docker daemon, even when the running container later mounts `/var/run/docker.sock`. Start Docker and run `eve build` again, deploy to Vercel, or select a provider explicitly in the sandbox file, for example `DockerSandbox.environment()` from `eve/sandbox/docker`. See [How eve selects the provider](/docs/sandbox/default#how-eve-selects-the-provider).
89
+ The production `eve build` ran outside Vercel without a reachable Docker daemon, so `DefaultSandbox` recorded no provider. A `RUN eve build` step in a Dockerfile usually has no Docker daemon, even when the running container later mounts `/var/run/docker.sock`. Start Docker and run `eve build` again, deploy to Vercel, or select a provider explicitly, for example `DockerSandbox.environment()` from `eve/sandbox/docker`. See [How eve selects the provider](/docs/sandbox/default#how-eve-selects-the-provider).
84
90
 
85
91
  ### `Sandbox template ... is not available to this runtime`
86
92
 
@@ -88,7 +94,7 @@ The production `eve build` ran outside Vercel without a reachable Docker daemon,
88
94
  Sandbox template "..." for provider "docker" is not available to this runtime.
89
95
  ```
90
96
 
91
- The build recorded an artifact, but the provider can no longer use its template. When the provider knows the cause, the message includes it:
97
+ The build recorded an artifact, but the provider can't find its template. When the provider knows the cause, the message includes it:
92
98
 
93
99
  | Provider | Common cause |
94
100
  | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -105,11 +111,11 @@ The runtime never recreates a template. Run `eve build` again and deploy its out
105
111
  Invalid prepared Docker sandbox artifact.
106
112
  ```
107
113
 
108
- The recorded artifact does not match the format that this eve version expects, usually because the build used a different eve version than the runtime. Run `eve build` with the same eve version that the runtime uses, then redeploy.
114
+ The recorded artifact doesn't match the format this eve version expects. Usually the build used a different eve version than the runtime. Rebuild with the runtime's eve version, then redeploy.
109
115
 
110
116
  ## Errors when a session resumes
111
117
 
112
- A session records which provider created its sandbox, and later turns resume that sandbox directly without running the selector again.
118
+ A session records which provider created its sandbox, and later turns resume it without running the selector.
113
119
 
114
120
  ### `This session's sandbox was created by provider`
115
121
 
@@ -117,7 +123,7 @@ A session records which provider created its sandbox, and later turns resume tha
117
123
  This session's sandbox was created by provider "just-bash", but the agent now selects provider "docker".
118
124
  ```
119
125
 
120
- eve logs this warning when a session resumes on a build whose sandbox file selects a different provider than the one that created the session's sandbox, for example after you change providers or `DefaultSandbox` records a different choice in a new build. eve cannot move a sandbox between providers, so the session continues in a fresh sandbox from the current provider, without the old sandbox's files. eve does not delete the old sandbox. Remove it with the old provider's tooling, for example `docker rm` for a Docker container. To keep the session's files instead, restore the previous provider before the session resumes.
126
+ eve logs this warning when a session continues on a build whose provider didn't create its sandbox. This happens after you change providers, or when `DefaultSandbox` selects differently in a new build. The session continues in a fresh sandbox from the current provider, without the old sandbox's files. eve doesn't delete the old sandbox; remove it with the old provider's tooling, such as `docker rm`. To keep the session's files, restore the previous provider before the session resumes.
121
127
 
122
128
  ### `DefaultSandbox selected just-bash, which always allows network access`
123
129
 
@@ -125,7 +131,7 @@ eve logs this warning when a session resumes on a build whose sandbox file selec
125
131
  DefaultSandbox selected just-bash, which always allows network access and accepts only the "allow-all" network policy.
126
132
  ```
127
133
 
128
- The sandbox passed a `networkPolicy` other than `"allow-all"` to `open()`, or called `setNetworkPolicy()`, while `DefaultSandbox` uses just-bash during `eve dev` or `eve eval` because Docker is not reachable. just-bash cannot restrict network access. Start Docker and restart `eve dev` so `DefaultSandbox` selects Docker, or select `VercelSandbox.environment()` or `DockerSandbox.environment()` explicitly.
134
+ The sandbox set a network policy other than `"allow-all"` through `open()` or `setNetworkPolicy()`. `DefaultSandbox` had selected just-bash, because Docker wasn't reachable during `eve dev` or `eve eval`. Start Docker and restart `eve dev` so `DefaultSandbox` selects Docker, or select `VercelSandbox.environment()` or `DockerSandbox.environment()` explicitly.
129
135
 
130
136
  ### `Invalid ... session state`
131
137
 
@@ -133,7 +139,7 @@ The sandbox passed a `networkPolicy` other than `"allow-all"` to `open()`, or ca
133
139
  Invalid Docker sandbox session state.
134
140
  ```
135
141
 
136
- The session's recorded sandbox state does not match the format that this eve version expects, usually because the session started under a different eve version. Start a new session to get a fresh sandbox.
142
+ The session's saved sandbox state doesn't match the format this eve version expects. Usually the session started under a different eve version. Start a new session to get a fresh sandbox.
137
143
 
138
144
  ## Errors during eve dev
139
145
 
@@ -145,7 +151,7 @@ During `eve dev`, the first sandbox access prepares every sandbox environment in
145
151
  Timed out after 10 minutes waiting for another request or eve dev worker to prepare sandbox environments (this request needs provider "docker").
146
152
  ```
147
153
 
148
- Another request or `eve dev` worker is still preparing environments. Check the `eve dev` output, or run `eve logs`, to find the slow step, such as an image pull, a Dockerfile build, or a `prepare` callback. Retry after preparation finishes, or restart `eve dev` to cancel it.
154
+ Another request or `eve dev` worker is still preparing environments. Find the slow step, such as an image pull, a Dockerfile build, or a `prepare` callback, in the `eve dev` output or `eve logs`. Retry after preparation finishes, or restart `eve dev` to cancel it.
149
155
 
150
156
  ## Custom provider errors
151
157
 
@@ -157,7 +163,7 @@ These errors come from a provider defined with `defineSandboxProvider()`, or fro
157
163
  Sandbox provider "acme" cannot keep a sandbox between invokeTool calls, so a call with a key cannot open one.
158
164
  ```
159
165
 
160
- A keyed `invokeTool` call, such as an MCP tool session, requested the sandbox, and the provider does not keep sandboxes between calls. Call the tool without a key, use Vercel Sandbox or just-bash, or set `toolSessions: true` on a custom provider that bounds how long it keeps those sandboxes. Docker does not support keyed calls. See [Keep sandboxes for keyed tool calls](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls).
166
+ A keyed `invokeTool` call, such as an MCP tool session, requested the sandbox from a provider that doesn't keep sandboxes between calls. Docker is one such provider. Call the tool without a key, or use Vercel Sandbox or just-bash. On a custom provider, set `toolSessions: true` and limit how long the provider keeps those sandboxes. See [Keep sandboxes for keyed tool calls](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls).
161
167
 
162
168
  ### `Sandbox connection extensions cannot replace the session members eve provides`
163
169
 
@@ -165,7 +171,7 @@ A keyed `invokeTool` call, such as an MCP tool session, requested the sandbox, a
165
171
  Sandbox connection extensions cannot replace the session members eve provides: run. Rename them.
166
172
  ```
167
173
 
168
- The connection's `extensions` define a member that eve already provides on every sandbox session, such as `run`, `readFile`, `stop`, or `delete`. Rename the extension member.
174
+ The connection's `extensions` define a member eve already provides, such as `run`, `readFile`, `stop`, or `delete`. Rename the extension member.
169
175
 
170
176
  ### `ctx.templateKey() reserves`
171
177
 
@@ -173,7 +179,7 @@ The connection's `extensions` define a member that eve already provides on every
173
179
  ctx.templateKey() reserves "sourceRevision": eve adds the workspace and skill files and the sandbox source revision itself.
174
180
  ```
175
181
 
176
- The identity passed to `ctx.templateKey()` in `prepare()` sets `resources` or `sourceRevision`. eve adds both to every template key. Rename that identity field.
182
+ The identity passed to `ctx.templateKey()` sets `resources` or `sourceRevision`. eve adds both to every template key itself. Rename that field.
177
183
 
178
184
  ### `returned non-serializable session state`
179
185
 
@@ -200,7 +206,7 @@ Install and start Docker Desktop, OrbStack, Colima, or another runtime with a Do
200
206
  The just-bash sandbox provider requires the `just-bash` package, which is not bundled with eve.
201
207
  ```
202
208
 
203
- `eve dev` installs `just-bash` automatically unless the environment sets `autoInstall: false`. Other commands require you to install it. Add it to your application, for example with `pnpm add -D just-bash`, which matches what `eve dev` installs. See [just-bash Sandbox](/docs/sandbox/just-bash#automatic-installation).
209
+ `eve dev` installs `just-bash` automatically unless the environment sets `autoInstall: false`. For other commands, add it to your application, for example with `pnpm add -D just-bash`, which matches what `eve dev` installs. See [just-bash Sandbox](/docs/sandbox/just-bash#automatic-installation).
204
210
 
205
211
  ### `Cannot build deployable Vercel output because this app requires sandbox templates`
206
212
 
@@ -208,8 +214,8 @@ The just-bash sandbox provider requires the `just-bash` package, which is not bu
208
214
  Cannot build deployable Vercel output because this app requires sandbox templates and VERCEL_OIDC_TOKEN is missing.
209
215
  ```
210
216
 
211
- eve raises this during a Vercel build, when `VERCEL` is set, if the app needs sandbox templates prepared and `VERCEL_OIDC_TOKEN` is missing. Do not deploy the `.vercel/output` from a build that failed this way. For a local `vercel build`, run `vercel link` and `vercel pull`, then retry. In a build on Vercel, Vercel sets `VERCEL_OIDC_TOKEN` automatically; see [Vercel OIDC federation](https://vercel.com/docs/oidc).
217
+ A build with `VERCEL` set needs `VERCEL_OIDC_TOKEN` to prepare sandbox templates. Don't deploy the `.vercel/output` from a build that failed this way. For a local `vercel build`, run `vercel link` and `vercel pull`, then retry. Builds on Vercel set `VERCEL_OIDC_TOKEN` automatically; see [Vercel OIDC federation](https://vercel.com/docs/oidc).
212
218
 
213
219
  ### Vercel Sandbox authentication fails
214
220
 
215
- When `eve build` or the runtime cannot create a Vercel Sandbox because of missing or expired credentials, the Vercel Sandbox SDK reports an authentication or OIDC token error. Locally, run `eve link` to link a project and pull `VERCEL_OIDC_TOKEN` into `.env.local`. Outside Vercel without a linked project, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. See [Vercel Sandbox authentication](/docs/sandbox/vercel#authentication) for the full resolution order.
221
+ With missing or expired credentials, the Vercel Sandbox SDK reports an authentication or OIDC token error during `eve build` or at runtime. Locally, run `eve link` to link a project and pull `VERCEL_OIDC_TOKEN` into `.env.local`. Outside Vercel without a linked project, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. See [Vercel Sandbox authentication](/docs/sandbox/vercel#authentication) for the full resolution order.
@@ -3,19 +3,21 @@ title: "Vercel Sandbox"
3
3
  description: "Create persistent sandboxes on Vercel, from a prepared snapshot when the environment has build-time setup."
4
4
  ---
5
5
 
6
- `VercelSandbox.environment()` prepares a reusable Vercel Sandbox snapshot when the environment has build-time setup, and creates persistent session sandboxes from its recorded snapshot ID.
6
+ `VercelSandbox.environment()` runs each eve session in its own Vercel Sandbox, which keeps its files between turns. When the environment has build-time setup, eve prepares a reusable snapshot and starts session sandboxes from it.
7
7
 
8
- ```ts
8
+ ```ts title="agent/sandbox.ts"
9
9
  import { defineSandbox } from "eve/sandbox";
10
10
  import { VercelSandbox } from "eve/sandbox/vercel";
11
11
 
12
12
  export const environment = VercelSandbox.environment({
13
+ // optional: setup captured in the snapshot that every session starts from
13
14
  prepare: async (sandbox) => {
14
15
  await sandbox.run({ command: "npm ci" });
15
16
  },
16
17
  });
17
18
 
18
19
  export default defineSandbox(() =>
20
+ // optional: live sandbox options, applied when eve creates the sandbox
19
21
  environment.open({
20
22
  networkPolicy: {
21
23
  allow: {
@@ -29,9 +31,7 @@ export default defineSandbox(() =>
29
31
 
30
32
  ## Authentication
31
33
 
32
- eve needs a Vercel token, team ID, and project ID to create Vercel Sandboxes. `eve build` needs them to capture the snapshot, and the runtime needs them to create and resume session sandboxes. Deployments on Vercel provide them automatically.
33
-
34
- eve resolves each value from the first source that is set:
34
+ eve needs a Vercel token, team ID, and project ID. `eve build` uses them to capture the snapshot, and the runtime uses them to create and resume session sandboxes. Deployments on Vercel provide them automatically. eve resolves each value from the first source that is set:
35
35
 
36
36
  | Value | Sources, in order |
37
37
  | ---------- | --------------------------------------------------------------- |
@@ -39,7 +39,7 @@ eve resolves each value from the first source that is set:
39
39
  | Team ID | `teamId` environment option, `VERCEL_TEAM_ID`, `VERCEL_ORG_ID` |
40
40
  | Project ID | `projectId` environment option, `VERCEL_PROJECT_ID` |
41
41
 
42
- When all three resolve, eve uses them. Otherwise, eve requests a Vercel OIDC token and reads the team and project from the token. On Vercel, the deployment provides that token. Elsewhere, eve reads `VERCEL_OIDC_TOKEN` and, when it is missing or expired, refreshes it with your Vercel CLI login and the project linked in `.vercel/project.json`. If that also fails, eve falls back to the Vercel Sandbox SDK's own credential lookup, which reports an authentication error if it finds none.
42
+ When any of the three is unset, eve uses a Vercel OIDC token and reads the team and project from it. Outside a Vercel deployment, eve reads `VERCEL_OIDC_TOKEN`. It refreshes a missing or expired token with your Vercel CLI login and the project linked in `.vercel/project.json`. If that fails, the Vercel Sandbox SDK's own credential lookup runs, and it reports an authentication error when it finds none.
43
43
 
44
44
  For local development, link the app to a Vercel project and pull its environment into `.env.local`:
45
45
 
@@ -49,21 +49,27 @@ eve link
49
49
 
50
50
  `vercel link` followed by `vercel env pull` produces the same `.env.local`. A running `eve dev` reloads env files automatically.
51
51
 
52
- Outside Vercel and without a linked project, such as in CI or on a self-hosted server, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`, or pass `token`, `teamId`, and `projectId` to `VercelSandbox.environment()`.
52
+ Outside Vercel and without a linked project, such as in CI or on a self-hosted server, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. You can also pass `token`, `teamId`, and `projectId` to `VercelSandbox.environment()`.
53
53
 
54
- ## Snapshot preparation
54
+ ## Live sandbox options
55
55
 
56
- eve creates a temporary, non-persistent Vercel Sandbox during build, installs the base runtime, writes managed workspace and skill files, and runs the authored `prepare` callback. It then checks the base runtime again before capturing the snapshot, so a `prepare` callback that breaks it fails the build. The build artifact records the snapshot ID.
56
+ `open()` accepts Vercel compute resources, timeout, environment variables, network policy, and Drive mounts. They apply only when eve creates the sandbox. Reopening the sandbox or resuming it keeps the original environment variables, mounts, and network policy. Pass `env` to `run()` or `spawn()` to override a variable for one command, or call `setNetworkPolicy()` to change the live policy.
57
+
58
+ Set `image`, `source`, `tags`, project credentials, and `fetch` on the environment, because `open()` doesn't accept them. eve sets the sandbox's name and persistence itself.
59
+
60
+ If initialization fails, eve keeps the sandbox and runs the selector against it again on the next access. If the named Vercel Sandbox later disappears, eve runs the selector again to start a fresh sandbox.
61
+
62
+ ## Snapshot preparation
57
63
 
58
- When a live session sandbox does not exist, eve creates it directly from that snapshot ID. Runtime does not need to look up the temporary template Sandbox.
64
+ During build, eve installs its base runtime in a temporary Vercel Sandbox, writes managed workspace and skill files, and runs the authored `prepare` callback. A `prepare` callback that breaks the base runtime fails the build. eve creates each new session sandbox from the captured snapshot.
59
65
 
60
- When the environment has no `prepare` callback, no managed workspace or skill files, and no `source`, a snapshot would contain only the base runtime. eve skips it: the build records no snapshot ID, and each new session sandbox starts from the image and installs the base runtime itself. A `source` always produces a snapshot, so sessions start from what the build captured instead of fetching the source again.
66
+ eve skips the snapshot when the environment has no `prepare` callback, managed workspace or skill files, or `source`. Each new session sandbox then starts from the image and installs the base runtime itself. A `source` always produces a snapshot, so sessions start from what the build captured instead of fetching the source again.
61
67
 
62
- A new session sandbox created from a prepared snapshot of [eve's default image](/docs/sandbox/docker#eves-default-image), without Drive mounts, inherits the base runtime the build checked and runs no setup command. Existing or resumed sandboxes, custom images or snapshot sources, sandboxes with Drive mounts, and sandboxes created without a prepared snapshot still run base-runtime setup when eve attaches them.
68
+ A new session sandbox from a snapshot of [eve's default image](/docs/sandbox/docker#eves-default-image), without Drive mounts, runs no setup command. eve runs base-runtime setup when it attaches any other sandbox. These include existing or resumed sandboxes, custom images or snapshot sources, sandboxes with Drive mounts, and sandboxes created without a snapshot.
63
69
 
64
70
  ## Initialize after open
65
71
 
66
- Initialize session-specific state after `open()` and before returning the sandbox. This selector writes a configuration file into the persistent `/workspace` filesystem:
72
+ Initialize state for one session after `open()` and before you return the sandbox. Relative paths, including a relative `workingDirectory` passed to `run()` or `spawn()`, resolve from `/workspace`:
67
73
 
68
74
  ```ts
69
75
  import { defineSandbox } from "eve/sandbox";
@@ -73,35 +79,22 @@ export const environment = VercelSandbox.environment();
73
79
 
74
80
  export default defineSandbox(async ({ session }) => {
75
81
  const sandbox = await environment.open();
82
+ // writes /workspace/.eve/session.json
76
83
  await sandbox.writeTextFile({
77
84
  content: JSON.stringify({ sessionId: session.id, workspace: "analysis" }),
78
85
  path: ".eve/session.json",
79
86
  });
80
- return sandbox;
81
- });
82
- ```
83
-
84
- The selector runs until initialization succeeds. Later workflow steps and process restarts resume the same provider state without rerunning the selector, so the file is not rewritten at each boundary.
85
-
86
- You can also configure the live sandbox and run setup commands before returning it:
87
-
88
- ```ts
89
- export default defineSandbox(async () => {
90
- const sandbox = await environment.open();
91
- await sandbox.setNetworkPolicy("deny-all");
92
87
  const result = await sandbox.run({ command: "mkdir -p .cache/app" });
93
88
  if (result.exitCode !== 0) throw new Error(result.stderr);
94
89
  return sandbox;
95
90
  });
96
91
  ```
97
92
 
98
- Relative paths, including a relative `workingDirectory` passed to `run()` or `spawn()`, resolve from `/workspace`.
99
-
100
- Use the environment's `prepare` callback for immutable setup that every new session should inherit. Use post-open initialization for state that belongs only to one durable session.
93
+ Later workflow steps and process restarts resume the sandbox without running the selector again, so the file isn't rewritten at each step. Use the environment's `prepare` callback for setup that every new session inherits, and post-open initialization for state that belongs to one session. See [Initialize a session's sandbox](/docs/sandbox#initialize-a-sessions-sandbox) for why initialization must be safe to repeat.
101
94
 
102
95
  ## Network policy
103
96
 
104
- Pass the initial policy to `open()`. It applies to the new live Vercel Sandbox, not to the environment definition:
97
+ Pass the initial policy for the live sandbox to `open()`:
105
98
 
106
99
  ```ts
107
100
  return environment.open({
@@ -117,7 +110,9 @@ return environment.open({
117
110
  });
118
111
  ```
119
112
 
120
- Credential transforms inject headers at the network boundary so the secret does not enter the sandbox process. The dedicated Vercel environment returns a session where `setNetworkPolicy()` is required, so you can update the policy directly after `open()` without a capability check:
113
+ Credential transforms add headers at the network boundary, so the secret never enters the sandbox process.
114
+
115
+ Sandboxes from a Vercel environment always have `setNetworkPolicy()`, so you can update the policy without checking that the method exists:
121
116
 
122
117
  ```ts
123
118
  const sandbox = await environment.open();
@@ -127,7 +122,7 @@ return sandbox;
127
122
 
128
123
  ## Live sandbox name
129
124
 
130
- Sessions returned by `environment.open()` and `ctx.getSandbox(environment)` expose a read-only `name` property. The name identifies the live Vercel Sandbox and stays stable across stop/resume for the session. Use it as `sandboxName` when creating Vercel git-credential-broker grants scoped to that sandbox:
125
+ Sandboxes from `environment.open()` and `ctx.getSandbox(environment)` have a read-only `name`. It identifies the live Vercel Sandbox and stays the same across stop and resume. Use it as `sandboxName` when you create Vercel git-credential-broker grants for that sandbox:
131
126
 
132
127
  ```ts
133
128
  const sandbox = await ctx.getSandbox(environment);
@@ -136,7 +131,7 @@ const sandboxName = sandbox.name;
136
131
 
137
132
  ## Mount a Drive
138
133
 
139
- A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. Install `@vercel/sandbox` in your app, create or retrieve the Drive before calling `open()`, then pass its name and mount mode in `mounts` under an absolute path:
134
+ A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. Install `@vercel/sandbox` in your app and create or retrieve the Drive before calling `open()`. Then pass its name and mount mode in `mounts` under an absolute path:
140
135
 
141
136
  ```bash
142
137
  pnpm add @vercel/sandbox
@@ -147,6 +142,7 @@ import { Drive } from "@vercel/sandbox";
147
142
  import { defineSandbox } from "eve/sandbox";
148
143
  import { VercelSandbox } from "eve/sandbox/vercel";
149
144
 
145
+ // use one region for the environment and the Drive, so sandboxes run next to the Drive
150
146
  const REGION = "iad1";
151
147
 
152
148
  export const environment = VercelSandbox.environment({ region: REGION });
@@ -165,13 +161,24 @@ export default defineSandbox(async () => {
165
161
  });
166
162
  ```
167
163
 
168
- `Drive.getOrCreate()` comes from your app's own `@vercel/sandbox`, so it resolves credentials through the SDK, not eve: it reads `token`, `teamId`, and `projectId` passed to it, or a Vercel OIDC token, which the SDK refreshes from your Vercel CLI login and linked project. It does not read `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, or the credentials passed to `VercelSandbox.environment()`, so outside Vercel without a linked project, pass them to `Drive.getOrCreate()` too.
164
+ Files written to `/data` remain on the Drive after the sandbox stops. Keep Drive mounts separate from eve's managed `/workspace` directory.
165
+
166
+ Each `mounts` entry is one of these:
167
+
168
+ - A `Drive`, which mounts read-write.
169
+ - A `{ drive, mode }` reference to an existing Drive by name, where `mode` is `"read-write"` or `"snapshot"`. `drive.snapshot()` returns such a reference.
170
+
171
+ Vercel allows up to four non-overlapping, absolute Drive mount paths per sandbox. See the Vercel documentation for [how Drives work, their limits, and pricing](https://vercel.com/docs/sandbox/concepts/drives).
172
+
173
+ ### Drive credentials
174
+
175
+ `Drive.getOrCreate()` gets credentials through your app's `@vercel/sandbox`, not through eve. It reads the `token`, `teamId`, and `projectId` passed to it. Without them, it uses a Vercel OIDC token that the SDK refreshes from your Vercel CLI login and linked project.
169
176
 
170
- This example mounts the Drive read-write at `/data`. Files written there remain on the Drive after the sandbox stops. Keep Drive mounts separate from eve's managed `/workspace` directory.
177
+ `Drive.getOrCreate()` ignores `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, and the credentials passed to `VercelSandbox.environment()`. Outside Vercel without a linked project, pass the credentials to `Drive.getOrCreate()` too.
171
178
 
172
- Set the same region on the environment and the Drive. The environment region places the prepared snapshot and each session sandbox together with the Drive.
179
+ ### Concurrent sessions
173
180
 
174
- A Drive supports one active read-write mount. Because each eve session gets its own sandbox, the fixed `agent-workspace` name works only when one eve session uses the Drive at a time. If sessions can overlap, derive an opaque, stable Drive name per owner or tenant. The [Vercel guide to using Drives with eve](https://vercel.com/kb/guide/vercel-drives-eve-agent) shows how to derive a Drive name from the session initiator.
181
+ A Drive supports one active read-write mount, and each eve session gets its own sandbox. The fixed `agent-workspace` name therefore works only when one session uses the Drive at a time. If sessions can overlap, derive an opaque, stable Drive name per user or tenant. The [Vercel guide to using Drives with eve](https://vercel.com/kb/guide/vercel-drives-eve-agent) shows how to derive a Drive name from the user who started the session.
175
182
 
176
183
  To share a point-in-time view across concurrent sandboxes, mount a read-only snapshot instead:
177
184
 
@@ -183,20 +190,6 @@ return environment.open({
183
190
  });
184
191
  ```
185
192
 
186
- Before mounting a Drive snapshot, seed a new Drive by mounting it read-write and writing at least one file. An uninitialized Drive cannot be mounted as a snapshot.
187
-
188
- Each `mounts` entry is a `Drive`, which mounts read-write, or a `{ drive, mode }` reference to an existing Drive by name, where `mode` is `"read-write"` or `"snapshot"`. `drive.snapshot()` returns such a reference.
189
-
190
- Vercel allows up to four non-overlapping, absolute Drive mount paths per sandbox. See the Vercel documentation for [Drive lifecycle, limits, and pricing](https://vercel.com/docs/sandbox/concepts/drives).
191
-
192
- ## Live sandbox options
193
-
194
- `open()` also accepts Vercel compute resources, timeout, environment variables, and Drive mounts. These options apply only when creating the sandbox. Reopening the same key or resuming recorded state keeps the native sandbox's original environment variables, mounts, and network policy. Pass `env` to `run()` or `spawn()` for a per-command override, or call `setNetworkPolicy()` to change the live network policy.
195
-
196
- Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.
197
-
198
- Initialize the returned sandbox directly in `defineSandbox()`. If initialization fails, eve keeps the sandbox and runs the selector against it again on the next access, so make initialization safe to repeat; session end deletes the sandbox. After initialization succeeds, the provider persists only immutable JSON-compatible state. If the named Vercel Sandbox later disappears, resume does not recreate it; eve reruns the selector to start a fresh sandbox instead.
199
-
200
- eve owns the persistent sandbox identity and prepared snapshot source.
193
+ Before you mount a Drive snapshot, seed a new Drive by mounting it read-write and writing at least one file. An uninitialized Drive can't be mounted as a snapshot.
201
194
 
202
- See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.
195
+ See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers. Use [Docker Sandbox](/docs/sandbox/docker) for local containers.