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,7 @@ title: "Default Sandbox"
3
3
  description: "Let eve select the sandbox provider when it prepares the sandbox."
4
4
  ---
5
5
 
6
- `DefaultSandbox.environment()` selects a sandbox provider when eve prepares the sandbox, records the choice, and uses that provider for every session the build serves.
6
+ `DefaultSandbox.environment()` lets eve pick the sandbox provider for you. eve picks once, when it prepares the sandbox, and every session the build serves uses that provider. It's also what eve uses when the agent has no sandbox file.
7
7
 
8
8
  ```ts
9
9
  import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -12,35 +12,28 @@ export const environment = DefaultSandbox.environment();
12
12
  export default defineSandbox(() => environment.open());
13
13
  ```
14
14
 
15
- On Vercel, it selects [Vercel Sandbox](/docs/sandbox/vercel). Elsewhere, it selects [Docker](/docs/sandbox/docker) when a Docker daemon is reachable, and [just-bash](/docs/sandbox/just-bash) only during `eve dev` and `eve eval`.
16
-
17
15
  ## How eve selects the provider
18
16
 
19
- eve selects the provider when it prepares the sandbox: during `eve build`, or during `eve dev` the first time a session opens the sandbox. It checks in this order:
20
-
21
- 1. If the `VERCEL` environment variable is set, it selects Vercel.
22
- 2. Otherwise, if `docker version` reports a running Linux Docker daemon within five seconds, it selects Docker.
23
- 3. Otherwise, during `eve dev` and `eve eval`, it selects just-bash.
24
- 4. Otherwise, in a production `eve build`, it selects no provider.
17
+ eve prepares the sandbox during `eve build`, or during `eve dev` the first time a session opens the sandbox. It takes the first row that matches:
25
18
 
26
- | Where eve prepares the sandbox | Selected provider |
27
- | ------------------------------------------------- | --------------------------------------------- |
28
- | On Vercel (`vercel build` or a Vercel deploy) | [Vercel Sandbox](/docs/sandbox/vercel) |
29
- | Anywhere a Linux Docker daemon is reachable | [Docker](/docs/sandbox/docker) |
30
- | `eve dev` or `eve eval` without Docker | [just-bash](/docs/sandbox/just-bash) |
31
- | A production `eve build` without Vercel or Docker | None: opening the sandbox fails with an error |
19
+ | Where eve prepares the sandbox | Selected provider |
20
+ | ---------------------------------------------------------------------------- | --------------------------------------------- |
21
+ | The `VERCEL` environment variable is set (`vercel build` or a Vercel deploy) | [Vercel Sandbox](/docs/sandbox/vercel) |
22
+ | `docker version` reports a running Linux Docker daemon within five seconds | [Docker](/docs/sandbox/docker) |
23
+ | `eve dev` or `eve eval` | [just-bash](/docs/sandbox/just-bash) |
24
+ | A production `eve build` | None: opening the sandbox fails with an error |
32
25
 
33
- Production builds never fall back to just-bash, because just-bash runs no native processes and provides no network isolation. When no provider is available, `eve build` still succeeds and logs that no provider is available. The first session that opens the sandbox fails with an error that asks you to start Docker and rebuild, deploy to Vercel, or select a provider explicitly in your sandbox file. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting).
26
+ Production builds never fall back to just-bash, because just-bash runs no native processes and provides no network isolation. Without a provider, `eve build` succeeds and logs that no provider is available. The first session that opens the sandbox then fails. The error asks you to start Docker and rebuild, deploy to Vercel, or select a provider in your sandbox file. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting#defaultsandbox-has-no-sandbox-provider-for-this-build).
34
27
 
35
28
  ## The build records the choice
36
29
 
37
- `eve build` stores the selected provider in the build's prepared sandbox artifact. At runtime, `DefaultSandbox` reads the recorded provider and does not check for Vercel or Docker again, so the build and the server it produces always use the same provider, even when the server runs on a different host. To change the provider, rebuild where the provider you want is available.
30
+ `eve build` records the selected provider. The server always uses that provider, even on a different host, and doesn't check for Vercel or Docker again. To change the provider, rebuild where the provider you want is available.
38
31
 
39
- Each session also records the provider that created its sandbox. If a later build selects a different provider, a session that resumes on the new build starts a fresh sandbox from the new provider, without the old sandbox's files. eve does not delete the old sandbox: a Vercel Sandbox stays in your Vercel project, and a Docker container stays on the Docker host until you remove it.
32
+ When a session continues on a build with a different provider, it starts a fresh sandbox without the old sandbox's files. eve doesn't delete the old sandbox. A Vercel Sandbox stays in your Vercel project, and a Docker container stays on the Docker host until you remove it.
40
33
 
41
34
  ## Environment options
42
35
 
43
- `DefaultSandbox.environment()` accepts options for each provider it might select. eve passes only the selected provider's options and ignores the rest:
36
+ `DefaultSandbox.environment()` accepts options for each provider it might select. It passes on only the selected provider's options:
44
37
 
45
38
  ```ts
46
39
  import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -64,13 +57,13 @@ export default defineSandbox(() => environment.open());
64
57
  | `vercel` | Vercel is selected | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials. |
65
58
  | `justBash` | just-bash is selected | `autoInstall` and `prepare`. Use [`JustBashSandbox.environment()`](/docs/sandbox/just-bash#experimental-options) for experimental `customCommands` or `filesystem`. |
66
59
 
67
- Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects. just-bash runs no native binaries, so commands such as `apt-get` fail there during `eve dev`.
60
+ Keep a shared `prepare` callback portable, because it runs on whichever provider eve selects. Commands such as `apt-get` fail on just-bash, which runs no native binaries.
68
61
 
69
- On Vercel, when the environment has no `prepare` callback, workspace seed, skill files, or `source`, eve skips the snapshot and creates each session sandbox directly from the configured `image`, or from eve's base image when none is set. See [Vercel Sandbox](/docs/sandbox/vercel#snapshot-preparation).
62
+ On Vercel, eve skips the snapshot when the environment has no `prepare` callback, workspace seed, skill files, or `source`. Each session sandbox then starts directly from the configured `image`, or from eve's base image when none is set. See [Vercel Sandbox](/docs/sandbox/vercel#snapshot-preparation).
70
63
 
71
64
  ## Network policy
72
65
 
73
- Pass `networkPolicy` to `open()`, or call `setNetworkPolicy()` on the session from `ctx.getSandbox(environment)`. eve forwards the policy to the selected provider:
66
+ To set a network policy on the selected provider, pass `networkPolicy` to `open()`. You can also call `setNetworkPolicy()` on the sandbox from `ctx.getSandbox(environment)`.
74
67
 
75
68
  ```ts
76
69
  import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -79,6 +72,12 @@ export const environment = DefaultSandbox.environment();
79
72
  export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
80
73
  ```
81
74
 
82
- Vercel Sandbox accepts every network policy, including domain allow-lists and credential transforms. Docker accepts only `"allow-all"` and `"deny-all"` and rejects any other policy with an error. just-bash always allows network access, so it accepts only `"allow-all"` and rejects any other policy with an error. Use [Vercel Sandbox](/docs/sandbox/vercel) directly when you need domain-level policies in every environment.
75
+ | Provider | Accepted policies |
76
+ | --------- | -------------------------------------------------------------------- |
77
+ | Vercel | Every policy, including domain allow-lists and credential transforms |
78
+ | Docker | `"allow-all"` and `"deny-all"` |
79
+ | just-bash | `"allow-all"` only, because it always allows network access |
80
+
81
+ Other policies throw an error.
83
82
 
84
- Use a provider directly when you need its other `open()` options, such as Vercel compute resources or Drive `mounts`.
83
+ Use a provider directly when you need domain-level policies in every environment, or its other `open()` options, such as Vercel compute resources or Drive `mounts`. See [Vercel Sandbox](/docs/sandbox/vercel) and [Docker Sandbox](/docs/sandbox/docker).
@@ -3,20 +3,21 @@ title: "Docker Sandbox"
3
3
  description: "Create local persistent containers from an image or Dockerfile."
4
4
  ---
5
5
 
6
- Docker environments can use eve's default image, an existing OCI image, or `agent/sandbox/Dockerfile`.
6
+ A Docker sandbox runs each session in its own local container, which keeps its files between turns. The container comes from eve's default image, an existing OCI image, or `agent/sandbox/Dockerfile`.
7
7
 
8
- ```ts
8
+ ```ts title="agent/sandbox.ts"
9
9
  import { defineSandbox } from "eve/sandbox";
10
10
  import { DockerSandbox } from "eve/sandbox/docker";
11
11
 
12
12
  export const environment = DockerSandbox.image("ghcr.io/acme/agent@sha256:...");
13
13
 
14
+ // networkPolicy is optional: "allow-all" or "deny-all"
14
15
  export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
15
16
  ```
16
17
 
17
18
  ## Choose the base image
18
19
 
19
- `DockerSandbox.environment()`, `DockerSandbox.image()`, and `DockerSandbox.dockerfile()` all create the same Docker environment. They differ only in how you pass the base image:
20
+ The three constructors create the same Docker environment. They differ only in how you pass the base image:
20
21
 
21
22
  | Constructor | Base image without a Dockerfile |
22
23
  | ------------------------------------------- | ---------------------------------------- |
@@ -24,28 +25,33 @@ export default defineSandbox(() => environment.open({ networkPolicy: "deny-all"
24
25
  | `DockerSandbox.image("ghcr.io/acme/agent")` | The image reference you pass |
25
26
  | `DockerSandbox.dockerfile()` | eve's default image |
26
27
 
27
- When `agent/sandbox/Dockerfile` exists, eve builds it during preparation and uses the result as the base image for every constructor. The Dockerfile takes precedence over any `image` you pass, including `DockerSandbox.image(ref)`. eve uses the files under `agent/sandbox/` as the Docker build context. To use an existing image instead, remove the Dockerfile.
28
+ When `agent/sandbox/Dockerfile` exists, eve builds it during preparation with `agent/sandbox/` as the build context. The result is the base image for every constructor, and it overrides any `image` you pass, including `DockerSandbox.image(ref)`. To use an existing image, remove the Dockerfile.
28
29
 
29
- `DockerSandbox.dockerfile()` does not accept an `image` option, which makes the Dockerfile convention explicit in your sandbox file.
30
+ Use `DockerSandbox.dockerfile()`, which takes no `image` option, to make the sandbox file show that it uses the Dockerfile.
30
31
 
31
32
  ## eve's default image
32
33
 
33
34
  eve's default image runs Ubuntu with Node.js 24, npm, Python 3, git, ripgrep, jq, and curl. Commands run as the `vercel-sandbox` user in `/workspace`, with passwordless `sudo`. Docker pulls it from `ghcr.io/vercel/eve`, and [Vercel Sandbox](/docs/sandbox/vercel) uses the same image from `vcr.vercel.com/vercel/eve/base`.
34
35
 
35
- The default image does not include pnpm or pip, so install them in `prepare` when your agent needs them. `npm install -g pnpm` installs pnpm for the `vercel-sandbox` user. Ubuntu's system Python refuses `pip install`, so install `python3-venv` with `sudo apt-get install -y python3-venv`, then use the pip inside a virtual environment. The [analysis tutorial](/docs/tutorial/run-analysis#install-the-chart-dependencies) shows the Python setup. Preparation runs when eve builds the template, so it needs network access to the package registries.
36
+ The default image doesn't include pnpm or pip, so install them in `prepare` when your agent needs them:
36
37
 
37
- Each eve release pins one tag of the default image. The tag comes from the image definition, not the eve version. Prepared templates include the image reference, so an eve upgrade that keeps the same image reuses them. A release that changes the image rebuilds them once.
38
+ - `npm install -g pnpm` installs pnpm for the `vercel-sandbox` user.
39
+ - Ubuntu's system Python refuses `pip install`, so run `sudo apt-get install -y python3-venv` and use the pip inside a virtual environment. The [analysis tutorial](/docs/tutorial/run-analysis#install-the-chart-dependencies) shows the Python setup.
40
+
41
+ Preparation runs when eve builds the template, so it needs network access to the package registries.
42
+
43
+ Each eve release pins one tag of the default image, and the tag is not the eve version. Prepared templates include the image reference, so a new eve release reuses them unless it pins a different image.
38
44
 
39
45
  To run a different published tag, set `EVE_SANDBOX_IMAGE_TAG` in both the build and runtime environments. eve applies the tag to both registries.
40
46
 
41
47
  ## Environment options
42
48
 
43
- Image, pull policy, environment variables, and `prepare` belong to the reusable environment. During preparation, eve starts a temporary container, seeds workspace and skill files, runs your `prepare`, and commits the result as the recorded template image.
49
+ Pass `image`, `pullPolicy`, `env`, and `prepare` to the environment. During preparation, eve copies workspace and skill files into a temporary container and runs your `prepare`. It saves the result as the template image.
44
50
 
45
51
  ## Live container options
46
52
 
47
- Pass `networkPolicy` to `open()`. Docker supports only `"allow-all"` and `"deny-all"`. The policy applies to the live container, not the prepared image.
53
+ Pass `networkPolicy` to `open()` to set the live container's policy: `"allow-all"` or `"deny-all"`.
48
54
 
49
- A session-owned container keeps writable `/workspace` state in its container filesystem. A stopped container restarts with that state. `sandbox.delete()` removes the session's container by name and succeeds when the container is already gone.
55
+ Each session's container keeps `/workspace` in its filesystem, and a stopped container restarts with those files. `sandbox.delete()` removes the container and succeeds when it's already gone.
50
56
 
51
57
  See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.
@@ -3,11 +3,33 @@ title: "Sandbox"
3
3
  description: "Configure the isolated filesystem and command environment used by an eve agent."
4
4
  ---
5
5
 
6
- Every eve agent has one sandbox. Its workspace root, where commands start and relative paths resolve from, is `/workspace` on every built-in provider. The built-in `bash`, `read_file`, and `write_file` tools use it. Without an authored sandbox file, eve selects the best available environment automatically.
6
+ The sandbox is the isolated filesystem and command environment of an eve agent. Each agent has one, and the built-in `bash`, `read_file`, and `write_file` tools run in it. Define it in `agent/sandbox.ts`, or omit the file to let eve select an environment automatically.
7
+
8
+ ## Define an environment
9
+
10
+ ```text
11
+ agent/
12
+ ├── agent.ts
13
+ └── sandbox.ts # or agent/sandbox/sandbox.ts when agent/sandbox/ exists
14
+ ```
15
+
16
+ ```ts title="agent/sandbox.ts"
17
+ import { DefaultSandbox, defineSandbox } from "eve/sandbox";
18
+
19
+ // required: `eve build` prepares this export before any session exists
20
+ export const environment = DefaultSandbox.environment();
21
+ // required: the selector that opens the sandbox for a session
22
+ export default defineSandbox(() => environment.open());
23
+ ```
24
+
25
+ - Put the file at `agent/sandbox/sandbox.ts` when the agent also has [workspace seeds](#managed-workspace-and-skills) or a Docker `Dockerfile` in `agent/sandbox/`. When the `agent/sandbox/` folder exists, put the definition there. A root `agent/sandbox.ts` beside that folder is a build error.
26
+ - `environment.open()` starts the sandbox for the current session.
27
+ - The selector runs until it succeeds once. After that, later workflow steps and process restarts resume the same sandbox without running the selector again.
28
+ - Commands start and relative paths resolve from the workspace root, `/workspace` on every built-in provider.
7
29
 
8
30
  ## Use the sandbox
9
31
 
10
- Authored tools and callbacks access the live sandbox with `ctx.getSandbox()`:
32
+ Authored tools and callbacks get the live sandbox with `ctx.getSandbox()`:
11
33
 
12
34
  ```ts title="agent/tools/run_analysis.ts"
13
35
  import { defineTool } from "eve/tools";
@@ -19,6 +41,7 @@ export default defineTool({
19
41
  async execute({ script }, ctx) {
20
42
  const sandbox = await ctx.getSandbox();
21
43
  await sandbox.writeTextFile({ path: "analysis.py", content: script });
44
+ // run() doesn't throw on a nonzero exit code
22
45
  const result = await sandbox.run({ command: "python analysis.py" });
23
46
  if (result.exitCode !== 0) throw new Error(result.stderr);
24
47
  return result.stdout;
@@ -26,11 +49,11 @@ export default defineTool({
26
49
  });
27
50
  ```
28
51
 
29
- Relative paths resolve from the workspace root, and `sandbox.resolvePath(".")` returns its absolute path. `run()` returns `{ exitCode, stdout, stderr }`; a nonzero exit code does not throw automatically. Use `spawn()` for a long-running process. Pass `stdin: true` to get a writable `stdin` stream on the process, for example to talk to a stdio server; closing it sends EOF. The Vercel and Docker sandboxes support it.
30
-
31
- Built-in environments set `AI_AGENT=eve` on every `run()` and `spawn()` call, including the `bash` tool and `prepare`, so agent-aware CLIs such as `vercel` skip interactive prompts. To use a different value, set `AI_AGENT` in the environment's `env` option or pass it in the `env` of one `run()` or `spawn()` call.
52
+ - `run()` returns `{ exitCode, stdout, stderr }`. `sandbox.resolvePath(".")` returns the workspace root's absolute path.
53
+ - Use `spawn()` for a long-running process. On Vercel and Docker, pass `stdin: true` to get a writable `stdin` stream, for example to talk to a stdio server. Closing the stream sends EOF.
54
+ - Built-in environments set `AI_AGENT=eve` on every `run()` and `spawn()` call, including the `bash` tool and `prepare`. Agent-aware CLIs such as `vercel` then skip interactive prompts. To override it, set `AI_AGENT` in the environment's `env` option or in one call's `env`.
32
55
 
33
- Pass the configured environment to preserve its specific session capabilities in authored runtime code:
56
+ The handle from `ctx.getSandbox()` has only the methods every provider shares. Pass the configured environment to also get provider-specific methods, such as Vercel's `setNetworkPolicy()`:
34
57
 
35
58
  ```ts
36
59
  import { environment } from "../sandbox";
@@ -39,22 +62,22 @@ const sandbox = await ctx.getSandbox(environment);
39
62
  await sandbox.setNetworkPolicy("deny-all");
40
63
  ```
41
64
 
42
- For example, a Vercel environment returns a handle with `setNetworkPolicy()`. The common handle from `ctx.getSandbox()` does not expose provider-specific capabilities. The environment must match the one configured for the current sandbox.
43
-
44
- ## Define an environment
65
+ The environment you pass must match the one configured for the current sandbox.
45
66
 
46
- A sandbox module exports an environment and returns a sandbox from `defineSandbox()`. Put it at `agent/sandbox.ts`, or at `agent/sandbox/sandbox.ts` when the agent also has [workspace seeds](#managed-workspace-and-skills) or a Docker `Dockerfile` in `agent/sandbox/`. When the `agent/sandbox/` folder exists, put the definition at `agent/sandbox/sandbox.ts`. Keeping `agent/sandbox.ts` beside that folder is a build error, even when the folder only contains workspace seeds or a Dockerfile.
67
+ ## Providers
47
68
 
48
- ```ts title="agent/sandbox.ts"
49
- import { DefaultSandbox, defineSandbox } from "eve/sandbox";
69
+ | Provider | Use it for |
70
+ | ------------------------------------ | ------------------------------------------------------------------------------------------- |
71
+ | [Default](/docs/sandbox/default) | Vercel Sandbox on Vercel, Docker when reachable, and just-bash in development. |
72
+ | [Vercel](/docs/sandbox/vercel) | Persistent Vercel Sandboxes, prepared snapshots, domain network policies, and Drive mounts. |
73
+ | [Docker](/docs/sandbox/docker) | Local containers from the default image, an existing OCI image, or a Dockerfile. |
74
+ | [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation. |
50
75
 
51
- export const environment = DefaultSandbox.environment();
52
- export default defineSandbox(() => environment.open());
53
- ```
76
+ `DefaultSandbox` accepts only `autoInstall` and `prepare` for just-bash. Use the [experimental options](/docs/sandbox/just-bash#experimental-options) of `JustBashSandbox.environment()` from `eve/sandbox/just-bash` for custom commands or filesystems.
54
77
 
55
- `environment.open()` starts the persistent sandbox owned by the current eve session. The `defineSandbox()` selector runs until initialization succeeds, then eve checkpoints the selected provider and its state. Later workflow steps and process restarts call the provider's `resume()` directly without rerunning the selector or `environment.open()`. Once a session has recorded its sandbox, eve resumes it in the background when each turn starts, so a tool that uses the sandbox waits only for whatever remains of the resume.
78
+ ## Initialize a session's sandbox
56
79
 
57
- Pass options for the live sandbox to `open()`, then configure the returned sandbox before returning it. `open()` applies its options only when it creates the sandbox. Initialization can run more than once against the same sandbox, for example when a subagent that shares the sandbox opens it before the parent does, when a [workflow step](/docs/tools/workflows#use-the-session-sandbox-in-a-step) opens it before the session records it, when the first turn of a prewarmed session opens it while prewarming is still starting it, or on the next access after an initialization that failed. Make it safe to repeat:
80
+ Pass live sandbox options to `open()`, then configure the sandbox before you return it. `open()` applies its options only when it creates the sandbox.
58
81
 
59
82
  ```ts
60
83
  import { defineSandbox } from "eve/sandbox";
@@ -69,13 +92,18 @@ export default defineSandbox(async ({ session }) => {
69
92
  });
70
93
  ```
71
94
 
72
- When a client prewarms a session, for example with `useEveAgent({ prewarm: true })`, eve runs the selector before the first message arrives. `session.auth` then describes the request that created the session, and the first message's `onMessage` hook can return a different identity. Do not derive per-user sandbox options or `defineState()` values from `session.auth` in an agent whose clients prewarm sessions: eve keeps both from the prewarming run. See [prewarming](/docs/guides/frontend/use-eve-agent#prewarming) for when eve prewarms a session.
95
+ Make initialization safe to repeat, because it can run more than once against the same sandbox:
96
+
97
+ - A subagent that shares the sandbox opens it before the parent does.
98
+ - A [workflow step](/docs/tools/workflows#use-the-session-sandbox-in-a-step) opens it before the session records it.
99
+ - The first turn of a prewarmed session opens it while prewarming is still starting it.
100
+ - A previous initialization failed.
73
101
 
74
- The environment export is required because `eve build` prepares immutable environment inputs before a session exists.
102
+ A [prewarmed session](/docs/guides/frontend/use-eve-agent#prewarming), for example from `useEveAgent({ prewarm: true })`, runs the selector before the first message. The selector sees `session.auth` from the request that created the session. eve keeps the sandbox options and `defineState()` values from that run, even when the first message's `onMessage` hook returns a different identity. In an agent whose clients prewarm, don't derive either from `session.auth`.
75
103
 
76
- ### Prepare a reusable environment
104
+ ## Prepare a reusable environment
77
105
 
78
- Use the environment's `prepare` option for setup every new sandbox inherits:
106
+ Use the environment's `prepare` option for setup that every new sandbox inherits:
79
107
 
80
108
  ```ts
81
109
  import { defineSandbox } from "eve/sandbox";
@@ -93,19 +121,19 @@ export const environment = VercelSandbox.environment({
93
121
  export default defineSandbox(() => environment.open());
94
122
  ```
95
123
 
96
- eve runs `prepare` while creating a reusable provider artifact, not once for each live session sandbox. Vercel captures a snapshot; Docker captures an image; and just-bash captures a filesystem template.
124
+ `prepare` runs once per reusable template, not once per session. The template is a Vercel snapshot, a Docker image, or a just-bash filesystem template.
97
125
 
98
- During `eve dev`, startup and authored-source rebuilds do not prepare sandbox environments. The first sandbox access prepares all environments in that compiled generation before opening the requested sandbox. This includes environments declared by subagents and extensions, even if they use different providers. Concurrent requests share the preparation work; a failed preparation can be retried on a later access. Optional provider installation and setup can make that first access slow.
126
+ `eve build` prepares every environment. During `eve dev`, the first sandbox access after startup or a rebuild prepares all environments in the build, including those of subagents and extensions. That access can be slow, and a later access retries a failed preparation.
99
127
 
100
- `eve build` still prepares environments eagerly. In production, eve passes the recorded artifact directly to the provider when it creates a live sandbox. Production runtime does not rebuild or repair a missing artifact. A missing image, snapshot, or template fails with rebuild or redeploy guidance. [Sandbox troubleshooting](/docs/sandbox/troubleshooting) lists these errors with their causes and fixes.
128
+ Production creates sandboxes only from the templates the build recorded, and never rebuilds a missing one. A missing image, snapshot, or template fails with rebuild or redeploy guidance; see [Sandbox troubleshooting](/docs/sandbox/troubleshooting).
101
129
 
102
- ### Reuse native resources across sessions
130
+ ## Reuse native resources across sessions
103
131
 
104
- Built-in environments do not expose cross-session sharing. To reuse native compute or storage across eve sessions, define a [custom provider](/docs/sandbox/custom-providers) whose connection is a session-owned logical sandbox view and that keeps shared resources outside the connection's `stop()` and the provider's `onSessionEnd()`. A session-specific path is not an isolation boundary; mutually untrusted sessions require separate native compute or stronger provider-owned isolation.
132
+ Built-in environments don't share sandboxes across sessions. To reuse native compute or storage, define a [custom provider](/docs/sandbox/custom-providers) that gives each session its own view of the shared resources. Keep the shared resources out of its `stop()` and `onSessionEnd()`. A session-specific path is not an isolation boundary, so sessions that don't trust each other need separate native compute or stronger isolation from the provider.
105
133
 
106
- ### Share a parent sandbox
134
+ ## Share a parent sandbox
107
135
 
108
- A declared subagent can use its dispatching parent's sandbox explicitly:
136
+ A declared subagent can use the sandbox of the parent that called it:
109
137
 
110
138
  ```ts title="agent/subagents/reviewer/sandbox.ts"
111
139
  import { defineParentSandbox } from "eve/sandbox";
@@ -113,13 +141,14 @@ import { defineParentSandbox } from "eve/sandbox";
113
141
  export default defineParentSandbox();
114
142
  ```
115
143
 
116
- An inheriting subagent cannot declare its own managed workspace or skill files.
117
-
118
- The parent and every subagent that shares its sandbox, including children of the built-in `agent` tool, use one sandbox keyed by the parent's session. Whichever session opens it first runs the parent's `defineSandbox()` selector to create it. When the parent session ends, eve deletes the sandbox, even one that only a subagent opened.
144
+ - The parent and every subagent that shares its sandbox, including children of the built-in `agent` tool, use one sandbox that belongs to the parent's session.
145
+ - Whichever agent opens the sandbox first runs the parent's selector.
146
+ - eve deletes the sandbox when the parent session ends, even if only a subagent opened it.
147
+ - A subagent that shares its parent's sandbox can't declare its own managed workspace or skill files.
119
148
 
120
149
  ## Managed workspace and skills
121
150
 
122
- Use the sandbox directory for authored workspace seeds:
151
+ Put workspace seed files in the sandbox directory:
123
152
 
124
153
  ```text
125
154
  agent/sandbox/
@@ -128,61 +157,64 @@ agent/sandbox/
128
157
  schema.sql
129
158
  ```
130
159
 
131
- Files under `agent/sandbox/workspace/` seed writable `/workspace`. eve copies the seed into the prepared environment when it prepares a new environment generation, and each new session sandbox starts from that copy. Existing live sandbox state is not overwritten by later seed changes.
160
+ Files under `agent/sandbox/workspace/` seed writable `/workspace`. Each new session sandbox starts with a copy of them. Later changes to the seeds don't overwrite existing sandboxes.
132
161
 
133
- Agent skills are compiled into a separate resource tree and exposed at `$HOME/.agents/skills`. These are stable paths across every built-in provider, so instructions and tools can refer to `/workspace` and `$HOME/.agents/skills`. A [custom provider](/docs/sandbox/custom-providers) can declare a different workspace root, so prefer relative paths in code that runs on any provider. eve resolves `$HOME` by reading it inside the sandbox; when a sandbox has no usable home directory, skill paths fall back to `skills/` under the workspace root. Do not refer to a concrete home directory or `/eve/resources`, which is provider-internal staging.
162
+ Agent skills appear at `$HOME/.agents/skills`, or at `skills/` under the workspace root when the sandbox has no usable home directory. Instructions and tools can refer to `/workspace` and `$HOME/.agents/skills` on every built-in provider. Don't refer to a concrete home directory or to `/eve/resources`, which is internal to providers.
134
163
 
135
- Docker mounts the compiled trees read-only under `/eve/resources` and copies them into place. Vercel Sandbox writes workspace and skill files into the build sandbox before capturing its snapshot. A custom provider seeds both trees with `ctx.populate()` when it prepares a template; see [Bake files into templates](/docs/sandbox/custom-providers#bake-files-into-templates).
164
+ A [custom provider](/docs/sandbox/custom-providers#bake-files-into-templates) can declare a different workspace root, so prefer relative paths in code that runs on any provider.
136
165
 
137
166
  ## Inbound attachments
138
167
 
139
- eve writes byte-backed files that reach the agent into the sandbox under `.eve/attachments/` in the workspace root (`/workspace/.eve/attachments/` on built-in providers) and keeps only a reference in session history. This covers files attached to user messages and files that tools return to the model with `toolOutputPart.file` or as MCP image, audio, and blob content.
168
+ eve copies files that reach the agent into `.eve/attachments/` in the workspace root, which is `/workspace/.eve/attachments/` on built-in providers. Session history keeps only a reference to each file. This covers:
140
169
 
141
- Files that tools return by URL with `toolOutputPart.fileUrl` are not staged: the model provider reads the URL directly. See [Send a file by URL](/docs/tools#send-a-file-by-url).
170
+ - Files attached to user messages.
171
+ - Files that tools return with `toolOutputPart.file`.
172
+ - MCP image, audio, and blob content.
142
173
 
143
- Every file, whether attached to a message or returned by a tool, reaches the model on every call with a label that names its sandbox path, such as `Attached file /workspace/.eve/attachments/<hash>/report.csv (text/csv)`. The agent can open that path with `read_file` or `bash`. The file's bytes follow its label only when every major provider reads the format natively:
174
+ Files returned by URL with `toolOutputPart.fileUrl` aren't copied, because the model provider reads the URL directly; see [Send a file by URL](/docs/tools#send-a-file-by-url).
175
+
176
+ Every copied file reaches the model on every call with a label that names its sandbox path, such as `Attached file /workspace/.eve/attachments/<hash>/report.csv (text/csv)`. The agent can open that path with `read_file` or `bash`. The file's bytes follow the label only for formats every major provider reads natively:
144
177
 
145
178
  - A PNG, JPEG, GIF, or WebP image up to 3 MiB and at most 8000 pixels per side.
146
179
  - A PDF up to 20 MiB.
147
180
 
148
- Other files, such as CSV, HEIC, audio, and video, reach the model as the label alone. eve checks image and PDF media types against the file's bytes when it stages the file. A file whose bytes don't match its declared image or PDF type is staged as `application/octet-stream`, so a provider never receives bytes it would reject.
181
+ Other files, such as CSV, HEIC, audio, and video, reach the model as the label alone. An image or PDF whose bytes don't match its declared type is stored as `application/octet-stream`, so a provider never receives bytes it would reject.
149
182
 
150
- To let the agent answer voice notes and other audio, add a tool that transcribes the staged file. See [Voice notes](/docs/patterns/voice-notes).
183
+ To let the agent answer voice notes and other audio, add a tool that transcribes the copied file. See [Voice notes](/docs/patterns/voice-notes).
151
184
 
152
- eve keeps the bytes of recent images and PDFs it staged or read for a session in memory, so preparing a model call's attachments resumes the sandbox only when it needs bytes that eve doesn't already hold. If a file read back from the sandbox is missing, or its bytes no longer match what eve staged because something in the sandbox overwrote it, the model receives a `FileNotFound` note in its place.
185
+ | What happens | What the model receives |
186
+ | ---------------------------------------------------------------------- | ---------------------------------- |
187
+ | The copied file is missing from the sandbox, or something overwrote it | A `FileNotFound` note in its place |
188
+ | A channel's `fetchFile` fails | A note that names the file |
189
+ | A file part's `data` is not bytes, base64, a `data:` URL, or a URL | A note that names the file |
153
190
 
154
- A file that eve can't stage never enters session history. When a channel's `fetchFile` fails, or a file part's `data` is not bytes, base64, a `data:` URL, or a URL, the model receives a note that names the file instead.
191
+ In the last two cases, the file never enters session history.
155
192
 
156
- Each call sends the same bytes for the same file, so the model still sees attachments from earlier turns and the provider's prompt cache stays valid. Compaction replaces files in older tool results with their text reference. The `read_file` tool shows the same images and PDFs to the model as files, so the agent can look at an attachment again after compaction, or open a PDF that a tool or `bash` wrote to the sandbox.
193
+ The model keeps seeing attachments from earlier turns. Each call sends the same bytes, so the provider's prompt cache stays valid. Compaction replaces files in older tool results with their text reference. `read_file` returns images and PDFs to the model as files. The agent can use it to reopen an attachment after compaction, or to view a PDF that `bash` wrote.
157
194
 
158
195
  ## Custom providers
159
196
 
160
- To run sandboxes on a backend eve does not ship, define a provider with `defineSandboxProvider()` from `eve/sandbox/provider`. A provider implements a byte-level connection to one sandbox (`spawn`, `readFile`, `writeFiles`, `removePath`, and `stop`) and a lifecycle of `prepare`, `start`, `resume`, and `onSessionEnd`. eve derives the full sandbox session from the connection, seeds workspace and skill files into the provider's templates during `eve build`, and maps `sandbox.stop()`, `sandbox.delete()`, and server shutdown onto the lifecycle. [Custom sandbox providers](/docs/sandbox/custom-providers) has a complete example and the full contract.
161
-
162
- ## Providers
163
-
164
- | Provider | Use it for |
165
- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
166
- | [Default](/docs/sandbox/default) | Vercel Sandbox on Vercel, Docker when reachable, and just-bash in development. |
167
- | [Vercel](/docs/sandbox/vercel) | Persistent Vercel Sandboxes, prepared snapshots, domain network policies, and Drive mounts. |
168
- | [Docker](/docs/sandbox/docker) | Local containers from the default image, an existing OCI image, or a Dockerfile. |
169
- | [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation. |
170
-
171
- For SDK-specific just-bash commands or filesystem factories, use the experimental options of
172
- `JustBashSandbox.environment()` from `eve/sandbox/just-bash`. `DefaultSandbox` keeps only
173
- `autoInstall` and `prepare` for its just-bash fallback.
197
+ To run sandboxes on a backend eve doesn't ship, define a provider with `defineSandboxProvider()` from `eve/sandbox/provider`. It implements a connection to one sandbox (`spawn`, `readFile`, `writeFiles`, `removePath`, and `stop`) and the methods `prepare`, `start`, `resume`, and `onSessionEnd`. See [Custom sandbox providers](/docs/sandbox/custom-providers) for a complete example.
174
198
 
175
199
  ## Lifecycle
176
200
 
177
- Session-owned sandboxes persist across turns and deployments while their provider state remains available. `sandbox.stop()` stops compute without deleting persisted state; a later access resumes that state directly. `sandbox.delete()` deletes the sandbox and clears provider state, so the next `ctx.getSandbox()` reruns the selector, and the provider starts a fresh sandbox under the same session key from the current environment. If the native sandbox is gone when a session resumes, for example after a local daemon restart, a removed container, or a deleted just-bash session directory, eve does the same: the session continues in a fresh sandbox, without the lost sandbox's files. eve also starts a fresh sandbox when the recorded state belongs to another provider or state protocol than the current environment, for example after you change providers; the old sandbox is not deleted. When the durable session reaches a terminal outcome, eve calls the provider's `onSessionEnd()` hook to delete what remains under the session's key.
201
+ Each session's sandbox persists across turns and deployments while the provider still has it.
202
+
203
+ | Event | Result |
204
+ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
205
+ | `sandbox.stop()` | Compute stops and files persist. The next access resumes it. |
206
+ | `sandbox.delete()` | The sandbox and its files are deleted. The next `ctx.getSandbox()` runs the selector again for a fresh sandbox. |
207
+ | The native sandbox is gone on resume, such as after a removed container or deleted just-bash session directory | The session continues in a fresh sandbox, without the lost files. |
208
+ | The session's sandbox came from another provider or state version, such as after you change providers | The session continues in a fresh sandbox. eve doesn't delete the old one. |
209
+ | The session ends | eve calls the provider's `onSessionEnd()` to delete the session's remaining sandbox. |
178
210
 
179
- Before that cleanup, session end ends the session's task runs, and each run ends the subagent sessions it opened. eve does not wait for those subagents to stop. A subagent step that is still running at that moment can open the sandbox again after cleanup, and eve does not remove a sandbox created that late.
211
+ Session end doesn't wait for running subagent steps to stop. A subagent step still running at that moment can reopen the sandbox after cleanup, and eve doesn't remove a sandbox created that late.
180
212
 
181
- Changing sandbox source, preparation code, Dockerfile content, environment options, workspace resources, or skills produces a new environment generation. Existing durable sessions keep their sandbox, because its identity comes from the session key alone; new sessions use the current generation.
213
+ New sessions get a new environment when you change the sandbox source, `prepare` code, Dockerfile, environment options, workspace seeds, or skills. Existing sessions keep their sandbox.
182
214
 
183
215
  ## What to read next
184
216
 
185
217
  - [Sandbox troubleshooting](/docs/sandbox/troubleshooting) explains common sandbox errors and how to fix them.
186
- - [Subagents](/docs/subagents) explains delegation and sandbox ownership.
218
+ - [Subagents](/docs/subagents) explains delegation and which agent's session a sandbox belongs to.
187
219
  - [Security model](/docs/concepts/security-model) describes the app-runtime and sandbox trust boundary.
188
220
  - [Vercel Sandbox](https://vercel.com/docs/sandbox) documents hosted sandbox behavior.
@@ -3,9 +3,9 @@ title: "just-bash Sandbox"
3
3
  description: "Use a pure-JavaScript shell and virtual filesystem."
4
4
  ---
5
5
 
6
- `JustBashSandbox.environment()` provides a shell and filesystem without starting a container or VM.
6
+ `JustBashSandbox.environment()` gives each session a pure-JavaScript shell and a virtual filesystem that keeps its files between turns. It starts no container or VM.
7
7
 
8
- ```ts
8
+ ```ts title="agent/sandbox.ts"
9
9
  import { defineSandbox } from "eve/sandbox";
10
10
  import { JustBashSandbox } from "eve/sandbox/just-bash";
11
11
 
@@ -13,21 +13,21 @@ export const environment = JustBashSandbox.environment();
13
13
  export default defineSandbox(() => environment.open());
14
14
  ```
15
15
 
16
- just-bash can prepare and persist its virtual filesystem. It cannot use OCI images or Dockerfiles, does not run native processes, and provides no network isolation. The session does not expose `setNetworkPolicy()`.
16
+ just-bash can't use OCI images or Dockerfiles, runs no native processes, and provides no network isolation. Its session has no `setNetworkPolicy()`.
17
17
 
18
18
  ## Automatic installation
19
19
 
20
- When an environment uses just-bash during `eve dev`, eve installs the package into your application if it is missing, unless you set `autoInstall: false` in the environment options. `DefaultSandbox` selects only one provider, but another environment, such as local self-modification, can use just-bash independently. Other environments require you to install the package yourself.
20
+ During `eve dev`, eve installs the `just-bash` package into your application when an environment uses it and it's missing. Set `autoInstall: false` in the environment options to skip this. Other commands require you to install the package yourself.
21
21
 
22
- For pnpm projects, automatic installation adds `@mongodb-js/zstd` and `node-liblzma` to `ignoredOptionalDependencies` in the owning `pnpm-workspace.yaml` when they have no explicit package policy. These optional native codecs are not needed for basic shell and filesystem operations. Commands that require those codecs may be unavailable without them. eve preserves existing package-specific build decisions and does not automatically approve build scripts.
22
+ With pnpm, automatic installation skips the optional native codecs `@mongodb-js/zstd` and `node-liblzma` unless they have an explicit package policy. It adds them to `ignoredOptionalDependencies` in the `pnpm-workspace.yaml` of the workspace that contains your app. Basic shell and filesystem operations don't need them, but commands that do may be unavailable. eve keeps your existing per-package build settings and doesn't approve build scripts.
23
23
 
24
24
  ## Experimental options
25
25
 
26
- `experimental.customCommands` and `experimental.filesystem` follow just-bash's own command and filesystem contracts, so they are experimental and have no compatibility promise. Their types, such as `JustBashCommand` and `JustBashFilesystem`, come from `eve/experimental/sandbox/just-bash`. `autoInstall` and `prepare` are stable.
26
+ `experimental.customCommands` and `experimental.filesystem` follow just-bash's own command and filesystem contracts, so they have no compatibility promise. Import their types, such as `JustBashCommand` and `JustBashFilesystem`, from `eve/experimental/sandbox/just-bash`. `autoInstall` and `prepare` are stable.
27
27
 
28
28
  ### Custom commands
29
29
 
30
- `experimental.customCommands` registers your own functions as commands in each live just-bash shell, where they work in pipelines and redirections:
30
+ `experimental.customCommands` adds your own functions as commands in each live shell. They work in pipelines and redirections:
31
31
 
32
32
  ```ts
33
33
  import { defineSandbox } from "eve/sandbox";
@@ -47,13 +47,19 @@ export const environment = JustBashSandbox.environment({
47
47
  export default defineSandbox(() => environment.open());
48
48
  ```
49
49
 
50
- A `JustBashCommand` receives `cwd`, `env`, `fs`, and `signal` in its context. When a command needs standard input or the rest of just-bash's command context, create it with `defineCommand()` from `just-bash`; `customCommands` accepts the result.
50
+ A `JustBashCommand` receives `cwd`, `env`, `fs`, and `signal` in its context. When a command needs standard input or the rest of just-bash's command context, create it with `defineCommand()` from `just-bash`. `experimental.customCommands` accepts the result.
51
51
 
52
- Custom commands run as application code in the app runtime process, outside the virtual filesystem. They are not available while eve prepares the template.
52
+ Custom commands run as app code in the app runtime process, outside the virtual filesystem. They aren't available while eve prepares the template.
53
53
 
54
54
  ### Custom filesystem
55
55
 
56
- `experimental.filesystem` composes the filesystem of each live sandbox. eve calls it with `defaultFilesystem`, the session's durable filesystem that holds `/workspace`, and `justBash`, the loaded `just-bash` module. Return a `JustBashFilesystem` that keeps `defaultFilesystem` as its base, such as a just-bash `MountableFs`:
56
+ `experimental.filesystem` builds the filesystem of each live sandbox. eve calls it with:
57
+
58
+ - `defaultFilesystem`: the session's saved filesystem that holds `/workspace`.
59
+ - `justBash`: the loaded `just-bash` module.
60
+ - `resolveProjectPath`: resolves a path relative to your app.
61
+
62
+ Return a `JustBashFilesystem` that keeps `defaultFilesystem` as its base, such as a just-bash `MountableFs`:
57
63
 
58
64
  ```ts
59
65
  import { defineSandbox } from "eve/sandbox";
@@ -82,6 +88,6 @@ export const environment = JustBashSandbox.environment({
82
88
  export default defineSandbox(() => environment.open());
83
89
  ```
84
90
 
85
- eve does not call `filesystem` while it prepares the template, so files under a mount are not part of the template.
91
+ eve does not call `experimental.filesystem` while it prepares the template, so files under a mount are not part of the template.
86
92
 
87
93
  See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.