eve 0.82.0 → 0.83.1

package/docs/sandbox/default.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Default Sandbox"
-description: "Let eve select the sandbox provider for the current environment."
+description: "Let eve select the sandbox provider when it prepares the sandbox."
 ---
 
-`DefaultSandbox.environment()` preserves eve's standard behavior without exposing provider-specific live creation options.
+`DefaultSandbox.environment()` selects a sandbox provider when eve prepares the sandbox, records the choice, and uses that provider for every session the build serves.
 
 ```ts
 import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -12,6 +12,73 @@ export const environment = DefaultSandbox.environment();
 export default defineSandbox(() => environment.open());
 ```
 
-On Vercel, it selects [Vercel Sandbox](/docs/sandbox/vercel). Elsewhere, it tries [Docker](/docs/sandbox/docker), [microsandbox](/docs/sandbox/microsandbox), and [just-bash](/docs/sandbox/just-bash), in that order, according to host support.
+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`.
 
-Use a provider directly when you need its image, VM, network, compute, or mount options.
+## How eve selects the provider
+
+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:
+
+1. If the `VERCEL` environment variable is set, it selects Vercel.
+2. Otherwise, if `docker version` reports a running Linux Docker daemon within five seconds, it selects Docker.
+3. Otherwise, during `eve dev` and `eve eval`, it selects just-bash.
+4. Otherwise, in a production `eve build`, it selects no provider.
+
+| Where eve prepares the sandbox                    | Selected provider                             |
+| ------------------------------------------------- | --------------------------------------------- |
+| On Vercel (`vercel build` or a Vercel deploy)     | [Vercel Sandbox](/docs/sandbox/vercel)        |
+| Anywhere a Linux Docker daemon is reachable       | [Docker](/docs/sandbox/docker)                |
+| `eve dev` or `eve eval` without Docker            | [just-bash](/docs/sandbox/just-bash)          |
+| A production `eve build` without Vercel or Docker | None: opening the sandbox fails with an error |
+
+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).
+
+## The build records the choice
+
+`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.
+
+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.
+
+## Environment options
+
+`DefaultSandbox.environment()` accepts options for each provider it might select. eve passes only the selected provider's options and ignores the rest:
+
+```ts
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+
+export const environment = DefaultSandbox.environment({
+  prepare: async (sandbox) => {
+    await sandbox.writeTextFile({ path: "notes/README.md", content: "Analysis notes\n" });
+  },
+  docker: { env: { APP_MODE: "agent" } },
+  vercel: { region: "iad1" },
+  justBash: { autoInstall: false },
+});
+
+export default defineSandbox(() => environment.open());
+```
+
+| Option     | Used when             | Accepts                                                                                                                             |
+| ---------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `prepare`  | Any provider          | Setup captured in the prepared environment. Replaces a `prepare` set inside the provider options.                                   |
+| `docker`   | Docker is selected    | The options of [`DockerSandbox.environment()`](/docs/sandbox/docker#environment-options), such as `image`, `env`, and `pullPolicy`. |
+| `vercel`   | Vercel is selected    | The options of [`VercelSandbox.environment()`](/docs/sandbox/vercel), such as `region`, `resources`, and credentials.               |
+| `justBash` | just-bash is selected | The options of [`JustBashSandbox.environment()`](/docs/sandbox/just-bash), such as `autoInstall` and `customCommands`.              |
+
+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`.
+
+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).
+
+## Network policy
+
+Pass `networkPolicy` to `open()`, or call `setNetworkPolicy()` on the session from `ctx.getSandbox(environment)`. eve forwards the policy to the selected provider:
+
+```ts
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+
+export const environment = DefaultSandbox.environment();
+export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
+```
+
+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.
+
+Use a provider directly when you need its other `open()` options, such as Vercel compute resources or Drive `mounts`.

package/docs/sandbox/docker.mdx

@@ -14,16 +14,28 @@ export const environment = DockerSandbox.image("ghcr.io/acme/agent@sha256:...");
 export default defineSandbox(() => environment.open({ networkPolicy: "deny-all" }));
 ```
 
-Use `DockerSandbox.environment()` for the default image or `DockerSandbox.dockerfile()` for the colocated Dockerfile convention.
+## Choose the base image
+
+`DockerSandbox.environment()`, `DockerSandbox.image()`, and `DockerSandbox.dockerfile()` all create the same Docker environment. They differ only in how you pass the base image:
+
+| Constructor                                 | Base image without a Dockerfile          |
+| ------------------------------------------- | ---------------------------------------- |
+| `DockerSandbox.environment({ image })`      | `image`, or eve's default image if unset |
+| `DockerSandbox.image("ghcr.io/acme/agent")` | The image reference you pass             |
+| `DockerSandbox.dockerfile()`                | eve's default image                      |
+
+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.
+
+`DockerSandbox.dockerfile()` does not accept an `image` option, which makes the Dockerfile convention explicit in your sandbox file.
 
 ## Environment options
 
-Image, pull policy, environment variables, and `prepare` belong to the reusable environment. During preparation, eve starts a temporary container, hydrates managed resources, runs authored preparation, and commits the result as the recorded template image.
+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.
 
 ## Live container options
 
 Pass `networkPolicy` to `open()`. Docker supports only `"allow-all"` and `"deny-all"`. The policy applies to the live container, not the prepared image.
 
-A session-owned container keeps writable `/workspace` state in its container filesystem. A stopped container restarts with that state.
+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.
 
 See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

package/docs/sandbox/index.mdx

@@ -3,7 +3,7 @@ title: "Sandbox"
 description: "Configure the isolated filesystem and command environment used by an eve agent."
 ---
 
-Every eve agent has one sandbox rooted at `/workspace`. The built-in `bash`, `read_file`, and `write_file` tools use it. Without an authored sandbox file, eve selects the best available environment automatically.
+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.
 
 ## Use the sandbox
 
@@ -26,7 +26,7 @@ export default defineTool({
 });
 ```
 
-Relative paths resolve under `/workspace`. `run()` returns `{ exitCode, stdout, stderr }`; a nonzero exit code does not throw automatically. Use `spawn()` for a long-running process.
+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.
 
 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.
 
@@ -43,7 +43,7 @@ For example, a Vercel environment returns a handle with `setNetworkPolicy()`. Th
 
 ## Define an environment
 
-A sandbox module exports an environment and returns a sandbox from `defineSandbox()`:
+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, eve reads the definition only from `agent/sandbox/sandbox.ts`.
 
 ```ts title="agent/sandbox.ts"
 import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -52,9 +52,9 @@ export const environment = DefaultSandbox.environment();
 export default defineSandbox(() => environment.open());
 ```
 
-`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()`.
+`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.
 
-Pass options for the live sandbox to `open()`, then configure the returned sandbox before returning it. This initialization runs once for a successfully started durable sandbox:
+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:
 
 ```ts
 import { defineSandbox } from "eve/sandbox";
@@ -69,6 +69,8 @@ export default defineSandbox(async ({ session }) => {
 });
 ```
 
+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/overview#returned-state) for when eve prewarms a session.
+
 The environment export is required because `eve build` prepares immutable environment inputs before a session exists.
 
 ### Prepare a reusable environment
@@ -91,15 +93,15 @@ export const environment = VercelSandbox.environment({
 export default defineSandbox(() => environment.open());
 ```
 
-eve runs `prepare` while creating a reusable provider artifact, not once for each live session sandbox. Vercel captures a snapshot; Docker captures an image; microsandbox captures a VM snapshot; and just-bash captures a filesystem template.
+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.
 
 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.
 
-`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.
+`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.
 
 ### Reuse native resources across sessions
 
-Built-in environments do not expose cross-session sharing. To reuse native compute or storage across eve sessions, define a custom provider that returns a session-owned logical sandbox view and keeps shared resources outside that view's `stop`, `shutdown`, and `delete` operations. A session-specific path is not an isolation boundary; mutually untrusted sessions require separate native compute or stronger provider-owned isolation.
+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.
 
 ### Share a parent sandbox
 
@@ -113,6 +115,8 @@ export default defineParentSandbox();
 
 An inheriting subagent cannot declare its own managed workspace or skill files.
 
+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.
+
 ## Managed workspace and skills
 
 Use the sandbox directory for authored workspace seeds:
@@ -124,38 +128,19 @@ agent/sandbox/
     schema.sql
 ```
 
-Files under `agent/sandbox/workspace/` seed writable `/workspace`. eve copies the seed when it prepares a new environment generation. Existing live sandbox state is not overwritten by later seed changes.
-
-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`. Do not refer to a concrete home directory or `/eve/resources`, which is provider-internal staging.
+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.
 
-Providers receive both trees with explicit metadata:
+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.
 
-```ts
-interface SandboxProviderResources {
-  source:
-    | { kind: "none" }
-    | { kind: "inline"; key: string }
-    | { kind: "materialized"; key: string; path: string }
-    | { kind: "reference"; key: string };
-  workspace?: SandboxProviderResourceTree;
-  skills?: SandboxProviderResourceTree;
-}
-
-interface SandboxProviderResourceTree {
-  key: string;
-  files: ResourceFile[];
-  mountPath: string;
-  targetPath: string;
-}
-```
-
-Docker and microsandbox mount the compiled trees read-only under `/eve/resources`, copy workspace seeds into writable `/workspace`, and expose skills read-only where possible. Vercel's snapshot environment writes workspace and skill contents before capturing its snapshot. Custom providers decide whether to upload, mount, or write each tree, but must expose the final target paths before authored preparation runs.
+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).
 
 ## Inbound attachments
 
-eve writes byte-backed files that reach the agent into the sandbox under `/workspace/.eve/attachments/` 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.
+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.
+
+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).
 
-Before every model call, eve reads the referenced files back from the sandbox. Every file, whether attached to a message or returned by a tool, reaches the model 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:
+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:
 
 - A PNG, JPEG, GIF, or WebP image up to 3 MiB and at most 8000 pixels per side.
 - A PDF up to 20 MiB.
@@ -164,7 +149,7 @@ Other files, such as CSV, HEIC, audio, and video, reach the model as the label a
 
 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).
 
-If a referenced file 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.
+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.
 
 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.
 
@@ -172,87 +157,28 @@ Each call sends the same bytes for the same file, so the model still sees attach
 
 ## Custom providers
 
-Define a provider with `defineSandboxProvider()` from `eve/sandbox/provider`. The five generic parameters describe environment options, live options, the prepared artifact, minimal serialized session state, and the provider-specific sandbox session type:
-
-```ts
-import type { SandboxSession } from "eve/sandbox";
-import { defineSandboxProvider } from "eve/sandbox/provider";
-
-export const AcmeSandbox = defineSandboxProvider<
-  { image: string; prepare?: (sandbox: SandboxSession) => Promise<void> },
-  { networkPolicy?: "allow-all" | "deny-all" },
-  { templateId: string },
-  { remoteId: string; version: 1 },
-  SandboxSession
->({
-  name: "acme",
-  environment(options) {
-    const client = createAcmeClient(options);
-
-    return {
-      async onSessionEnd(_ctx, _artifact, state, { reason }) {
-        await client.delete({ id: state.remoteId, reason });
-      },
-
-      async prepare(ctx) {
-        const temporary = await client.createTemporary({
-          files: await ctx.files.list(),
-          resources: ctx.resources,
-        });
-        const sandbox = adaptAcmeSandbox(temporary);
-        await options?.prepare?.(sandbox);
-        return { templateId: (await temporary.capture()).id };
-      },
-
-      async start(ctx, liveOptions, artifact) {
-        const remote = await client.open({
-          identity: sessionIdentity(ctx.session.id, artifact, liveOptions),
-          networkPolicy: liveOptions?.networkPolicy,
-          templateId: artifact.templateId,
-        });
-        return {
-          handle: createHandle(remote),
-          state: { remoteId: remote.id, version: 1 },
-        };
-      },
-
-      async resume(_ctx, artifact, state) {
-        const remote = await client.resume({ id: state.remoteId, templateId: artifact.templateId });
-        return createHandle(remote);
-      },
-    };
-  },
-});
-```
-
-`prepare()` returns the complete JSON-serializable artifact. Core calls `start()` once for a new durable sandbox session and persists its minimal JSON-compatible state. Process restarts call `resume()` with only the current context, that state, and the target deployment's exact artifact.
-
-`onSessionEnd()` is invoked when the durable session reaches a completed, expired, or failed terminal outcome. It receives the exact prepared artifact, persisted provider state, and a `reason` of `"completed"`, `"expired"`, or `"failed"`. Implement idempotent permanent cleanup from those values rather than depending on a live handle. eve retries the cleanup step and logs an exhausted failure without replacing the session's terminal outcome. A session that never opened a sandbox and a child that borrows its parent's sandbox do not call the hook.
-
-Provider handles implement `onSandboxStop()`, `onRuntimeShutdown()`, and `onSandboxDelete()`. These handle-level methods cover authored stop or delete calls, process shutdown, and failed initialization; `onSessionEnd()` is the single provider hook for durable terminal session cleanup.
-
-Open options belong to `start()` and are not serialized or passed to `resume()`. A provider must put any immutable option-derived data needed for reconnection in its session state. With the current immutable-state contract, `resume()` reconnects existing native state and fails if it is gone rather than recreating callback side effects. A custom provider may define start-only callback fields, but built-in providers initialize the sandbox in `defineSandbox()` after `open()`.
-
-Preparation discovers authored files through `ctx.files`; core keeps project layout and artifact storage keys private. Keep provider SDK values behind the provider. `environment.open()` preserves the provider's sandbox capability type, while the heterogeneous runtime registry erases it to eve's common session surface.
+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.
 
 ## Providers
 
-| Provider                                   | Use it for                                                                              |
-| ------------------------------------------ | --------------------------------------------------------------------------------------- |
-| [Default](/docs/sandbox/default)           | Automatic provider selection with eve's standard behavior.                              |
-| [Vercel](/docs/sandbox/vercel)             | Snapshot-backed persistent Vercel Sandboxes, domain network policies, and Drive mounts. |
-| [Docker](/docs/sandbox/docker)             | Local containers from the default image, an existing OCI image, or a Dockerfile.        |
-| [microsandbox](/docs/sandbox/microsandbox) | Local lightweight VMs from an OCI image or Dockerfile.                                  |
-| [just-bash](/docs/sandbox/just-bash)       | A pure-JavaScript shell and virtual filesystem without native process isolation.        |
+| Provider                             | Use it for                                                                                  |
+| ------------------------------------ | ------------------------------------------------------------------------------------------- |
+| [Default](/docs/sandbox/default)     | Vercel Sandbox on Vercel, Docker when reachable, and just-bash in development.              |
+| [Vercel](/docs/sandbox/vercel)       | Persistent Vercel Sandboxes, prepared snapshots, domain network policies, and Drive mounts. |
+| [Docker](/docs/sandbox/docker)       | Local containers from the default image, an existing OCI image, or a Dockerfile.            |
+| [just-bash](/docs/sandbox/just-bash) | A pure-JavaScript shell and virtual filesystem without native process isolation.            |
 
 ## Lifecycle
 
-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()` clears provider state, so the next `ctx.getSandbox()` reruns the selector and starts a fresh sandbox from the current environment. When the durable session reaches a terminal outcome, eve calls the provider's `onSessionEnd()` hook to release any remaining session-owned resources.
+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.
+
+Before that cleanup, session end ends the session's task runs, and each run resets 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.
 
-Changing sandbox source, preparation code, Dockerfile content, environment options, workspace resources, or skills produces a new environment generation. Existing durable sessions retain their recorded sandbox state; new sessions use the current generation.
+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.
 
 ## What to read next
 
+- [Sandbox troubleshooting](/docs/sandbox/troubleshooting) explains common sandbox errors and how to fix them.
 - [Subagents](/docs/subagents) explains delegation and sandbox ownership.
 - [Security model](/docs/concepts/security-model) describes the app-runtime and sandbox trust boundary.
 - [Vercel Sandbox](https://vercel.com/docs/sandbox) documents hosted sandbox behavior.

package/docs/sandbox/just-bash.mdx

@@ -21,4 +21,58 @@ When an environment uses just-bash during `eve dev`, eve installs the package in
 
 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.
 
+## Custom commands
+
+`customCommands` registers your own functions as commands in each live just-bash shell, where they work in pipelines and redirections. Write a `JustBashCommand` from `eve/sandbox/just-bash`:
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { JustBashSandbox, type JustBashCommand } from "eve/sandbox/just-bash";
+
+const today: JustBashCommand = {
+  name: "today",
+  async execute() {
+    return { exitCode: 0, stderr: "", stdout: `${new Date().toISOString().slice(0, 10)}\n` };
+  },
+};
+
+export const environment = JustBashSandbox.environment({ customCommands: [today] });
+export default defineSandbox(() => environment.open());
+```
+
+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.
+
+Custom commands run as application code in the app runtime process, outside the virtual filesystem. They are not available while eve prepares the template.
+
+## Custom filesystem
+
+`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`:
+
+```ts
+import { defineSandbox } from "eve/sandbox";
+import { JustBashSandbox } from "eve/sandbox/just-bash";
+
+export const environment = JustBashSandbox.environment({
+  async filesystem({ defaultFilesystem, justBash, resolveProjectPath }) {
+    await defaultFilesystem.mkdir("/reference", { recursive: true });
+    return new justBash.MountableFs({
+      base: defaultFilesystem,
+      mounts: [
+        {
+          filesystem: new justBash.OverlayFs({
+            mountPoint: "/",
+            readOnly: true,
+            root: resolveProjectPath("reference"),
+          }),
+          mountPoint: "/reference",
+        },
+      ],
+    });
+  },
+});
+export default defineSandbox(() => environment.open());
+```
+
+eve does not call `filesystem` while it prepares the template, so files under a mount are not part of the template.
+
 See the [sandbox overview](/docs/sandbox) for managed workspace, skills, parent inheritance, and custom providers.

package/docs/sandbox/meta.json

@@ -1,5 +1,13 @@
 {
   "title": "Sandbox",
   "defaultOpen": false,
-  "pages": ["index", "default", "vercel", "docker", "microsandbox", "just-bash"]
+  "pages": [
+    "index",
+    "default",
+    "vercel",
+    "docker",
+    "just-bash",
+    "custom-providers",
+    "troubleshooting"
+  ]
 }