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.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- 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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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`
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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()`
|
|
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`.
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
package/docs/sandbox/vercel.mdx
CHANGED
|
@@ -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()`
|
|
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
|
|
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
|
|
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
|
|
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
|
-
##
|
|
54
|
+
## Live sandbox options
|
|
55
55
|
|
|
56
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
179
|
+
### Concurrent sessions
|
|
173
180
|
|
|
174
|
-
A Drive supports one active read-write mount
|
|
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
|
|
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.
|