The Open Framework for Building Agents
fix(eve): honor custom Vercel sandbox images (#3003)
Colton Padden38fd8d9badd2
diff --git a/.changeset/allow-vercel-custom-images.md b/.changeset/allow-vercel-custom-images.mdnew file mode 100644index 000000000..b17693dc1--- /dev/null+++ b/.changeset/allow-vercel-custom-images.md@@ -0,0 +1,5 @@+---+"eve": patch+---++Honor the `image` option passed to `vercel()` when creating fresh Vercel Sandbox instances.diff --git a/docs/sandbox.mdx b/docs/sandbox.mdxindex c3a4bd0ff..e1875cbdc 100644--- a/docs/sandbox.mdx+++ b/docs/sandbox.mdx@@ -156,7 +156,7 @@ With `backend` omitted, eve uses `defaultBackend()`, which resolves on first use3. **microsandbox** when the host supports it: macOS on Apple Silicon, or glibc Linux with KVM enabled.4. **just-bash** as the dependency-free fallback.-By default, Docker and microsandbox pull `ghcr.io/vercel/eve` while Vercel Sandbox pulls `vcr.vercel.com/vercel/eve/base`. Each image tag matches the installed eve version. Set `EVE_SANDBOX_IMAGE_TAG` to replace the version-derived tag for these default images. An explicit `image` passed to `docker()` or `microsandbox()` still takes precedence.+By default, Docker and microsandbox pull `ghcr.io/vercel/eve` while Vercel Sandbox pulls `vcr.vercel.com/vercel/eve/base`. Each image tag matches the installed eve version. Set `EVE_SANDBOX_IMAGE_TAG` to replace the version-derived tag for these default images. An explicit `image` passed to `docker()`, `microsandbox()`, or `vercel()` takes precedence. A snapshot `source` on `vercel()` takes precedence over its `image` because Vercel Sandbox treats them as mutually exclusive.On every backend, authored commands run as the non-root `vercel-sandbox` user through a non-interactive `bash -lc` login shell. `/workspace` and `$HOME` are writable, `$HOME/.local/bin` is on `PATH` for user-scoped executables, and system paths such as `/usr/local` stay root-owned. Use passwordless `sudo` when setup genuinely needs system-wide changes; `sudo` resets the environment, so pass through variables like `NPM_CONFIG_PREFIX` explicitly if a privileged step depends on them.diff --git a/packages/eve/src/execution/sandbox/bindings/vercel-create-sdk.ts b/packages/eve/src/execution/sandbox/bindings/vercel-create-sdk.tsindex 3d6100162..33d1ea3a5 100644--- a/packages/eve/src/execution/sandbox/bindings/vercel-create-sdk.ts+++ b/packages/eve/src/execution/sandbox/bindings/vercel-create-sdk.ts@@ -26,7 +26,7 @@ export async function createVercelEveImageSandbox(input: {readonly createOptions: VercelSandboxCreateParams;readonly sandboxModule: VercelModule;}): Promise<VercelSandbox> {- const { image: _image, runtime: _runtime, source, ...createOptions } = input.createOptions;+ const { image, runtime: _runtime, source, ...createOptions } = input.createOptions;const fetch = getVercelSandboxFetch(input.createOptions);/*@@ -43,7 +43,7 @@ export async function createVercelEveImageSandbox(input: {return await input.sandboxModule.Sandbox.create({...createOptions,source,- image: VERCEL_EVE_SANDBOX_IMAGE,+ image: image ?? VERCEL_EVE_SANDBOX_IMAGE,fetch,});}diff --git a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts b/packages/eve/src/execution/sandbox/bindings/vercel.test.tsindex 1038a150e..3f8224a0c 100644--- a/packages/eve/src/execution/sandbox/bindings/vercel.test.ts+++ b/packages/eve/src/execution/sandbox/bindings/vercel.test.ts@@ -193,6 +193,31 @@ describe("createVercelSandbox", () => {expect(templateSandbox.update).toHaveBeenCalledWith({ networkPolicy: "deny-all" });});+ it("uses an author-supplied image for fresh Vercel sandboxes", async () => {+ const templateSandbox = createMockSandbox({ name: "template-key" });+ const sandboxModule = {+ Sandbox: {+ create: vi.fn().mockResolvedValueOnce(templateSandbox),+ get: vi.fn().mockResolvedValueOnce(null),+ },+ };++ const backend = createVercelSandbox({+ createOptions: { image: "registry.example/eve-python:1.0.0" } as never,+ loadSandboxModule: async () => sandboxModule as never,+ });++ await backend.prewarm({+ runtimeContext: { appRoot: "/tmp/test-app-root" },+ seedFiles: [],+ templateKey: "template-key",+ });++ expect(sandboxModule.Sandbox.create).toHaveBeenCalledWith(+ expect.objectContaining({ image: "registry.example/eve-python:1.0.0" }),+ );+ });+it("forwards double-underscore create fields through Sandbox.create", async () => {const templateSandbox = createMockSandbox({ name: "template-key" });const sandboxModule = {diff --git a/packages/eve/src/public/sandbox/vercel-sandbox.ts b/packages/eve/src/public/sandbox/vercel-sandbox.tsindex dc4fd697f..3aa0e7266 100644--- a/packages/eve/src/public/sandbox/vercel-sandbox.ts+++ b/packages/eve/src/public/sandbox/vercel-sandbox.ts@@ -29,10 +29,14 @@ type VercelSandboxAuthorCreateOptions<T> = T extends unknown* are excluded: the framework owns those and overrides any* author-supplied values.*- * `runtime` is excluded as well: eve always boots its sandboxes from the- * published `vcr.vercel.com/vercel/eve/base` image tagged with the installed- * eve version or `EVE_SANDBOX_IMAGE_TAG` when set, which is mutually exclusive- * with a stock runtime.+ * `runtime` is excluded: eve defaults to its published+ * `vcr.vercel.com/vercel/eve/base` image tagged with the installed eve version+ * or `EVE_SANDBOX_IMAGE_TAG` when `image` is not supplied. Both are mutually+ * exclusive with a stock runtime.+ *+ * `image` is honored for fresh templates and template-less sessions. A+ * snapshot `source` takes precedence because the Vercel SDK makes it mutually+ * exclusive with `image`.** `source` is honored only on the template create at prewarm time, so* an author-supplied snapshot, git revision, or tarball becomes the