Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

docs(sandbox): fix contradictions and make sandbox errors actionable (#5227)

Andrew Barbabd050f8aaef0
diff --git a/.changeset/clearer-sandbox-errors.md b/.changeset/clearer-sandbox-errors.md
new file mode 100644
index 000000000..08c3ee8de
--- /dev/null
+++ b/.changeset/clearer-sandbox-errors.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Clearer sandbox error messages. Sandbox errors now say what went wrong and how to fix it, for example when the build and the runtime select different providers, a prepared template is missing, a session's sandbox came from another provider, or the sandbox file does not export its environment.
diff --git a/docs/concepts/security-model.md b/docs/concepts/security-model.md
index 6f14cd023..273e88304 100644
--- a/docs/concepts/security-model.md
+++ b/docs/concepts/security-model.md
@@ -18,6 +18,8 @@ The app runtime is the trusted side. Your tool implementations, model calls, con
The sandbox is the isolated side. The model runs shell commands and accesses files there through the default `bash`, `read_file`, and `write_file` tools and any opt-in sandbox tools such as `glob` and `grep`. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) Only shell commands execute in the sandbox. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
+The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
+
A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
See [Agent loop and sandbox](./execution-model-and-durability#agent-loop-and-sandbox) for how eve connects these contexts while keeping their state and lifetimes separate.
diff --git a/docs/reference/agent-files.md b/docs/reference/agent-files.md
index 2e0de262a..7378d5cc5 100644
--- a/docs/reference/agent-files.md
+++ b/docs/reference/agent-files.md
@@ -58,8 +58,8 @@ Paths below are relative to the agent directory. Root agents can use every path;
| `skills/` | On-demand procedures and capability packs | Yes | Flat Markdown, module-backed skills, or packaged skills. |
| `lib/` | Shared authored helper code | Yes | Import-only; not copied into the sandbox. |
| `memory.ts` or `memory/<name>.ts` | Cross-session memory | Yes | Provider-backed slots. See [Memory](/docs/memory). |
-| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's sandbox | Yes | The framework default applies when neither is authored. |
-| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Mirrored into `/workspace/` when a session starts. |
+| `sandbox.ts` or `sandbox/sandbox.ts` | The agent's sandbox | Yes | The framework default applies when neither is authored. When `sandbox/` exists, only `sandbox/sandbox.ts` is read. |
+| `sandbox/workspace/**` | Files seeded into the sandbox | Yes | Copied into the prepared environment; each new session sandbox starts with them in `/workspace/`. |
| `tools/` | Typed executable integrations | Yes | Module-backed only. |
| `schedules/` | Recurring jobs | No | `defineSchedule` modules or Markdown prompts with `cron` frontmatter; recursive nesting is supported. |
| `subagents/` | Specialist child agents | Yes | Local directories or remote-agent definitions; nested subagents are supported. |
@@ -82,7 +82,7 @@ Explicit imports, sandbox workspace files, and packaged skill resources are unaf
## Files available in the sandbox
-Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's `/workspace/` under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `/workspace/skills/` as a fallback. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).
+Agent source files are not automatically available to shell commands. Put files to copy into the sandbox's `/workspace/` under `agent/sandbox/workspace/`. Skill runtime files are seeded separately under `$HOME/.agents/skills/`, with `/workspace/skills/` as the fallback when the sandbox has no usable `$HOME`. See [Sandboxes](/docs/sandbox) and [Skills](/docs/skills).
## Local subagents
diff --git a/docs/reference/typescript-api.md b/docs/reference/typescript-api.md
index 5ab1c76ba..72b7d4082 100644
--- a/docs/reference/typescript-api.md
+++ b/docs/reference/typescript-api.md
@@ -48,7 +48,9 @@ export default defineTool({
| `defineHook` | `eve/hooks` | `agent/hooks/<slug>.ts` | [Hooks](../guides/hooks) |
| `defineSchedule` | `eve/schedules` | `agent/schedules/<name>.ts` | [Schedules](../schedules) |
| `defineState` | `eve/context` | tools, hooks, lifecycle | [Session context](../guides/session-context) |
-| `defineSandbox` | `eve/sandbox` | `agent/sandbox.ts` | [Sandbox](../sandbox) |
+| `defineSandbox` | `eve/sandbox` | `agent/sandbox.ts` or `agent/sandbox/sandbox.ts` | [Sandbox](../sandbox) |
+| `defineParentSandbox` | `eve/sandbox` | `agent/subagents/<name>/sandbox.ts` | [Sandbox](../sandbox#share-a-parent-sandbox) |
+| `defineSandboxProvider` | `eve/sandbox/provider` | custom sandbox provider modules | [Sandbox](../sandbox#custom-providers) |
| `defineInstrumentation` | `eve/instrumentation` | `agent/instrumentation/<name>.ts` | [Instrumentation](../observability/instrumentation) |
| `otel`, `otelIntegration` | `eve/instrumentation/otel` | `agent/instrumentation/<destination>.ts` | [OpenTelemetry](../observability/otel) |
| `defineRemoteAgent` | `eve` | `agent/subagents/<id>/agent.ts` | [Remote agents](../guides/remote-agents) |
@@ -140,7 +142,11 @@ Tool definitions accept `availableInSubagents: false` to restrict the tool to to
| `eve/memory/file` | `fileMemory`, `inMemory`, and the conditional document backend contract |
| `eve/memory/file/vercel` | `vercelBlob` and Vercel Blob backend options |
| `eve/context` | `defineState`, session and state types |
-| `eve/sandbox` | `defineSandbox`, provider environments, and sandbox session types |
+| `eve/sandbox` | `defineSandbox`, `defineParentSandbox`, `DefaultSandbox`, and sandbox session types |
+| `eve/sandbox/provider` | `defineSandboxProvider` and custom provider types |
+| [`eve/sandbox/docker`](../sandbox/docker) | `DockerSandbox` and Docker environment and session types |
+| [`eve/sandbox/vercel`](../sandbox/vercel) | `VercelSandbox`, `Drive`, and Vercel environment, session, and mount types |
+| [`eve/sandbox/just-bash`](../sandbox/just-bash) | `JustBashSandbox` and just-bash environment types |
| `eve/instrumentation` | `defineInstrumentation`, `disableInstrumentation`, `isChannel`, lifecycle provider types |
| `eve/instrumentation/otel` | `otel`, `otelIntegration`, `localTraces`, `agentRuns`, OpenTelemetry policy types |
| `eve/local-dev` | `getLocalDevCapability`, `LocalDevCapability` |
diff --git a/docs/sandbox/default.mdx b/docs/sandbox/default.mdx
index c181f97db..d4dcf258f 100644
--- a/docs/sandbox/default.mdx
+++ b/docs/sandbox/default.mdx
@@ -3,7 +3,7 @@ title: "Default Sandbox"
description: "Let eve select the sandbox provider for the current environment."
---
-`DefaultSandbox.environment()` preserves eve's standard behavior without exposing provider-specific live creation options.
+`DefaultSandbox.environment()` selects a sandbox provider for the host that loads your sandbox file. Its `open()` method takes no options.
```ts
import { DefaultSandbox, defineSandbox } from "eve/sandbox";
@@ -14,4 +14,46 @@ export default defineSandbox(() => environment.open());
On Vercel, it selects [Vercel Sandbox](/docs/sandbox/vercel). Elsewhere, it selects [Docker](/docs/sandbox/docker) when a Docker daemon is reachable and falls back to [just-bash](/docs/sandbox/just-bash) otherwise.
-Use a provider directly when you need its image, network, compute, or mount options.
+Use a provider directly when you need options for `open()`, such as a per-sandbox `networkPolicy` or Vercel Drive `mounts`, or a provider-specific session such as one with `setNetworkPolicy()`.
+
+## How eve selects the provider
+
+`DefaultSandbox.environment()` selects the provider when it runs, which is when your sandbox module loads:
+
+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. eve checks once per process and reuses the answer.
+3. Otherwise, it selects just-bash.
+
+`eve build`, `eve dev`, and each production server process load the sandbox module separately, so each one selects a provider for its own host. If the build host and the runtime host differ, they can select different providers. For example, a build on a CI machine without Docker prepares a different provider's environment than a server with Docker selects, and the server fails with a provider mismatch error. Run `eve build` where the runtime's provider is available, or select that provider explicitly with `DockerSandbox` or `VercelSandbox`. See [Sandbox troubleshooting](/docs/sandbox/troubleshooting) for the exact errors.
+
+A running session keeps the provider that created its sandbox. If a later process selects a different provider, for example because Docker stopped, that session cannot resume its sandbox.
+
+## 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.
+
+On Vercel, when the environment has no `prepare` callback, workspace seed, or skill files, `DefaultSandbox` skips the snapshot and creates each session sandbox directly from the configured `image` or `source`, or from eve's base image when neither is set.
diff --git a/docs/sandbox/docker.mdx b/docs/sandbox/docker.mdx
index e1d8fe732..cccc25ee2 100644
--- a/docs/sandbox/docker.mdx
+++ b/docs/sandbox/docker.mdx
@@ -14,7 +14,19 @@ 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
diff --git a/docs/sandbox/index.mdx b/docs/sandbox/index.mdx
index d7975b4a5..837755da0 100644
--- a/docs/sandbox/index.mdx
+++ b/docs/sandbox/index.mdx
@@ -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";
@@ -95,7 +95,7 @@ eve runs `prepare` while creating a reusable provider artifact, not once for eac
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
@@ -126,26 +126,25 @@ 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.
+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.
-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.
+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`. eve resolves `$HOME` by reading it inside the sandbox; when a sandbox has no usable home directory, skill paths fall back to `/workspace/skills`. Do not refer to a concrete home directory or `/eve/resources`, which is provider-internal staging.
-Providers receive both trees with explicit metadata:
+Providers receive both trees with explicit metadata. `source.kind` is `"none"` when the agent has no managed workspace or skill files, `"materialized"` when eve has also written the compiled files to the host directory at `path`, and `"inline"` when the contents are available only in each tree's `files`:
```ts
interface SandboxProviderResources {
source:
| { kind: "none" }
| { kind: "inline"; key: string }
- | { kind: "materialized"; key: string; path: string }
- | { kind: "reference"; key: string };
+ | { kind: "materialized"; key: string; path: string };
workspace?: SandboxProviderResourceTree;
skills?: SandboxProviderResourceTree;
}
interface SandboxProviderResourceTree {
key: string;
- files: ResourceFile[];
+ files: SandboxProviderResourceFile[];
mountPath: string;
targetPath: string;
}
@@ -261,6 +260,7 @@ Changing sandbox source, preparation code, Dockerfile content, environment optio
## 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.
diff --git a/docs/sandbox/meta.json b/docs/sandbox/meta.json
index 023d879c4..db48aa286 100644
--- a/docs/sandbox/meta.json
+++ b/docs/sandbox/meta.json
@@ -1,5 +1,5 @@
{
"title": "Sandbox",
"defaultOpen": false,
- "pages": ["index", "default", "vercel", "docker", "just-bash"]
+ "pages": ["index", "default", "vercel", "docker", "just-bash", "troubleshooting"]
}
diff --git a/docs/sandbox/troubleshooting.mdx b/docs/sandbox/troubleshooting.mdx
new file mode 100644
index 000000000..45cc9f1bb
--- /dev/null
+++ b/docs/sandbox/troubleshooting.mdx
@@ -0,0 +1,162 @@
+---
+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 "just-bash", but this process selects provider "docker".
+```
+
+The process that prepared the sandbox and the process that uses it selected different providers. `DefaultSandbox.environment()` [selects a provider in each process](/docs/sandbox/default#how-eve-selects-the-provider), so a build on a machine without Docker and a server with Docker disagree. Prepare the sandbox where the using process's provider is available: run `eve build` on that host, or restart `eve dev` locally. To make every process use the same provider, select it explicitly, for example with `DockerSandbox.environment()`.
+
+### `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. |
+
+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".
+```
+
+The agent selects a different provider than the one that created this session's sandbox. With `DefaultSandbox`, this happens when Docker starts or stops between processes. eve cannot move a sandbox between providers. Start a new session, or restore the previous provider, for example by starting Docker again. In the `eve dev` terminal, `/new` starts a new session.
+
+### `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.
+
+## 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()` so eve selects a provider that the host supports.
+
+### 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.
diff --git a/docs/sandbox/vercel.mdx b/docs/sandbox/vercel.mdx
index 8197c098c..9077782a9 100644
--- a/docs/sandbox/vercel.mdx
+++ b/docs/sandbox/vercel.mdx
@@ -27,6 +27,30 @@ 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.
diff --git a/packages/eve/src/compiler/normalize-sandbox.ts b/packages/eve/src/compiler/normalize-sandbox.ts
index 6bddc26dc..28a4a75fb 100644
--- a/packages/eve/src/compiler/normalize-sandbox.ts
+++ b/packages/eve/src/compiler/normalize-sandbox.ts
@@ -23,7 +23,10 @@ export async function compileSandboxDefinition(
? namespace.environment
: getBoundSandboxEnvironment(selector);
if (!inheritsParent && candidate === undefined)
- throw new Error(`Sandbox "${source.logicalPath}" must export an environment.`);
+ throw new Error(
+ `Sandbox "${source.logicalPath}" must export an environment. ` +
+ "Add `export const environment = DefaultSandbox.environment();` (or another provider's environment) and open it in the selector.",
+ );
const authoredSource =
options.binding.backing.kind === "programmatic"
? (options.binding.backing.semanticRevision ?? options.binding.backing.revision)
diff --git a/packages/eve/src/execution/sandbox/bindings/docker.ts b/packages/eve/src/execution/sandbox/bindings/docker.ts
index 681ab7f11..6a7eac926 100644
--- a/packages/eve/src/execution/sandbox/bindings/docker.ts
+++ b/packages/eve/src/execution/sandbox/bindings/docker.ts
@@ -51,6 +51,10 @@ import {
type SandboxProviderSessionContext,
} from "#shared/sandbox-provider.js";
import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";
+import {
+ invalidPreparedSandboxArtifactError,
+ invalidSandboxSessionStateError,
+} from "#shared/sandbox-recorded-data-error.js";
import { SandboxSessionGoneError } from "#shared/sandbox-session-gone-error.js";
import type {
DockerSandboxEnvironmentOptions,
@@ -147,6 +151,8 @@ export function createDockerSandboxProvider(
if (!(await dockerImageExists(cli, artifact.imageReference))) {
throw new SandboxTemplateNotProvisionedError({
providerName: DOCKER_PROVIDER_NAME,
+ reason:
+ "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.",
templateKey: artifact.imageReference,
});
}
@@ -364,7 +370,7 @@ function requirePreparedDockerArtifact(
artifact: SandboxPreparedArtifact,
): DockerSandboxPreparedArtifact {
if (!isSandboxPreparedArtifactRecord(artifact) || typeof artifact.imageReference !== "string") {
- throw new Error("Invalid prepared Docker artifact.");
+ throw invalidPreparedSandboxArtifactError("Docker sandbox");
}
return { imageReference: artifact.imageReference };
}
@@ -375,7 +381,7 @@ function requireDockerSessionState(state: SandboxPreparedArtifact): DockerSandbo
state.version !== 2 ||
typeof state.containerName !== "string"
) {
- throw new Error("Invalid Docker sandbox session state.");
+ throw invalidSandboxSessionStateError("Docker sandbox");
}
return { containerName: state.containerName, version: 2 };
}
diff --git a/packages/eve/src/execution/sandbox/bindings/just-bash.ts b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
index 34635c1c4..cf4ecd161 100644
--- a/packages/eve/src/execution/sandbox/bindings/just-bash.ts
+++ b/packages/eve/src/execution/sandbox/bindings/just-bash.ts
@@ -38,6 +38,10 @@ import {
type SandboxProviderSessionContext,
} from "#shared/sandbox-provider.js";
import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";
+import {
+ invalidPreparedSandboxArtifactError,
+ invalidSandboxSessionStateError,
+} from "#shared/sandbox-recorded-data-error.js";
import { SandboxSessionGoneError } from "#shared/sandbox-session-gone-error.js";
const JUST_BASH_CACHE_DIRECTORY_NAME = "just-bash";
@@ -162,6 +166,8 @@ async function ensureSessionRoot(templateRootPath: string, sessionRootPath: stri
if (!(await pathExists(templateRootPath))) {
throw new SandboxTemplateNotProvisionedError({
providerName: JUST_BASH_PROVIDER_NAME,
+ reason:
+ "The template directory does not exist: it was deleted, or the build ran on another machine.",
templateKey: templateRootPath,
});
}
@@ -236,7 +242,7 @@ function requirePreparedJustBashArtifact(
artifact: SandboxPreparedArtifact,
): JustBashPreparedArtifact {
if (!isSandboxPreparedArtifactRecord(artifact) || typeof artifact.templateKey !== "string") {
- throw new Error("Invalid prepared just-bash artifact.");
+ throw invalidPreparedSandboxArtifactError("just-bash sandbox");
}
return { templateKey: artifact.templateKey };
}
@@ -247,7 +253,7 @@ function requireJustBashSessionState(state: SandboxPreparedArtifact): JustBashSe
state.version !== 2 ||
typeof state.rootPath !== "string"
) {
- throw new Error("Invalid just-bash session state.");
+ throw invalidSandboxSessionStateError("just-bash sandbox");
}
return { rootPath: state.rootPath, version: 2 };
}
diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.ts b/packages/eve/src/execution/sandbox/bindings/vercel.ts
index b13bf4aea..653ae5788 100644
--- a/packages/eve/src/execution/sandbox/bindings/vercel.ts
+++ b/packages/eve/src/execution/sandbox/bindings/vercel.ts
@@ -28,6 +28,10 @@ import {
type SandboxProviderSessionContext,
} from "#shared/sandbox-provider.js";
import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";
+import {
+ invalidPreparedSandboxArtifactError,
+ invalidSandboxSessionStateError,
+} from "#shared/sandbox-recorded-data-error.js";
import { SandboxSessionGoneError } from "#shared/sandbox-session-gone-error.js";
import type {
VercelSandboxMountOptions,
@@ -198,6 +202,7 @@ export function createVercelSandbox(
if (isVercelSnapshotUnavailableError(error) && artifact.snapshotId !== undefined) {
throw new SandboxTemplateNotProvisionedError({
providerName: "vercel",
+ reason: "The Vercel Sandbox snapshot expired or was deleted.",
templateKey: artifact.snapshotId,
});
}
@@ -309,7 +314,7 @@ function requireVercelSessionState(state: SandboxPreparedArtifact): VercelSandbo
state.version !== 3 ||
typeof state.sandboxName !== "string"
) {
- throw new Error("Invalid Vercel sandbox session state.");
+ throw invalidSandboxSessionStateError("Vercel sandbox");
}
return { sandboxName: state.sandboxName, version: 3 };
}
@@ -321,7 +326,7 @@ function requirePreparedVercelTemplate(
!isSandboxPreparedArtifactRecord(artifact) ||
(artifact.snapshotId !== undefined && typeof artifact.snapshotId !== "string")
) {
- throw new Error("Invalid prepared Vercel sandbox artifact.");
+ throw invalidPreparedSandboxArtifactError("Vercel sandbox");
}
return artifact.snapshotId === undefined ? {} : { snapshotId: artifact.snapshotId };
}
diff --git a/packages/eve/src/execution/sandbox/development-lazy-prewarm.ts b/packages/eve/src/execution/sandbox/development-lazy-prewarm.ts
index b65b8f6ec..752d73a40 100644
--- a/packages/eve/src/execution/sandbox/development-lazy-prewarm.ts
+++ b/packages/eve/src/execution/sandbox/development-lazy-prewarm.ts
@@ -29,7 +29,12 @@ export async function ensureDevelopmentSandboxesPrepared(input: {
let lease;
while ((lease = await acquireRecoveryLease(lockPath, token)) === undefined) {
if (Date.now() >= deadline) {
- throw new Error("Timed out waiting for development sandbox preparation.");
+ throw new Error(
+ `Timed out after ${PREPARATION_WAIT_TIMEOUT_MS / 60_000} minutes waiting for another request or eve dev worker to prepare sandbox environments ` +
+ `(this request needs provider "${input.providerName}"). ` +
+ "Check the eve dev output or run `eve logs` to see which step is slow, such as an image pull, a Dockerfile build, or a `prepare` callback. " +
+ "Retry after preparation finishes, or restart eve dev to cancel it.",
+ );
}
await new Promise((resolve) => setTimeout(resolve, 250));
}
diff --git a/packages/eve/src/execution/sandbox/ensure.test.ts b/packages/eve/src/execution/sandbox/ensure.test.ts
index 4c10cac67..3f9c626c6 100644
--- a/packages/eve/src/execution/sandbox/ensure.test.ts
+++ b/packages/eve/src/execution/sandbox/ensure.test.ts
@@ -12,6 +12,7 @@ import {
type SandboxProviderSessionContext,
} from "#shared/sandbox-provider.js";
import { SandboxSessionGoneError } from "#shared/sandbox-session-gone-error.js";
+import { SandboxTemplateNotProvisionedError } from "#shared/sandbox-template-error.js";
import { createBundledRuntimeCompiledArtifactsSource } from "#runtime/compiled-artifacts-source.js";
import type { RuntimeSandboxRegistry } from "#runtime/sandbox/registry.js";
import { loadSandboxPreparedArtifact } from "#runtime/sandbox/prepared-artifacts.js";
@@ -181,7 +182,9 @@ describe("ensureSandboxAccess", () => {
it("keeps missing production artifacts fatal without starting a sandbox", async () => {
vi.mocked(loadSandboxPreparedArtifact).mockResolvedValueOnce(undefined);
const value = fixture();
- await expect(open(value.registry)).rejects.toThrow();
+ const failure = open(value.registry);
+ await expect(failure).rejects.toThrow(SandboxTemplateNotProvisionedError);
+ await expect(failure).rejects.toThrow('agent node "__root__"');
expect(value.create).not.toHaveBeenCalled();
});
@@ -232,7 +235,12 @@ describe("ensureSandboxAccess", () => {
expect(setup).toHaveBeenCalledOnce();
expect(value.start).toHaveBeenCalledOnce();
await expect(access.captureState()).resolves.toEqual({
- session: { providerName: "test", state: { key: "session-1" }, stateProtocolVersion: 1 },
+ session: {
+ generation: expect.any(String),
+ providerName: "test",
+ state: { key: "session-1" },
+ stateProtocolVersion: 1,
+ },
});
});
diff --git a/packages/eve/src/execution/sandbox/ensure.ts b/packages/eve/src/execution/sandbox/ensure.ts
index 40976d8be..4bfe2ffcb 100644
--- a/packages/eve/src/execution/sandbox/ensure.ts
+++ b/packages/eve/src/execution/sandbox/ensure.ts
@@ -146,7 +146,10 @@ export async function ensureSandboxAccess(
function activeDefinition() {
const definition = registered.inheritance?.definition ?? registered.definition;
if (definition.kind !== "independent")
- throw new Error(`Sandbox "${definition.logicalPath}" has no environment.`);
+ throw new Error(
+ `Sandbox "${definition.logicalPath}" uses defineParentSandbox(), but this agent has no parent sandbox to share. ` +
+ "Only a declared subagent can share its parent's sandbox. Give this agent its own sandbox with defineSandbox() and an exported environment.",
+ );
return definition;
}
@@ -159,8 +162,8 @@ export async function ensureSandboxAccess(
});
if (artifact === undefined) {
throw new SandboxTemplateNotProvisionedError({
+ nodeId: artifactNodeId,
providerName: provider.providerName,
- templateKey: artifactNodeId,
});
}
return artifact;
@@ -172,14 +175,23 @@ export async function ensureSandboxAccess(
environment: object,
context: SandboxProviderSessionContext,
): Promise<RuntimeSandboxSession> {
- if (opening !== undefined) throw new Error("A sandbox definition can open only one sandbox.");
+ if (opening !== undefined)
+ throw new Error(
+ "A sandbox definition can open only one sandbox. Call `environment.open()` once in the defineSandbox() selector and return that sandbox.",
+ );
const definition = activeDefinition();
if (environment !== definition.environment)
- throw new Error(`Sandbox "${definition.logicalPath}" selected a different environment.`);
+ throw new Error(
+ `Sandbox "${definition.logicalPath}" opened an environment other than the one it exports as \`environment\`. ` +
+ "Call `open()` on the exported environment. A selector cannot open an environment created inside the selector or exported by another sandbox file.",
+ );
if (provider !== getSandboxEnvironmentRuntime(definition.environment))
throw new Error(`Sandbox "${definition.logicalPath}" selected a different provider.`);
if (persisted !== null) {
- throw new Error(`Sandbox "${definition.logicalPath}" is already initialized.`);
+ throw new Error(
+ `Sandbox "${definition.logicalPath}" already opened this session's sandbox. ` +
+ "Call `environment.open()` once in the defineSandbox() selector and return that sandbox.",
+ );
}
const artifact = await loadArtifact(provider);
@@ -225,7 +237,9 @@ export async function ensureSandboxAccess(
const provider = getSandboxEnvironmentRuntime(activeDefinition().environment);
if (persisted.providerName !== provider.providerName) {
throw new Error(
- `Sandbox session state belongs to provider "${persisted.providerName}", not "${provider.providerName}".`,
+ `This session's sandbox was created by provider "${persisted.providerName}", but the agent now selects provider "${provider.providerName}". ` +
+ "eve cannot move a sandbox between providers. Start a new session, or restore the previous provider. " +
+ "With DefaultSandbox, the provider can change when Docker starts or stops between processes.",
);
}
if (persisted.stateProtocolVersion !== provider.stateProtocolVersion) {
diff --git a/packages/eve/src/runtime/resolve-agent-graph.ts b/packages/eve/src/runtime/resolve-agent-graph.ts
index 70caeabd0..c019c7111 100644
--- a/packages/eve/src/runtime/resolve-agent-graph.ts
+++ b/packages/eve/src/runtime/resolve-agent-graph.ts
@@ -409,7 +409,8 @@ function attachInheritedSandboxWorkspaceResources(input: {
const parentNodeId = parentNodeIdByChildNodeId.get(nodeId);
if (parentNodeId === undefined) {
throw new ResolveRuntimeAgentGraphError(
- `Sandbox "${node.sandboxRegistry.sandbox.definition.logicalPath}" selects parent.sandbox but agent node "${nodeId}" has no parent.`,
+ `Sandbox "${node.sandboxRegistry.sandbox.definition.logicalPath}" selects parent.sandbox but agent node "${nodeId}" has no parent. ` +
+ "Only a declared subagent can share its parent's sandbox with defineParentSandbox(). Give this agent its own sandbox with defineSandbox() and an exported environment.",
{ nodeId },
);
}
diff --git a/packages/eve/src/runtime/resolve-sandbox.ts b/packages/eve/src/runtime/resolve-sandbox.ts
index 6a3f0031a..3eb9d0297 100644
--- a/packages/eve/src/runtime/resolve-sandbox.ts
+++ b/packages/eve/src/runtime/resolve-sandbox.ts
@@ -44,6 +44,9 @@ export async function resolveSandboxDefinition(
sourceKind: "module" as const,
};
if (!isSandboxEnvironment(environment))
- throw new ResolveAgentError(`Sandbox "${definition.logicalPath}" has no environment.`);
+ throw new ResolveAgentError(
+ `Sandbox "${definition.logicalPath}" has no environment. ` +
+ "Export the environment its selector opens, for example `export const environment = DefaultSandbox.environment();`.",
+ );
return { ...base, environment, kind: "independent" };
}
diff --git a/packages/eve/src/runtime/sandbox/prepared-artifacts.ts b/packages/eve/src/runtime/sandbox/prepared-artifacts.ts
index 302f4098e..8fccb92b3 100644
--- a/packages/eve/src/runtime/sandbox/prepared-artifacts.ts
+++ b/packages/eve/src/runtime/sandbox/prepared-artifacts.ts
@@ -50,7 +50,9 @@ export async function loadSandboxPreparedArtifact(input: {
const entry = manifest?.entries.find((candidate) => candidate.nodeId === input.nodeId);
if (entry !== undefined && entry.providerName !== input.providerName) {
throw new Error(
- `Prepared sandbox artifact for node "${input.nodeId}" belongs to provider "${entry.providerName}", not "${input.providerName}".`,
+ `The prepared sandbox artifact for agent node "${input.nodeId}" was created with provider "${entry.providerName}", but this process selects provider "${input.providerName}". ` +
+ "DefaultSandbox selects a provider separately in each process, so processes on hosts with different Docker availability can disagree. " +
+ "Prepare the sandbox where this process's provider is available (run `eve build` on that host, or restart `eve dev`), or select a provider explicitly in the sandbox file.",
);
}
return entry?.artifact;
diff --git a/packages/eve/src/shared/sandbox-environment.ts b/packages/eve/src/shared/sandbox-environment.ts
index cc04dedd4..1391ff0b7 100644
--- a/packages/eve/src/shared/sandbox-environment.ts
+++ b/packages/eve/src/shared/sandbox-environment.ts
@@ -82,7 +82,10 @@ export function createSandboxEnvironment<
const context = contextStorage.getStore();
const runtime = context === undefined ? undefined : runtimes.get(context);
if (runtime === undefined) {
- throw new Error("Sandbox environments can only open sandboxes inside defineSandbox().");
+ throw new Error(
+ "Sandbox environments can only open sandboxes inside defineSandbox(). " +
+ "Use `ctx.getSandbox()` to reach the session's sandbox from tools and other runtime code.",
+ );
}
return (await runtime.open({
configurationHash: hashConstructorOptions({
diff --git a/packages/eve/src/shared/sandbox-recorded-data-error.ts b/packages/eve/src/shared/sandbox-recorded-data-error.ts
new file mode 100644
index 000000000..a4fda629b
--- /dev/null
+++ b/packages/eve/src/shared/sandbox-recorded-data-error.ts
@@ -0,0 +1,17 @@
+/** A provider's recorded session state does not match the shape this eve version writes. */
+export function invalidSandboxSessionStateError(label: string): Error {
+ return new Error(
+ `Invalid ${label} session state. ` +
+ "This session's recorded sandbox state does not match the format this eve version expects, usually because the session started under a different eve version. " +
+ "Start a new session to get a fresh sandbox.",
+ );
+}
+
+/** A provider's prepared artifact from `eve build` does not match the shape this eve version writes. */
+export function invalidPreparedSandboxArtifactError(label: string): Error {
+ return new Error(
+ `Invalid prepared ${label} artifact. ` +
+ "The artifact recorded by `eve build` does not match the format this eve version expects, usually because the build used a different eve version. " +
+ "Run `eve build` with the eve version this runtime uses, then redeploy.",
+ );
+}
diff --git a/packages/eve/src/shared/sandbox-template-error.ts b/packages/eve/src/shared/sandbox-template-error.ts
index 748672da5..01550f135 100644
--- a/packages/eve/src/shared/sandbox-template-error.ts
+++ b/packages/eve/src/shared/sandbox-template-error.ts
@@ -1,14 +1,32 @@
+type SandboxTemplateNotProvisionedInput =
+ /** The build recorded no prepared artifact for this agent node. */
+ | { readonly nodeId: string; readonly providerName: string }
+ /**
+ * The provider cannot use the recorded template. Callers that know why pass
+ * `reason`; the default message names no cause, because callers raise this for
+ * several different ones.
+ */
+ | { readonly providerName: string; readonly reason?: string; readonly templateKey: string };
+
export class SandboxTemplateNotProvisionedError extends Error {
readonly providerName: string;
+ /** The provider's template identifier, or the agent node id when the build recorded no artifact. */
readonly templateKey: string;
- constructor(input: { readonly providerName: string; readonly templateKey: string }) {
+ constructor(input: SandboxTemplateNotProvisionedInput) {
super(
- `Sandbox template "${input.templateKey}" is not provisioned for provider "${input.providerName}". Run \`eve build\` before serving traffic.`,
+ "nodeId" in input
+ ? `No prepared "${input.providerName}" sandbox environment is recorded for agent node "${input.nodeId}". ` +
+ "eve prepares sandbox environments during `eve build` and never prepares them in production. " +
+ "Run `eve build` without `--skip-sandbox-prewarm` and deploy that output with this runtime."
+ : `Sandbox template "${input.templateKey}" for provider "${input.providerName}" is not available to this runtime. ` +
+ (input.reason === undefined ? "" : `${input.reason} `) +
+ "The runtime only uses templates that `eve build` prepared and never recreates them. " +
+ "Run `eve build` again and deploy its output.",
);
this.name = "SandboxTemplateNotProvisionedError";
this.providerName = input.providerName;
- this.templateKey = input.templateKey;
+ this.templateKey = "nodeId" in input ? input.nodeId : input.templateKey;
}
static is(error: unknown): error is SandboxTemplateNotProvisionedError {