Keep an image entrypoint the dev-folder mount would hide available to the run

Apify's Playwright base images start through ./xvfb-entrypoint.sh inside
the working directory. A dev-folder run bind-mounts the local folder over
that directory, so unless the folder happens to carry the same file the
engine refuses to start the container ("executable file not found"). The
driver now inspects the image's command: a working-directory-relative
entrypoint (or Cmd) the dev folder does not provide is read out of the
image and placed in the container before start, and the run starts
through that copy. Absolute and PATH-resolved commands are untouched, as
is anything the dev folder provides itself.

Covered by unit tests and a new e2e case with a busybox Actor whose
entrypoint lives in its working directory.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CZhuUP13NByepkP4n3sg3P

Author: claude

README.md

@@ -123,8 +123,10 @@ apify call --input '{"maxPages":3}'   # picks up the new dist/, no rebuild
 
 Node doesn't hot-reload a running process, so a local recompile is picked up by the **next** run's
 container start, not by any run already in progress. `node_modules` inside the container still comes
-from the built image - an anonymous volume preserves it underneath the bind mount - so a new dependency
-in `package.json` still needs a real `apify push`/build; only source edits skip it. Clear the
+from the built image - a per-run volume preserves it underneath the bind mount - so a new dependency
+in `package.json` still needs a real `apify push`/build; only source edits skip it. An entrypoint script
+the image keeps in its working directory (Apify's Playwright images start through an Xvfb wrapper there)
+stays available too, unless your folder carries its own copy. Clear the
 registration with an empty body (`--body '""'`) to go back to running purely from the built image. Full
 mechanics: `requirements/actor-driver.md`'s "Bind mount volumes with Actor source code";
 endpoint/console details: `requirements/api.md`'s `/actor-runtime/*` section and

requirements/actor-driver.md

@@ -52,6 +52,9 @@
       else unverifiable reports a generic "could not verify".
 - **Registration has no build-first precondition** - it requires no build of the Actor to exist,
   succeeded or otherwise.
+- An entrypoint the image keeps inside its working directory (Apify's Playwright base images start
+  through an Xvfb script there) stays available to the run even though the mount covers that directory,
+  unless the dev folder provides its own copy; the run log says so.
 - The working directory the mount covers is recorded **per build**, never on the Actor
   (`storage.md`); the mount a run applies always uses the one from _that run's own resolved build_,
   never any other build the Actor happens to have.

src/driver/docker-driver.ts

@@ -224,6 +224,46 @@ function devNodeModulesVolumeName(runId: string): string {
 	return `${DEV_NODE_MODULES_VOLUME_PREFIX}${runId}`;
 }
 
+/** A command token the engine resolves against the working directory rather than `PATH`: `./x.sh`,
+ * `bin/x` - relative, with a slash. A bare `x.sh` goes through `PATH`, an absolute path is unaffected
+ * by what is mounted over the working directory. */
+function isWorkingDirectoryRelative(token: string): boolean {
+	return !token.startsWith('/') && token.includes('/');
+}
+
+function readStream(stream: NodeJS.ReadableStream): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+		stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+		stream.once('error', reject);
+		stream.once('end', () => resolve(Buffer.concat(chunks)));
+	});
+}
+
+/** Re-packs the single-file archive `getArchive` returns so its entries land under `directory` when
+ * extracted at `/`, with an explicit directory entry so no engine has to invent the parent. */
+async function repackUnderDirectory(archive: Buffer, directory: string): Promise<Buffer> {
+	const dir = directory.replace(/^\/+/, '');
+	const pack = tar.pack();
+	const extract = tar.extract();
+	const packed = readStream(pack);
+	pack.entry({ name: dir, type: 'directory', mode: 0o755 });
+	await new Promise<void>((resolve, reject) => {
+		extract.on('entry', (header, content, next) => {
+			const entry = pack.entry({ ...header, name: `${dir}/${header.name}` }, (error) => {
+				if (error) reject(error);
+				else next();
+			});
+			content.pipe(entry);
+		});
+		extract.once('error', reject);
+		extract.once('finish', resolve);
+		extract.end(archive);
+	});
+	pack.finalize();
+	return packed;
+}
+
 /** A container's address on `network`, else on whatever network it does have. */
 function containerAddress(info: Docker.ContainerInspectInfo, network: string | undefined): string | undefined {
 	const networks = info.NetworkSettings?.Networks ?? {};
@@ -252,6 +292,17 @@ const X11_SOCKET_DIR = '/tmp/.X11-unix';
  * follows. Named, not anonymous, because Podman 3.x refuses a volume mount without a source ("must set
  * source volume"). Removed with the run, and swept by this prefix after a restart. */
 const DEV_NODE_MODULES_VOLUME_PREFIX = 'actor-runtime-node-modules-';
+/** Where a `devMount` run keeps the image's own copy of an entrypoint file the bind mount would hide
+ * (`preserveHiddenEntrypoint`). */
+const PRESERVED_ENTRYPOINT_DIR = '/apify-runtime-entrypoint';
+
+/** The image command a `devMount` run starts through instead of its own, plus the tar that puts the
+ * preserved file in place before the container starts. */
+interface PreservedEntrypoint {
+	field: 'Entrypoint' | 'Cmd';
+	command: string[];
+	tar: Buffer;
+}
 /** Reachable only on `apify-local`; never published on the host. */
 const BROWSER_VIEWER_VNC_PORT = 5900;
 const BROWSER_VIEWER_MEMORY_BYTES = 256 * 1024 * 1024;
@@ -1017,12 +1068,14 @@ export class DockerDriver implements Driver {
 		// bind whose source vanished since registration, but Podman's Docker-compatible API auto-creates the
 		// missing source instead - which would silently start the run against an empty directory, exactly
 		// what `actor-driver.md` forbids ("fail visibly - never silently mount an empty directory").
+		let preservedEntrypoint: PreservedEntrypoint | undefined;
 		if (ctx.devMount) {
 			await this.assertDevFolderStillPresent(ctx.devMount.localDevFolder);
 			onLog(
 				`Mounting local dev folder ${ctx.devMount.localDevFolder} over the image's working directory ` +
-					`${ctx.devMount.imageWorkingDirectory} (node_modules preserved via an anonymous volume).\n`,
+					`${ctx.devMount.imageWorkingDirectory} (node_modules preserved via a per-run volume).\n`,
 			);
+			preservedEntrypoint = await this.preserveHiddenEntrypoint(ctx.imageId, ctx.devMount, onLog);
 		}
 
 		// Loaded and logged before `createContainer` so a missing payload fails the run before any
@@ -1055,6 +1108,7 @@ export class DockerDriver implements Driver {
 				Image: ctx.imageId,
 				Env: env,
 				Labels: { [RUN_LABEL]: ctx.runId },
+				...(preservedEntrypoint ? { [preservedEntrypoint.field]: preservedEntrypoint.command } : {}),
 				...(ctx.debug ? { ExposedPorts: { [`${ctx.debug.port}/tcp`]: {} } } : {}),
 				HostConfig: {
 					...(await this.actorNetworkHostConfig(onActorNetwork)),
@@ -1094,6 +1148,7 @@ export class DockerDriver implements Driver {
 
 		try {
 			// Inside the try so a failed upload still reaches the finally below and removes the container.
+			if (preservedEntrypoint) await container.putArchive(preservedEntrypoint.tar, { path: '/' });
 			if (debugPayload) {
 				await container.putArchive(debugPayload.tar, { path: '/' });
 			}
@@ -1117,6 +1172,7 @@ export class DockerDriver implements Driver {
 				this.runContainers.set(ctx.runId, retry);
 				container = retry;
 				try {
+					if (preservedEntrypoint) await retry.putArchive(preservedEntrypoint.tar, { path: '/' });
 					if (debugPayload) await retry.putArchive(debugPayload.tar, { path: '/' });
 					await retry.start();
 				} catch (retryError) {
@@ -1245,6 +1301,75 @@ export class DockerDriver implements Driver {
 		);
 	}
 
+	/**
+	 * A `devMount` run starts through the image's own `Entrypoint` (or `Cmd`); when that names a file
+	 * inside the working directory - Apify's Playwright base images start through `./xvfb-entrypoint.sh`
+	 * there - the bind mount hides it unless the dev folder happens to carry the same file, and the engine
+	 * refuses to start ("executable file not found"). Unless the dev folder provides it, the file is
+	 * taken from the image and the run starts through that copy, at a path no mount covers. Anything
+	 * `PATH`-resolved or absolute is left alone: the mount cannot hide it.
+	 */
+	private async preserveHiddenEntrypoint(
+		imageId: string,
+		devMount: DevFolderMount,
+		onLog: (chunk: string) => void,
+	): Promise<PreservedEntrypoint | undefined> {
+		const info = await this.docker.getImage(imageId).inspect();
+		const entrypointRaw = info.Config?.Entrypoint;
+		const entrypoint = Array.isArray(entrypointRaw) ? entrypointRaw : entrypointRaw ? [entrypointRaw] : [];
+		const field: PreservedEntrypoint['field'] = entrypoint.length > 0 ? 'Entrypoint' : 'Cmd';
+		const command = field === 'Entrypoint' ? entrypoint : (info.Config?.Cmd ?? []);
+		const first = command[0];
+		if (!first || !isWorkingDirectoryRelative(first)) return undefined;
+		if (await this.devFolderHasEntry(devMount.localDevFolder, first)) return undefined;
+
+		const inImage = path.posix.resolve(devMount.imageWorkingDirectory, first);
+		const archive = await this.extractFromImage(imageId, inImage);
+		const tarball = await repackUnderDirectory(archive, PRESERVED_ENTRYPOINT_DIR);
+		onLog(
+			`The image starts through ${first} in its working directory, which the dev folder does not contain; ` +
+				`using the image's own copy of it.\n`,
+		);
+		return {
+			field,
+			command: [`${PRESERVED_ENTRYPOINT_DIR}/${path.posix.basename(inImage)}`, ...command.slice(1)],
+			tar: tarball,
+		};
+	}
+
+	/** Whether `relativePath` exists inside the registered dev folder on the host - through the same probe
+	 * container `probeDevFolder` uses, so the answer is the engine's own. Public for tests. */
+	async devFolderHasEntry(localDevFolder: string, relativePath: string): Promise<boolean> {
+		const container = await this.docker.createContainer({
+			Image: await this.ensureProbeImage(),
+			Labels: { [PROBE_LABEL]: 'true' },
+			HostConfig: {
+				Mounts: [{ Type: 'bind', Source: PROBE_MOUNT_SOURCE, Target: PROBE_MOUNT_TARGET, ReadOnly: true }],
+			},
+		});
+		try {
+			const outcome = await statInProbe(
+				container,
+				path.posix.join(PROBE_MOUNT_TARGET, localDevFolder, relativePath),
+			);
+			return outcome.ok;
+		} finally {
+			await container.remove().catch((error: Error) => {
+				console.warn(`Could not remove dev-folder probe container ${container.id}: ${error.message}`);
+			});
+		}
+	}
+
+	/** The archive of one path from an image, read through a container created (never started) from it. */
+	private async extractFromImage(imageId: string, pathInImage: string): Promise<Buffer> {
+		const container = await this.docker.createContainer({ Image: imageId, Labels: { [PROBE_LABEL]: 'true' } });
+		try {
+			return await readStream((await container.getArchive({ path: pathInImage })) as NodeJS.ReadableStream);
+		} finally {
+			await container.remove().catch(() => undefined);
+		}
+	}
+
 	/** The two `HostConfig.Mounts` entries for a `devMount` run: a read-write bind for the dev folder
 	 * itself (`Mounts`, not `Binds` - a `Mounts`-type bind errors on a missing source instead of silently
 	 * auto-creating one), plus a fresh per-run volume over `node_modules` - the engine creates it at

test/e2e/dev-folder-bind-mount.test.ts

@@ -14,7 +14,7 @@
  * Requires a reachable Docker daemon and fails loudly, never skips, mirroring `actor-dev-loop.test.ts`.
  */
 import { execFileSync } from 'node:child_process';
-import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
@@ -298,6 +298,63 @@ describe('local dev-folder bind mount: edit-compile-call loop with no rebuild (r
 		5 * 60 * 1000,
 	);
 
+	it(
+		"an entrypoint the image keeps inside its working directory (Apify's Playwright images start through one) stays available under the mount when the dev folder lacks it",
+		() => {
+			const env = apifyEnv(isolatedApifyHome);
+			// A tiny Actor of its own: busybox, an entrypoint script at ./entry.sh in the working directory
+			// (what `apify/actor-*-playwright*` images do with their Xvfb wrapper), and a dev folder that has
+			// no such file - mounting it over /app would hide the script.
+			const entryActorDir = mkdtempSync(join(tmpdir(), 'actor-runtime-e2e-devfolder-entry-'));
+			const devFolder = mkdtempSync(join(tmpdir(), 'actor-runtime-e2e-devfolder-entry-src-'));
+			try {
+				mkdirSync(join(entryActorDir, '.actor'));
+				writeFileSync(
+					join(entryActorDir, '.actor', 'actor.json'),
+					JSON.stringify({
+						actorSpecification: 1,
+						name: 'devfolder-entrypoint',
+						version: '0.0',
+						buildTag: 'latest',
+					}),
+				);
+				writeFileSync(
+					join(entryActorDir, 'entry.sh'),
+					'#!/bin/sh\necho "entry.sh from the image: $0"\nexec "$@"\n',
+				);
+				writeFileSync(
+					join(entryActorDir, 'Dockerfile'),
+					[
+						'FROM docker.io/library/busybox',
+						'WORKDIR /app',
+						'COPY entry.sh ./entry.sh',
+						'RUN chmod 755 ./entry.sh',
+						'ENTRYPOINT ["./entry.sh"]',
+						'CMD ["sh", "-c", "ls /app; echo run-body-done"]',
+						'',
+					].join('\n'),
+				);
+				writeFileSync(join(devFolder, 'only-in-dev-folder.txt'), 'x');
+
+				const push = JSON.parse(apify(['push', '--json'], { cwd: entryActorDir, env })) as PushResult;
+				expect(push.build.status).toBe('SUCCEEDED');
+				registerDevFolder(push.actor.id, devFolder, env);
+
+				// `apify call` streams the run log; a FAILED run makes it exit non-zero, which throws here.
+				const output = apifyAllOutput(['call'], { cwd: entryActorDir, env });
+				expect(output).toContain('starts through ./entry.sh in its working directory');
+				expect(output).toContain('entry.sh from the image: /apify-runtime-entrypoint/entry.sh');
+				// The dev folder, not the image's /app, is what the run sees in the working directory.
+				expect(output).toContain('only-in-dev-folder.txt');
+				expect(output).toContain('run-body-done');
+			} finally {
+				rmSync(entryActorDir, { recursive: true, force: true });
+				rmSync(devFolder, { recursive: true, force: true });
+			}
+		},
+		5 * 60 * 1000,
+	);
+
 	it(
 		'anonymous node_modules volumes do not accumulate across runs ({ v: true } cleanup)',
 		async () => {

test/unit/docker-driver.test.ts

@@ -1009,6 +1009,110 @@ describe('DockerDriver.probeDevFolder (actor-driver.md: "A host-side existence-a
 	});
 });
 
+describe('DockerDriver.startRun - an image entrypoint the dev-folder mount would hide (actor-driver.md: "stays available to the run")', () => {
+	const devMountRun = {
+		runId: 'run-entry',
+		imageId: 'fake-image',
+		env: {},
+		memoryMbytes: 128,
+		timeoutSecs: 60,
+		devMount: { localDevFolder: '/host/src', imageWorkingDirectory: '/usr/src/app' },
+	};
+
+	function scriptArchive(name: string, content: string): NodeJS.ReadableStream {
+		const pack = tar.pack();
+		pack.entry({ name, mode: 0o755 }, content);
+		pack.finalize();
+		return pack as unknown as NodeJS.ReadableStream;
+	}
+
+	async function entryNamesOf(archive: Buffer): Promise<Array<{ name: string; type?: string; content: string }>> {
+		const entries: Array<{ name: string; type?: string; content: string }> = [];
+		const extract = tar.extract();
+		await new Promise<void>((resolve, reject) => {
+			extract.on('entry', (header, stream, next) => {
+				const chunks: Buffer[] = [];
+				stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+				stream.on('end', () => {
+					entries.push({ name: header.name, type: header.type, content: Buffer.concat(chunks).toString() });
+					next();
+				});
+				stream.resume();
+			});
+			extract.once('finish', resolve);
+			extract.once('error', reject);
+			extract.end(archive);
+		});
+		return entries;
+	}
+
+	it('a relative entrypoint inside the working directory that the dev folder lacks: the file comes out of the image, lands in the container before start, and the run starts through that copy - the run log says so', async () => {
+		const stub = stubDockerForRun();
+		stub.imageInspect.mockResolvedValue({
+			Config: {
+				Entrypoint: ['./xvfb-entrypoint.sh'],
+				Cmd: ['python', '-m', 'my_actor'],
+				WorkingDir: '/usr/src/app',
+			},
+		});
+		stub.container.getArchive.mockResolvedValue(scriptArchive('xvfb-entrypoint.sh', '#!/bin/sh\nexec "$@"\n'));
+		const driver = new DockerDriver(stub.docker);
+		driver.available = true;
+		allowDevMountRecheck(driver);
+		const hasEntry = vi.spyOn(driver, 'devFolderHasEntry').mockResolvedValue(false);
+		const logged: string[] = [];
+
+		const outcomePromise = driver.startRun(devMountRun, (chunk) => logged.push(chunk));
+		await new Promise((resolve) => setImmediate(resolve));
+		await new Promise((resolve) => setImmediate(resolve));
+		stub.triggerContainerExit(0);
+		stub.endLogStream();
+		await outcomePromise;
+
+		expect(hasEntry).toHaveBeenCalledWith('/host/src', './xvfb-entrypoint.sh');
+		expect(stub.container.getArchive).toHaveBeenCalledWith({ path: '/usr/src/app/xvfb-entrypoint.sh' });
+		// Two containers: the throwaway one the file is read from, then the run's own.
+		expect(stub.createContainer).toHaveBeenCalledTimes(2);
+		const runOptions = stub.createContainer.mock.calls[1]![0];
+		expect(runOptions.Entrypoint).toEqual(['/apify-runtime-entrypoint/xvfb-entrypoint.sh']);
+		expect(runOptions.Cmd).toBeUndefined();
+		const [archive, putOptions] = stub.container.putArchive.mock.calls[0]!;
+		expect(putOptions).toEqual({ path: '/' });
+		expect(await entryNamesOf(archive as Buffer)).toEqual([
+			{ name: 'apify-runtime-entrypoint', type: 'directory', content: '' },
+			{ name: 'apify-runtime-entrypoint/xvfb-entrypoint.sh', type: 'file', content: '#!/bin/sh\nexec "$@"\n' },
+		]);
+		expect(logged.join('')).toContain('starts through ./xvfb-entrypoint.sh in its working directory');
+	});
+
+	it('the dev folder providing the file itself, an absolute entrypoint, or a PATH-resolved one: nothing is preserved and the image command stands', async () => {
+		for (const [config, devFolderHasIt] of [
+			[{ Entrypoint: ['./xvfb-entrypoint.sh'], WorkingDir: '/usr/src/app' }, true],
+			[{ Entrypoint: ['/usr/local/bin/xvfb-run', 'node', 'main.js'], WorkingDir: '/usr/src/app' }, false],
+			[{ Cmd: ['npm', 'start'], WorkingDir: '/usr/src/app' }, false],
+		] as Array<[Record<string, unknown>, boolean]>) {
+			const stub = stubDockerForRun();
+			stub.imageInspect.mockResolvedValue({ Config: config });
+			const driver = new DockerDriver(stub.docker);
+			driver.available = true;
+			allowDevMountRecheck(driver);
+			vi.spyOn(driver, 'devFolderHasEntry').mockResolvedValue(devFolderHasIt);
+
+			const outcomePromise = driver.startRun(devMountRun, () => {});
+			await new Promise((resolve) => setImmediate(resolve));
+			await new Promise((resolve) => setImmediate(resolve));
+			stub.triggerContainerExit(0);
+			stub.endLogStream();
+			await outcomePromise;
+
+			expect(stub.container.getArchive).not.toHaveBeenCalled();
+			expect(stub.createContainer).toHaveBeenCalledTimes(1);
+			expect(stub.createContainer.mock.calls[0]![0].Entrypoint).toBeUndefined();
+			expect(stub.container.putArchive).not.toHaveBeenCalled();
+		}
+	});
+});
+
 /** Lets a `startRun` test with a `devMount` get past the run-start dev-folder re-check
  * (`assertDevFolderStillPresent`) when that check is not what the test is about. */
 function allowDevMountRecheck(driver: DockerDriver): void {