Run Expo serve-sim under EAS supervision

CHANGELOG.md

@@ -19,6 +19,8 @@ This is the log of notable changes to EAS CLI and related packages.
 
 ### 🧹 Chores
 
+- [build-tools] Run EAS Simulator previews with the official `@expo/serve-sim` package under EAS-owned supervision. ([#4114](https://github.com/expo/eas-cli/pull/4114) by [@szdziedzic](https://github.com/szdziedzic))
+
 ## [21.4.0](https://github.com/expo/eas-cli/releases/tag/v21.4.0) - 2026-07-28
 
 ### 🎉 New features

packages/build-tools/src/steps/functions/__tests__/startArgentRemoteSession-orchestration.test.ts

@@ -56,6 +56,7 @@ const ARGENT_STATE_DIR = path.join(TEST_HOME, '.argent');
 const EXPECTED_EVENT_LOG_PATH = path.join(ARGENT_STATE_DIR, 'tool-server-events.jsonl');
 
 const mockStopAsync = jest.fn();
+const mockTunnelStopAsync = jest.fn();
 
 describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
   beforeEach(async () => {
@@ -65,14 +66,22 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     jest.mocked(isProcessDescendantOfAsync).mockResolvedValue(true);
     jest.mocked(pollArgentArtifactsForUploadAsync).mockResolvedValue(undefined);
     mockStopAsync.mockResolvedValue(undefined);
+    mockTunnelStopAsync.mockResolvedValue(undefined);
     jest.mocked(startArgentEventCollectionAsync).mockResolvedValue({ stopAsync: mockStopAsync });
 
     jest.mocked(getDeviceRunSessionIdOrThrow).mockReturnValue('device-run-session-id');
     jest.mocked(getNgrokTunnelDomainOrThrow).mockReturnValue('tunnel.example.com');
     jest.mocked(getNgrokAuthtokenOrThrow).mockReturnValue('ngrok-token');
     jest.mocked(selectXcodeDeveloperDirectoryAsync).mockResolvedValue(undefined);
-    jest.mocked(spawnDetached).mockReturnValue({ pid: 4242, getOutput: () => '' });
-    jest.mocked(startNgrokTunnelAsync).mockResolvedValue('https://argent-abc.tunnel.example.com');
+    jest.mocked(spawnDetached).mockReturnValue({
+      pid: 4242,
+      getOutput: () => '',
+      stopAsync: jest.fn(),
+    });
+    jest.mocked(startNgrokTunnelAsync).mockResolvedValue({
+      url: 'https://argent-abc.tunnel.example.com',
+      stopAsync: mockTunnelStopAsync,
+    });
     jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
     jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
 
@@ -134,5 +143,6 @@ describe('createStartArgentRemoteSessionBuildFunction orchestration', () => {
     expect(mockStopAsync.mock.invocationCallOrder[0]).toBeGreaterThan(
       jest.mocked(waitForDeviceRunSessionStoppedAsync).mock.invocationCallOrder[0]
     );
+    expect(mockTunnelStopAsync).toHaveBeenCalledTimes(1);
   });
 });

packages/build-tools/src/steps/functions/startAgentDeviceRemoteSession.ts

@@ -84,66 +84,76 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
       });
       logger.info(`Daemon is listening on port ${daemonPort}; loaded auth token.`);
 
-      const agentDeviceRemoteSessionUrl = await startNgrokTunnelAsync({
+      const agentDeviceTunnel = await startNgrokTunnelAsync({
         port: daemonPort,
         subdomainPrefix: 'agent-device',
         baseDomain: ngrokTunnelDomain,
         authtoken: ngrokAuthtoken,
         logger,
       });
+      const agentDeviceRemoteSessionUrl = agentDeviceTunnel.url;
       logger.info(`Tunnel is ready at ${agentDeviceRemoteSessionUrl}.`);
 
-      // serve-sim is iOS-only — only launch it (and report a webPreviewUrl)
-      // on Darwin. Android sessions go without a preview URL.
-      let webPreviewUrl: string | undefined;
-      if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-        const { previewUrl } = await startServeSimWithTunnelAsync(ctx, {
-          baseDomain: ngrokTunnelDomain,
-          env,
+      let serveSim: Awaited<ReturnType<typeof startServeSimWithTunnelAsync>> | undefined;
+      let eventCollection:
+        | Awaited<ReturnType<typeof startAgentDeviceEventCollectionAsync>>
+        | undefined;
+      try {
+        // serve-sim is iOS-only — only launch it (and report a webPreviewUrl)
+        // on Darwin. Android sessions go without a preview URL.
+        if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
+          serveSim = await startServeSimWithTunnelAsync(ctx, {
+            baseDomain: ngrokTunnelDomain,
+            env,
+            logger,
+            timeoutMs: STARTUP_TIMEOUT_MS,
+          });
+          logger.info(`Web preview URL: ${serveSim.previewUrl}`);
+        }
+
+        await uploadRemoteSessionConfigAsync({
+          ctx,
+          deviceRunSessionId,
+          remoteConfig: {
+            agentDeviceRemoteSessionUrl,
+            agentDeviceRemoteSessionToken: daemonToken,
+            ...(serveSim ? { webPreviewUrl: serveSim.previewUrl } : {}),
+          },
+          logger,
+        });
+        void pollAgentDeviceArtifactsForUploadAsync(ctx, {
+          deviceRunSessionId,
+          daemonUrl: `http://127.0.0.1:${daemonPort}`,
+          daemonToken,
           logger,
-          timeoutMs: STARTUP_TIMEOUT_MS,
         });
-        webPreviewUrl = previewUrl;
-        logger.info(`Web preview URL: ${webPreviewUrl}`);
-      }
-
-      await uploadRemoteSessionConfigAsync({
-        ctx,
-        deviceRunSessionId,
-        remoteConfig: {
-          agentDeviceRemoteSessionUrl,
-          agentDeviceRemoteSessionToken: daemonToken,
-          ...(webPreviewUrl ? { webPreviewUrl } : {}),
-        },
-        logger,
-      });
-      void pollAgentDeviceArtifactsForUploadAsync(ctx, {
-        deviceRunSessionId,
-        daemonUrl: `http://127.0.0.1:${daemonPort}`,
-        daemonToken,
-        logger,
-      });
 
-      const eventCollection = await startAgentDeviceEventCollectionAsync({
-        ctx,
-        deviceRunSessionId,
-        stateDir: AGENT_DEVICE_STATE_DIR,
-        logger,
-      });
+        eventCollection = await startAgentDeviceEventCollectionAsync({
+          ctx,
+          deviceRunSessionId,
+          stateDir: AGENT_DEVICE_STATE_DIR,
+          logger,
+        });
 
-      try {
         await waitForDeviceRunSessionStoppedAsync({
           ctx,
           deviceRunSessionId,
           logger,
           signal,
         });
       } finally {
-        await stopAgentDeviceEventCollectionSafelyAsync({
-          eventCollection,
-          deviceRunSessionId,
-          logger,
-        });
+        if (serveSim) {
+          await serveSim.stopAsync();
+        }
+        await agentDeviceTunnel.stopAsync();
+        if (eventCollection) {
+          await stopAgentDeviceEventCollectionSafelyAsync({
+            eventCollection,
+            deviceRunSessionId,
+            logger,
+          });
+        }
+        await daemonProcess.stopAsync();
       }
     },
   });

packages/build-tools/src/steps/functions/startArgentRemoteSession.ts

@@ -165,21 +165,24 @@ export function createStartArgentRemoteSessionBuildFunction(
         logger,
       });
 
+      let toolsTunnel: Awaited<ReturnType<typeof startNgrokTunnelAsync>> | undefined;
+      let serveSim: Awaited<ReturnType<typeof startServeSimWithTunnelAsync>> | undefined;
       try {
-        const publicToolsUrl = await startNgrokTunnelAsync({
+        toolsTunnel = await startNgrokTunnelAsync({
           port: toolServerPort,
           subdomainPrefix: 'argent',
           baseDomain: ngrokTunnelDomain,
           authtoken: ngrokAuthtoken,
           rewriteHostHeader: true,
           logger,
         });
+        const publicToolsUrl = toolsTunnel.url;
         logger.info(`Tunnel is ready at ${publicToolsUrl}.`);
 
         // serve-sim is iOS-only — Android sessions go without a preview URL.
         let webPreviewUrl: string | undefined;
         if (runtimePlatform === BuildRuntimePlatform.DARWIN) {
-          const serveSim = await startServeSimWithTunnelAsync(ctx, {
+          serveSim = await startServeSimWithTunnelAsync(ctx, {
             baseDomain: ngrokTunnelDomain,
             env,
             logger,
@@ -207,6 +210,12 @@ export function createStartArgentRemoteSessionBuildFunction(
           signal,
         });
       } finally {
+        if (serveSim) {
+          await serveSim.stopAsync();
+        }
+        if (toolsTunnel) {
+          await toolsTunnel.stopAsync();
+        }
         await stopArgentEventCollectionSafelyAsync({ eventCollection, deviceRunSessionId, logger });
         artifactPollAbortController.abort();
         try {
@@ -216,6 +225,7 @@ export function createStartArgentRemoteSessionBuildFunction(
           Sentry.capture('Could not finish Argent remote session artifact polling', error);
           logger.warn({ err: error }, 'Could not finish Argent remote session artifact polling.');
         }
+        await argentServer.stopAsync();
       }
     },
   });

packages/build-tools/src/steps/functions/startServeSimRemoteSession.ts

@@ -29,27 +29,31 @@ export function createStartServeSimRemoteSessionBuildFunction(
 
       await selectXcodeDeveloperDirectoryAsync({ env, logger });
 
-      const { previewUrl } = await startServeSimWithTunnelAsync(ctx, {
+      const serveSim = await startServeSimWithTunnelAsync(ctx, {
         baseDomain: ngrokTunnelDomain,
         env,
         logger,
         timeoutMs: STARTUP_TIMEOUT_MS,
       });
-      logger.info(`Preview URL: ${previewUrl}`);
-
-      await uploadRemoteSessionConfigAsync({
-        ctx,
-        deviceRunSessionId,
-        remoteConfig: { previewUrl },
-        logger,
-      });
-
-      await waitForDeviceRunSessionStoppedAsync({
-        ctx,
-        deviceRunSessionId,
-        logger,
-        signal,
-      });
+      logger.info(`Preview URL: ${serveSim.previewUrl}`);
+
+      try {
+        await uploadRemoteSessionConfigAsync({
+          ctx,
+          deviceRunSessionId,
+          remoteConfig: { previewUrl: serveSim.previewUrl },
+          logger,
+        });
+
+        await waitForDeviceRunSessionStoppedAsync({
+          ctx,
+          deviceRunSessionId,
+          logger,
+          signal,
+        });
+      } finally {
+        await serveSim.stopAsync();
+      }
     },
   });
 }

packages/build-tools/src/steps/utils/__tests__/remoteDeviceRunSession.test.ts

@@ -1,18 +1,25 @@
 import { bunyan } from '@expo/logger';
 import { BuildStepEnv } from '@expo/steps';
+import * as ngrok from '@ngrok/ngrok';
 import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
 
 import { CustomBuildContext } from '../../../customBuildContext';
 import { Sentry } from '../../../sentry';
 import { turtleFetch } from '../../../utils/turtleFetch';
+import { sleepAsync } from '../../../utils/retry';
 import {
+  createServeSimArgs,
   fetchServeSimTurnArgsAsync,
+  startNgrokTunnelAsync,
   turnIceServersToServeSimArgs,
   waitForDeviceRunSessionStoppedAsync,
+  waitForServeSimReadyAsync,
 } from '../remoteDeviceRunSession';
 
+jest.mock('@ngrok/ngrok');
 jest.mock('node:timers/promises');
 jest.mock('../../../utils/turtleFetch');
+jest.mock('../../../utils/retry', () => ({ sleepAsync: jest.fn() }));
 jest.mock('../../../sentry');
 
 function createLoggerMock(): bunyan {
@@ -80,6 +87,99 @@ function createEnvMock(): BuildStepEnv {
   return { DEVICE_RUN_SESSION_ID: 'drs-id' } as unknown as BuildStepEnv;
 }
 
+describe(createServeSimArgs, () => {
+  it('uses the latest Expo package and applies the EAS streaming policy', () => {
+    expect(
+      createServeSimArgs({
+        port: 4321,
+        turnArgs: ['--turn-url', 'turns:turn.example.test:443'],
+      })
+    ).toEqual([
+      '--yes',
+      '@expo/serve-sim@latest',
+      '--port',
+      '4321',
+      '--host',
+      '127.0.0.1',
+      '--transport',
+      'webrtc',
+      '--webrtc-codec',
+      'vp8',
+      '--max-dimension',
+      '1280',
+      '--mjpeg-quality',
+      '0.55',
+      '--video-bitrate',
+      '3000000',
+      '--video-fps',
+      '60',
+      '--turn-url',
+      'turns:turn.example.test:443',
+    ]);
+  });
+});
+
+describe(waitForServeSimReadyAsync, () => {
+  beforeEach(() => {
+    jest.mocked(turtleFetch).mockReset();
+    jest.mocked(sleepAsync).mockReset();
+    jest.mocked(sleepAsync).mockResolvedValue(undefined);
+  });
+
+  it('waits for the stable readiness endpoint', async () => {
+    jest
+      .mocked(turtleFetch)
+      .mockRejectedValueOnce(new Error('not ready'))
+      .mockResolvedValueOnce({
+        json: async () => ({ status: 'ready', device: 'DEVICE-A' }),
+      } as unknown as Awaited<ReturnType<typeof turtleFetch>>);
+
+    await waitForServeSimReadyAsync({
+      serveSim: { pid: undefined, getOutput: () => '' },
+      port: 4321,
+      timeoutMs: 10_000,
+    });
+
+    expect(jest.mocked(turtleFetch)).toHaveBeenCalledTimes(2);
+    expect(jest.mocked(turtleFetch)).toHaveBeenLastCalledWith(
+      'http://127.0.0.1:4321/readyz',
+      'GET',
+      expect.objectContaining({ retries: 0 })
+    );
+    expect(sleepAsync).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe(startNgrokTunnelAsync, () => {
+  it('uses a 128-bit capability hostname and exposes explicit cleanup', async () => {
+    const close = jest.fn().mockResolvedValue(undefined);
+    jest.mocked(ngrok.forward).mockResolvedValue({
+      url: () => 'https://serve-sim.example.test',
+      close,
+    } as never);
+
+    const tunnel = await startNgrokTunnelAsync({
+      port: 4321,
+      subdomainPrefix: 'serve-sim',
+      baseDomain: 'tunnel.example.test',
+      authtoken: 'token',
+      logger: createLoggerMock(),
+    });
+
+    expect(ngrok.forward).toHaveBeenCalledWith(
+      expect.objectContaining({
+        addr: 4321,
+        authtoken: 'token',
+        domain: expect.stringMatching(/^serve-sim-[a-f0-9]{32}\.tunnel\.example\.test$/),
+      })
+    );
+    expect(tunnel.url).toBe('https://serve-sim.example.test');
+    await tunnel.stopAsync();
+    await tunnel.stopAsync();
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+});
+
 describe(turnIceServersToServeSimArgs, () => {
   it('returns no args for an empty ICE server list', () => {
     expect(turnIceServersToServeSimArgs([])).toEqual([]);