Reach the browser-view sidecar on localhost when the runtime is not on apify-local

Under rootless Podman the runtime container cannot join the network, so the console could not reach
the VNC sidecar by its address there and the viewer never got the RFB greeting. The sidecar now shares
the runtime container's own network namespace in that case, on a port allocated in that namespace, and
the console connects to it on 127.0.0.1. The alias route is unchanged whenever it is available.

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

Author: Pijukatel

README.md

@@ -76,7 +76,7 @@ Good to know:
 - Under rootless Podman the runtime container cannot join the `apify-local` network, so Actors reach
   the API through the runtime's published port 3333 instead. Keep `-p 3333:3333` published on all
   interfaces, or pre-create the network (`podman network create apify-local`) and add
-  `--network apify-local` to the run command to use the direct route (browser view needs it).
+  `--network apify-local` to the run command to use the direct route.
 - Rootless engines on a cgroups v1 host do not apply the per-run memory and CPU limits.
 - If you restart a hand-started `podman system service`, the socket file mounted into the runtime goes
   stale; restart the runtime container too. The `podman.socket` unit does not have this problem.

src/driver/docker-driver.ts

@@ -34,6 +34,7 @@
 import { PassThrough } from 'node:stream';
 import { createReadStream } from 'node:fs';
 import { readFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
 import * as path from 'node:path';
 import Docker from 'dockerode';
 import * as tar from 'tar-stream';
@@ -215,6 +216,22 @@ async function statInProbe(container: Docker.Container, containerPath: string):
 	return parseProbeStatResponse(response);
 }
 
+/** A TCP port that is free in this process's own network namespace right now - bound on loopback and
+ * released again, for a sidecar about to share that namespace (`startBrowserViewer`). */
+async function allocateFreePort(): Promise<number> {
+	return new Promise((resolve, reject) => {
+		const server = createServer();
+		server.once('error', reject);
+		server.listen(0, '127.0.0.1', () => {
+			const address = server.address();
+			server.close(() => {
+				if (address && typeof address === 'object') resolve(address.port);
+				else reject(new Error('Could not allocate a free port for the browser-view sidecar'));
+			});
+		});
+	});
+}
+
 /**
  * Maps the `linkTarget` a symlink stat reports back to a host path. Docker resolves a link's target in
  * the scope of the container's root filesystem and reports that absolute container path: a target that
@@ -542,8 +559,8 @@ export class DockerDriver implements Driver {
 				`Could not attach the runtime's own container to the ${NETWORK_NAME} network: ${(error as Error).message}. ` +
 					`Actor containers will reach this API through the host's published port ${API_PORT} instead ` +
 					`(${CONTAINER_API_ALIAS} -> host-gateway), so keep -p ${API_PORT}:${API_PORT} published on all interfaces. ` +
-					`Browser view needs the direct route: pre-create the network (\`podman network create ${NETWORK_NAME}\`) ` +
-					`and start the runtime container with \`--network ${NETWORK_NAME}\`, which also restores the alias.`,
+					`To use the network alias anyway, pre-create the network (\`podman network create ${NETWORK_NAME}\`) ` +
+					`and start the runtime container with \`--network ${NETWORK_NAME}\`.`,
 			);
 		}
 	}
@@ -1191,6 +1208,15 @@ export class DockerDriver implements Driver {
 			Labels: labels,
 		});
 
+		// How the console reaches the sidecar's VNC server. Normally the sidecar joins `apify-local` and is
+		// reached by its address there. When this process runs in a container that could not join that
+		// network (`apiReachableByAlias`'s doc comment - rootless Podman), the sidecar shares this
+		// container's own network namespace instead, so the console reaches it on localhost; every sidecar
+		// then needs a port of its own in that shared namespace, allocated here where it will be used.
+		const selfContainerId = process.env.HOSTNAME;
+		const sharesRuntimeNetns = !this.apiReachableByAlias && !!selfContainerId;
+		const vncPort = sharesRuntimeNetns ? await allocateFreePort() : BROWSER_VIEWER_VNC_PORT;
+
 		let container: Docker.Container | undefined;
 		try {
 			container = await this.docker.createContainer({
@@ -1199,11 +1225,11 @@ export class DockerDriver implements Driver {
 				Cmd: ['/bin/sh', BROWSER_VIEWER_SCRIPT],
 				Env: [
 					`${BROWSER_VIEWER_INTERACTIVE_ENV}=${target.interactive ? '1' : '0'}`,
-					`${BROWSER_VIEWER_PORT_ENV}=${BROWSER_VIEWER_VNC_PORT}`,
+					`${BROWSER_VIEWER_PORT_ENV}=${vncPort}`,
 				],
 				Labels: labels,
 				HostConfig: {
-					NetworkMode: NETWORK_NAME,
+					NetworkMode: sharesRuntimeNetns ? `container:${selfContainerId}` : NETWORK_NAME,
 					Memory: BROWSER_VIEWER_MEMORY_BYTES,
 					AutoRemove: false,
 					Mounts: [{ Type: 'volume', Source: volumeName, Target: X11_SOCKET_DIR }],
@@ -1213,12 +1239,15 @@ export class DockerDriver implements Driver {
 			this.browserViewers.set(target.runId, { container, volumeName });
 			await container.start();
 
+			if (sharesRuntimeNetns) {
+				return { vncHost: '127.0.0.1', vncPort, x11SocketVolume: volumeName };
+			}
 			const info = await container.inspect();
 			const address = info.NetworkSettings?.Networks?.[NETWORK_NAME]?.IPAddress;
 			return {
 				// The IP also works from a runtime running outside Docker; the name only resolves from inside.
 				vncHost: address || containerName,
-				vncPort: BROWSER_VIEWER_VNC_PORT,
+				vncPort,
 				x11SocketVolume: volumeName,
 			};
 		} catch (error) {

test/unit/docker-driver-browser-view.test.ts

@@ -81,6 +81,7 @@ describe('DockerDriver.startBrowserViewer / stopBrowserViewer', () => {
 	});
 
 	afterEach(() => {
+		vi.unstubAllEnvs();
 		rmSync(payloadDir, { recursive: true, force: true });
 		if (originalEnv === undefined) delete process.env[PAYLOAD_ENV];
 		else process.env[PAYLOAD_ENV] = originalEnv;
@@ -148,6 +149,42 @@ describe('DockerDriver.startBrowserViewer / stopBrowserViewer', () => {
 		expect(stub.getImage).toHaveBeenCalledTimes(1);
 	});
 
+	it("when this process runs in a container that could not join apify-local (rootless Podman), the sidecar shares this container's network namespace on a port of its own and is reached on localhost", async () => {
+		vi.stubEnv('HOSTNAME', 'abc123def456');
+		const stub = stubDockerForViewer({ imagePresent: true });
+		const driver = new DockerDriver(stub.docker);
+		driver.available = true; // `apiReachableByAlias` stays false: `init()` never attached this container.
+
+		const handle = await driver.startBrowserViewer({ runId: 'run-netns', interactive: false });
+
+		const [containerOptions] = stub.createContainer.mock.calls[0]!;
+		expect(containerOptions.HostConfig?.NetworkMode).toBe('container:abc123def456');
+		expect(handle.vncHost).toBe('127.0.0.1');
+		expect(handle.vncPort).toBeGreaterThan(0);
+		expect(handle.vncPort).not.toBe(5900);
+		expect(containerOptions.Env).toContain(`APIFY_BROWSER_VIEWER_PORT=${handle.vncPort}`);
+		// Nothing to look up on the network: the address is this container's own loopback.
+		expect(stub.container.inspect).not.toHaveBeenCalled();
+	});
+
+	it('joins apify-local as usual when this container did attach to it, even though it runs in a container', async () => {
+		vi.stubEnv('HOSTNAME', 'abc123def456');
+		const stub = stubDockerForViewer({ imagePresent: true });
+		const driver = new DockerDriver(stub.docker);
+		driver.available = true;
+		(driver as unknown as { apiReachableByAlias: boolean }).apiReachableByAlias = true;
+
+		const handle = await driver.startBrowserViewer({ runId: 'run-alias', interactive: false });
+
+		const [containerOptions] = stub.createContainer.mock.calls[0]!;
+		expect(containerOptions.HostConfig?.NetworkMode).toBe('apify-local');
+		expect(handle).toEqual({
+			vncHost: '172.18.0.9',
+			vncPort: 5900,
+			x11SocketVolume: 'actor-runtime-x11-run-alias',
+		});
+	});
+
 	it('falls back to the sidecar container name as vncHost when the daemon reports no IP on apify-local', async () => {
 		const stub = stubDockerForViewer({ imagePresent: true, ipAddress: '' });
 		const driver = new DockerDriver(stub.docker);