eve 0.81.1 → 0.83.0

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";
@@ -54,7 +54,7 @@ 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()`.
 
-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, or on the next access after an initialization that failed. Make it safe to repeat:
 
 ```ts
 import { defineSandbox } from "eve/sandbox";
@@ -91,15 +91,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 +113,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,36 +126,17 @@ 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.
-
-Providers receive both trees with explicit metadata:
+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.
 
-```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;
-}
-```
+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.
 
-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:
 
@@ -172,87 +155,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"
+  ]
 }

package/docs/sandbox/troubleshooting.mdx

@@ -0,0 +1,215 @@
+---
+title: "Sandbox Troubleshooting"
+description: "Causes and fixes for common eve sandbox errors in the sandbox file, after a build, when a session resumes, and during eve dev."
+---
+
+Sections whose heading is in code format start with the beginning of an error message, so you can search this page for the text you see. Most sandbox errors come from one of three mismatches: the sandbox file does not match what eve expects, the build output does not match the runtime, or a session's recorded sandbox does not match the current agent.
+
+## Errors in the sandbox file
+
+### `must export an environment`
+
+```text
+Sandbox "sandbox.ts" must export an environment.
+```
+
+eve compiles the sandbox file during `eve build` and `eve dev`, and it needs the environment as a named `environment` export so it can prepare it before any session exists. Export the environment that the selector opens:
+
+```ts title="agent/sandbox.ts"
+import { DefaultSandbox, defineSandbox } from "eve/sandbox";
+
+export const environment = DefaultSandbox.environment();
+export default defineSandbox(() => environment.open());
+```
+
+### `opened an environment other than the one it exports`
+
+```text
+Sandbox "sandbox.ts" opened an environment other than the one it exports as `environment`.
+```
+
+The selector called `open()` on a different environment object than the exported `environment`. This happens when the selector creates an environment inline, such as `DefaultSandbox.environment().open()`, or imports another sandbox file's environment. Create the environment once at module scope, export it, and call `environment.open()` on that export.
+
+### `can open only one sandbox`
+
+```text
+A sandbox definition can open only one sandbox.
+```
+
+The selector called `environment.open()` more than once. Call `environment.open()` once in the `defineSandbox()` selector and return that sandbox.
+
+### `can only open sandboxes inside defineSandbox()`
+
+```text
+Sandbox environments can only open sandboxes inside defineSandbox().
+```
+
+Code outside the `defineSandbox()` selector called `environment.open()`, for example a tool or a module's top level. Only the selector opens the sandbox. From tools and other runtime code, use `ctx.getSandbox()` to reach the session's sandbox, or `ctx.getSandbox(environment)` to keep the provider-specific session type.
+
+### `selects parent.sandbox but agent node ... has no parent`
+
+```text
+Sandbox "sandbox.ts" selects parent.sandbox but agent node "..." has no parent.
+```
+
+The sandbox file uses `defineParentSandbox()`, but the agent is not a declared subagent, so it has no parent sandbox to share. eve reports this when it loads the agent graph. Only a declared subagent can [share its parent's sandbox](/docs/sandbox#share-a-parent-sandbox). Give this agent its own sandbox file with `defineSandbox()` and an exported environment.
+
+## Errors after a build or deploy
+
+Production never prepares sandbox environments. `eve build` prepares them and records one artifact for each agent sandbox, such as a Docker image, a Vercel snapshot, or a just-bash template, and the runtime only uses those recorded artifacts.
+
+### `No prepared ... sandbox environment is recorded`
+
+```text
+No prepared "docker" sandbox environment is recorded for agent node "...".
+```
+
+The deployed build output has no prepared artifact for this agent. This usually means the output came from `eve build --skip-sandbox-prewarm`, which [the CLI reference](/docs/reference/cli) marks as not deployable. Run `eve build` without that flag and deploy its output together with the runtime.
+
+### `The prepared sandbox artifact ... was created with provider`
+
+```text
+The prepared sandbox artifact for agent node "..." was created with provider "vercel", but this process selects provider "docker".
+```
+
+The sandbox file selected one provider when eve prepared the sandbox and a different one in the process that uses it. This happens when the sandbox file chooses a provider by reading the host, for example with `process.env.VERCEL ? VercelSandbox.environment() : DockerSandbox.environment()`, and the build and runtime hosts differ. `DefaultSandbox.environment()` does not cause this, because it [records its choice when it prepares the sandbox](/docs/sandbox/default#the-build-records-the-choice). Select one provider explicitly, or use `DefaultSandbox.environment()`, then rebuild with `eve build`, or restart `eve dev` locally.
+
+### `DefaultSandbox has no sandbox provider for this build`
+
+```text
+DefaultSandbox has no sandbox provider for this build: it did not run on Vercel, no Docker daemon was reachable, and production builds do not fall back to just-bash.
+```
+
+The production `eve build` ran outside Vercel without a reachable Docker daemon, so `DefaultSandbox` recorded no provider, and the first session that opens the sandbox fails. A `RUN eve build` step in a Dockerfile usually has no Docker daemon, even when the running container later mounts `/var/run/docker.sock`. Start Docker and run `eve build` again, deploy to Vercel, or select a provider explicitly in the sandbox file, for example `DockerSandbox.environment()` from `eve/sandbox/docker`. See [How eve selects the provider](/docs/sandbox/default#how-eve-selects-the-provider).
+
+### `Sandbox template ... is not available to this runtime`
+
+```text
+Sandbox template "..." for provider "docker" is not available to this runtime.
+```
+
+The build recorded an artifact, but the provider can no longer use its template. When the provider knows the cause, the message includes it:
+
+| Provider  | Common cause                                                                                                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Docker    | The Docker daemon has no image with that name: it was removed, for example by `docker image prune -a`, or the build used another Docker daemon. |
+| Vercel    | The Vercel Sandbox snapshot expired or was deleted.                                                                                             |
+| just-bash | The template directory under `.eve/sandbox-cache/` was deleted, or the build ran on another machine.                                            |
+| Custom    | The image, snapshot, or template that the artifact names no longer exists, so the provider threw `SandboxTemplateNotProvisionedError`.          |
+
+The runtime never recreates a template. Run `eve build` again and deploy its output.
+
+### `Invalid prepared ... artifact`
+
+```text
+Invalid prepared Docker sandbox artifact.
+```
+
+The recorded artifact does not match the format that this eve version expects, usually because the build used a different eve version than the runtime. Run `eve build` with the same eve version that the runtime uses, then redeploy.
+
+## Errors when a session resumes
+
+A session records which provider created its sandbox, and later turns resume that sandbox directly without running the selector again.
+
+### `This session's sandbox was created by provider`
+
+```text
+This session's sandbox was created by provider "just-bash", but the agent now selects provider "docker".
+```
+
+eve logs this warning when a session resumes on a build whose sandbox file selects a different provider than the one that created the session's sandbox, for example after you change providers or `DefaultSandbox` records a different choice in a new build. eve cannot move a sandbox between providers, so the session continues in a fresh sandbox from the current provider, without the old sandbox's files. eve does not delete the old sandbox. Remove it with the old provider's tooling, for example `docker rm` for a Docker container. To keep the session's files instead, restore the previous provider before the session resumes.
+
+### `DefaultSandbox selected just-bash, which always allows network access`
+
+```text
+DefaultSandbox selected just-bash, which always allows network access and accepts only the "allow-all" network policy.
+```
+
+The sandbox passed a `networkPolicy` other than `"allow-all"` to `open()`, or called `setNetworkPolicy()`, while `DefaultSandbox` uses just-bash during `eve dev` or `eve eval` because Docker is not reachable. just-bash cannot restrict network access. Start Docker and restart `eve dev` so `DefaultSandbox` selects Docker, or select `VercelSandbox.environment()` or `DockerSandbox.environment()` explicitly.
+
+### `Invalid ... session state`
+
+```text
+Invalid Docker sandbox session state.
+```
+
+The session's recorded sandbox state does not match the format that this eve version expects, usually because the session started under a different eve version. Start a new session to get a fresh sandbox.
+
+## Errors during eve dev
+
+During `eve dev`, the first sandbox access prepares every sandbox environment in the current build. See [Prepare a reusable environment](/docs/sandbox#prepare-a-reusable-environment).
+
+### `Timed out after 10 minutes waiting for another request or eve dev worker`
+
+```text
+Timed out after 10 minutes waiting for another request or eve dev worker to prepare sandbox environments (this request needs provider "docker").
+```
+
+Another request or `eve dev` worker is still preparing environments. Check the `eve dev` output, or run `eve logs`, to find the slow step, such as an image pull, a Dockerfile build, or a `prepare` callback. Retry after preparation finishes, or restart `eve dev` to cancel it.
+
+## Custom provider errors
+
+These errors come from a provider defined with `defineSandboxProvider()`, or from a keyed tool call on a provider that cannot keep its sandbox. See [Custom sandbox providers](/docs/sandbox/custom-providers).
+
+### `cannot keep a sandbox between invokeTool calls`
+
+```text
+Sandbox provider "acme" cannot keep a sandbox between invokeTool calls, so a call with a key cannot open one.
+```
+
+A keyed `invokeTool` call, such as an MCP tool session, requested the sandbox, and the provider does not keep sandboxes between calls. Call the tool without a key, use Vercel Sandbox or just-bash, or set `toolSessions: true` on a custom provider that bounds how long it keeps those sandboxes. Docker does not support keyed calls. See [Keep sandboxes for keyed tool calls](/docs/sandbox/custom-providers#keep-sandboxes-for-keyed-tool-calls).
+
+### `Sandbox connection extensions cannot replace the session members eve provides`
+
+```text
+Sandbox connection extensions cannot replace the session members eve provides: run. Rename them.
+```
+
+The connection's `extensions` define a member that eve already provides on every sandbox session, such as `run`, `readFile`, `stop`, or `delete`. Rename the extension member.
+
+### `ctx.templateKey() reserves`
+
+```text
+ctx.templateKey() reserves "sourceRevision": eve adds the workspace and skill files and the sandbox source revision itself.
+```
+
+The identity passed to `ctx.templateKey()` in `prepare()` sets `resources` or `sourceRevision`. eve adds both to every template key. Rename that identity field.
+
+### `returned non-serializable session state`
+
+```text
+Sandbox provider "acme" returned non-serializable session state.
+```
+
+`start()` returned state that is not JSON-compatible, such as a class instance, a function, or `undefined`. Return only strings, numbers, booleans, `null`, arrays, and plain objects, and keep live clients in the connection instead.
+
+## Provider setup errors
+
+### Docker is not installed or not running
+
+```text
+The Docker sandbox provider requires Docker, but the `docker` CLI was not found.
+The Docker sandbox provider requires a running Docker daemon, but it is not reachable.
+```
+
+Install and start Docker Desktop, OrbStack, Colima, or another runtime with a Docker-compatible `docker` CLI. To use another compatible CLI, such as Podman, set `EVE_DOCKER_PATH` to its path. If you do not need Docker specifically, use `DefaultSandbox.environment()`, which falls back to just-bash during `eve dev` and `eve eval`.
+
+### The just-bash package is missing
+
+```text
+The just-bash sandbox provider requires the `just-bash` package, which is not bundled with eve.
+```
+
+`eve dev` installs `just-bash` automatically unless the environment sets `autoInstall: false`. Other commands require you to install it. Add it to your application, for example with `pnpm add -D just-bash`, which matches what `eve dev` installs. See [just-bash Sandbox](/docs/sandbox/just-bash#automatic-installation).
+
+### `Cannot build deployable Vercel output because this app requires sandbox templates`
+
+```text
+Cannot build deployable Vercel output because this app requires sandbox templates and VERCEL_OIDC_TOKEN is missing.
+```
+
+eve raises this during a Vercel build, when `VERCEL` is set, if the app needs sandbox templates prepared and `VERCEL_OIDC_TOKEN` is missing. Do not deploy the `.vercel/output` from a build that failed this way. For a local `vercel build`, run `vercel link` and `vercel pull`, then retry. In a build on Vercel, Vercel sets `VERCEL_OIDC_TOKEN` automatically; see [Vercel OIDC federation](https://vercel.com/docs/oidc).
+
+### Vercel Sandbox authentication fails
+
+When `eve build` or the runtime cannot create a Vercel Sandbox because of missing or expired credentials, the Vercel Sandbox SDK reports an authentication or OIDC token error. Locally, run `eve link` to link a project and pull `VERCEL_OIDC_TOKEN` into `.env.local`. Outside Vercel without a linked project, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`. See [Vercel Sandbox authentication](/docs/sandbox/vercel#authentication) for the full resolution order.

package/docs/sandbox/vercel.mdx

@@ -1,9 +1,9 @@
 ---
 title: "Vercel Sandbox"
-description: "Create snapshot-backed persistent sandboxes on Vercel."
+description: "Create persistent sandboxes on Vercel, from a prepared snapshot when the environment has build-time setup."
 ---
 
-`VercelSandbox.environment()` prepares a reusable Vercel Sandbox snapshot and creates persistent session sandboxes from its recorded snapshot ID.
+`VercelSandbox.environment()` prepares a reusable Vercel Sandbox snapshot when the environment has build-time setup, and creates persistent session sandboxes from its recorded snapshot ID.
 
 ```ts
 import { defineSandbox } from "eve/sandbox";
@@ -27,12 +27,40 @@ export default defineSandbox(() =>
 );
 ```
 
+## Authentication
+
+eve needs a Vercel token, team ID, and project ID to create Vercel Sandboxes. `eve build` needs them to capture the snapshot, and the runtime needs them to create and resume session sandboxes. Deployments on Vercel provide them automatically.
+
+eve resolves each value from the first source that is set:
+
+| Value      | Sources, in order                                               |
+| ---------- | --------------------------------------------------------------- |
+| Token      | `token` environment option, `VERCEL_OIDC_TOKEN`, `VERCEL_TOKEN` |
+| Team ID    | `teamId` environment option, `VERCEL_TEAM_ID`, `VERCEL_ORG_ID`  |
+| Project ID | `projectId` environment option, `VERCEL_PROJECT_ID`             |
+
+When all three resolve, eve uses them. Otherwise, eve requests a Vercel OIDC token and reads the team and project from the token. On Vercel, the deployment provides that token. Elsewhere, eve reads `VERCEL_OIDC_TOKEN` and, when it is missing or expired, refreshes it with your Vercel CLI login and the project linked in `.vercel/project.json`. If that also fails, eve falls back to the Vercel Sandbox SDK's own credential lookup, which reports an authentication error if it finds none.
+
+For local development, link the app to a Vercel project and pull its environment into `.env.local`:
+
+```bash
+eve link
+```
+
+`vercel link` followed by `vercel env pull` produces the same `.env.local`. A running `eve dev` reloads env files automatically.
+
+Outside Vercel and without a linked project, such as in CI or on a self-hosted server, set `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, and `VERCEL_PROJECT_ID`, or pass `token`, `teamId`, and `projectId` to `VercelSandbox.environment()`.
+
 ## Snapshot preparation
 
-eve creates a temporary persistent Vercel Sandbox during build, installs the base runtime, writes managed workspace and skill files, runs the authored `prepare` callback, and captures a snapshot. The build artifact records the snapshot ID.
+eve creates a temporary, non-persistent Vercel Sandbox during build, installs the base runtime, writes managed workspace and skill files, and runs the authored `prepare` callback. It then checks the base runtime again before capturing the snapshot, so a `prepare` callback that breaks it fails the build. The build artifact records the snapshot ID.
 
 When a live session sandbox does not exist, eve creates it directly from that snapshot ID. Runtime does not need to look up the temporary template Sandbox.
 
+When the environment has no `prepare` callback, no managed workspace or skill files, and no `source`, a snapshot would contain only the base runtime. eve skips it: the build records no snapshot ID, and each new session sandbox starts from the image and installs the base runtime itself. A `source` always produces a snapshot, so sessions start from what the build captured instead of fetching the source again.
+
+A new session sandbox created from a prepared snapshot of the standard eve image, without Drive mounts, inherits the base runtime the build checked and runs no setup command. Existing or resumed sandboxes, custom images or snapshot sources, sandboxes with Drive mounts, and sandboxes created without a prepared snapshot still run base-runtime setup when eve attaches them.
+
 ## Initialize after open
 
 Initialize session-specific state after `open()` and before returning the sandbox. This selector writes a configuration file into the persistent `/workspace` filesystem:
@@ -67,6 +95,8 @@ export default defineSandbox(async () => {
 });
 ```
 
+Relative paths, including a relative `workingDirectory` passed to `run()` or `spawn()`, resolve from `/workspace`.
+
 Use the environment's `prepare` callback for immutable setup that every new session should inherit. Use post-open initialization for state that belongs only to one durable session.
 
 ## Network policy
@@ -106,11 +136,16 @@ const sandboxName = sandbox.name;
 
 ## Mount a Drive
 
-A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. Create or retrieve the Drive before calling `open()`, then pass it in `mounts` under an absolute path:
+A [Vercel Sandbox Drive](https://vercel.com/docs/sandbox/concepts/drives) stores files independently of a sandbox. Install `@vercel/sandbox` in your app, create or retrieve the Drive before calling `open()`, then pass it in `mounts` under an absolute path:
+
+```bash
+pnpm add @vercel/sandbox
+```
 
 ```ts
+import { Drive } from "@vercel/sandbox";
 import { defineSandbox } from "eve/sandbox";
-import { Drive, VercelSandbox } from "eve/sandbox/vercel";
+import { VercelSandbox } from "eve/sandbox/vercel";
 
 const REGION = "iad1";
 
@@ -130,6 +165,8 @@ export default defineSandbox(async () => {
 });
 ```
 
+`Drive.getOrCreate()` comes from your app's own `@vercel/sandbox`, so it resolves credentials through the SDK, not eve: it reads `token`, `teamId`, and `projectId` passed to it, or a Vercel OIDC token, which the SDK refreshes from your Vercel CLI login and linked project. It does not read `VERCEL_TOKEN`, `VERCEL_TEAM_ID`, `VERCEL_PROJECT_ID`, or the credentials passed to `VercelSandbox.environment()`, so outside Vercel without a linked project, pass them to `Drive.getOrCreate()` too.
+
 This example mounts the Drive read-write at `/data`. Files written there remain on the Drive after the sandbox stops. Keep Drive mounts separate from eve's managed `/workspace` directory.
 
 Set the same region on the environment and the Drive. The environment region places the prepared snapshot and each session sandbox together with the Drive.
@@ -148,13 +185,17 @@ return environment.open({
 
 Before mounting `drive.snapshot()`, seed a new Drive by mounting it read-write and writing at least one file. An uninitialized Drive cannot be mounted as a snapshot.
 
+Each `mounts` entry is a `Drive`, which mounts read-write, or a `{ drive, mode }` reference to an existing Drive by name, where `mode` is `"read-write"` or `"snapshot"`. `drive.snapshot()` returns such a reference.
+
 Vercel allows up to four non-overlapping, absolute Drive mount paths per sandbox. See the Vercel documentation for [Drive lifecycle, limits, and pricing](https://vercel.com/docs/sandbox/concepts/drives).
 
 ## Live sandbox options
 
-`open()` also accepts Vercel compute resources, timeout, and Drive mounts. Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.
+`open()` also accepts Vercel compute resources, timeout, environment variables, and Drive mounts. These options apply only when creating the sandbox. Reopening the same key or resuming recorded state keeps the native sandbox's original environment variables, mounts, and network policy. Pass `env` to `run()` or `spawn()` for a per-command override, or call `setNetworkPolicy()` to change the live network policy.
+
+Configure project credentials and custom fetch behavior on the environment, not in `open()`, because resume does not reconstruct start-only options.
 
-Initialize the returned sandbox directly in `defineSandbox()`. If initialization fails, eve deletes the newly started sandbox and retries the selector on the next access. After initialization succeeds, the provider persists only immutable JSON-compatible state. If the named Vercel Sandbox later disappears, resume fails rather than recreating initialization side effects.
+Initialize the returned sandbox directly in `defineSandbox()`. If initialization fails, eve keeps the sandbox and runs the selector against it again on the next access, so make initialization safe to repeat; session end deletes the sandbox. After initialization succeeds, the provider persists only immutable JSON-compatible state. If the named Vercel Sandbox later disappears, resume does not recreate it; eve reruns the selector to start a fresh sandbox instead.
 
 eve owns the persistent sandbox identity and prepared snapshot source.
 

package/docs/schedules.mdx

@@ -7,6 +7,8 @@ A schedule starts the agent on its own clock instead of waiting for an inbound m
 
 The name comes from the path under `schedules/` (`agent/schedules/billing/sweep.ts` → `"billing/sweep"`), and nested directories are fine. An extension mount prefixes that name (`extension/schedules/sweep.ts` mounted as `crm` → `"crm__sweep"`) without changing its cron expression.
 
+For creator-owned schedules created and managed at runtime, see [Experimental dynamic schedules](./experimental/dynamic-schedules). `defineSchedule` remains the fixed, code-authored cron API.
+
 ## `defineSchedule`
 
 Every schedule provides a `cron` and exactly one of `markdown` or `run`: