v24.1.1

[eas-cli] describe the inline egress client instead of asking to start one (#4382 )
[eas-cli] improve EasCommand test reliability (#4381 )
2026-11-15 03:38:08 -10:00 · 2026-09-11 00:10:40 +00:00 · 2026-09-10 17:07:16 -07:00 · 2026-09-10 17:05:16 -07:00 · 2026-09-10 23:27:17 +00:00 · 2026-09-10 23:24:59 +00:00
45 changed files with 6282 additions and 464 deletions
@@ -6,6 +6,32 @@ This is the log of notable changes to EAS CLI and related packages.

 ### 🛠 Breaking changes

+### 🎉 New features
+
+### 🐛 Bug fixes
+
+- [eas-cli] Stop telling interactive `eas simulator:start --egress local` users to run `eas simulator:egress` when the egress client already runs in the same terminal. ([#4382](https://github.com/expo/eas-cli/pull/4382) by [@brentvatne](https://github.com/brentvatne))
+
+### 🧹 Chores
+
+## [24.1.0](https://github.com/expo/eas-cli/releases/tag/v24.1.0) - 2026-09-10
+
+### 🎉 New features
+
+- [eas-cli] Add `--egress-allow <host:port>` to `eas simulator:start` so local egress sessions can reach dev servers on this machine or its network. ([#4369](https://github.com/expo/eas-cli/pull/4369) by [@brentvatne](https://github.com/brentvatne))
+- [eas-cli][build-tools] Forward `--egress-allow localhost:<port>` and `127.0.0.1:<port>` entries from the simulator host's loopback interface to this machine (like `adb reverse`), so dev server URLs that use `127.0.0.1` work through local egress. ([#4369](https://github.com/expo/eas-cli/pull/4369) by [@brentvatne](https://github.com/brentvatne))
+- [build-tools] Add the `eas/start_local_egress` step for iOS simulator sessions with local egress: the device host's system proxy points at a reverse tunnel to the EAS CLI machine, so HTTP(S) requests that honor it exit from that machine and third parties see its IP. ([#4364](https://github.com/expo/eas-cli/pull/4364) by [@brentvatne](https://github.com/brentvatne))
+- [eas-cli] Add `--egress local` to `eas simulator:start` and the `eas simulator:egress` command, which run the local egress client for the session. ([#4364](https://github.com/expo/eas-cli/pull/4364) by [@brentvatne](https://github.com/brentvatne))
+- [build-tools] Require the serve-sim session token for device run session previews, so the tunnel no longer exposes the shell-exec route. ([#4306](https://github.com/expo/eas-cli/pull/4306) by [@gwdp](https://github.com/gwdp))
+
+### 🐛 Bug fixes
+
+- [build-tools] Report a system error when project source refresh fails for a remote build. ([#4359](https://github.com/expo/eas-cli/pull/4359) by [@sjchmiela](https://github.com/sjchmiela))
+
+## [24.0.0](https://github.com/expo/eas-cli/releases/tag/v24.0.0) - 2026-09-09
+
+### 🛠 Breaking changes
+
 - [eas-cli] Align the `eas observe:*` commands with the renamed Observe GraphQL schema. `--json` output now uses `name`/`value` instead of `metricName`/`metricValue` (metrics) and `name` instead of `eventName` (log events and event-name summaries), and `eas observe:events` now lists user-defined events only — exceptions moved to the new `eas observe:errors`. ([#4338](https://github.com/expo/eas-cli/pull/4338) by [@douglowder](https://github.com/douglowder))

 ### 🎉 New features
@@ -1,4 +1,4 @@
 {
-  "STAGING": "23.2.0",
-  "PRODUCTION": "23.2.0"
+  "STAGING": "24.1.0",
+  "PRODUCTION": "24.1.0"
 }
@@ -1,5 +1,5 @@
 {
  "npmClient": "yarn",
-  "version": "24.0.0",
+  "version": "24.1.1",
  "$schema": "node_modules/lerna/schemas/lerna-schema.json"
 }
@@ -1,6 +1,6 @@
 {
  "name": "@expo/build-tools",
-  "version": "24.0.0",
+  "version": "24.1.0",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
  "author": "Expo <[email protected]>",
@@ -4,9 +4,11 @@ import { BuildStepGlobalContext, StepsConfigParser } from '@expo/steps';
 import { runGenericJobAsync } from '../generic';
 import { CustomBuildContext } from '../customBuildContext';
 import { uploadJobOutputsToWwwAsync } from '../utils/outputs';
+import { stopLocalEgressResourcesAsync } from '../steps/utils/localEgress';

 jest.mock('../customBuildContext');
 jest.mock('../utils/outputs');
+jest.mock('../steps/utils/localEgress', () => ({ stopLocalEgressResourcesAsync: jest.fn() }));
 jest.mock('../common/projectSources');
 jest.mock('../steps/easFunctions', () => ({ getEasFunctions: jest.fn().mockReturnValue([]) }));
 jest.mock('../steps/easFunctionGroups', () => ({
@@ -58,6 +60,25 @@ describe(runGenericJobAsync, () => {
    mockUploadJobOutputsToWwwAsync.mockResolvedValue(undefined);
  });

+  it.each(['success', 'failure'])(
+    'releases local egress after workflow %s, before uploading outputs',
+    async outcome => {
+      const executeAsync =
+        outcome === 'success'
+          ? jest.fn().mockResolvedValue(undefined)
+          : jest.fn().mockRejectedValue(new Error(outcome));
+      (StepsConfigParser as unknown as jest.Mock).mockImplementation(() => ({
+        parseAsync: jest.fn().mockResolvedValue({ executeAsync }),
+      }));
+      const { runResult } = await runGenericJobAsync(mockCtx);
+      expect(runResult.ok).toBe(outcome === 'success');
+      expect(stopLocalEgressResourcesAsync).toHaveBeenCalledWith(mockCtx.logger);
+      expect(jest.mocked(stopLocalEgressResourcesAsync).mock.invocationCallOrder[0]).toBeLessThan(
+        mockUploadJobOutputsToWwwAsync.mock.invocationCallOrder[0]
+      );
+    }
+  );
+
  it('awaits drainPendingMetricUploads in COMPLETE_JOB phase', async () => {
    const mockWorkflow = { executeAsync: jest.fn().mockResolvedValue(undefined) };
    (StepsConfigParser as unknown as jest.Mock).mockImplementation(() => ({
@@ -2,8 +2,10 @@ import {
  ArchiveSourceType,
  BuildMode,
  BuildTrigger,
+  ErrorCode,
  Job,
  Platform,
+  SystemError,
  Workflow,
 } from '@expo/eas-build-job';
 import spawn from '@expo/turtle-spawn';
@@ -45,7 +47,7 @@ describe('projectSources', () => {
    expect(logger.info).toHaveBeenCalledWith('Normalizing project source permissions');
  });

-  it('should use the refreshed repository URL', async () => {
+  it.each([false, true])('uses the correct repository URL (local: %s)', async isLocal => {
    const robotAccessToken = randomUUID();
    const buildId = randomUUID();
    await vol.promises.mkdir('/workingdir/environment-secrets/', { recursive: true });
@@ -76,7 +78,7 @@ describe('projectSources', () => {
          __API_SERVER_URL: 'https://api.expo.dev',
          EXPO_TOKEN: robotAccessToken,
          EAS_BUILD_ID: buildId,
-          EAS_BUILD_RUNNER: 'eas-build',
+          EAS_BUILD_RUNNER: isLocal ? 'local-build-plugin' : 'eas-build',
        },
        workingdir: '/workingdir',
        logger: createMockLogger(),
@@ -105,108 +107,88 @@ describe('projectSources', () => {
      expect.objectContaining({
        archiveSource: {
          ...ctx.job.projectArchive,
-          repositoryUrl: 'https://x-access-token:[email protected]/expo/eas-cli.git',
+          repositoryUrl: isLocal
+            ? 'https://x-access-token:[email protected]/expo/eas-cli.git'
+            : 'https://x-access-token:[email protected]/expo/eas-cli.git',
        },
      })
    );
+    if (isLocal) {
+      expect(fetchMock).not.toHaveBeenCalled();
+    }
  });

-  it('should fallback to the original repository URL if the refresh fails', async () => {
-    const robotAccessToken = randomUUID();
-    const buildId = randomUUID();
-    await vol.promises.mkdir('/workingdir/environment-secrets/', { recursive: true });
+  it.each(['http', 'network', 'json', 'schema'])(
+    'throws a system error if refresh fails (%s)',
+    async failure => {
+      const robotAccessToken = randomUUID();
+      const buildId = randomUUID();
+      await vol.promises.mkdir('/workingdir/environment-secrets/', { recursive: true });

-    const ctx = new BuildContext(
-      {
-        triggeredBy: BuildTrigger.GIT_BASED_INTEGRATION,
-        type: Workflow.MANAGED,
-        mode: BuildMode.BUILD,
-        initiatingUserId: randomUUID(),
-        appId: randomUUID(),
-        projectArchive: {
-          type: ArchiveSourceType.GIT,
-          repositoryUrl: 'https://x-access-token:[email protected]/expo/eas-cli.git',
-          gitRef: 'refs/heads/main',
-          gitCommitHash: randomBytes(20).toString('hex'),
-        },
-        platform: Platform.IOS,
-        secrets: {
-          robotAccessToken,
-          environmentSecrets: [],
-        },
-      } as Job,
-      {
-        env: {
-          __API_SERVER_URL: 'https://api.expo.dev',
-          EXPO_TOKEN: robotAccessToken,
-          EAS_BUILD_ID: buildId,
-          EAS_BUILD_RUNNER: 'eas-build',
-        },
-        workingdir: '/workingdir',
-        logger: createMockLogger(),
-        logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
-        uploadArtifact: jest.fn(),
+      const ctx = new BuildContext(
+        {
+          triggeredBy: BuildTrigger.GIT_BASED_INTEGRATION,
+          type: Workflow.MANAGED,
+          mode: BuildMode.BUILD,
+          initiatingUserId: randomUUID(),
+          appId: randomUUID(),
+          projectArchive: {
+            type: ArchiveSourceType.GIT,
+            repositoryUrl: 'https://x-access-token:[email protected]/expo/eas-cli.git',
+            gitRef: 'refs/heads/main',
+            gitCommitHash: randomBytes(20).toString('hex'),
+          },
+          platform: Platform.IOS,
+          secrets: {
+            robotAccessToken,
+            environmentSecrets: [],
+          },
+        } as Job,
+        {
+          env: {
+            __API_SERVER_URL: 'https://api.expo.dev',
+            EXPO_TOKEN: robotAccessToken,
+            EAS_BUILD_ID: buildId,
+            EAS_BUILD_RUNNER: 'eas-build',
+          },
+          workingdir: '/workingdir',
+          logger: createMockLogger(),
+          logBuffer: { getLogs: () => [], getPhaseLogs: () => [] },
+          uploadArtifact: jest.fn(),
+        }
+      );
+      const fetchMock = jest.mocked(fetch);
+      const cause = new Error('Source request failed');
+      fetchMock.mockImplementation(async () => {
+        if (failure === 'network') {
+          throw cause;
+        }
+        return {
+          ok: failure !== 'http',
+          status: failure === 'http' ? 500 : 200,
+          json: async () => {
+            if (failure === 'json') {
+              throw cause;
+            }
+            return { data: { repository_url: 'https://github.com/expo/eas-cli.git' } };
+          },
+        } as Response;
+      });
+
+      const result = prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
+      await expect(result).rejects.toBeInstanceOf(SystemError);
+      await expect(result).rejects.toMatchObject({
+        errorCode: ErrorCode.SERVER_ERROR,
+        cause: expect.any(Error),
+      });
+      if (failure === 'network') {
+        await expect(result).rejects.toMatchObject({ cause });
      }
-    );
-    const fetchMock = jest.mocked(fetch);
-    fetchMock.mockImplementation(
-      async () =>
-        ({
-          ok: false,
-          text: async () => 'Failed to generate repository URL',
-        }) as Response
-    );
-
-    await prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
-    expect(shallowCloneRepositoryAsync).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        archiveSource: {
-          ...ctx.job.projectArchive,
-          repositoryUrl: 'https://x-access-token:[email protected]/expo/eas-cli.git',
-        },
-      })
-    );
-    fetchMock.mockImplementation(
-      async () =>
-        ({
-          ok: false,
-          json: async () => ({
-            // repositoryUrl is the right key
-            repository_url: 'https://x-access-token:[email protected]/expo/eas-cli.git',
-          }),
-        }) as Response
-    );
-
-    await prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
-    expect(shallowCloneRepositoryAsync).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        archiveSource: {
-          ...ctx.job.projectArchive,
-          repositoryUrl: 'https://x-access-token:[email protected]/expo/eas-cli.git',
-        },
-      })
-    );
-
-    fetchMock.mockImplementation(
-      async () =>
-        ({
-          ok: false,
-          json: () => Promise.reject(new Error('Failed to generate repository URL')),
-        }) as Response
-    );
-
-    await prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
-    expect(shallowCloneRepositoryAsync).toHaveBeenLastCalledWith(
-      expect.objectContaining({
-        archiveSource: {
-          ...ctx.job.projectArchive,
-          repositoryUrl: 'https://x-access-token:[email protected]/expo/eas-cli.git',
-        },
-      })
-    );
-
-    expect(shallowCloneRepositoryAsync).toHaveBeenCalledTimes(3);
-  }, 15_000);
+      expect(shallowCloneRepositoryAsync).not.toHaveBeenCalled();
+      expect(spawn).not.toHaveBeenCalled();
+    },
+    15_000
+  );

  it('should retry fetching the repository URL', async () => {
    const robotAccessToken = randomUUID();
@@ -281,7 +263,7 @@ describe('projectSources', () => {
    );
  }, 15_000);

-  it(`should fallback to the original repository URL if we're missing some config`, async () => {
+  it(`throws a system error if refresh configuration is missing`, async () => {
    const robotAccessToken = randomUUID();
    await vol.promises.mkdir('/workingdir/environment-secrets/', { recursive: true });
    const logger = createMockLogger();
@@ -319,12 +301,11 @@ describe('projectSources', () => {
      }
    );

-    await prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
-
-    expect(logger.error).toHaveBeenCalledWith(
-      { err: expect.any(Error) },
-      'Failed to refresh project archive, falling back to the original one'
-    );
+    await expect(prepareProjectSourcesAsync(ctx, ctx.buildDirectory)).rejects.toMatchObject({
+      errorCode: ErrorCode.SERVER_ERROR,
+      cause: new Error('EAS_BUILD_ID is not set'),
+    });
+    expect(shallowCloneRepositoryAsync).not.toHaveBeenCalled();
  });

  describe('uploadProjectMetadataAsFireAndForget', () => {
@@ -404,6 +385,10 @@ describe('projectSources', () => {

      const fetchMock = jest.mocked(fetch);
      fetchMock.mockImplementation(async () => ({ ok: true }) as Response);
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ data: ctx.job.projectArchive }),
+      } as Response);

      // Call prepareProjectSourcesAsync and don't await metadata upload
      await prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
@@ -517,6 +502,10 @@ describe('projectSources', () => {

      const fetchMock = jest.mocked(fetch);
      fetchMock.mockResolvedValue({ ok: true } as Response);
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ data: ctx.job.projectArchive }),
+      } as Response);

      const startTime = Date.now();
      await prepareProjectSourcesAsync(ctx, ctx.buildDirectory);
@@ -581,6 +570,10 @@ describe('projectSources', () => {

      const fetchMock = jest.mocked(fetch);
      fetchMock.mockResolvedValue({ ok: true } as Response);
+      fetchMock.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ data: ctx.job.projectArchive }),
+      } as Response);

      // Should not throw even though upload will fail
      await expect(prepareProjectSourcesAsync(ctx, ctx.buildDirectory)).resolves.not.toThrow();
@@ -1,5 +1,11 @@
 import downloadFile from '@expo/downloader';
-import { ArchiveSource, ArchiveSourceSchemaZ, ArchiveSourceType, Job } from '@expo/eas-build-job';
+import {
+  ArchiveSource,
+  ArchiveSourceSchemaZ,
+  ArchiveSourceType,
+  Job,
+  SystemError,
+} from '@expo/eas-build-job';
 import { bunyan } from '@expo/logger';
 import { asyncResult } from '@expo/results';
 import spawn from '@expo/turtle-spawn';
@@ -26,13 +32,12 @@ Promise<{ handled: boolean }> {
    const projectArchiveResult = await asyncResult(fetchProjectArchiveSourceAsync(ctx));

    if (!projectArchiveResult.ok) {
-      ctx.logger.error(
-        { err: projectArchiveResult.reason },
-        'Failed to refresh project archive, falling back to the original one'
-      );
+      throw new SystemError('Failed to fetch project sources. Re-run the job.', {
+        cause: projectArchiveResult.reason,
+      });
    }

-    projectArchive = projectArchiveResult.value ?? ctx.job.projectArchive;
+    projectArchive = projectArchiveResult.value;
  }

  switch (projectArchive.type) {
@@ -16,6 +16,7 @@ import { BuildContext } from './context';
 import { CustomBuildContext } from './customBuildContext';
 import { getEasFunctionGroups } from './steps/easFunctionGroups';
 import { getEasFunctions } from './steps/easFunctions';
+import { stopLocalEgressResourcesAsync } from './steps/utils/localEgress';
 import { uploadJobOutputsToWwwAsync } from './utils/outputs';
 import { retryAsync } from './utils/retry';

@@ -82,7 +83,17 @@ export async function runGenericJobAsync(
    }
  });

-  const runResult = await asyncResult(workflow.executeAsync());
+  const runResult = await asyncResult(
+    (async () => {
+      try {
+        await workflow.executeAsync();
+      } finally {
+        // The session-owning step may never run if simulator boot/setup fails,
+        // or may time out while resource acquisition is still in flight.
+        await stopLocalEgressResourcesAsync(ctx.logger);
+      }
+    })()
+  );

  await ctx.runBuildPhase(BuildPhase.COMPLETE_JOB, async () => {
    const results = await Promise.allSettled([
@@ -51,6 +51,7 @@ import { createStartAppiumRemoteSessionBuildFunction } from './functions/startAp
 import { createStartCuttlefishDeviceBuildFunction } from './functions/startCuttlefishDevice';
 import { createStartIosSimulatorBuildFunction } from './functions/startIosSimulator';
 import { createStartIosSimulatorRecordingsBuildFunction } from './functions/startIosSimulatorRecordings';
+import { createStartLocalEgressBuildFunction } from './functions/startLocalEgress';
 import { createStartWebPreviewRemoteSessionBuildFunction } from './functions/startWebPreviewRemoteSession';
 import { createStartServeSimMetricsBuildFunction } from './functions/startServeSimMetrics';
 import { createCollectServeSimMetricsBuildFunction } from './functions/collectServeSimMetrics';
@@ -103,6 +104,7 @@ export function getEasFunctions(ctx: CustomBuildContext): BuildFunction[] {
    createStartAndroidEmulatorBuildFunction(),
    createStartCuttlefishDeviceBuildFunction(),
    createStartIosSimulatorBuildFunction(),
+    createStartLocalEgressBuildFunction(),
    createStartIosSimulatorRecordingsBuildFunction(),
    createFinishIosSimulatorRecordingsBuildFunction(),
    createUploadDeviceRunSessionScreenRecordingsBuildFunction(ctx),
@@ -0,0 +1,205 @@
+import { type bunyan } from '@expo/logger';
+import { BuildRuntimePlatform, type BuildStepContext } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import fs from 'node:fs';
+
+import { type CustomBuildContext } from '../../../customBuildContext';
+import { IosSimulatorUtils } from '../../../utils/IosSimulatorUtils';
+import { isProcessDescendantOfAsync } from '../../../utils/processes';
+import { turtleFetch } from '../../../utils/turtleFetch';
+import {
+  monitorLocalEgressAsync,
+  readLocalEgressHandoffAsync,
+  registerLocalEgressResources,
+  stopLocalEgressResourcesAsync,
+} from '../../utils/localEgress';
+import {
+  startDeviceWebPreviewWithTunnelAsync,
+  uploadRemoteSessionConfigAsync,
+  waitForDeviceRunSessionStoppedAsync,
+} from '../../utils/remoteDeviceRunSession';
+import { createStartAgentDeviceRemoteSessionBuildFunction } from '../startAgentDeviceRemoteSession';
+import { createStartAppiumRemoteSessionBuildFunction } from '../startAppiumRemoteSession';
+import { createStartArgentRemoteSessionBuildFunction } from '../startArgentRemoteSession';
+import { createStartWebPreviewRemoteSessionBuildFunction } from '../startWebPreviewRemoteSession';
+
+jest.mock('@expo/turtle-spawn');
+jest.mock('../../../utils/IosSimulatorUtils');
+jest.mock('../../../utils/processes');
+jest.mock('../../../utils/turtleFetch');
+jest.mock('../../utils/agentDeviceArtifacts');
+jest.mock('../../utils/argentArtifacts');
+jest.mock('../../utils/agentDeviceEvents', () => ({
+  startAgentDeviceEventCollectionAsync: async () => ({ stopAsync: jest.fn() }),
+}));
+jest.mock('../../utils/argentEvents', () => ({
+  ARGENT_EVENT_LOG_FILENAME: 'events.jsonl',
+  startArgentEventCollectionAsync: async () => ({ stopAsync: jest.fn() }),
+}));
+jest.mock('../../utils/appiumEvents', () => ({
+  startAppiumEventCollectionAsync: async () => ({ stopAsync: jest.fn() }),
+}));
+jest.mock('../../utils/localEgress', () => ({
+  ...jest.requireActual('../../utils/localEgress'),
+  readLocalEgressHandoffAsync: jest.fn(),
+  monitorLocalEgressAsync: jest.fn(),
+}));
+jest.mock('../../utils/remoteDeviceRunSession', () => ({
+  getDeviceRunSessionIdOrThrow: () => 'session-id',
+  getNgrokTunnelDomainOrThrow: () => 'example.test',
+  getNgrokAuthtokenOrThrow: () => 'ngrok-token',
+  selectXcodeDeveloperDirectoryAsync: jest.fn(),
+  ensureFfmpegInstalledOnceAsync: jest.fn(),
+  spawnDetached: () => ({ pid: 123, getOutput: () => '', stopAsync: jest.fn() }),
+  waitForFileAsync: async () => ({ port: 1234, token: 'controller-token' }),
+  startNgrokTunnelAsync: async () => ({ url: 'https://controller.test', stopAsync: jest.fn() }),
+  startDeviceWebPreviewWithTunnelAsync: jest.fn(),
+  uploadRemoteSessionConfigAsync: jest.fn(),
+  waitForDeviceRunSessionStoppedAsync: jest.fn(),
+}));
+
+const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+const ctx = {} as CustomBuildContext;
+const env = { DEVICE_RUN_SESSION_ID: 'session-id' };
+const handoff = { url: 'https://egress.test', token: 'secret', fingerprint: 'key=', port: 8899 };
+const fields = {
+  egressUrl: handoff.url,
+  egressToken: handoff.token,
+  egressFingerprint: handoff.fingerprint,
+  egressPort: handoff.port,
+};
+const controllers = [
+  ['agent-device', createStartAgentDeviceRemoteSessionBuildFunction, 'agentDeviceRemoteSessionUrl'],
+  ['Appium', createStartAppiumRemoteSessionBuildFunction, 'appiumUrl'],
+  ['Argent', createStartArgentRemoteSessionBuildFunction, 'toolsUrl'],
+  ['web preview', createStartWebPreviewRemoteSessionBuildFunction, 'previewUrl'],
+] as const;
+
+describe.each(controllers)('%s local egress', (_name, createFunction, controllerField) => {
+  const stopPreview = jest.fn();
+  const stopEgress = jest.fn();
+  let lifetime: AbortSignal;
+  async function run(signal?: AbortSignal): Promise<void> {
+    await createFunction(ctx).fn!(
+      { logger, global: { runtimePlatform: BuildRuntimePlatform.DARWIN } } as BuildStepContext,
+      {
+        inputs: {
+          package_version: { value: undefined },
+          max_idle_time_minutes: { value: undefined },
+        },
+        outputs: {},
+        env,
+        signal,
+      } as never
+    );
+  }
+  beforeEach(() => {
+    jest.clearAllMocks();
+    lifetime = registerLocalEgressResources(stopEgress);
+    stopEgress.mockResolvedValue(undefined);
+    stopPreview.mockResolvedValue(undefined);
+    jest.spyOn(fs, 'existsSync').mockReturnValue(true);
+    jest.spyOn(fs.promises, 'mkdtemp').mockResolvedValue('/tmp/appium-egress-test');
+    jest.spyOn(fs.promises, 'writeFile').mockResolvedValue(undefined);
+    jest.spyOn(fs.promises, 'rm').mockResolvedValue(undefined);
+    jest.spyOn(fs.promises, 'readdir').mockResolvedValue(['tool-server.json'] as never);
+    jest
+      .spyOn(fs.promises, 'readFile')
+      .mockResolvedValue(JSON.stringify({ port: 1234, pid: 124, token: 'controller-token' }));
+    jest.mocked(spawn).mockResolvedValue({ stdout: '{}' } as never);
+    jest.mocked(isProcessDescendantOfAsync).mockResolvedValue(true);
+    jest
+      .mocked(IosSimulatorUtils.getAvailableDevicesAsync)
+      .mockResolvedValue([{ udid: 'sim' }] as never);
+    jest.mocked(turtleFetch).mockResolvedValue({ ok: true } as never);
+    jest.mocked(readLocalEgressHandoffAsync).mockResolvedValue(handoff);
+    jest.mocked(monitorLocalEgressAsync).mockResolvedValue(undefined);
+    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
+      previewUrl: 'https://preview.test',
+      previewToken: 'preview-secret',
+      stopAsync: stopPreview,
+    });
+    jest.mocked(uploadRemoteSessionConfigAsync).mockResolvedValue(undefined);
+    jest.mocked(waitForDeviceRunSessionStoppedAsync).mockImplementation(async () => {
+      expect(lifetime.aborted).toBe(false);
+      expect(monitorLocalEgressAsync).toHaveBeenCalledTimes(1);
+    });
+  });
+  afterEach(async () => {
+    await stopLocalEgressResourcesAsync(logger);
+    jest.restoreAllMocks();
+  });
+
+  it('reports credentials and starts monitoring before waiting, then releases resources', async () => {
+    await run();
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith({
+      ctx,
+      deviceRunSessionId: 'session-id',
+      logger,
+      remoteConfig: expect.objectContaining({
+        ...fields,
+        [controllerField]: expect.any(String),
+        [controllerField === 'previewUrl' ? 'previewToken' : 'webPreviewToken']: 'preview-secret',
+      }),
+    });
+    expect(monitorLocalEgressAsync).toHaveBeenCalledWith({
+      port: handoff.port,
+      env,
+      logger,
+      signal: expect.any(AbortSignal),
+    });
+    expect(lifetime.aborted).toBe(true);
+    expect(stopEgress).toHaveBeenCalledTimes(1);
+  });
+  it('leaves ordinary remote config unchanged and does not monitor', async () => {
+    await stopLocalEgressResourcesAsync(logger);
+    stopEgress.mockClear();
+    jest.mocked(readLocalEgressHandoffAsync).mockResolvedValue(null);
+    jest.mocked(waitForDeviceRunSessionStoppedAsync).mockResolvedValue(undefined);
+    await run();
+    const { remoteConfig } = jest.mocked(uploadRemoteSessionConfigAsync).mock.calls[0][0];
+    expect(remoteConfig).toHaveProperty(controllerField);
+    expect(Object.keys(remoteConfig).some(key => key.startsWith('egress'))).toBe(false);
+    expect(monitorLocalEgressAsync).not.toHaveBeenCalled();
+    expect(stopEgress).not.toHaveBeenCalled();
+  });
+  it.each(['startup', 'report', 'wait', 'teardown'])(
+    'releases egress after %s fails',
+    async phase => {
+      const error = new Error(`${phase} failed`);
+      if (phase === 'startup') {
+        jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockRejectedValue(error);
+      } else if (phase === 'report') {
+        jest.mocked(uploadRemoteSessionConfigAsync).mockRejectedValue(error);
+      } else if (phase === 'wait') {
+        jest.mocked(waitForDeviceRunSessionStoppedAsync).mockRejectedValue(error);
+      } else {
+        stopPreview.mockRejectedValue(error);
+      }
+      await expect(run()).rejects.toThrow(error);
+      expect(lifetime.aborted).toBe(true);
+      expect(stopEgress).toHaveBeenCalledTimes(1);
+      expect(monitorLocalEgressAsync).toHaveBeenCalledTimes(
+        phase === 'startup' || phase === 'report' ? 0 : 1
+      );
+    }
+  );
+  it('passes cancellation to the monitor and releases the lifetime', async () => {
+    const abort = new AbortController();
+    jest.mocked(waitForDeviceRunSessionStoppedAsync).mockImplementation(async () => abort.abort());
+    await run(abort.signal);
+    expect(monitorLocalEgressAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ signal: abort.signal })
+    );
+    expect(lifetime.aborted).toBe(true);
+    expect(stopEgress).toHaveBeenCalledTimes(1);
+  });
+  it('does not report or start a monitor after cancellation', async () => {
+    const abort = new AbortController();
+    abort.abort();
+    await expect(run(abort.signal)).rejects.toThrow();
+    expect(uploadRemoteSessionConfigAsync).not.toHaveBeenCalled();
+    expect(monitorLocalEgressAsync).not.toHaveBeenCalled();
+    expect(stopEgress).toHaveBeenCalledTimes(1);
+  });
+});
@@ -0,0 +1,187 @@
+import { type bunyan } from '@expo/logger';
+import { type BuildStepContext } from '@expo/steps';
+import fs from 'node:fs';
+
+import {
+  LOCAL_EGRESS_HANDOFF_PATH,
+  configureSystemProxyAsync,
+  downloadChiselAsync,
+  startChiselServerAsync,
+  stopLocalEgressResourcesAsync,
+  writeLocalEgressHandoffAsync,
+} from '../../utils/localEgress';
+import { findAvailablePortAsync, startNgrokTunnelAsync } from '../../utils/remoteDeviceRunSession';
+import { createStartLocalEgressBuildFunction } from '../startLocalEgress';
+
+jest.mock('../../utils/localEgress', () => ({
+  ...jest.requireActual('../../utils/localEgress'),
+  configureSystemProxyAsync: jest.fn(),
+  downloadChiselAsync: jest.fn(),
+  startChiselServerAsync: jest.fn(),
+  writeLocalEgressHandoffAsync: jest.fn(),
+}));
+jest.mock('../../utils/remoteDeviceRunSession', () => ({
+  findAvailablePortAsync: jest.fn(),
+  startNgrokTunnelAsync: jest.fn(),
+  getNgrokAuthtokenOrThrow: () => 'ngrok-token',
+  getNgrokTunnelDomainOrThrow: () => 'example.com',
+}));
+
+const logger = { info: jest.fn(), warn: jest.fn() } as unknown as bunyan;
+const server = { pid: 12345, getOutput: () => '', stopAsync: jest.fn() };
+const tunnel = { url: 'https://egress.example.com', stopAsync: jest.fn() };
+
+async function start(signal?: AbortSignal): Promise<void> {
+  await createStartLocalEgressBuildFunction().fn!({ logger } as BuildStepContext, {
+    env: {},
+    inputs: {},
+    outputs: {},
+    signal,
+  });
+}
+
+describe('local egress acquisition', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(fs.promises, 'mkdtemp').mockResolvedValue('/tmp/egress-acquisition-test');
+    jest.spyOn(fs.promises, 'writeFile').mockResolvedValue(undefined);
+    jest.spyOn(fs.promises, 'rm').mockResolvedValue(undefined);
+    server.stopAsync.mockResolvedValue(undefined);
+    tunnel.stopAsync.mockResolvedValue(undefined);
+    jest.mocked(findAvailablePortAsync).mockResolvedValue(52001);
+    jest.mocked(downloadChiselAsync).mockResolvedValue('/tmp/egress-acquisition-test/chisel');
+    jest.mocked(startChiselServerAsync).mockResolvedValue({ process: server, fingerprint: 'key=' });
+    jest.mocked(startNgrokTunnelAsync).mockResolvedValue(tunnel);
+    jest.mocked(configureSystemProxyAsync).mockResolvedValue({ service: 'Ethernet' });
+    jest.mocked(writeLocalEgressHandoffAsync).mockResolvedValue(undefined);
+  });
+
+  afterEach(async () => {
+    await stopLocalEgressResourcesAsync(logger);
+    jest.restoreAllMocks();
+  });
+
+  it('stops the detached server and removes credentials when ngrok acquisition fails', async () => {
+    jest.mocked(startNgrokTunnelAsync).mockRejectedValue(new Error('listener quota'));
+    await expect(start()).rejects.toThrow('listener quota');
+    expect(server.stopAsync).toHaveBeenCalledTimes(1);
+    expect(configureSystemProxyAsync).not.toHaveBeenCalled();
+    expect(fs.promises.rm).toHaveBeenCalledWith('/tmp/egress-acquisition-test', {
+      recursive: true,
+      force: true,
+    });
+  });
+
+  it('attempts every release even when one resource cannot stop', async () => {
+    await start();
+    tunnel.stopAsync.mockRejectedValue(new Error('ngrok close failed'));
+    await stopLocalEgressResourcesAsync(logger);
+    expect(server.stopAsync).toHaveBeenCalledTimes(1);
+    expect(fs.promises.rm).toHaveBeenCalledWith(LOCAL_EGRESS_HANDOFF_PATH, { force: true });
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.objectContaining({ err: expect.any(Error) }),
+      'Could not stop a local egress resource.'
+    );
+  });
+
+  it.each([false, true])(
+    'disposes late listeners without delaying cleanup (close fails: %s)',
+    async closeFails => {
+      let finishTunnel!: (value: typeof tunnel) => void;
+      jest.mocked(startNgrokTunnelAsync).mockImplementation(
+        () =>
+          new Promise(resolve => {
+            finishTunnel = resolve;
+          })
+      );
+      const started = start();
+      const rejected = expect(started).rejects.toThrow();
+      await new Promise(resolve => setImmediate(resolve));
+      expect(startNgrokTunnelAsync).toHaveBeenCalledTimes(1);
+      const stopped = stopLocalEgressResourcesAsync(logger);
+      await Promise.all([stopped, rejected]);
+      expect(server.stopAsync).toHaveBeenCalledTimes(1);
+      expect(tunnel.stopAsync).not.toHaveBeenCalled();
+      if (closeFails) {
+        tunnel.stopAsync.mockRejectedValue(new Error('late close failed'));
+      }
+      finishTunnel(tunnel);
+      await new Promise(resolve => setImmediate(resolve));
+      if (closeFails) {
+        expect(logger.warn).toHaveBeenCalledWith(
+          expect.objectContaining({ err: expect.any(Error) }),
+          'Could not release a cancelled local egress acquisition.'
+        );
+      }
+      expect(tunnel.stopAsync).toHaveBeenCalledTimes(1);
+      expect(configureSystemProxyAsync).not.toHaveBeenCalled();
+      expect(writeLocalEgressHandoffAsync).not.toHaveBeenCalled();
+    }
+  );
+
+  it.each(['job', 'step'])('finishes %s cancellation when ngrok never settles', async source => {
+    jest.mocked(startNgrokTunnelAsync).mockReturnValue(new Promise(() => {}));
+    const controller = new AbortController();
+    const started = start(controller.signal);
+    const rejected = expect(started).rejects.toThrow();
+    await new Promise(resolve => setImmediate(resolve));
+    expect(startNgrokTunnelAsync).toHaveBeenCalledTimes(1);
+    if (source === 'step') {
+      controller.abort(new Error('cancelled'));
+    }
+    const stopped = source === 'job' ? stopLocalEgressResourcesAsync(logger) : Promise.resolve();
+    const outcome = await Promise.race([
+      Promise.all([stopped, rejected]).then(() => 'stopped'),
+      new Promise(resolve => setImmediate(() => resolve('still waiting'))),
+    ]);
+    expect(outcome).toBe('stopped');
+    expect(server.stopAsync).toHaveBeenCalledTimes(1);
+    expect(configureSystemProxyAsync).not.toHaveBeenCalled();
+    expect(writeLocalEgressHandoffAsync).not.toHaveBeenCalled();
+  });
+
+  it('handles ngrok rejection after finalization without an unhandled rejection', async () => {
+    let rejectTunnel!: (error: Error) => void;
+    jest.mocked(startNgrokTunnelAsync).mockReturnValue(
+      new Promise((_resolve, reject) => {
+        rejectTunnel = reject;
+      })
+    );
+    const started = start();
+    const rejected = expect(started).rejects.toThrow();
+    await new Promise(resolve => setImmediate(resolve));
+    await Promise.all([stopLocalEgressResourcesAsync(logger), rejected]);
+    rejectTunnel(new Error('late connection failure'));
+    await new Promise(resolve => setImmediate(resolve));
+    expect(server.stopAsync).toHaveBeenCalledTimes(1);
+    expect(configureSystemProxyAsync).not.toHaveBeenCalled();
+  });
+
+  it('does not launch a server after a download finishes following cancellation', async () => {
+    let finishDownload!: (value: string) => void;
+    jest.mocked(downloadChiselAsync).mockImplementation(
+      () =>
+        new Promise(resolve => {
+          finishDownload = resolve;
+        })
+    );
+    const controller = new AbortController();
+    const started = start(controller.signal);
+    const rejected = expect(started).rejects.toThrow('cancelled');
+    await new Promise(resolve => setImmediate(resolve));
+    controller.abort(new Error('cancelled'));
+    await rejected;
+    finishDownload('/tmp/chisel');
+    await new Promise(resolve => setImmediate(resolve));
+    expect(startChiselServerAsync).not.toHaveBeenCalled();
+    expect(
+      jest
+        .mocked(fs.promises.rm)
+        .mock.calls.filter(([target]) => target === '/tmp/egress-acquisition-test')
+    ).toHaveLength(2);
+    expect(fs.promises.rm).toHaveBeenCalledWith('/tmp/egress-acquisition-test', {
+      recursive: true,
+      force: true,
+    });
+  });
+});
@@ -52,6 +52,25 @@ describe(createStartWebPreviewRemoteSessionBuildFunction, () => {
    stopAsync.mockResolvedValue(undefined);
  });

+  it('reports the session token when serve-sim minted one', async () => {
+    jest.mocked(startDeviceWebPreviewWithTunnelAsync).mockResolvedValue({
+      previewUrl: 'https://web-preview.example.test',
+      previewToken: 'tok-1',
+      stopAsync,
+    });
+
+    await runAsync(BuildRuntimePlatform.DARWIN);
+
+    expect(uploadRemoteSessionConfigAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        remoteConfig: {
+          previewUrl: 'https://web-preview.example.test',
+          previewToken: 'tok-1',
+        },
+      })
+    );
+  });
+
  it.each([
    [BuildRuntimePlatform.DARWIN, true],
    [BuildRuntimePlatform.LINUX, false],
@@ -13,6 +13,10 @@ import os from 'node:os';
 import path from 'node:path';

 import { type CustomBuildContext } from '../../customBuildContext';
+import {
+  uploadRemoteSessionConfigWithLocalEgressAsync,
+  withLocalEgressSession,
+} from '../utils/localEgressSession';
 import { Sentry } from '../../sentry';
 import { pollAgentDeviceArtifactsForUploadAsync } from '../utils/agentDeviceArtifacts';
 import { startAgentDeviceEventCollectionAsync } from '../utils/agentDeviceEvents';
@@ -25,7 +29,6 @@ import {
  spawnDetached,
  startDeviceWebPreviewWithTunnelAsync,
  startNgrokTunnelAsync,
-  uploadRemoteSessionConfigAsync,
  waitForDeviceRunSessionStoppedAsync,
  waitForFileAsync,
 } from '../utils/remoteDeviceRunSession';
@@ -66,7 +69,7 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
        allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
      }),
    ],
-    fn: async ({ logger, global }, { inputs, env, signal }) => {
+    fn: withLocalEgressSession(async ({ logger, global }, { inputs, env, signal }) => {
      // Fail fast before any expensive setup if the injected env
      // vars are missing: DEVICE_RUN_SESSION_ID (to report the remote config
      // back to the API server), EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN (base domain
@@ -121,13 +124,16 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
        });
        logger.info(`Web preview URL: ${webPreview.previewUrl}`);

-        await uploadRemoteSessionConfigAsync({
+        await uploadRemoteSessionConfigWithLocalEgressAsync({
+          env,
+          signal,
          ctx,
          deviceRunSessionId,
          remoteConfig: {
            agentDeviceRemoteSessionUrl,
            agentDeviceRemoteSessionToken: daemonToken,
            webPreviewUrl: webPreview.previewUrl,
+            ...(webPreview.previewToken ? { webPreviewToken: webPreview.previewToken } : {}),
          },
          logger,
        });
@@ -173,7 +179,7 @@ export function createStartAgentDeviceRemoteSessionBuildFunction(
        }
        await daemonProcess.stopAsync();
      }
-    },
+    }),
  });
 }

@@ -15,6 +15,10 @@ import semver from 'semver';
 import { z } from 'zod';

 import { type CustomBuildContext } from '../../customBuildContext';
+import {
+  uploadRemoteSessionConfigWithLocalEgressAsync,
+  withLocalEgressSession,
+} from '../utils/localEgressSession';
 import { AndroidEmulatorUtils } from '../../utils/AndroidEmulatorUtils';
 import { IosSimulatorUtils } from '../../utils/IosSimulatorUtils';
 import { sleepAsync } from '../../utils/retry';
@@ -28,7 +32,6 @@ import {
  spawnDetached,
  startDeviceWebPreviewWithTunnelAsync,
  startNgrokTunnelAsync,
-  uploadRemoteSessionConfigAsync,
  waitForDeviceRunSessionStoppedAsync,
 } from '../utils/remoteDeviceRunSession';

@@ -62,7 +65,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
        allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
      }),
    ],
-    fn: async ({ logger, global }, { inputs, env, signal }) => {
+    fn: withLocalEgressSession(async ({ logger, global }, { inputs, env, signal }) => {
      const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);
      const ngrokAuthtoken = getNgrokAuthtokenOrThrow(env);
@@ -138,7 +141,9 @@ export function createStartAppiumRemoteSessionBuildFunction(
          timeoutMs: APPIUM_STARTUP_TIMEOUT_MS,
        });

-        await uploadRemoteSessionConfigAsync({
+        await uploadRemoteSessionConfigWithLocalEgressAsync({
+          env,
+          signal,
          ctx,
          deviceRunSessionId,
          remoteConfig: {
@@ -149,6 +154,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
              'appium:udid': device.udid,
            },
            webPreviewUrl: webPreview.previewUrl,
+            ...(webPreview.previewToken ? { webPreviewToken: webPreview.previewToken } : {}),
          },
          logger,
        });
@@ -177,7 +183,7 @@ export function createStartAppiumRemoteSessionBuildFunction(
        await appiumProcess.stopAsync();
        await fs.promises.rm(appiumHome, { recursive: true, force: true });
      }
-    },
+    }),
  });
 }

@@ -14,6 +14,10 @@ import semver from 'semver';
 import { z } from 'zod';

 import { CustomBuildContext } from '../../customBuildContext';
+import {
+  uploadRemoteSessionConfigWithLocalEgressAsync,
+  withLocalEgressSession,
+} from '../utils/localEgressSession';
 import { Sentry } from '../../sentry';
 import { isProcessDescendantOfAsync } from '../../utils/processes';
 import { sleepAsync } from '../../utils/retry';
@@ -28,7 +32,6 @@ import {
  spawnDetached,
  startDeviceWebPreviewWithTunnelAsync,
  startNgrokTunnelAsync,
-  uploadRemoteSessionConfigAsync,
  waitForDeviceRunSessionStoppedAsync,
 } from '../utils/remoteDeviceRunSession';

@@ -79,7 +82,7 @@ export function createStartArgentRemoteSessionBuildFunction(
        allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
      }),
    ],
-    fn: async ({ logger, global }, { inputs, env, signal }) => {
+    fn: withLocalEgressSession(async ({ logger, global }, { inputs, env, signal }) => {
      // Fail fast before any expensive setup if the injected env
      // vars are missing: DEVICE_RUN_SESSION_ID (to report the remote config
      // back to the API server), EAS_SIMULATOR_NGROK_TUNNEL_DOMAIN (base domain
@@ -215,13 +218,16 @@ export function createStartArgentRemoteSessionBuildFunction(
        });
        logger.info(`Web preview URL: ${webPreview.previewUrl}`);

-        await uploadRemoteSessionConfigAsync({
+        await uploadRemoteSessionConfigWithLocalEgressAsync({
+          env,
+          signal,
          ctx,
          deviceRunSessionId,
          remoteConfig: {
            toolsUrl: publicToolsUrl,
            ...(toolServerToken ? { toolsAuthToken: toolServerToken } : {}),
            webPreviewUrl: webPreview.previewUrl,
+            ...(webPreview.previewToken ? { webPreviewToken: webPreview.previewToken } : {}),
          },
          logger,
        });
@@ -258,7 +264,7 @@ export function createStartArgentRemoteSessionBuildFunction(
        }
        await argentServer.stopAsync();
      }
-    },
+    }),
  });
 }

@@ -0,0 +1,199 @@
+import { type bunyan } from '@expo/logger';
+import { BuildFunction, BuildRuntimePlatform } from '@expo/steps';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  CHISEL_VERSION,
+  LOCAL_EGRESS_HANDOFF_PATH,
+  LOCAL_EGRESS_PROXY_PORT,
+  configureSystemProxyAsync,
+  createChiselAuthfileContents,
+  downloadChiselAsync,
+  generateEgressCredentials,
+  registerLocalEgressResources,
+  startChiselServerAsync,
+  stopLocalEgressResourcesAsync,
+  writeLocalEgressHandoffAsync,
+} from '../utils/localEgress';
+import {
+  type DetachedProcessHandle,
+  type NgrokTunnelHandle,
+  findAvailablePortAsync,
+  getNgrokAuthtokenOrThrow,
+  getNgrokTunnelDomainOrThrow,
+  startNgrokTunnelAsync,
+} from '../utils/remoteDeviceRunSession';
+
+/**
+ * The downloader and ngrok SDK do not accept an AbortSignal. Stop awaiting them
+ * on cancellation, while retaining handlers that dispose any eventual result.
+ */
+function awaitLocalEgressAcquisitionAsync<T>(
+  pending: Promise<T>,
+  signal: AbortSignal,
+  disposeAbandonedAsync: (result?: T) => Promise<void>,
+  logger: bunyan
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let abandoned = false;
+    const abort = (): void => {
+      signal.removeEventListener('abort', abort);
+      abandoned = true;
+      reject(signal.reason);
+    };
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) {
+      abort();
+    }
+    void pending
+      .then(
+        async result => {
+          signal.removeEventListener('abort', abort);
+          if (abandoned) {
+            await disposeAbandonedAsync(result);
+          } else {
+            resolve(result);
+          }
+        },
+        async error => {
+          signal.removeEventListener('abort', abort);
+          if (abandoned) {
+            await disposeAbandonedAsync();
+          } else {
+            reject(error);
+          }
+        }
+      )
+      .catch(err =>
+        logger.warn({ err }, 'Could not release a cancelled local egress acquisition.')
+      );
+  });
+}
+
+/**
+ * Points the device host's system HTTP(S) proxy at the EAS CLI's egress client.
+ * Must run before `eas/start_ios_simulator`: the simulator reads the system proxy
+ * at boot. Nothing else on the host changes, so requests from libraries that
+ * bypass the system proxy are not covered; the shared session monitor reports
+ * them. The shared session cleanup releases the resources started here when
+ * the session ends, with a job finalizer as a fallback.
+ */
+export function createStartLocalEgressBuildFunction(): BuildFunction {
+  return new BuildFunction({
+    namespace: 'eas',
+    id: 'start_local_egress',
+    name: 'Start local egress',
+    __metricsId: 'eas/start_local_egress',
+    supportedRuntimePlatforms: [BuildRuntimePlatform.DARWIN],
+    fn: async ({ logger }, { env, signal }) => {
+      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);
+      const ngrokAuthtoken = getNgrokAuthtokenOrThrow(env);
+      let workDir: string | undefined;
+      let server: DetachedProcessHandle | undefined;
+      let tunnel: NgrokTunnelHandle | undefined;
+      let finishSetup!: () => void;
+      const setupFinished = new Promise<void>(resolve => {
+        finishSetup = resolve;
+      });
+      // Register before acquisition. Cancellation ends setup promptly; pending
+      // SDK calls retain their own late-result disposal handlers.
+      const lifetimeSignal = registerLocalEgressResources(async () => {
+        await setupFinished;
+        const results = await Promise.allSettled([
+          Promise.resolve().then(() => tunnel?.stopAsync()),
+          Promise.resolve().then(() => server?.stopAsync()),
+        ]);
+        for (const result of results) {
+          if (result.status === 'rejected') {
+            logger.warn({ err: result.reason }, 'Could not stop a local egress resource.');
+          }
+        }
+        await Promise.all([
+          fs.promises.rm(LOCAL_EGRESS_HANDOFF_PATH, { force: true }),
+          workDir ? fs.promises.rm(workDir, { recursive: true, force: true }) : undefined,
+        ]);
+      });
+      const startupSignal = signal ? AbortSignal.any([signal, lifetimeSignal]) : lifetimeSignal;
+
+      try {
+        startupSignal.throwIfAborted();
+        workDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'eas-local-egress-'));
+        startupSignal.throwIfAborted();
+        logger.info(`Downloading the reverse tunnel server (chisel ${CHISEL_VERSION}).`);
+        const downloadDir = workDir;
+        const chiselPath = await awaitLocalEgressAcquisitionAsync(
+          downloadChiselAsync({ destinationDir: downloadDir, logger }),
+          startupSignal,
+          async () => await fs.promises.rm(downloadDir, { recursive: true, force: true }),
+          logger
+        );
+        startupSignal.throwIfAborted();
+
+        const credentials = generateEgressCredentials();
+        const authfilePath = path.join(workDir, 'authfile.json');
+        await fs.promises.writeFile(
+          authfilePath,
+          createChiselAuthfileContents({ ...credentials, port: LOCAL_EGRESS_PROXY_PORT }),
+          { encoding: 'utf8', mode: 0o600 }
+        );
+        startupSignal.throwIfAborted();
+
+        const controlPort = await findAvailablePortAsync();
+        startupSignal.throwIfAborted();
+        logger.info(`Starting the reverse tunnel server on 127.0.0.1:${controlPort}.`);
+        const started = await startChiselServerAsync({
+          chiselPath,
+          controlPort,
+          authfilePath,
+          env,
+          signal: startupSignal,
+        });
+        server = started.process;
+        startupSignal.throwIfAborted();
+        tunnel = await awaitLocalEgressAcquisitionAsync(
+          startNgrokTunnelAsync({
+            port: controlPort,
+            subdomainPrefix: 'egress',
+            baseDomain: ngrokTunnelDomain,
+            authtoken: ngrokAuthtoken,
+            logger,
+          }),
+          startupSignal,
+          async listener => await listener?.stopAsync(),
+          logger
+        );
+        startupSignal.throwIfAborted();
+
+        const { service } = await configureSystemProxyAsync({
+          env,
+          logger,
+          port: LOCAL_EGRESS_PROXY_PORT,
+          signal: startupSignal,
+        });
+        startupSignal.throwIfAborted();
+        await writeLocalEgressHandoffAsync({
+          url: tunnel.url,
+          token: credentials.password,
+          fingerprint: started.fingerprint,
+          port: LOCAL_EGRESS_PROXY_PORT,
+        });
+        startupSignal.throwIfAborted();
+        logger.info(
+          `Local egress is configured on network service "${service}". HTTP(S) and WebSocket ` +
+            'requests that honor the system proxy (WebKit, URLSession and other CFNetwork clients) ' +
+            'fail until the EAS CLI egress client connects, then exit from that machine. Requests ' +
+            'from libraries that bypass the system proxy are not covered and exit from this worker. ' +
+            'Connection sampling may report these bypasses, but can miss short connections and unconnected UDP traffic.'
+        );
+      } catch (error) {
+        finishSetup();
+        await stopLocalEgressResourcesAsync(logger);
+        throw error;
+      } finally {
+        finishSetup();
+      }
+    },
+  });
+}
@@ -6,12 +6,15 @@ import {
 } from '@expo/steps';

 import { CustomBuildContext } from '../../customBuildContext';
+import {
+  uploadRemoteSessionConfigWithLocalEgressAsync,
+  withLocalEgressSession,
+} from '../utils/localEgressSession';
 import {
  getDeviceRunSessionIdOrThrow,
  getNgrokTunnelDomainOrThrow,
  selectXcodeDeveloperDirectoryAsync,
  startDeviceWebPreviewWithTunnelAsync,
-  uploadRemoteSessionConfigAsync,
  waitForDeviceRunSessionStoppedAsync,
 } from '../utils/remoteDeviceRunSession';

@@ -37,7 +40,7 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
        allowedValueTypeName: BuildStepInputValueTypeName.NUMBER,
      }),
    ],
-    fn: async ({ logger, global }, { inputs, env, signal }) => {
+    fn: withLocalEgressSession(async ({ logger, global }, { inputs, env, signal }) => {
      const deviceRunSessionId = getDeviceRunSessionIdOrThrow(env);
      const ngrokTunnelDomain = getNgrokTunnelDomainOrThrow(env);
      const maxDurationSeconds = inputs.max_duration_seconds?.value as number | undefined;
@@ -61,10 +64,15 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
      logger.info(`Preview URL: ${webPreview.previewUrl}`);

      try {
-        await uploadRemoteSessionConfigAsync({
+        await uploadRemoteSessionConfigWithLocalEgressAsync({
+          env,
+          signal,
          ctx,
          deviceRunSessionId,
-          remoteConfig: { previewUrl: webPreview.previewUrl },
+          remoteConfig: {
+            previewUrl: webPreview.previewUrl,
+            ...(webPreview.previewToken ? { previewToken: webPreview.previewToken } : {}),
+          },
          logger,
        });

@@ -78,6 +86,6 @@ export function createStartWebPreviewRemoteSessionBuildFunction(
      } finally {
        await webPreview.stopAsync();
      }
-    },
+    }),
  });
 }
@@ -0,0 +1,425 @@
+import { type bunyan } from '@expo/logger';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { spawnDetached } from '../remoteDeviceRunSession';
+
+import {
+  CHISEL_VERSION,
+  LOCAL_EGRESS_PROXY_PORT,
+  buildEgressRemoteConfigFields,
+  buildNetworksetupProxyArgs,
+  collectSimulatorProcessIds,
+  createChiselAuthfileContents,
+  getChiselAssetName,
+  getChiselDownloadUrl,
+  parseChiselFingerprint,
+  parseDefaultRouteInterface,
+  parseDirectSimulatorConnections,
+  parseExitIpResponse,
+  parseNetworkServiceNameForDevice,
+  readLocalEgressHandoffAsync,
+  registerLocalEgressResources,
+  startChiselServerAsync,
+  stopLocalEgressResourcesAsync,
+  writeLocalEgressHandoffAsync,
+} from '../localEgress';
+
+jest.mock('@ngrok/ngrok');
+jest.mock('@expo/turtle-spawn');
+jest.mock('../remoteDeviceRunSession', () => ({ spawnDetached: jest.fn() }));
+
+describe(getChiselAssetName, () => {
+  it.each([
+    ['darwin', 'arm64', `chisel_${CHISEL_VERSION}_darwin_arm64.gz`],
+    ['darwin', 'x64', `chisel_${CHISEL_VERSION}_darwin_amd64.gz`],
+    ['linux', 'x64', `chisel_${CHISEL_VERSION}_linux_amd64.gz`],
+    ['linux', 'arm64', `chisel_${CHISEL_VERSION}_linux_arm64.gz`],
+  ] as const)('maps %s/%s to %s', (platform, arch, expected) => {
+    expect(getChiselAssetName({ platform, arch })).toBe(expected);
+  });
+
+  it('rejects platforms without a pinned binary', () => {
+    expect(() => getChiselAssetName({ platform: 'win32', arch: 'x64' })).toThrow(
+      'Local egress is not supported on win32/x64'
+    );
+    expect(() => getChiselAssetName({ platform: 'linux', arch: 'ia32' })).toThrow(
+      'Local egress is not supported on linux/ia32'
+    );
+  });
+
+  it('downloads from the pinned GitHub release', () => {
+    expect(getChiselDownloadUrl(`chisel_${CHISEL_VERSION}_darwin_arm64.gz`)).toBe(
+      `https://github.com/jpillora/chisel/releases/download/v${CHISEL_VERSION}/chisel_${CHISEL_VERSION}_darwin_arm64.gz`
+    );
+  });
+});
+
+describe(createChiselAuthfileContents, () => {
+  it('allows reverse remotes on the loopback proxy port and unprivileged loopback ports only', () => {
+    const contents = createChiselAuthfileContents({ user: 'eas', password: 'pw', port: 8899 });
+    const parsed = JSON.parse(contents) as Record<string, string[]>;
+    expect(parsed['eas:pw']).toHaveLength(2);
+    expect(parsed['eas:pw'][0]).toBe('^R:127\\.0\\.0\\.1:8899$');
+
+    const patterns = parsed['eas:pw'].map(source => new RegExp(source));
+    const allowed = (remote: string): boolean => patterns.some(pattern => pattern.test(remote));
+    expect(allowed('R:127.0.0.1:8899')).toBe(true);
+    expect(allowed('R:127.0.0.1:1024')).toBe(true);
+    expect(allowed('R:127.0.0.1:3000')).toBe(true);
+    expect(allowed('R:127.0.0.1:8081')).toBe(true);
+    expect(allowed('R:127.0.0.1:65535')).toBe(true);
+    // Privileged and out-of-range ports, other interfaces, and forward remotes stay denied.
+    expect(allowed('R:127.0.0.1:1023')).toBe(false);
+    expect(allowed('R:127.0.0.1:80')).toBe(false);
+    expect(allowed('R:127.0.0.1:0')).toBe(false);
+    expect(allowed('R:127.0.0.1:65536')).toBe(false);
+    expect(allowed('R:127.0.0.1:88990')).toBe(false);
+    expect(allowed('R:0.0.0.0:8899')).toBe(false);
+    expect(allowed('R:0.0.0.0:3000')).toBe(false);
+    expect(allowed('R:[::1]:3000')).toBe(false);
+    expect(allowed('R:127x0x0x1:8899')).toBe(false);
+    expect(allowed('R:socks')).toBe(false);
+    expect(allowed('example.com:443')).toBe(false);
+    expect(allowed('127.0.0.1:3000')).toBe(false);
+  });
+});
+
+describe(parseChiselFingerprint, () => {
+  it('extracts the fingerprint chisel prints at startup', () => {
+    const output =
+      '2026/09/07 22:00:00 server: Fingerprint eZm5d2ZQ+Zb2aS0lJm7A5GkWm9G9ZqnPz2W0i2Y6Q1c=\n' +
+      '2026/09/07 22:00:00 server: Reverse tunnelling enabled\n' +
+      '2026/09/07 22:00:00 server: Listening on http://127.0.0.1:52001\n';
+    expect(parseChiselFingerprint(output)).toBe('eZm5d2ZQ+Zb2aS0lJm7A5GkWm9G9ZqnPz2W0i2Y6Q1c=');
+  });
+
+  it('returns null before the fingerprint line appears', () => {
+    expect(parseChiselFingerprint('')).toBeNull();
+    expect(parseChiselFingerprint('2026/09/07 22:00:00 server: starting')).toBeNull();
+  });
+});
+
+describe(parseDefaultRouteInterface, () => {
+  it('reads the interface from `route -n get default`', () => {
+    const output =
+      '   route to: default\n' +
+      'destination: default\n' +
+      '       mask: default\n' +
+      '    gateway: 172.20.10.1\n' +
+      '  interface: en0\n' +
+      '      flags: <UP,GATEWAY,DONE,STATIC,PRCLONING,GLOBAL>\n';
+    expect(parseDefaultRouteInterface(output)).toBe('en0');
+  });
+
+  it('returns null when there is no default route', () => {
+    expect(
+      parseDefaultRouteInterface('route: writing to routing socket: not in table\n')
+    ).toBeNull();
+  });
+});
+
+describe(parseNetworkServiceNameForDevice, () => {
+  const listOutput =
+    'An asterisk (*) denotes that a network service is disabled.\n' +
+    '(1) Thunderbolt Ethernet Slot 0\n' +
+    '(Hardware Port: Thunderbolt Ethernet Slot 0, Device: en8)\n' +
+    '\n' +
+    '(2) Thunderbolt Bridge\n' +
+    '(Hardware Port: Thunderbolt Bridge, Device: bridge0)\n' +
+    '\n' +
+    '(3) Wi-Fi\n' +
+    '(Hardware Port: Wi-Fi, Device: en0)\n' +
+    '\n' +
+    '(4) iPhone USB\n' +
+    '(Hardware Port: iPhone USB, Device: en9)\n';
+
+  it('returns the service whose device matches', () => {
+    expect(parseNetworkServiceNameForDevice(listOutput, 'en0')).toBe('Wi-Fi');
+    expect(parseNetworkServiceNameForDevice(listOutput, 'en8')).toBe('Thunderbolt Ethernet Slot 0');
+  });
+
+  it('returns null for an unknown device', () => {
+    expect(parseNetworkServiceNameForDevice(listOutput, 'utun3')).toBeNull();
+  });
+});
+
+describe(buildNetworksetupProxyArgs, () => {
+  it('sets both the HTTP and HTTPS proxy to the loopback egress port', () => {
+    expect(
+      buildNetworksetupProxyArgs({ service: 'Ethernet', host: '127.0.0.1', port: 8899 })
+    ).toEqual([
+      ['-setwebproxy', 'Ethernet', '127.0.0.1', '8899'],
+      ['-setsecurewebproxy', 'Ethernet', '127.0.0.1', '8899'],
+    ]);
+  });
+});
+
+describe(collectSimulatorProcessIds, () => {
+  const runtimeRoot =
+    '/Library/Developer/CoreSimulator/Volumes/iOS_23F77/Library/Developer/CoreSimulator/Profiles/Runtimes/iOS 26.5.simruntime/Contents/Resources/RuntimeRoot';
+  const psOutput =
+    '    1     0 /sbin/launchd\n' +
+    '  501     1 /usr/local/bin/node\n' +
+    `  600     1 ${runtimeRoot}/sbin/launchd_sim\n` +
+    '  610   600 /Users/expo/Library/Developer/CoreSimulator/Devices/ABC/data/Containers/Bundle/Application/DEF/App.app/App\n' +
+    `  611   600 ${runtimeRoot}/System/Library/ExtensionKit/Extensions/NetworkingExtension.appex/com.apple.WebKit.Networking\n` +
+    '  620   610 /usr/bin/helper\n' +
+    '  700     1 /usr/sbin/lsof\n';
+
+  it('returns every descendant of launchd_sim and nothing else', () => {
+    expect(collectSimulatorProcessIds(psOutput).sort((a, b) => a - b)).toEqual([610, 611, 620]);
+  });
+
+  it('returns nothing when no simulator is running', () => {
+    expect(
+      collectSimulatorProcessIds('    1     0 /sbin/launchd\n  501     1 /usr/local/bin/node\n')
+    ).toEqual([]);
+  });
+});
+
+describe(parseDirectSimulatorConnections, () => {
+  const lsofOutput = [
+    'p610',
+    'cApp',
+    'f10',
+    'PTCP',
+    'n127.0.0.1:52344->127.0.0.1:8899',
+    'TST=ESTABLISHED',
+    'f11',
+    'PTCP',
+    'n192.168.64.2:52345->93.184.216.34:443',
+    'TST=ESTABLISHED',
+    'f12',
+    'PTCP',
+    'n192.168.64.2:52346->104.16.0.1:443',
+    'TST=SYN_SENT',
+    'f13',
+    'PTCP',
+    'n*:8080',
+    'TST=LISTEN',
+    'f14',
+    'PUDP',
+    'n*:5353',
+    'f15',
+    'PUDP',
+    'n192.168.64.2:60000->1.1.1.1:443',
+    'f16',
+    'PTCP',
+    'n[::1]:52347->[::1]:8899',
+    'TST=ESTABLISHED',
+    'f17',
+    'PTCP',
+    'n[fd00::2]:52348->[2606:4700:4700::1111]:443',
+    'TST=ESTABLISHED',
+    'p700',
+    'cnode',
+    'f20',
+    'PTCP',
+    'n192.168.64.2:52349->93.184.216.34:443',
+    'TST=ESTABLISHED',
+    '',
+  ].join('\n');
+
+  it('reports simulator connections to non-loopback peers only', () => {
+    expect(parseDirectSimulatorConnections(lsofOutput, new Set([610]))).toEqual([
+      { pid: 610, command: 'App', protocol: 'TCP', remote: '93.184.216.34:443' },
+      { pid: 610, command: 'App', protocol: 'TCP', remote: '104.16.0.1:443' },
+      { pid: 610, command: 'App', protocol: 'UDP', remote: '1.1.1.1:443' },
+      { pid: 610, command: 'App', protocol: 'TCP', remote: '[2606:4700:4700::1111]:443' },
+    ]);
+  });
+
+  it('ignores processes outside the simulator', () => {
+    expect(parseDirectSimulatorConnections(lsofOutput, new Set([700]))).toEqual([
+      { pid: 700, command: 'node', protocol: 'TCP', remote: '93.184.216.34:443' },
+    ]);
+    expect(parseDirectSimulatorConnections(lsofOutput, new Set([999]))).toEqual([]);
+  });
+
+  it('returns nothing for an empty listing', () => {
+    expect(parseDirectSimulatorConnections('', new Set([610]))).toEqual([]);
+  });
+});
+
+describe(buildEgressRemoteConfigFields, () => {
+  it('returns nothing without a handoff', () => {
+    expect(buildEgressRemoteConfigFields(null)).toEqual({});
+  });
+
+  it('maps the handoff to the remoteConfig field names', () => {
+    expect(
+      buildEgressRemoteConfigFields({
+        url: 'https://egress-abc.eas-simulator.ngrok.dev',
+        token: 'pw',
+        fingerprint: 'fp=',
+        port: LOCAL_EGRESS_PROXY_PORT,
+      })
+    ).toEqual({
+      egressUrl: 'https://egress-abc.eas-simulator.ngrok.dev',
+      egressToken: 'pw',
+      egressFingerprint: 'fp=',
+      egressPort: LOCAL_EGRESS_PROXY_PORT,
+    });
+  });
+});
+
+describe(parseExitIpResponse, () => {
+  it('reads the ip field', () => {
+    expect(parseExitIpResponse('{"ip":"64.114.211.44"}')).toBe('64.114.211.44');
+  });
+
+  it('rejects responses without an ip', () => {
+    expect(() => parseExitIpResponse('{"error":"rate limited"}')).toThrow(
+      'Unexpected exit IP response'
+    );
+  });
+});
+
+describe('local egress handoff', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'local-egress-test-'));
+  });
+
+  afterEach(async () => {
+    await fs.promises.rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('round-trips through the handoff file', async () => {
+    const handoffPath = path.join(tempDir, 'handoff.json');
+    const handoff = {
+      url: 'https://egress-abc.eas-simulator.ngrok.dev',
+      token: 'pw',
+      fingerprint: 'fp=',
+      port: 8899,
+    };
+    await writeLocalEgressHandoffAsync(handoff, handoffPath);
+    await expect(readLocalEgressHandoffAsync(handoffPath)).resolves.toEqual(handoff);
+  });
+
+  it('returns null when no egress step ran', async () => {
+    await expect(
+      readLocalEgressHandoffAsync(path.join(tempDir, 'missing.json'))
+    ).resolves.toBeNull();
+  });
+
+  it('rejects a malformed handoff', async () => {
+    const handoffPath = path.join(tempDir, 'handoff.json');
+    await fs.promises.writeFile(handoffPath, JSON.stringify({ url: 'x' }), 'utf8');
+    await expect(readLocalEgressHandoffAsync(handoffPath)).rejects.toThrow('malformed');
+  });
+});
+
+describe(startChiselServerAsync, () => {
+  const options = {
+    chiselPath: '/tmp/chisel',
+    controlPort: 52001,
+    authfilePath: '/tmp/authfile.json',
+    env: { PATH: '/bin', AUTH: 'unexpected:password' },
+  };
+  let output: string;
+  let stopAsync: jest.Mock;
+
+  beforeEach(() => {
+    jest.useFakeTimers();
+    output = 'server: Fingerprint pinned-key=\n';
+    stopAsync = jest.fn().mockResolvedValue(undefined);
+    jest.spyOn(process, 'kill').mockReturnValue(true);
+    jest.mocked(spawnDetached).mockReturnValue({
+      pid: 12345,
+      getOutput: () => output,
+      stopAsync,
+    });
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+    jest.useRealTimers();
+  });
+
+  it('waits for the child to bind its exact port and clears inherited AUTH', async () => {
+    let resolved = false;
+    const started = startChiselServerAsync(options).then(result => {
+      resolved = true;
+      return result;
+    });
+    output += 'server: Listening on http://127.0.0.1:520010\n';
+    await jest.advanceTimersByTimeAsync(250);
+    expect(resolved).toBe(false);
+    output += 'server: Listening on http://127.0.0.1:52001\n';
+    await jest.advanceTimersByTimeAsync(250);
+    await expect(started).resolves.toMatchObject({ fingerprint: 'pinned-key=' });
+    expect(spawnDetached).toHaveBeenCalledWith(
+      expect.objectContaining({ env: { PATH: '/bin', AUTH: '' } })
+    );
+    expect(options.env.AUTH).toBe('unexpected:password');
+    expect(stopAsync).not.toHaveBeenCalled();
+  });
+
+  it('rejects and stops a child that prints its fingerprint then fails to bind', async () => {
+    const started = startChiselServerAsync(options);
+    const rejected = expect(started).rejects.toThrow('address already in use');
+    output += 'listen tcp 127.0.0.1:52001: bind: address already in use\n';
+    jest.mocked(process.kill).mockImplementation(() => {
+      throw new Error('ESRCH');
+    });
+    await jest.advanceTimersByTimeAsync(250);
+    await rejected;
+    expect(stopAsync).toHaveBeenCalledTimes(1);
+  });
+
+  it('stops the child when startup is cancelled', async () => {
+    const controller = new AbortController();
+    const started = startChiselServerAsync({ ...options, signal: controller.signal });
+    const rejected = expect(started).rejects.toThrow('cancelled');
+    controller.abort(new Error('cancelled'));
+    await jest.advanceTimersByTimeAsync(250);
+    await rejected;
+    expect(stopAsync).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe('local egress resource lifetime', () => {
+  const logger = { warn: jest.fn() } as unknown as bunyan;
+
+  it('aborts the lifetime and awaits the same cleanup for concurrent callers', async () => {
+    let finish!: () => void;
+    const cleanup = jest.fn(
+      () =>
+        new Promise<void>(resolve => {
+          finish = resolve;
+        })
+    );
+    const signal = registerLocalEgressResources(cleanup);
+    const first = stopLocalEgressResourcesAsync(logger);
+    const second = stopLocalEgressResourcesAsync(logger);
+    expect(signal.aborted).toBe(true);
+    await Promise.resolve();
+    expect(cleanup).toHaveBeenCalledTimes(1);
+    let complete = false;
+    void second.then(() => {
+      complete = true;
+    });
+    await Promise.resolve();
+    expect(complete).toBe(false);
+    finish();
+    await Promise.all([first, second]);
+    await stopLocalEgressResourcesAsync(logger);
+    expect(cleanup).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports cleanup failure without masking the job result', async () => {
+    const error = new Error('cleanup failed');
+    registerLocalEgressResources(async () => {
+      throw error;
+    });
+    await expect(stopLocalEgressResourcesAsync(logger)).resolves.toBeUndefined();
+    expect(logger.warn).toHaveBeenCalledWith(
+      { err: error },
+      'Could not stop a local egress resource.'
+    );
+  });
+});
@@ -11,6 +11,7 @@ import { setTimeout as setTimeoutAsync } from 'node:timers/promises';
 import { CustomBuildContext } from '../../../customBuildContext';
 import { Sentry } from '../../../sentry';
 import { turtleFetch } from '../../../utils/turtleFetch';
+import { readServeSimServersAsync } from '../serveSimMetricsRecorder';
 import { sleepAsync } from '../../../utils/retry';
 import {
  createExpoDeviceHubArgs,
@@ -33,6 +34,11 @@ jest.mock('../../../utils/turtleFetch');
 jest.mock('../../../utils/retry', () => ({ sleepAsync: jest.fn() }));
 jest.mock('../../../sentry');
 jest.mock('@expo/turtle-spawn');
+// Spyable so a test can stand in for the serve-sim state directory, which a local serve-sim owns.
+jest.mock('../serveSimMetricsRecorder', () => {
+  const actual = jest.requireActual('../serveSimMetricsRecorder');
+  return { ...actual, readServeSimServersAsync: jest.fn(actual.readServeSimServersAsync) };
+});

 function createLoggerMock(): bunyan {
  return {
@@ -130,6 +136,7 @@ describe(createServeSimArgs, () => {
      '4321',
      '--host',
      '127.0.0.1',
+      '--require-token',
      '--transport',
      'webrtc',
      '--webrtc-codec',
@@ -329,6 +336,9 @@ describe(startDeviceWebPreviewWithTunnelAsync, () => {
    jest.mocked(spawn).mockReset();
    jest.mocked(ngrok.forward).mockReset();
    jest.mocked(turtleFetch).mockReset();
+    jest
+      .mocked(readServeSimServersAsync)
+      .mockResolvedValue([{ udid: 'device-id', url: 'http://127.0.0.1:1', token: 'tok-1' }]);

    const spawnPromise = Object.assign(Promise.resolve(undefined), {
      child: {
@@ -417,6 +427,63 @@ describe(startDeviceWebPreviewWithTunnelAsync, () => {
    expect(close).toHaveBeenCalledTimes(1);
  });

+  it('carries the serve-sim session token for Darwin', async () => {
+    jest.mocked(ngrok.forward).mockResolvedValue({
+      url: () => 'https://preview.example.test',
+      close: jest.fn().mockResolvedValue(undefined),
+    } as never);
+
+    const preview = await startDeviceWebPreviewWithTunnelAsync(createCtxMock(), {
+      runtimePlatform: BuildRuntimePlatform.DARWIN,
+      baseDomain,
+      env,
+      logger: createLoggerMock(),
+      timeoutMs: 10_000,
+    });
+
+    expect(preview.previewToken).toBe('tok-1');
+    expect(preview.previewUrl).toBe('https://preview.example.test');
+  });
+
+  // serve-sim is always launched with --require-token, so a missing token means it is running
+  // ungated on a public tunnel. Failing beats handing out a preview that is dead or unprotected.
+  it('fails for Darwin when serve-sim reports no token', async () => {
+    jest
+      .mocked(readServeSimServersAsync)
+      .mockResolvedValue([{ udid: 'device-id', url: 'http://127.0.0.1:1' }]);
+
+    await expect(
+      startDeviceWebPreviewWithTunnelAsync(createCtxMock(), {
+        runtimePlatform: BuildRuntimePlatform.DARWIN,
+        baseDomain,
+        env,
+        logger: createLoggerMock(),
+        timeoutMs: 10_000,
+      })
+    ).rejects.toThrow(/wrote no session token/);
+  });
+
+  // expo-device-hub mints no token, so the Android preview must not require one.
+  it('starts for Linux without a token, and does not gate expo-device-hub', async () => {
+    jest.mocked(readServeSimServersAsync).mockResolvedValue([]);
+    jest.mocked(ngrok.forward).mockResolvedValue({
+      url: () => 'https://android-preview.example.test',
+      close: jest.fn().mockResolvedValue(undefined),
+    } as never);
+
+    const preview = await startDeviceWebPreviewWithTunnelAsync(createCtxMock(), {
+      runtimePlatform: BuildRuntimePlatform.LINUX,
+      baseDomain,
+      env,
+      logger: createLoggerMock(),
+      timeoutMs: 10_000,
+    });
+
+    expect(preview.previewToken).toBeUndefined();
+    const [, args] = jest.mocked(spawn).mock.calls[0];
+    expect(args).not.toContain('--require-token');
+  });
+
  it('starts serve-sim for Darwin with its metrics policy and cleans up the preview resources', async () => {
    const packageVersion = '4.5.6';
    const close = jest.fn().mockResolvedValue(undefined);
@@ -101,6 +101,14 @@ describe(readServeSimServersAsync, () => {
    ]);
  });

+  it('includes the session token when the state file carries one', async () => {
+    await writeServerStateAsync('E', { device: 'E', url: 'http://127.0.0.1:5', token: 'tok-abc' });
+
+    expect(await readServeSimServersAsync(stateDir)).toEqual([
+      { udid: 'E', url: 'http://127.0.0.1:5', token: 'tok-abc' },
+    ]);
+  });
+
  it('returns [] when the state dir does not exist', async () => {
    expect(await readServeSimServersAsync(path.join(workDir, 'nope'))).toEqual([]);
  });
@@ -120,6 +128,20 @@ describe(streamServeSimMetricsToFileAsync, () => {
    expect(String(jest.mocked(fetch).mock.calls[0][0])).toBe('https://sim.example/metrics');
  });

+  it('sends the session token as a bearer header when given one', async () => {
+    jest.mocked(fetch).mockResolvedValue(sseResponse());
+    await streamServeSimMetricsToFileAsync({
+      serveSimUrl: 'https://sim.example',
+      serveSimToken: 'tok-abc',
+      filePath: path.join(workDir, 'auth.ndjson'),
+      signal: new AbortController().signal,
+      logger: createLoggerMock(),
+    });
+    expect(jest.mocked(fetch).mock.calls[0][1]?.headers).toMatchObject({
+      Authorization: 'Bearer tok-abc',
+    });
+  });
+
  it('writes nothing on a non-ok response', async () => {
    jest.mocked(fetch).mockResolvedValue(new Response('nope', { status: 502 }));
    const filePath = path.join(workDir, 'empty.ndjson');
@@ -0,0 +1,724 @@
+import downloadFile from '@expo/downloader';
+import { SystemError } from '@expo/eas-build-job';
+import { bunyan } from '@expo/logger';
+import { BuildStepEnv } from '@expo/steps';
+import spawn from '@expo/turtle-spawn';
+import { createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import zlib from 'node:zlib';
+
+import { sleepAsync } from '../../utils/retry';
+
+import { type DetachedProcessHandle, spawnDetached } from './remoteDeviceRunSession';
+
+/**
+ * Local egress provides an HTTP(S) proxy through the machine running the EAS CLI.
+ * Requests that use this proxy exit through that machine's network.
+ *
+ * Worker side: a chisel server in reverse mode listens on loopback and is exposed
+ * through the session's ngrok domain. When the CLI's egress client connects, chisel
+ * opens LOCAL_EGRESS_PROXY_PORT on this host and forwards every connection to the
+ * HTTP proxy the CLI runs. The macOS system proxy points at that port. Until the
+ * client connects, nothing listens on the port and proxied requests fail.
+ *
+ * Contract: HTTP(S) and WebSocket requests that honor the system proxy (WebKit,
+ * URLSession and other CFNetwork clients) exit from the egress client's network
+ * and fail while the client is disconnected. Requests from libraries that bypass
+ * the system proxy are not covered and exit from this host. Nothing here enforces
+ * routing; the session monitor reports such direct connections instead.
+ */
+
+export const LOCAL_EGRESS_PROXY_HOST = '127.0.0.1';
+export const LOCAL_EGRESS_PROXY_PORT = 8899;
+export const LOCAL_EGRESS_USERNAME = 'eas';
+export const LOCAL_EGRESS_HANDOFF_PATH = path.join(os.tmpdir(), 'eas-simulator-local-egress.json');
+
+export const CHISEL_VERSION = '1.12.0';
+// sha256 of the release .gz assets, cross-checked against chisel_1.12.0_checksums.txt.
+const CHISEL_SHA256_BY_ASSET: Record<string, string> = {
+  'chisel_1.12.0_darwin_arm64.gz':
+    '707a4b932eea214765146504a0df246cefc415b4297af65a80dd67cf69ba85a9',
+  'chisel_1.12.0_darwin_amd64.gz':
+    '4aeae36c867f11c8e8c3f2b913a0e063ea3c6d29e1c14a52ed2e6eef8cfc4395',
+  'chisel_1.12.0_linux_amd64.gz':
+    'f3f180f1d93aa72cce4e6386f98cc06569a0146fbd65eb4423cf83e6434bcfe6',
+  'chisel_1.12.0_linux_arm64.gz':
+    '2ec6152cd2c74fe0146d4d79e4e7aa174521368c56e433d55e023a92ea404ec3',
+};
+
+const CHISEL_STARTUP_TIMEOUT_MS = 15_000;
+const EGRESS_MONITOR_INTERVAL_MS = 2_000;
+const EGRESS_ESCAPE_SCAN_INTERVAL_MS = 5_000;
+const EGRESS_ESCAPE_LOG_LIMIT = 50;
+
+export type LocalEgressHandoff = {
+  /** Public URL of the reverse tunnel server, reachable through ngrok. */
+  url: string;
+  /** Secret the client presents to the tunnel server, paired with LOCAL_EGRESS_USERNAME. */
+  token: string;
+  /** Fingerprint of the tunnel server key, for the client to pin. */
+  fingerprint: string;
+  /** Loopback port on this host that the client must serve. */
+  port: number;
+};
+
+export function getChiselAssetName({
+  platform,
+  arch,
+}: {
+  platform: NodeJS.Platform;
+  arch: string;
+}): string {
+  const os = platform === 'darwin' ? 'darwin' : platform === 'linux' ? 'linux' : null;
+  const cpu = arch === 'arm64' ? 'arm64' : arch === 'x64' ? 'amd64' : null;
+  if (!os || !cpu) {
+    throw new SystemError(
+      `Local egress is not supported on ${platform}/${arch}. The reverse tunnel binary is available for macOS and Linux on arm64 and x64.`
+    );
+  }
+  return `chisel_${CHISEL_VERSION}_${os}_${cpu}.gz`;
+}
+
+export function getChiselDownloadUrl(assetName: string): string {
+  return `https://github.com/jpillora/chisel/releases/download/v${CHISEL_VERSION}/${assetName}`;
+}
+
+async function sha256FileAsync(filePath: string): Promise<string> {
+  const hash = createHash('sha256');
+  await pipeline(fs.createReadStream(filePath), hash);
+  return hash.digest('hex');
+}
+
+export async function downloadChiselAsync({
+  destinationDir,
+  logger,
+  platform = process.platform,
+  arch = process.arch,
+}: {
+  destinationDir: string;
+  logger: bunyan;
+  platform?: NodeJS.Platform;
+  arch?: string;
+}): Promise<string> {
+  const assetName = getChiselAssetName({ platform, arch });
+  const expectedSha256 = CHISEL_SHA256_BY_ASSET[assetName];
+  if (!expectedSha256) {
+    throw new SystemError(`No pinned checksum for ${assetName}.`);
+  }
+  const url = getChiselDownloadUrl(assetName);
+  const archivePath = path.join(destinationDir, assetName);
+  logger.info(`Downloading ${url}.`);
+  await downloadFile(url, archivePath, { retry: 3, timeout: 60_000 });
+
+  const actualSha256 = await sha256FileAsync(archivePath);
+  if (actualSha256 !== expectedSha256) {
+    throw new SystemError(
+      `Checksum mismatch for ${assetName}: expected ${expectedSha256}, got ${actualSha256}. ` +
+        'The download may be corrupted or tampered with; the session was not started.'
+    );
+  }
+
+  const binaryPath = path.join(destinationDir, 'chisel');
+  await pipeline(
+    fs.createReadStream(archivePath),
+    zlib.createGunzip(),
+    fs.createWriteStream(binaryPath)
+  );
+  await fs.promises.chmod(binaryPath, 0o755);
+  return binaryPath;
+}
+
+export function generateEgressCredentials(): { user: string; password: string } {
+  return { user: LOCAL_EGRESS_USERNAME, password: randomBytes(24).toString('base64url') };
+}
+
+// Matches 1024-65535: every unprivileged TCP port.
+const UNPRIVILEGED_PORT_PATTERN =
+  '(102[4-9]|10[3-9][0-9]|1[1-9][0-9]{2}|[2-9][0-9]{3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])';
+
+/**
+ * chisel authfile: one user, allowed to open reverse remotes on loopback only.
+ * The proxy port carries proxied requests. Any unprivileged loopback port may be
+ * forwarded too: the EAS CLI opens one per `--egress-allow localhost:<port>`
+ * entry so `127.0.0.1:<port>` inside the simulator reaches that port on the
+ * developer's machine, like `adb reverse`. iOS never sends loopback-literal
+ * requests to the system proxy, so the proxy alone cannot serve them.
+ * Reverse remotes are matched as `R:<interface>:<port>`.
+ */
+export function createChiselAuthfileContents({
+  user,
+  password,
+  port,
+}: {
+  user: string;
+  password: string;
+  port: number;
+}): string {
+  const escapedHost = LOCAL_EGRESS_PROXY_HOST.replace(/\./g, '\\.');
+  return JSON.stringify({
+    [`${user}:${password}`]: [
+      `^R:${escapedHost}:${port}$`,
+      `^R:${escapedHost}:${UNPRIVILEGED_PORT_PATTERN}$`,
+    ],
+  });
+}
+
+export function parseChiselFingerprint(output: string): string | null {
+  const match = /Fingerprint\s+(\S+)/.exec(output);
+  return match?.[1] ?? null;
+}
+
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function startChiselServerAsync({
+  chiselPath,
+  controlPort,
+  authfilePath,
+  env,
+  signal,
+}: {
+  chiselPath: string;
+  controlPort: number;
+  authfilePath: string;
+  env: BuildStepEnv;
+  signal?: AbortSignal;
+}): Promise<{ process: DetachedProcessHandle; fingerprint: string }> {
+  const server = spawnDetached({
+    command: chiselPath,
+    args: [
+      'server',
+      '--host',
+      LOCAL_EGRESS_PROXY_HOST,
+      '--port',
+      String(controlPort),
+      '--reverse',
+      '--authfile',
+      authfilePath,
+    ],
+    // AUTH adds an unrestricted user even when --authfile is supplied.
+    env: { ...env, AUTH: '' },
+  });
+
+  try {
+    const deadline = Date.now() + CHISEL_STARTUP_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+      signal?.throwIfAborted();
+      if (server.pid === undefined || !isProcessRunning(server.pid)) {
+        break;
+      }
+      const output = server.getOutput();
+      const fingerprint = parseChiselFingerprint(output);
+      // Chisel prints the fingerprint before binding. This line comes from the
+      // child only after its listener succeeds, unlike a probe of a reused port.
+      const listening = output
+        .split('\n')
+        .some(line =>
+          line
+            .trimEnd()
+            .endsWith(`server: Listening on http://${LOCAL_EGRESS_PROXY_HOST}:${controlPort}`)
+        );
+      if (fingerprint && listening) {
+        return { process: server, fingerprint };
+      }
+      await sleepAsync(250);
+    }
+    throw new SystemError(
+      `The reverse tunnel server did not start within ${CHISEL_STARTUP_TIMEOUT_MS / 1000}s. Output:\n${
+        server.getOutput() || '<empty>'
+      }`
+    );
+  } catch (error) {
+    await server.stopAsync();
+    throw error;
+  }
+}
+
+export function parseDefaultRouteInterface(routeOutput: string): string | null {
+  const match = /^\s*interface:\s*(\S+)/m.exec(routeOutput);
+  return match?.[1] ?? null;
+}
+
+/**
+ * `networksetup -listnetworkserviceorder` prints each service as two lines:
+ * "(1) Wi-Fi" followed by "(Hardware Port: Wi-Fi, Device: en0)". Return the
+ * service name whose device matches.
+ */
+export function parseNetworkServiceNameForDevice(
+  listOutput: string,
+  device: string
+): string | null {
+  const lines = listOutput.split('\n').map(line => line.trim());
+  for (let i = 0; i < lines.length; i++) {
+    const hardwarePortMatch = /^\(Hardware Port: (.+), Device: (\S+)\)$/.exec(lines[i]);
+    if (!hardwarePortMatch || hardwarePortMatch[2] !== device) {
+      continue;
+    }
+    const serviceLineMatch = /^\(\d+\) (.+)$/.exec(lines[i - 1] ?? '');
+    return serviceLineMatch?.[1] ?? hardwarePortMatch[1];
+  }
+  return null;
+}
+
+export async function resolveActiveNetworkServiceNameAsync({
+  env,
+}: {
+  env: BuildStepEnv;
+}): Promise<string> {
+  const routeResult = await spawn('route', ['-n', 'get', 'default'], { env, stdio: 'pipe' });
+  const device = parseDefaultRouteInterface(routeResult.stdout);
+  if (!device) {
+    throw new SystemError(
+      'Could not determine the default network interface of the device host, so the system proxy ' +
+        'cannot be configured. Output of `route -n get default`:\n' +
+        (routeResult.stdout || '<empty>')
+    );
+  }
+  const listResult = await spawn('networksetup', ['-listnetworkserviceorder'], {
+    env,
+    stdio: 'pipe',
+  });
+  const service = parseNetworkServiceNameForDevice(listResult.stdout, device);
+  if (!service) {
+    throw new SystemError(
+      `Could not find the network service for interface ${device}, so the system proxy cannot be ` +
+        'configured. Output of `networksetup -listnetworkserviceorder`:\n' +
+        (listResult.stdout || '<empty>')
+    );
+  }
+  return service;
+}
+
+export function buildNetworksetupProxyArgs({
+  service,
+  host,
+  port,
+}: {
+  service: string;
+  host: string;
+  port: number;
+}): string[][] {
+  return [
+    ['-setwebproxy', service, host, String(port)],
+    ['-setsecurewebproxy', service, host, String(port)],
+  ];
+}
+
+/**
+ * Point the macOS system HTTP and HTTPS proxy at the loopback egress port. The
+ * simulator reads these settings when it boots, so this must run before
+ * `start_ios_simulator`. Existing bypass and automatic proxy settings are left
+ * unchanged. Requests that bypass this proxy can leave from this host's address.
+ */
+export async function configureSystemProxyAsync({
+  env,
+  logger,
+  port,
+  signal,
+}: {
+  env: BuildStepEnv;
+  logger: bunyan;
+  port: number;
+  signal?: AbortSignal;
+}): Promise<{ service: string }> {
+  if (process.env.ENVIRONMENT === 'development') {
+    logger.info('Job running outside of EAS, not changing the system proxy.');
+    return { service: '<development>' };
+  }
+  const service = await resolveActiveNetworkServiceNameAsync({ env });
+  for (const args of buildNetworksetupProxyArgs({ service, host: LOCAL_EGRESS_PROXY_HOST, port })) {
+    signal?.throwIfAborted();
+    await spawn('networksetup', args, { env, logger, signal });
+  }
+  logger.info(`System proxy for "${service}" set to ${LOCAL_EGRESS_PROXY_HOST}:${port}.`);
+  return { service };
+}
+
+export async function writeLocalEgressHandoffAsync(
+  handoff: LocalEgressHandoff,
+  handoffPath: string = LOCAL_EGRESS_HANDOFF_PATH
+): Promise<void> {
+  await fs.promises.writeFile(handoffPath, JSON.stringify(handoff), {
+    encoding: 'utf8',
+    mode: 0o600,
+  });
+}
+
+export async function readLocalEgressHandoffAsync(
+  handoffPath: string = LOCAL_EGRESS_HANDOFF_PATH
+): Promise<LocalEgressHandoff | null> {
+  let raw: string;
+  try {
+    raw = await fs.promises.readFile(handoffPath, 'utf8');
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+      return null;
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(raw) as Partial<LocalEgressHandoff>;
+  if (
+    typeof parsed.url !== 'string' ||
+    typeof parsed.token !== 'string' ||
+    typeof parsed.fingerprint !== 'string' ||
+    typeof parsed.port !== 'number'
+  ) {
+    throw new SystemError(`Local egress handoff at ${handoffPath} is malformed.`);
+  }
+  return {
+    url: parsed.url,
+    token: parsed.token,
+    fingerprint: parsed.fingerprint,
+    port: parsed.port,
+  };
+}
+
+/** remoteConfig fields the CLI needs to start the egress client. */
+export function buildEgressRemoteConfigFields(
+  handoff: LocalEgressHandoff | null
+): Record<string, string | number> {
+  if (!handoff) {
+    return {};
+  }
+  return {
+    egressUrl: handoff.url,
+    egressToken: handoff.token,
+    egressFingerprint: handoff.fingerprint,
+    egressPort: handoff.port,
+  };
+}
+
+// The egress step returns before the session ends, so the resources it created
+// are held here and released by the session step or the job's finally block.
+let activeLocalEgressResources:
+  | { stopAsync: () => Promise<void>; controller: AbortController; stopping?: Promise<void> }
+  | undefined;
+
+export function registerLocalEgressResources(stopAsync: () => Promise<void>): AbortSignal {
+  if (activeLocalEgressResources) {
+    throw new SystemError('Local egress resources are already registered for this job.');
+  }
+  const controller = new AbortController();
+  activeLocalEgressResources = { stopAsync, controller };
+  return controller.signal;
+}
+
+export async function stopLocalEgressResourcesAsync(logger: bunyan): Promise<void> {
+  const resources = activeLocalEgressResources;
+  if (!resources) {
+    return;
+  }
+  resources.controller.abort();
+  resources.stopping ??= Promise.resolve()
+    .then(resources.stopAsync)
+    .catch(err => logger.warn({ err }, 'Could not stop a local egress resource.'))
+    .finally(() => {
+      activeLocalEgressResources = undefined;
+    });
+  await resources.stopping;
+}
+
+export async function isPortListeningAsync({
+  host,
+  port,
+  timeoutMs = 1_000,
+}: {
+  host: string;
+  port: number;
+  timeoutMs?: number;
+}): Promise<boolean> {
+  return await new Promise<boolean>(resolve => {
+    const socket = net.connect({ host, port });
+    const finish = (listening: boolean): void => {
+      socket.destroy();
+      resolve(listening);
+    };
+    socket.setTimeout(timeoutMs, () => finish(false));
+    socket.once('connect', () => finish(true));
+    socket.once('error', () => finish(false));
+  });
+}
+
+export function parseExitIpResponse(body: string): string {
+  const parsed = JSON.parse(body) as { ip?: unknown };
+  if (typeof parsed.ip !== 'string' || parsed.ip.length === 0) {
+    throw new SystemError(`Unexpected exit IP response: ${body}`);
+  }
+  return parsed.ip;
+}
+
+export async function fetchExitIpThroughProxyAsync({
+  port,
+  env,
+}: {
+  port: number;
+  env: BuildStepEnv;
+}): Promise<string> {
+  const result = await spawn(
+    'curl',
+    [
+      '-sS',
+      '--max-time',
+      '10',
+      '-x',
+      `http://${LOCAL_EGRESS_PROXY_HOST}:${port}`,
+      'https://api.ipify.org?format=json',
+    ],
+    { env, stdio: 'pipe' }
+  );
+  return parseExitIpResponse(result.stdout);
+}
+
+/**
+ * Processes inside the simulator run on the host as descendants of launchd_sim,
+ * so `ps -axo pid=,ppid=,comm=` ancestry identifies them. Returns every
+ * descendant pid; launchd_sim itself opens no network connections.
+ */
+export function collectSimulatorProcessIds(psOutput: string): number[] {
+  const childrenByParent = new Map<number, number[]>();
+  const roots: number[] = [];
+  for (const line of psOutput.split('\n')) {
+    const match = /^\s*(\d+)\s+(\d+)\s+(\S.*)$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const pid = Number(match[1]);
+    const parentPid = Number(match[2]);
+    const command = match[3].trim();
+    const siblings = childrenByParent.get(parentPid) ?? [];
+    siblings.push(pid);
+    childrenByParent.set(parentPid, siblings);
+    if (path.basename(command) === 'launchd_sim') {
+      roots.push(pid);
+    }
+  }
+
+  const descendants: number[] = [];
+  const seen = new Set<number>(roots);
+  const queue = [...roots];
+  for (let i = 0; i < queue.length; i++) {
+    for (const child of childrenByParent.get(queue[i]) ?? []) {
+      if (seen.has(child)) {
+        continue;
+      }
+      seen.add(child);
+      descendants.push(child);
+      queue.push(child);
+    }
+  }
+  return descendants;
+}
+
+export type DirectSimulatorConnection = {
+  pid: number;
+  command: string;
+  protocol: string;
+  /** Remote peer as lsof prints it, e.g. `93.184.216.34:443` or `[2606::1]:443`. */
+  remote: string;
+};
+
+function remoteHostOf(remote: string): string {
+  if (remote.startsWith('[')) {
+    const end = remote.indexOf(']');
+    return end === -1 ? remote : remote.slice(1, end);
+  }
+  const colon = remote.lastIndexOf(':');
+  return colon === -1 ? remote : remote.slice(0, colon);
+}
+
+function isLoopbackHost(host: string): boolean {
+  return (
+    host === 'localhost' || host.startsWith('127.') || host === '::1' || host === '::ffff:127.0.0.1'
+  );
+}
+
+/**
+ * Parse `lsof -nP -i -F pcPnT` output. Returns the TCP and UDP connections that
+ * simulator processes hold to peers outside loopback. Those did not go through
+ * the proxy on 127.0.0.1, so they exit from this host instead of the egress
+ * client. Listening sockets, unconnected UDP sockets and connections to
+ * loopback (the proxy itself) are ignored.
+ */
+export function parseDirectSimulatorConnections(
+  lsofOutput: string,
+  simulatorPids: ReadonlySet<number>
+): DirectSimulatorConnection[] {
+  const connections: DirectSimulatorConnection[] = [];
+  let pid: number | null = null;
+  let command = '';
+  let protocol: string | null = null;
+  let name: string | null = null;
+  let tcpState: string | null = null;
+
+  const flush = (): void => {
+    if (pid !== null && simulatorPids.has(pid) && protocol && name) {
+      const arrow = name.indexOf('->');
+      const remote = arrow === -1 ? null : name.slice(arrow + 2);
+      const active =
+        protocol !== 'TCP' ||
+        tcpState === null ||
+        tcpState === 'ESTABLISHED' ||
+        tcpState === 'SYN_SENT';
+      if (remote && active && !isLoopbackHost(remoteHostOf(remote))) {
+        connections.push({ pid, command, protocol, remote });
+      }
+    }
+    protocol = null;
+    name = null;
+    tcpState = null;
+  };
+
+  for (const line of lsofOutput.split('\n')) {
+    const field = line[0];
+    const value = line.slice(1);
+    switch (field) {
+      case 'p':
+        flush();
+        pid = Number(value);
+        command = '';
+        break;
+      case 'c':
+        command = value;
+        break;
+      case 'f':
+        flush();
+        break;
+      case 'P':
+        protocol = value;
+        break;
+      case 'n':
+        name = value;
+        break;
+      case 'T':
+        if (value.startsWith('ST=')) {
+          tcpState = value.slice('ST='.length);
+        }
+        break;
+      default:
+        break;
+    }
+  }
+  flush();
+  return connections;
+}
+
+async function findDirectSimulatorConnectionsAsync({
+  env,
+}: {
+  env: BuildStepEnv;
+}): Promise<DirectSimulatorConnection[]> {
+  const ps = await spawn('ps', ['-axo', 'pid=,ppid=,comm='], { env, stdio: 'pipe' });
+  const pids = collectSimulatorProcessIds(ps.stdout);
+  if (pids.length === 0) {
+    return [];
+  }
+  let lsofOutput: string;
+  try {
+    const lsof = await spawn('lsof', ['-nP', '-i', '-F', 'pcPnT', '-a', '-p', pids.join(',')], {
+      env,
+      stdio: 'pipe',
+    });
+    lsofOutput = lsof.stdout;
+  } catch (err) {
+    // lsof exits with 1 when none of the processes holds a matching socket, and
+    // when one of them exited between `ps` and `lsof`. Its stdout is still valid.
+    const result = err as { status?: number | null; stdout?: string };
+    if (result.status !== 1) {
+      throw err;
+    }
+    lsofOutput = result.stdout ?? '';
+  }
+  return parseDirectSimulatorConnections(lsofOutput, new Set(pids));
+}
+
+/**
+ * Log proxy listener availability, the exit IP observed by a worker request
+ * through it, and simulator connections that bypassed the proxy. Neither check
+ * verifies that proxied simulator requests reach the egress client. Never
+ * rejects: it runs in the background for the whole session.
+ */
+export async function monitorLocalEgressAsync({
+  port,
+  env,
+  logger,
+  signal,
+}: {
+  port: number;
+  env: BuildStepEnv;
+  logger: bunyan;
+  signal: AbortSignal;
+}): Promise<void> {
+  let connected = false;
+  let lastEscapeScanAt = 0;
+  let escapeScanBroken = false;
+  const reportedEscapes = new Set<string>();
+  const lifetimeSignal = activeLocalEgressResources?.controller.signal;
+  try {
+    while (!signal.aborted && !lifetimeSignal?.aborted) {
+      const listening = await isPortListeningAsync({ host: LOCAL_EGRESS_PROXY_HOST, port });
+      if (listening && !connected) {
+        connected = true;
+        logger.info('Local egress proxy listener is available.');
+        try {
+          const exitIp = await fetchExitIpThroughProxyAsync({ port, env });
+          logger.info(
+            `Worker proxy exit-IP check observed ${exitIp}. This does not verify simulator routing.`
+          );
+        } catch (err) {
+          logger.warn(
+            { err },
+            'The local egress proxy listener is available, but the worker exit-IP check through it failed.'
+          );
+        }
+      } else if (!listening && connected) {
+        connected = false;
+        logger.warn(
+          'Local egress proxy listener is unavailable. Proxied HTTP(S) requests fail until it returns.'
+        );
+      }
+
+      if (!escapeScanBroken && Date.now() - lastEscapeScanAt >= EGRESS_ESCAPE_SCAN_INTERVAL_MS) {
+        lastEscapeScanAt = Date.now();
+        try {
+          for (const connection of await findDirectSimulatorConnectionsAsync({ env })) {
+            const key = `${connection.pid}|${connection.protocol}|${connection.remote}`;
+            if (reportedEscapes.has(key)) {
+              continue;
+            }
+            reportedEscapes.add(key);
+            if (reportedEscapes.size > EGRESS_ESCAPE_LOG_LIMIT) {
+              if (reportedEscapes.size === EGRESS_ESCAPE_LOG_LIMIT + 1) {
+                logger.warn(
+                  `Local egress: more than ${EGRESS_ESCAPE_LOG_LIMIT} direct connections were reported; further ones are not logged.`
+                );
+              }
+              continue;
+            }
+            logger.warn(
+              `Local egress: ${connection.command} (pid ${connection.pid}) opened a direct ${connection.protocol} connection to ${connection.remote}, bypassing the system proxy. That traffic exits from this worker, not from the egress client.`
+            );
+          }
+        } catch (err) {
+          escapeScanBroken = true;
+          logger.warn(
+            { err },
+            'Local egress: could not inspect simulator connections. Direct connections that bypass the proxy will not be reported.'
+          );
+        }
+      }
+      await sleepAsync(EGRESS_MONITOR_INTERVAL_MS);
+    }
+  } catch (err) {
+    logger.warn({ err }, 'Local egress monitoring stopped unexpectedly.');
+  }
+}
@@ -0,0 +1,55 @@
+import { type BuildFunction, type BuildStepEnv } from '@expo/steps';
+
+import {
+  buildEgressRemoteConfigFields,
+  monitorLocalEgressAsync,
+  readLocalEgressHandoffAsync,
+  stopLocalEgressResourcesAsync,
+} from './localEgress';
+import { uploadRemoteSessionConfigAsync } from './remoteDeviceRunSession';
+
+/** Release the pre-boot egress resources even if controller startup or teardown fails. */
+export function withLocalEgressSession(
+  fn: NonNullable<BuildFunction['fn']>
+): NonNullable<BuildFunction['fn']> {
+  return async (context, args) => {
+    try {
+      args.signal?.throwIfAborted();
+      await fn(context, args);
+    } finally {
+      await stopLocalEgressResourcesAsync(context.logger);
+    }
+  };
+}
+
+/** All simulator controllers publish the same egress handoff and run the same monitor. */
+export async function uploadRemoteSessionConfigWithLocalEgressAsync({
+  env,
+  signal,
+  ...options
+}: Parameters<typeof uploadRemoteSessionConfigAsync>[0] & {
+  env: BuildStepEnv;
+  signal?: AbortSignal;
+}): Promise<void> {
+  // Written by start_local_egress before simulator boot; absent for ordinary sessions.
+  const localEgress = await readLocalEgressHandoffAsync();
+  signal?.throwIfAborted();
+  await uploadRemoteSessionConfigAsync({
+    ...options,
+    remoteConfig: { ...options.remoteConfig, ...buildEgressRemoteConfigFields(localEgress) },
+  });
+  if (localEgress && !signal?.aborted) {
+    options.logger.info(
+      'Local egress: waiting for the EAS CLI egress client to connect. Proxied HTTP(S) ' +
+        'requests are unavailable until it does.'
+    );
+    // The monitor also observes the registered resources' lifetime signal, which
+    // withLocalEgressSession aborts on success, failure, or cancellation.
+    void monitorLocalEgressAsync({
+      port: localEgress.port,
+      env,
+      logger: options.logger,
+      signal: signal ?? new AbortController().signal,
+    });
+  }
+}
@@ -17,6 +17,7 @@ import { CustomBuildContext } from '../../customBuildContext';
 import { Sentry } from '../../sentry';
 import { sleepAsync } from '../../utils/retry';
 import { turtleFetch } from '../../utils/turtleFetch';
+import { SERVE_SIM_STATE_DIR, readServeSimServersAsync } from './serveSimMetricsRecorder';

 const XCODE_DEVELOPER_DIR = '/Applications/Xcode.app/Contents/Developer';
 const WEB_PREVIEW_HOST = '127.0.0.1';
@@ -652,6 +653,7 @@ export function createServeSimArgs({
    String(port),
    '--host',
    WEB_PREVIEW_HOST,
+    '--require-token',
    '--transport',
    'webrtc',
    '--webrtc-codec',
@@ -705,7 +707,7 @@ export function createExpoDeviceHubArgs({
  ];
 }

-async function findAvailablePortAsync(): Promise<number> {
+export async function findAvailablePortAsync(): Promise<number> {
  const server = createServer();
  server.unref();
  await new Promise<void>((resolve, reject) => {
@@ -737,7 +739,7 @@ export async function waitForWebPreviewReadyAsync({
  serverName: string;
  port: number;
  timeoutMs: number;
-}): Promise<void> {
+}): Promise<string> {
  const readyUrl = `http://${WEB_PREVIEW_HOST}:${port}/readyz`;
  const deadline = Date.now() + timeoutMs;
  let lastError: unknown;
@@ -754,8 +756,8 @@ export async function waitForWebPreviewReadyAsync({
        retries: 0,
        timeout: 2_000,
      });
-      WebPreviewReadyResponseSchema.parse(await response.json());
-      return;
+      const ready = WebPreviewReadyResponseSchema.parse(await response.json());
+      return ready.device;
    } catch (error) {
      lastError = error;
    }
@@ -770,6 +772,8 @@ export async function waitForWebPreviewReadyAsync({

 export type DeviceWebPreviewHandle = {
  previewUrl: string;
+  /** Session token gating the preview. Only serve-sim mints one. */
+  previewToken?: string;
  stopAsync: () => Promise<void>;
 };

@@ -785,6 +789,7 @@ async function startWebPreviewWithTunnelAsync(
    serverName,
    packageSpec,
    createArgs,
+    readPreviewTokenAsync,
  }: {
    baseDomain: string;
    env: BuildStepEnv;
@@ -793,6 +798,7 @@ async function startWebPreviewWithTunnelAsync(
    serverName: string;
    packageSpec: string;
    createArgs: (port: number, turnArgs: string[]) => string[];
+    readPreviewTokenAsync?: (device: string) => Promise<string>;
  }
 ): Promise<DeviceWebPreviewHandle> {
  const port = await findAvailablePortAsync();
@@ -806,7 +812,13 @@ async function startWebPreviewWithTunnelAsync(

  try {
    logger.info(`Waiting for ${serverName} to become ready.`);
-    await waitForWebPreviewReadyAsync({ previewServer, serverName, port, timeoutMs });
+    const device = await waitForWebPreviewReadyAsync({
+      previewServer,
+      serverName,
+      port,
+      timeoutMs,
+    });
+    const previewToken = await readPreviewTokenAsync?.(device);
    const tunnel = await startNgrokTunnelAsync({
      port,
      subdomainPrefix: 'web-preview',
@@ -816,6 +828,7 @@ async function startWebPreviewWithTunnelAsync(
    });
    return {
      previewUrl: tunnel.url,
+      previewToken,
      stopAsync: async () => {
        const results = await Promise.allSettled([tunnel.stopAsync(), previewServer.stopAsync()]);
        for (const result of results) {
@@ -831,6 +844,14 @@ async function startWebPreviewWithTunnelAsync(
  }
 }

+export async function readServeSimPreviewTokenAsync(
+  udid: string,
+  stateDir: string = SERVE_SIM_STATE_DIR
+): Promise<string | undefined> {
+  const servers = await readServeSimServersAsync(stateDir);
+  return servers.find(server => server.udid === udid)?.token;
+}
+
 export async function startServeSimWithTunnelAsync(
  ctx: CustomBuildContext,
  {
@@ -857,6 +878,20 @@ export async function startServeSimWithTunnelAsync(
    packageSpec: createServeSimPackageSpec(packageVersion),
    createArgs: (port, turnArgs) =>
      createServeSimArgs({ port, turnArgs, metricsCorsArgs, packageVersion }),
+    readPreviewTokenAsync: async device => {
+      const previewToken = await readServeSimPreviewTokenAsync(device);
+      if (!previewToken) {
+        // A serve-sim that does not know --require-token fails earlier, in the readiness check, so
+        // reaching here means it started and left no token in its state file.
+        throw new SystemError(
+          `serve-sim became ready but wrote no session token for device ${device}. The preview is ` +
+            'on a public tunnel and would be reachable without one, so the session cannot continue. ' +
+            'This usually means the state file was not written as expected; retry the session, and ' +
+            'report it if it repeats.'
+        );
+      }
+      return previewToken;
+    },
  });
 }

@@ -13,9 +13,9 @@ const POLL_INTERVAL_MS = 2_000;
 const MAX_CONSECUTIVE_STREAM_FAILURES_PER_DEVICE = 10;
 const END_STREAM_TIMEOUT_MS = 2_000;
 // serve-sim's own per-device registry while serving: `${tmpdir}/serve-sim/server-<udid>.json`.
-const SERVE_SIM_STATE_DIR = path.join(os.tmpdir(), 'serve-sim');
+export const SERVE_SIM_STATE_DIR = path.join(os.tmpdir(), 'serve-sim');

-type ServeSimServer = { udid: string; url: string };
+type ServeSimServer = { udid: string; url: string; token?: string };

 type ServeSimMetricsSession = {
  logger: bunyan;
@@ -130,6 +130,7 @@ async function pollServeSimMetricsAsync(session: ServeSimMetricsSession): Promis
      logger.info(`Collecting serve-sim metrics for ${server.udid}.`);
      const donePromise = streamServeSimMetricsToFileAsync({
        serveSimUrl: server.url,
+        serveSimToken: server.token,
        filePath,
        signal: streamSignal,
        logger,
@@ -172,9 +173,14 @@ export async function readServeSimServersAsync(stateDir: string): Promise<ServeS
      const state = JSON.parse(await readFile(path.join(stateDir, entry), 'utf-8')) as {
        device?: unknown;
        url?: unknown;
+        token?: unknown;
      };
      if (typeof state.device === 'string' && typeof state.url === 'string') {
-        servers.push({ udid: state.device, url: state.url });
+        servers.push({
+          udid: state.device,
+          url: state.url,
+          ...(typeof state.token === 'string' ? { token: state.token } : {}),
+        });
      }
    } catch {
      continue;
@@ -185,11 +191,13 @@ export async function readServeSimServersAsync(stateDir: string): Promise<ServeS

 export async function streamServeSimMetricsToFileAsync({
  serveSimUrl,
+  serveSimToken,
  filePath,
  signal,
  logger,
 }: {
  serveSimUrl: string;
+  serveSimToken?: string;
  filePath: string;
  signal: AbortSignal;
  logger: bunyan;
@@ -201,7 +209,10 @@ export async function streamServeSimMetricsToFileAsync({
  let receivedData = false;
  let metadata: Record<string, unknown> | undefined;
  try {
-    const response = await fetch(new URL('/metrics', serveSimUrl).toString(), { signal });
+    const response = await fetch(new URL('/metrics', serveSimUrl).toString(), {
+      signal,
+      ...(serveSimToken ? { headers: { Authorization: `Bearer ${serveSimToken}` } } : {}),
+    });
    if (!response.ok || !response.body) {
      logger.warn(`serve-sim /metrics responded ${response.status} for ${serveSimUrl}.`);
      return { receivedData, metadata };
@@ -6632,6 +6632,54 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "egressFingerprint",
+            "description": "Fingerprint of the reverse-tunnel server key for the client to pin. Null when\nthe session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressPort",
+            "description": "Loopback port on the device host that the local egress client must serve\nthrough the tunnel. Null when the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "Int",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressToken",
+            "description": "Secret the local egress client presents to the reverse-tunnel endpoint. Null\nwhen the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressUrl",
+            "description": "Reverse-tunnel endpoint the local egress client connects to. Null when the\nsession does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "webPreviewToken",
            "description": "Session token gating the web preview. Null when the preview runs ungated.",
@@ -33311,6 +33359,54 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "egressFingerprint",
+            "description": "Fingerprint of the reverse-tunnel server key for the client to pin. Null when\nthe session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressPort",
+            "description": "Loopback port on the device host that the local egress client must serve\nthrough the tunnel. Null when the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "Int",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressToken",
+            "description": "Secret the local egress client presents to the reverse-tunnel endpoint. Null\nwhen the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressUrl",
+            "description": "Reverse-tunnel endpoint the local egress client connects to. Null when the\nsession does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "webPreviewToken",
            "description": "Session token gating the web preview. Null when the preview runs ungated.",
@@ -36124,6 +36220,54 @@
        "name": "ArgentRunSessionRemoteConfig",
        "description": null,
        "fields": [
+          {
+            "name": "egressFingerprint",
+            "description": "Fingerprint of the reverse-tunnel server key for the client to pin. Null when\nthe session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressPort",
+            "description": "Loopback port on the device host that the local egress client must serve\nthrough the tunnel. Null when the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "Int",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressToken",
+            "description": "Secret the local egress client presents to the reverse-tunnel endpoint. Null\nwhen the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressUrl",
+            "description": "Reverse-tunnel endpoint the local egress client connects to. Null when the\nsession does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "toolsAuthToken",
            "description": null,
@@ -45010,6 +45154,18 @@
            "isDeprecated": false,
            "deprecationReason": null
          },
+          {
+            "name": "egress",
+            "description": "Where the virtual device's proxied network traffic exits to the internet. If\nomitted, all traffic exits from EAS infrastructure. LOCAL is only supported for\nsessions on IOS.",
+            "type": {
+              "kind": "ENUM",
+              "name": "DeviceRunSessionEgress",
+              "ofType": null
+            },
+            "defaultValue": null,
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "expoGo",
            "description": "Install and launch Expo Go before the simulator session becomes available. The server resolves\nthe platform-specific application archive. Mutually exclusive with buildId, buildFingerprint,\nand applicationArchiveUrl.",
@@ -50362,6 +50518,23 @@
        "enumValues": null,
        "possibleTypes": null
      },
+      {
+        "kind": "ENUM",
+        "name": "DeviceRunSessionEgress",
+        "description": "Where the virtual device's proxied network traffic exits to the internet. When\nunset, all traffic exits from EAS infrastructure.",
+        "fields": null,
+        "inputFields": null,
+        "interfaces": null,
+        "enumValues": [
+          {
+            "name": "LOCAL",
+            "description": "HTTP(S) requests that honor the device's system proxy exit through a reverse\ntunnel to the machine running the EAS CLI egress client, so third parties see\nthat machine's public IP. Those requests fail while the client is disconnected.\nRequests from libraries that bypass the system proxy are not covered and exit\nfrom EAS infrastructure. The client must stay connected for the life of the\nsession.",
+            "isDeprecated": false,
+            "deprecationReason": null
+          }
+        ],
+        "possibleTypes": null
+      },
      {
        "kind": "OBJECT",
        "name": "DeviceRunSessionEventLogUploadSession",
@@ -78421,6 +78594,54 @@
        "name": "ServeSimRunSessionRemoteConfig",
        "description": "Legacy remote config for SERVE_SIM sessions. Use WEB_PREVIEW_ONLY sessions and\nWebPreviewOnlyRunSessionRemoteConfig instead.",
        "fields": [
+          {
+            "name": "egressFingerprint",
+            "description": "Fingerprint of the reverse-tunnel server key for the client to pin. Null when\nthe session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressPort",
+            "description": "Loopback port on the device host that the local egress client must serve\nthrough the tunnel. Null when the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "Int",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressToken",
+            "description": "Secret the local egress client presents to the reverse-tunnel endpoint. Null\nwhen the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressUrl",
+            "description": "Reverse-tunnel endpoint the local egress client connects to. Null when the\nsession does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
          {
            "name": "previewToken",
            "description": "Session token gating the preview. Null when the preview runs ungated.",
@@ -92896,17 +93117,49 @@
        "description": null,
        "fields": [
          {
-            "name": "webPreviewUrl",
-            "description": null,
+            "name": "egressFingerprint",
+            "description": "Fingerprint of the reverse-tunnel server key for the client to pin. Null when\nthe session does not use local egress.",
            "args": [],
            "type": {
-              "kind": "NON_NULL",
-              "name": null,
-              "ofType": {
-                "kind": "SCALAR",
-                "name": "String",
-                "ofType": null
-              }
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressPort",
+            "description": "Loopback port on the device host that the local egress client must serve\nthrough the tunnel. Null when the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "Int",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressToken",
+            "description": "Secret the local egress client presents to the reverse-tunnel endpoint. Null\nwhen the session does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
+          },
+          {
+            "name": "egressUrl",
+            "description": "Reverse-tunnel endpoint the local egress client connects to. Null when the\nsession does not use local egress.",
+            "args": [],
+            "type": {
+              "kind": "SCALAR",
+              "name": "String",
+              "ofType": null
            },
            "isDeprecated": false,
            "deprecationReason": null
@@ -92922,6 +93175,22 @@
            },
            "isDeprecated": false,
            "deprecationReason": null
+          },
+          {
+            "name": "webPreviewUrl",
+            "description": null,
+            "args": [],
+            "type": {
+              "kind": "NON_NULL",
+              "name": null,
+              "ofType": {
+                "kind": "SCALAR",
+                "name": "String",
+                "ofType": null
+              }
+            },
+            "isDeprecated": false,
+            "deprecationReason": null
          }
        ],
        "inputFields": null,
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli",
-  "version": "24.0.0",
+  "version": "24.1.1",
  "description": "EAS command line tool",
  "keywords": [
    "cli",
@@ -1,3 +1,4 @@
+import { Config } from '@oclif/core';
 import { v4 as uuidv4 } from 'uuid';

 import { AnalyticsWithOrchestration } from '../../analytics/AnalyticsManager';
@@ -24,17 +25,24 @@ jest.mock('../../analytics/AnalyticsManager', () => {
 });
 jest.mock('../../log');

-let originalProcessArgv: string[];
 const mockRequestId = uuidv4();

-beforeAll(() => {
-  originalProcessArgv = process.argv;
-  process.argv = [];
-});
+/**
+ * A Config that is never loaded. Letting oclif load one discovers and requires
+ * every command in the package, which takes seconds under coverage with a cold
+ * transform cache and has timed out on slow CI runners. Nothing here needs the
+ * command table or hooks.
+ */
+function getMockOclifConfig(): Config {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({
+    failures: [],
+    successes: [],
+  });
+  return config;
+}

-afterAll(() => {
-  process.argv = originalProcessArgv;
-});
+let mockConfig: Config;

 const analytics: AnalyticsWithOrchestration = {
  logEvent: jest.fn((): void => {}),
@@ -44,42 +52,57 @@ const analytics: AnalyticsWithOrchestration = {

 beforeEach(() => {
  jest.resetAllMocks();
+  mockConfig = getMockOclifConfig();
 });

+/**
+ * The config oclif handed to the most recently run command. Command.run returns
+ * a pre-built Config untouched only when it was created by the same @oclif/core
+ * copy the command extends; otherwise it silently builds and fully loads a new
+ * one, bringing back the command discovery this suite avoids.
+ */
+let lastCommandConfig: Config | undefined;
+
 const createTestEasCommand = (): any => {
  const { createAnalyticsAsync } = jest.requireMock('../../analytics/AnalyticsManager');
  createAnalyticsAsync.mockResolvedValue(analytics);
  const EasCommand = require('../EasCommand').default;

  class TestEasCommand extends EasCommand {
-    async runAsync(): Promise<void> {}
+    async runAsync(): Promise<void> {
+      lastCommandConfig = this.config;
+    }
  }

  TestEasCommand.id = 'testEasCommand'; // normally oclif will assign ids, but b/c this is located outside the commands folder it will not
  return TestEasCommand;
 };

+// These tests go through the static Command.run rather than constructing an
+// instance and calling run() like other command tests, because they cover
+// oclif's catch and finally wiring, which only runs inside the static path.
 describe('EasCommand', () => {
  describe('without exceptions', () => {
-    // The first test in this suite should have an increased timeout
-    // because of the implementation of Command from @oclif/command.
-    // It seems that loading config takes significant amount of time
-    // and I'm not sure how to mock it.
-    //
-    // See https://github.com/oclif/command/blob/master/src/command.ts#L80
-    // and look for "Config.load"
    it('ensures the user data is read', async () => {
      const TestEasCommand = createTestEasCommand();
-      await TestEasCommand.run();
+      await TestEasCommand.run([], mockConfig);

      const SessionManager = jest.requireMock('../../user/SessionManager').default;
      const sessionManagerSpy = jest.spyOn(SessionManager.prototype, 'getUserAsync');
      expect(sessionManagerSpy).toBeCalledTimes(1);
-    }, 60_000);
+    });
+
+    it('runs with the unloaded config instead of loading one', async () => {
+      const TestEasCommand = createTestEasCommand();
+      await TestEasCommand.run([], mockConfig);
+
+      expect(lastCommandConfig).toBe(mockConfig);
+      expect(mockConfig.plugins.size).toBe(0);
+    });

    it('initializes analytics', async () => {
      const TestEasCommand = createTestEasCommand();
-      await TestEasCommand.run();
+      await TestEasCommand.run([], mockConfig);

      const { createAnalyticsAsync } = jest.requireMock('../../analytics/AnalyticsManager');
      expect(createAnalyticsAsync).toHaveBeenCalled();
@@ -87,14 +110,14 @@ describe('EasCommand', () => {

    it('flushes analytics', async () => {
      const TestEasCommand = createTestEasCommand();
-      await TestEasCommand.run();
+      await TestEasCommand.run([], mockConfig);

      expect(analytics.flushAsync).toHaveBeenCalled();
    });

    it('flushes Sentry', async () => {
      const TestEasCommand = createTestEasCommand();
-      await TestEasCommand.run();
+      await TestEasCommand.run([], mockConfig);

      const Sentry = jest.requireMock('../../sentry').default;
      expect(Sentry.flush).toHaveBeenCalled();
@@ -102,7 +125,7 @@ describe('EasCommand', () => {

    it('logs events', async () => {
      const TestEasCommand = createTestEasCommand();
-      await TestEasCommand.run();
+      await TestEasCommand.run([], mockConfig);

      expect(analytics.logEvent).toHaveBeenCalledWith('action', {
        action: `eas ${TestEasCommand.id}`,
@@ -114,7 +137,7 @@ describe('EasCommand', () => {
    it('flushes analytics', async () => {
      const TestEasCommand = createTestEasCommand();
      try {
-        await TestEasCommand.run().then(() => {
+        await TestEasCommand.run([], mockConfig).then(() => {
          throw new Error('foo');
        });
      } catch {}
@@ -140,7 +163,7 @@ describe('EasCommand', () => {
        });

        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch {}

        expect(sentryScope.setTag).toHaveBeenCalledWith('command', TestEasCommand.id);
@@ -167,7 +190,7 @@ describe('EasCommand', () => {
        });

        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch {}

        expect(Sentry.captureException).toHaveBeenCalledTimes(1);
@@ -184,7 +207,7 @@ describe('EasCommand', () => {
          throw error;
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch {}

        expect(logErrorSpy).toBeCalledWith('Unexpected, internal error message');
@@ -204,7 +227,7 @@ describe('EasCommand', () => {
          throw error;
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch {}

        expect(logErrorSpy).toBeCalledWith('Unexpected GraphQL error message');
@@ -237,7 +260,7 @@ describe('EasCommand', () => {
          throw error;
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch {}

        expect(logErrorSpy).toBeCalledWith(
@@ -273,7 +296,7 @@ describe('EasCommand', () => {
          throw error;
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch {}

        expect(logErrorSpy).toBeCalledWith(
@@ -294,7 +317,7 @@ describe('EasCommand', () => {
          throw new Error('Error message');
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch (caughtError) {
          expect(caughtError).toBeInstanceOf(Error);
          expect((caughtError as Error).message).toEqual('testEasCommand command failed.');
@@ -310,7 +333,7 @@ describe('EasCommand', () => {
          throw new CombinedError({ graphQLErrors });
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch (caughtError) {
          expect(caughtError).toBeInstanceOf(Error);
          expect((caughtError as Error).message).toEqual('GraphQL request failed.');
@@ -340,7 +363,7 @@ describe('EasCommand', () => {
          throw new CombinedError({ graphQLErrors });
        });
        try {
-          await TestEasCommand.run();
+          await TestEasCommand.run([], mockConfig);
        } catch (caughtError) {
          expect(caughtError).toBeInstanceOf(Error);
          expect((caughtError as Error).message).toEqual('GraphQL request failed.');
@@ -0,0 +1,114 @@
+import { Config } from '@oclif/core';
+
+import Log from '../../../log';
+import { runLocalEgressAsync } from '../../../simulator/egress';
+import { loadSimulatorEnvAsync } from '../../../simulator/env';
+import SimulatorEgress from '../egress';
+
+jest.mock('../../../log');
+jest.mock('../../../simulator/env', () => ({
+  ...jest.requireActual('../../../simulator/env'),
+  loadSimulatorEnvAsync: jest.fn(),
+}));
+jest.mock('../../../simulator/egress', () => ({
+  ...jest.requireActual('../../../simulator/egress'),
+  runLocalEgressAsync: jest.fn(),
+}));
+
+const shellSession = {
+  EAS_SIMULATOR_SESSION_ID: 'session-b',
+  EAS_SIMULATOR_EGRESS_ALLOW: '',
+  EAS_SIMULATOR_EGRESS_URL: 'https://egress-b.example.test',
+  EAS_SIMULATOR_EGRESS_TOKEN: 'token-b',
+  EAS_SIMULATOR_EGRESS_FINGERPRINT: 'fingerprint-b',
+  EAS_SIMULATOR_EGRESS_PORT: '8899',
+};
+const fileSession = {
+  EAS_SIMULATOR_SESSION_ID: 'session-a',
+  EAS_SIMULATOR_EGRESS_ALLOW: 'localhost:3000',
+  EAS_SIMULATOR_EGRESS_URL: 'https://egress-a.example.test',
+  EAS_SIMULATOR_EGRESS_TOKEN: 'token-a',
+  EAS_SIMULATOR_EGRESS_FINGERPRINT: 'fingerprint-a',
+  EAS_SIMULATOR_EGRESS_PORT: '8898',
+};
+
+function createCommand(argv: string[]): SimulatorEgress {
+  const config = new Config({ root: __dirname });
+  config.runHook = async () => ({ failures: [], successes: [] });
+  const command = new SimulatorEgress(argv, config);
+  // @ts-expect-error getContextAsync is protected
+  jest.spyOn(command, 'getContextAsync').mockResolvedValue({ projectDir: '/test/project' });
+  return command;
+}
+
+describe(SimulatorEgress, () => {
+  const previousEnv = Object.fromEntries(
+    Object.keys(shellSession).map(key => [key, process.env[key]])
+  );
+  beforeEach(() => {
+    jest.clearAllMocks();
+    Object.assign(process.env, shellSession);
+    jest.mocked(loadSimulatorEnvAsync).mockImplementation(async () => {
+      Object.assign(process.env, fileSession);
+    });
+    jest.mocked(runLocalEgressAsync).mockResolvedValue();
+  });
+  afterEach(() => {
+    for (const [key, value] of Object.entries(previousEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+
+  it('uses the complete exported session tuple without loading a stale dotenv session in env mode', async () => {
+    await createCommand(['--config-type', 'env']).runAsync();
+
+    expect(loadSimulatorEnvAsync).not.toHaveBeenCalled();
+    expect(runLocalEgressAsync).toHaveBeenCalledWith(
+      expect.objectContaining({
+        url: shellSession.EAS_SIMULATOR_EGRESS_URL,
+        token: shellSession.EAS_SIMULATOR_EGRESS_TOKEN,
+        fingerprint: shellSession.EAS_SIMULATOR_EGRESS_FINGERPRINT,
+        port: 8899,
+        allow: [],
+      })
+    );
+    expect(Log.log).toHaveBeenCalledWith(expect.stringContaining('session-b'));
+    expect(Log.log).toHaveBeenCalledWith(
+      expect.stringContaining('eas simulator:stop --id session-b')
+    );
+  });
+
+  it.each([[], ['--config-type', 'dotenv']])(
+    'loads the managed session by default or with explicit dotenv selection (%j)',
+    async (...argv) => {
+      await createCommand(argv).runAsync();
+
+      expect(loadSimulatorEnvAsync).toHaveBeenCalledWith('/test/project');
+      expect(runLocalEgressAsync).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: fileSession.EAS_SIMULATOR_EGRESS_URL,
+          token: fileSession.EAS_SIMULATOR_EGRESS_TOKEN,
+          fingerprint: fileSession.EAS_SIMULATOR_EGRESS_FINGERPRINT,
+          port: 8898,
+          allow: ['localhost:3000'],
+        })
+      );
+      expect(Log.log).toHaveBeenCalledWith(expect.stringContaining('session-a'));
+    }
+  );
+
+  it('does not fill missing exported credentials from a stale file in env mode', async () => {
+    delete process.env.EAS_SIMULATOR_EGRESS_TOKEN;
+
+    await expect(createCommand(['--config-type', 'env']).runAsync()).rejects.toThrow(
+      'no egress client to run'
+    );
+
+    expect(loadSimulatorEnvAsync).not.toHaveBeenCalled();
+    expect(runLocalEgressAsync).not.toHaveBeenCalled();
+  });
+});
@@ -6,6 +6,7 @@ import {
  AppPlatform,
  CreateDeviceRunSessionMutation,
  DeviceRunSessionByIdQuery,
+  DeviceRunSessionEgress,
  DeviceRunSessionResourceClass,
  DeviceRunSessionStatus,
  DeviceRunSessionType,
@@ -17,6 +18,7 @@ import { DeviceRunSessionQuery } from '../../../graphql/queries/DeviceRunSession
 import Log from '../../../log';
 import { ora } from '../../../ora';
 import { promptAsync } from '../../../prompts';
+import { runLocalEgressAsync } from '../../../simulator/egress';
 import {
  EAS_SIMULATOR_SESSION_ID,
  SIMULATOR_DOTENV_FILE_HEADER,
@@ -38,6 +40,8 @@ jest.mock('../../../log', () => ({
    log: jest.fn(),
    newLine: jest.fn(),
    warn: jest.fn(),
+    error: jest.fn(),
+    succeed: jest.fn(),
    withTick: jest.fn(),
  },
  link: jest.fn((url: string) => url),
@@ -49,6 +53,10 @@ jest.mock('../../../simulator/env', () => ({
 }));
 jest.mock('../../../simulator/expoGo');
 jest.mock('../../../prompts');
+jest.mock('../../../simulator/egress', () => ({
+  ...jest.requireActual('../../../simulator/egress'),
+  runLocalEgressAsync: jest.fn(),
+}));
 jest.mock('../../../ora', () => ({
  ora: jest.fn(() => {
    const spinner = {
@@ -856,6 +864,233 @@ describe(Simulator, () => {
    processExitSpy.mockRestore();
  });

+  const localEgressSessions: [
+    string,
+    DeviceRunSessionType,
+    NonNullable<DeviceRunSessionById['remoteConfig']>,
+  ][] = [
+    [
+      'agent-device',
+      DeviceRunSessionType.AgentDevice,
+      {
+        __typename: 'AgentDeviceRunSessionRemoteConfig',
+        agentDeviceRemoteSessionUrl: 'https://agent.example.com',
+        agentDeviceRemoteSessionToken: 'token',
+      },
+    ],
+    [
+      'appium',
+      DeviceRunSessionType.Appium,
+      {
+        __typename: 'AppiumRunSessionRemoteConfig',
+        appiumUrl: 'https://appium.example.com',
+        capabilities: {},
+      },
+    ],
+    [
+      'argent',
+      DeviceRunSessionType.Argent,
+      {
+        __typename: 'ArgentRunSessionRemoteConfig',
+        toolsUrl: 'https://argent.example.com',
+      },
+    ],
+    [
+      'web-preview-only',
+      DeviceRunSessionType.WebPreviewOnly,
+      {
+        __typename: 'WebPreviewOnlyRunSessionRemoteConfig',
+        previewUrl: 'https://preview.example.com',
+      },
+    ],
+    [
+      'web-preview-only',
+      DeviceRunSessionType.ServeSim,
+      {
+        __typename: 'ServeSimRunSessionRemoteConfig',
+        previewUrl: 'https://preview.example.com',
+      },
+    ],
+  ];
+  const localEgressFields = {
+    egressUrl: 'https://egress.example.com',
+    egressToken: 'pw',
+    egressFingerprint: 'fp',
+    egressPort: 8899,
+  };
+
+  it.each(localEgressSessions)(
+    'creates iOS %s sessions with local egress and saves connection details',
+    async (typeFlag, type, remoteConfig) => {
+      mockByIdAsync.mockResolvedValue(
+        makeDeviceRunSession({
+          type,
+          remoteConfig: { ...remoteConfig, ...localEgressFields },
+        })
+      );
+      const { command } = createCommand([
+        '--platform',
+        'ios',
+        '--type',
+        typeFlag,
+        '--egress',
+        'local',
+        '--non-interactive',
+      ]);
+      await command.runAsync();
+      expect(mockCreateDeviceRunSessionAsync).toHaveBeenCalledWith(
+        graphqlClient,
+        expect.objectContaining({
+          platform: AppPlatform.Ios,
+          egress: DeviceRunSessionEgress.Local,
+        })
+      );
+      expect(fs.writeFile).toHaveBeenCalledWith(
+        simulatorDotenvPath,
+        expect.stringContaining("EAS_SIMULATOR_EGRESS_TOKEN='pw'")
+      );
+      expect(Log.log).toHaveBeenCalledWith(expect.stringContaining('eas simulator:egress'));
+      expect(runLocalEgressAsync).not.toHaveBeenCalled();
+    }
+  );
+
+  it('prints the shell credential command when local egress uses env output', async () => {
+    const [typeFlag, type, remoteConfig] = localEgressSessions[1];
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({
+        type,
+        remoteConfig: { ...remoteConfig, ...localEgressFields },
+      })
+    );
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--type',
+      typeFlag,
+      '--egress',
+      'local',
+      '--out-config-type',
+      'env',
+      '--non-interactive',
+    ]);
+    await command.runAsync();
+    expect(fs.writeFile).not.toHaveBeenCalled();
+    expect(Log.log).toHaveBeenCalledWith(
+      expect.stringContaining('Start `eas simulator:egress --config-type env` in another process')
+    );
+    expect(Log.log).not.toHaveBeenCalledWith(
+      expect.stringContaining('Start `eas simulator:egress` in another process')
+    );
+  });
+
+  it.each(localEgressSessions)(
+    'rejects local egress for Android %s before creating a session',
+    async typeFlag => {
+      const { command } = createCommand([
+        '--platform',
+        'android',
+        '--type',
+        typeFlag,
+        '--egress',
+        'local',
+        '--non-interactive',
+      ]);
+      await expect(command.runAsync()).rejects.toThrow(
+        '--egress local is only supported with --platform ios.'
+      );
+      expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+    }
+  );
+
+  it.each(localEgressSessions)(
+    'stops %s after an interactive egress failure and removes its interrupt handler',
+    async (typeFlag, type, remoteConfig) => {
+      const failure = new Error('listen EADDRINUSE');
+      jest.mocked(runLocalEgressAsync).mockRejectedValueOnce(failure);
+      mockByIdAsync.mockResolvedValue(
+        makeDeviceRunSession({
+          type,
+          remoteConfig: { ...remoteConfig, ...localEgressFields },
+        })
+      );
+      const listeners = process.listeners('SIGINT');
+      const { command } = createCommand([
+        '--platform',
+        'ios',
+        '--type',
+        typeFlag,
+        '--egress',
+        'local',
+      ]);
+      await expect(command.runAsync()).rejects.toBe(failure);
+      expect(mockEnsureDeviceRunSessionStoppedAsync).toHaveBeenCalledWith(
+        graphqlClient,
+        'session-123'
+      );
+      expect(mockResetSimulatorEnvAsync).toHaveBeenCalledWith(projectDir, 'session-123');
+      expect(process.listeners('SIGINT')).toEqual(listeners);
+    }
+  );
+
+  it('passes normalized --egress-allow destinations to the egress client', async () => {
+    const session = makeDeviceRunSession({
+      remoteConfig: {
+        __typename: 'AgentDeviceRunSessionRemoteConfig',
+        agentDeviceRemoteSessionUrl: 'https://agent.example.com',
+        agentDeviceRemoteSessionToken: 'token',
+        egressUrl: 'https://egress.example.com',
+        egressToken: 'pw',
+        egressFingerprint: 'fp',
+        egressPort: 8899,
+      },
+    });
+    mockByIdAsync
+      .mockResolvedValueOnce(session)
+      .mockResolvedValueOnce({ ...session, status: DeviceRunSessionStatus.Stopped });
+    jest.mocked(runLocalEgressAsync).mockResolvedValueOnce(undefined);
+
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--egress',
+      'local',
+      '--egress-allow',
+      'localhost:3000',
+      '--egress-allow',
+      'LOCALHOST:3000',
+      '--egress-allow',
+      '192.168.1.20:8080',
+    ]);
+    await command.runAsync();
+
+    expect(runLocalEgressAsync).toHaveBeenCalledWith(
+      expect.objectContaining({ allow: ['localhost:3000', '192.168.1.20:8080'] })
+    );
+  });
+
+  it('rejects malformed --egress-allow values before creating a session', async () => {
+    // If validation were skipped, fail fast instead of polling a live session.
+    mockByIdAsync.mockResolvedValue(
+      makeDeviceRunSession({ status: DeviceRunSessionStatus.Stopped })
+    );
+    const { command } = createCommand([
+      '--platform',
+      'ios',
+      '--egress',
+      'local',
+      '--egress-allow',
+      'localhost',
+    ]);
+    await expect(command.runAsync()).rejects.toThrow('Invalid --egress-allow value "localhost"');
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
+  it('requires --egress for --egress-allow', async () => {
+    const { command } = createCommand(['--platform', 'ios', '--egress-allow', 'localhost:3000']);
+    await expect(command.runAsync()).rejects.toThrow(/--egress/);
+    expect(mockCreateDeviceRunSessionAsync).not.toHaveBeenCalled();
+  });
+
  it('prompts to select the platform when --platform is omitted', async () => {
    mockPromptAsync.mockResolvedValueOnce({ selectedPlatform: AppPlatform.Android });
    mockByIdAsync
@@ -0,0 +1,77 @@
+import { Flags } from '@oclif/core';
+
+import EasCommand from '../../commandUtils/EasCommand';
+import Log from '../../log';
+import { readLocalEgressConfigFromEnv, runLocalEgressAsync } from '../../simulator/egress';
+import {
+  EAS_SIMULATOR_SESSION_ID,
+  SIMULATOR_DOTENV_FILE_NAME,
+  loadSimulatorEnvAsync,
+} from '../../simulator/env';
+
+export default class SimulatorEgress extends EasCommand {
+  static override hidden = true;
+  static override aliases = ['sim:egress'];
+  static override description = `[EXPERIMENTAL] run the local egress client for a simulator session to route proxied HTTP(S) requests through this machine`;
+
+  static override flags = {
+    'config-type': Flags.option({
+      description: `Read session credentials from ${SIMULATOR_DOTENV_FILE_NAME} (dotenv) or the current shell environment (env).`,
+      options: ['dotenv', 'env'] as const,
+      default: 'dotenv',
+    })(),
+  };
+
+  static override contextDefinition = {
+    ...this.ContextOptions.ProjectDir,
+  };
+
+  async runAsync(): Promise<void> {
+    const { flags } = await this.parse(SimulatorEgress);
+    const { projectDir } = await this.getContextAsync(SimulatorEgress, {
+      nonInteractive: true,
+    });
+    if (flags['config-type'] === 'dotenv') {
+      await loadSimulatorEnvAsync(projectDir);
+    }
+
+    const egress = readLocalEgressConfigFromEnv(process.env);
+    const deviceRunSessionId = process.env[EAS_SIMULATOR_SESSION_ID];
+
+    Log.log(
+      `Starting the local egress client${
+        deviceRunSessionId ? ` for simulator session ${deviceRunSessionId}` : ''
+      }. When connected, proxied HTTP(S) requests can use this machine's network.`
+    );
+    Log.log(
+      'Press Ctrl+C to stop the egress client. The simulator session keeps running; ' +
+        `proxied HTTP(S) requests are unavailable until the tunnel reconnects. Stop the session with \`eas simulator:stop${deviceRunSessionId ? ` --id ${deviceRunSessionId}` : ''}\`.`
+    );
+    Log.newLine();
+
+    const abortController = new AbortController();
+    const handleSigint = (): void => {
+      abortController.abort();
+    };
+    process.on('SIGINT', handleSigint);
+    try {
+      await runLocalEgressAsync({
+        ...egress,
+        signal: abortController.signal,
+        onConnected: () => {
+          Log.succeed(
+            "Egress tunnel connected. Proxied HTTP(S) requests can use this machine's network."
+          );
+        },
+        onDisconnected: () => {
+          Log.warn(
+            'Egress tunnel disconnected; reconnecting. Proxied HTTP(S) requests are unavailable until it reconnects.'
+          );
+        },
+      });
+    } finally {
+      process.removeListener('SIGINT', handleSigint);
+    }
+    Log.log('Egress client stopped.');
+  }
+}
@@ -11,6 +11,7 @@ import {
 } from '../../commandUtils/flags';
 import {
  AppPlatform,
+  DeviceRunSessionEgress,
  DeviceRunSessionStatus,
  DeviceRunSessionType,
  JobRunStatus,
@@ -21,6 +22,7 @@ import { DeviceRunSessionQuery } from '../../graphql/queries/DeviceRunSessionQue
 import Log, { link } from '../../log';
 import { ora } from '../../ora';
 import { promptAsync } from '../../prompts';
+import { parseEgressAllowList, runLocalEgressAsync } from '../../simulator/egress';
 import {
  EAS_SIMULATOR_SESSION_ID,
  SIMULATOR_DOTENV_FILE_NAME,
@@ -37,6 +39,7 @@ import {
  DeviceRunSessionRemoteConfig,
  formatRemoteSessionInstructions,
  formatSimulatorUnavailableMessage,
+  getLocalEgressConfig,
  getRemoteSessionEnvironmentVariables,
  sanitizeRemoteConfigForJson,
 } from '../../simulator/utils';
@@ -51,6 +54,7 @@ const OUT_CONFIG_TYPE_VALUES = {
 } as const;
 const PLATFORM_FLAG_VALUES = ['android', 'ios'] as const;
 type PlatformFlagValue = (typeof PLATFORM_FLAG_VALUES)[number];
+const EGRESS_FLAG_VALUES = ['local'] as const;
 const APP_PLATFORM_BY_FLAG_VALUE: Record<PlatformFlagValue, AppPlatform> = {
  android: AppPlatform.Android,
  ios: AppPlatform.Ios,
@@ -133,6 +137,17 @@ export default class Simulator extends EasCommand {
      hidden: true,
      options: Object.values(DEVICE_RUN_SESSION_RESOURCE_CLASS_FLAG_VALUES),
    })(),
+    egress: Flags.option({
+      description:
+        'With "local", the simulator system proxy points at this machine: HTTP(S) and WebSocket requests that honor it (WebKit, URLSession) exit from this machine and fail while the egress client is disconnected. Requests from libraries that bypass the system proxy are not covered. The egress client must keep running for the life of the session. Only supported with --platform ios.',
+      options: EGRESS_FLAG_VALUES,
+    })(),
+    'egress-allow': Flags.string({
+      description:
+        'Destination on this machine or its network that the simulator may reach through local egress, as an exact host:port (for example localhost:3000). Repeat for multiple destinations. A localhost or 127.0.0.1 entry also forwards that port from the simulator host to this machine (like adb reverse), so dev server URLs that use 127.0.0.1 work. Requires --egress local.',
+      multiple: true,
+      dependsOn: ['egress'],
+    }),
    force: Flags.boolean({
      description:
        '[default: true] Create a new simulator session even when an existing simulator session is present in the environment.',
@@ -219,6 +234,16 @@ export default class Simulator extends EasCommand {
    }

    const platform = await resolvePlatformAsync(flags.platform, nonInteractive);
+    const egress = flags.egress === 'local' ? DeviceRunSessionEgress.Local : undefined;
+    if (egress && platform !== AppPlatform.Ios) {
+      throw new EasCommandError('--egress local is only supported with --platform ios.');
+    }
+    let egressAllow: string[] = [];
+    try {
+      egressAllow = parseEgressAllowList(flags['egress-allow'] ?? []);
+    } catch (err) {
+      throw new EasCommandError(err instanceof Error ? err.message : String(err));
+    }
    if (platform === AppPlatform.Android) {
      Log.warn(
        'Android emulator support in EAS Simulator is still in development. Some features available on iOS may not work on Android yet. Full parity with iOS is coming soon.'
@@ -263,6 +288,7 @@ export default class Simulator extends EasCommand {
        ...(launchArgs?.length ? { launchArgs } : {}),
        ...(openUrl ? { openUrl } : {}),
        ...(resourceClass ? { resourceClass } : {}),
+        ...(egress ? { egress } : {}),
        maxRunTimeMinutes: flags['max-duration-minutes'],
        maxIdleTimeMinutes: flags['max-idle-time-minutes'],
      });
@@ -363,7 +389,7 @@ export default class Simulator extends EasCommand {

    if (flags['out-config-type'] === OUT_CONFIG_TYPE_VALUES.Dotenv) {
      await writeSimulatorEnvSafelyAsync(projectDir, {
-        ...getRemoteSessionEnvironmentVariables(remoteConfig),
+        ...getRemoteSessionEnvironmentVariables(remoteConfig, { egressAllow }),
        [EAS_SIMULATOR_SESSION_ID]: deviceRunSessionId,
      });
    }
@@ -392,24 +418,81 @@ export default class Simulator extends EasCommand {
    }

    Log.newLine();
-    Log.log(formatRemoteSessionInstructions(remoteConfig, flags['out-config-type']));
+    Log.log(
+      formatRemoteSessionInstructions(remoteConfig, flags['out-config-type'], {
+        egressAllow,
+        egressClientRunsInline: !nonInteractive,
+      })
+    );
    Log.newLine();

+    const localEgress = getLocalEgressConfig(remoteConfig, egressAllow);
+
    if (nonInteractive) {
      sessionInterrupt.dispose();
+      if (localEgress) {
+        Log.log(
+          `Start \`eas simulator:egress${flags['out-config-type'] === OUT_CONFIG_TYPE_VALUES.Env ? ' --config-type env' : ''}\` in another process to connect the tunnel for proxied HTTP(S) requests.`
+        );
+      }
      Log.log(
        `When you are done, stop the session with: eas simulator:stop --id ${deviceRunSessionId}`
      );
      return;
    }

-    await waitForSessionEndOrInterruptAsync({
-      graphqlClient,
-      deviceRunSessionId,
-      deviceRunSessionUrl,
-      projectDir,
-      sessionInterrupt,
-    });
+    // In interactive mode the egress client runs right here, for as long as the
+    // session does. A session with a disconnected tunnel still bills, so Ctrl+C stops both.
+    let egressPromise: Promise<void> | undefined;
+    let egressError: Error | undefined;
+    const egressAbortController = new AbortController();
+    if (localEgress) {
+      Log.log('Press Ctrl+C to stop both the egress client and the simulator session.');
+      Log.newLine();
+      sessionInterrupt.signal.addEventListener(
+        'abort',
+        () => {
+          egressAbortController.abort();
+        },
+        { once: true }
+      );
+      egressPromise = runLocalEgressAsync({
+        ...localEgress,
+        signal: egressAbortController.signal,
+        onConnected: () => {
+          Log.succeed(
+            "Egress tunnel connected. Proxied HTTP(S) requests can use this machine's network."
+          );
+        },
+        onDisconnected: () => {
+          Log.warn(
+            'Egress tunnel disconnected; reconnecting. Proxied HTTP(S) requests are unavailable until it reconnects.'
+          );
+        },
+      }).catch(err => {
+        egressError = err instanceof Error ? err : new Error(String(err));
+        Log.error(
+          `${err instanceof Error ? err.message : String(err)} Stopping the simulator session.`
+        );
+        sessionInterrupt.abort();
+      });
+    }
+
+    try {
+      await waitForSessionEndOrInterruptAsync({
+        graphqlClient,
+        deviceRunSessionId,
+        deviceRunSessionUrl,
+        projectDir,
+        sessionInterrupt,
+      });
+    } finally {
+      egressAbortController.abort();
+      await egressPromise;
+    }
+    if (egressError) {
+      throw egressError;
+    }
  }
 }

@@ -527,6 +610,8 @@ async function waitForSessionEndOrInterruptAsync({
 type SessionInterrupt = {
  signal: AbortSignal;
  abortPromise: Promise<void>;
+  /** Stop the session as if the user had pressed Ctrl+C. */
+  abort: () => void;
  dispose: () => void;
 };

@@ -558,6 +643,9 @@ function registerSessionInterrupt(deviceRunSessionId: string): SessionInterrupt
  return {
    signal,
    abortPromise,
+    abort: () => {
+      abortController.abort();
+    },
    dispose: () => process.removeListener('SIGINT', sigintHandler),
  };
 }
@@ -1081,6 +1081,26 @@ export type AgentDeviceRunSessionRemoteConfig = {
  __typename?: 'AgentDeviceRunSessionRemoteConfig';
  agentDeviceRemoteSessionToken: Scalars['String']['output'];
  agentDeviceRemoteSessionUrl: Scalars['String']['output'];
+  /**
+   * Fingerprint of the reverse-tunnel server key for the client to pin. Null when
+   * the session does not use local egress.
+   */
+  egressFingerprint?: Maybe<Scalars['String']['output']>;
+  /**
+   * Loopback port on the device host that the local egress client must serve
+   * through the tunnel. Null when the session does not use local egress.
+   */
+  egressPort?: Maybe<Scalars['Int']['output']>;
+  /**
+   * Secret the local egress client presents to the reverse-tunnel endpoint. Null
+   * when the session does not use local egress.
+   */
+  egressToken?: Maybe<Scalars['String']['output']>;
+  /**
+   * Reverse-tunnel endpoint the local egress client connects to. Null when the
+   * session does not use local egress.
+   */
+  egressUrl?: Maybe<Scalars['String']['output']>;
  /** Session token gating the web preview. Null when the preview runs ungated. */
  webPreviewToken?: Maybe<Scalars['String']['output']>;
  /**
@@ -4673,6 +4693,26 @@ export type AppiumRunSessionRemoteConfig = {
  appiumUrl: Scalars['String']['output'];
  /** W3C capabilities for the device that backs this session. */
  capabilities: Scalars['JSONObject']['output'];
+  /**
+   * Fingerprint of the reverse-tunnel server key for the client to pin. Null when
+   * the session does not use local egress.
+   */
+  egressFingerprint?: Maybe<Scalars['String']['output']>;
+  /**
+   * Loopback port on the device host that the local egress client must serve
+   * through the tunnel. Null when the session does not use local egress.
+   */
+  egressPort?: Maybe<Scalars['Int']['output']>;
+  /**
+   * Secret the local egress client presents to the reverse-tunnel endpoint. Null
+   * when the session does not use local egress.
+   */
+  egressToken?: Maybe<Scalars['String']['output']>;
+  /**
+   * Reverse-tunnel endpoint the local egress client connects to. Null when the
+   * session does not use local egress.
+   */
+  egressUrl?: Maybe<Scalars['String']['output']>;
  /** Session token gating the web preview. Null when the preview runs ungated. */
  webPreviewToken?: Maybe<Scalars['String']['output']>;
  /**
@@ -5081,6 +5121,26 @@ export type AppleTeamUpdateInput = {

 export type ArgentRunSessionRemoteConfig = {
  __typename?: 'ArgentRunSessionRemoteConfig';
+  /**
+   * Fingerprint of the reverse-tunnel server key for the client to pin. Null when
+   * the session does not use local egress.
+   */
+  egressFingerprint?: Maybe<Scalars['String']['output']>;
+  /**
+   * Loopback port on the device host that the local egress client must serve
+   * through the tunnel. Null when the session does not use local egress.
+   */
+  egressPort?: Maybe<Scalars['Int']['output']>;
+  /**
+   * Secret the local egress client presents to the reverse-tunnel endpoint. Null
+   * when the session does not use local egress.
+   */
+  egressToken?: Maybe<Scalars['String']['output']>;
+  /**
+   * Reverse-tunnel endpoint the local egress client connects to. Null when the
+   * session does not use local egress.
+   */
+  egressUrl?: Maybe<Scalars['String']['output']>;
  toolsAuthToken?: Maybe<Scalars['String']['output']>;
  toolsUrl: Scalars['String']['output'];
  /** Session token gating the web preview. Null when the preview runs ungated. */
@@ -6284,6 +6344,12 @@ export type CreateDeviceRunSessionInput = {
   * Mutually exclusive with buildFingerprint, applicationArchiveUrl, and expoGo.
   */
  buildId?: InputMaybe<Scalars['ID']['input']>;
+  /**
+   * Where the virtual device's proxied network traffic exits to the internet. If
+   * omitted, all traffic exits from EAS infrastructure. LOCAL is only supported for
+   * sessions on IOS.
+   */
+  egress?: InputMaybe<DeviceRunSessionEgress>;
  /**
   * Install and launch Expo Go before the simulator session becomes available. The server resolves
   * the platform-specific application archive. Mutually exclusive with buildId, buildFingerprint,
@@ -7029,6 +7095,22 @@ export type DeviceRunSessionArtifactUploadSession = {
  url: Scalars['String']['output'];
 };

+/**
+ * Where the virtual device's proxied network traffic exits to the internet. When
+ * unset, all traffic exits from EAS infrastructure.
+ */
+export enum DeviceRunSessionEgress {
+  /**
+   * HTTP(S) requests that honor the device's system proxy exit through a reverse
+   * tunnel to the machine running the EAS CLI egress client, so third parties see
+   * that machine's public IP. Those requests fail while the client is disconnected.
+   * Requests from libraries that bypass the system proxy are not covered and exit
+   * from EAS infrastructure. The client must stay connected for the life of the
+   * session.
+   */
+  Local = 'LOCAL'
+}
+
 export type DeviceRunSessionEventLogUploadSession = {
  __typename?: 'DeviceRunSessionEventLogUploadSession';
  headers: Scalars['JSONObject']['output'];
@@ -11072,6 +11154,26 @@ export type SentryProjectMutation_DeleteSentryProjectArgs = {
 */
 export type ServeSimRunSessionRemoteConfig = {
  __typename?: 'ServeSimRunSessionRemoteConfig';
+  /**
+   * Fingerprint of the reverse-tunnel server key for the client to pin. Null when
+   * the session does not use local egress.
+   */
+  egressFingerprint?: Maybe<Scalars['String']['output']>;
+  /**
+   * Loopback port on the device host that the local egress client must serve
+   * through the tunnel. Null when the session does not use local egress.
+   */
+  egressPort?: Maybe<Scalars['Int']['output']>;
+  /**
+   * Secret the local egress client presents to the reverse-tunnel endpoint. Null
+   * when the session does not use local egress.
+   */
+  egressToken?: Maybe<Scalars['String']['output']>;
+  /**
+   * Reverse-tunnel endpoint the local egress client connects to. Null when the
+   * session does not use local egress.
+   */
+  egressUrl?: Maybe<Scalars['String']['output']>;
  /** Session token gating the preview. Null when the preview runs ungated. */
  previewToken?: Maybe<Scalars['String']['output']>;
  previewUrl: Scalars['String']['output'];
@@ -13135,6 +13237,26 @@ export type WebNotificationUpdateReadStateInput = {

 export type WebPreviewOnlyRunSessionRemoteConfig = {
  __typename?: 'WebPreviewOnlyRunSessionRemoteConfig';
+  /**
+   * Fingerprint of the reverse-tunnel server key for the client to pin. Null when
+   * the session does not use local egress.
+   */
+  egressFingerprint?: Maybe<Scalars['String']['output']>;
+  /**
+   * Loopback port on the device host that the local egress client must serve
+   * through the tunnel. Null when the session does not use local egress.
+   */
+  egressPort?: Maybe<Scalars['Int']['output']>;
+  /**
+   * Secret the local egress client presents to the reverse-tunnel endpoint. Null
+   * when the session does not use local egress.
+   */
+  egressToken?: Maybe<Scalars['String']['output']>;
+  /**
+   * Reverse-tunnel endpoint the local egress client connects to. Null when the
+   * session does not use local egress.
+   */
+  egressUrl?: Maybe<Scalars['String']['output']>;
  /** Session token gating the web preview. Null when the preview runs ungated. */
  webPreviewToken?: Maybe<Scalars['String']['output']>;
  webPreviewUrl: Scalars['String']['output'];
@@ -16178,11 +16300,11 @@ export type DeviceRunSessionByIdQueryVariables = Exact<{


 export type DeviceRunSessionByIdQuery = { __typename?: 'RootQuery', deviceRunSessions: { __typename?: 'DeviceRunSessionQuery', byId: { __typename?: 'DeviceRunSession', id: string, name?: string | null, tags: Array<string>, status: DeviceRunSessionStatus, type: DeviceRunSessionType, platform: AppPlatform, createdAt: any, startedAt?: any | null, finishedAt?: any | null, updatedAt: any, app: { __typename?: 'App', id: string, slug: string, ownerAccount: { __typename?: 'Account', id: string, name: string } }, artifacts: Array<{ __typename?: 'DeviceRunSessionArtifact', id: string, name: string, filename: string, downloadUrl: string, fileSizeBytes?: number | null, metadata?: any | null, createdAt: any, updatedAt: any }>, remoteConfig?:
-        | { __typename: 'AgentDeviceRunSessionRemoteConfig', agentDeviceRemoteSessionUrl: string, agentDeviceRemoteSessionToken: string, webPreviewUrl?: string | null, webPreviewToken?: string | null }
-        | { __typename: 'AppiumRunSessionRemoteConfig', appiumUrl: string, capabilities: any, webPreviewUrl?: string | null, webPreviewToken?: string | null }
-        | { __typename: 'ArgentRunSessionRemoteConfig', toolsUrl: string, toolsAuthToken?: string | null, webPreviewUrl?: string | null, webPreviewToken?: string | null }
-        | { __typename: 'ServeSimRunSessionRemoteConfig', previewUrl: string, previewToken?: string | null }
-        | { __typename: 'WebPreviewOnlyRunSessionRemoteConfig', previewUrl: string, previewToken?: string | null }
+        | { __typename: 'AgentDeviceRunSessionRemoteConfig', agentDeviceRemoteSessionUrl: string, agentDeviceRemoteSessionToken: string, webPreviewUrl?: string | null, webPreviewToken?: string | null, egressUrl?: string | null, egressToken?: string | null, egressFingerprint?: string | null, egressPort?: number | null }
+        | { __typename: 'AppiumRunSessionRemoteConfig', egressUrl?: string | null, egressToken?: string | null, egressFingerprint?: string | null, egressPort?: number | null, appiumUrl: string, capabilities: any, webPreviewUrl?: string | null, webPreviewToken?: string | null }
+        | { __typename: 'ArgentRunSessionRemoteConfig', egressUrl?: string | null, egressToken?: string | null, egressFingerprint?: string | null, egressPort?: number | null, toolsUrl: string, toolsAuthToken?: string | null, webPreviewUrl?: string | null, webPreviewToken?: string | null }
+        | { __typename: 'ServeSimRunSessionRemoteConfig', egressUrl?: string | null, egressToken?: string | null, egressFingerprint?: string | null, egressPort?: number | null, previewUrl: string, previewToken?: string | null }
+        | { __typename: 'WebPreviewOnlyRunSessionRemoteConfig', egressUrl?: string | null, egressToken?: string | null, egressFingerprint?: string | null, egressPort?: number | null, previewUrl: string, previewToken?: string | null }
       | null, turtleJobRun?: { __typename?: 'JobRun', id: string, status: JobRunStatus } | null } } };

 export type DeviceRunSessionsByAppIdQueryVariables = Exact<{
@@ -88,24 +88,44 @@ export const DeviceRunSessionQuery = {
                      agentDeviceRemoteSessionToken
                      webPreviewUrl
                      webPreviewToken
+                      egressUrl
+                      egressToken
+                      egressFingerprint
+                      egressPort
                    }
                    ... on ArgentRunSessionRemoteConfig {
+                      egressUrl
+                      egressToken
+                      egressFingerprint
+                      egressPort
                      toolsUrl
                      toolsAuthToken
                      webPreviewUrl
                      webPreviewToken
                    }
                    ... on AppiumRunSessionRemoteConfig {
+                      egressUrl
+                      egressToken
+                      egressFingerprint
+                      egressPort
                      appiumUrl
                      capabilities
                      webPreviewUrl
                      webPreviewToken
                    }
                    ... on ServeSimRunSessionRemoteConfig {
+                      egressUrl
+                      egressToken
+                      egressFingerprint
+                      egressPort
                      previewUrl
                      previewToken
                    }
                    ... on WebPreviewOnlyRunSessionRemoteConfig {
+                      egressUrl
+                      egressToken
+                      egressFingerprint
+                      egressPort
                      previewUrl: webPreviewUrl
                      previewToken: webPreviewToken
                    }
@@ -0,0 +1,938 @@
+import spawnAsync from '@expo/spawn-async';
+import * as fs from 'fs-extra';
+import { ChildProcess } from 'node:child_process';
+import dns from 'node:dns/promises';
+import { once } from 'node:events';
+import http from 'node:http';
+import net from 'node:net';
+
+import {
+  EgressPolicyError,
+  buildChiselClientArgs,
+  classifyChiselClientLogLine,
+  createEgressTargetResolver,
+  getChiselAssetName,
+  isChiselRemoteRejectionLine,
+  isForbiddenEgressAddress,
+  orderEgressAddresses,
+  parseEgressAllowList,
+  readLocalEgressConfigFromEnv,
+  resolveEgressTargetAsync,
+  runLocalEgressAsync,
+  startLocalEgressProxyServerAsync,
+} from '../egress';
+import Log from '../../log';
+
+jest.mock('../../log');
+jest.mock('@expo/spawn-async');
+jest.mock('fs-extra', () => ({
+  ...jest.requireActual('fs-extra'),
+  pathExists: jest.fn(),
+}));
+
+async function waitForAsync(predicate: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (!predicate()) {
+    if (Date.now() > deadline) {
+      throw new Error('Timed out waiting for socket cleanup.');
+    }
+    await new Promise(resolve => setTimeout(resolve, 5));
+  }
+}
+
+describe(isForbiddenEgressAddress, () => {
+  it.each([
+    '127.0.0.1',
+    '127.255.255.254',
+    '10.0.0.5',
+    '172.16.0.1',
+    '172.31.255.255',
+    '192.168.1.20',
+    '169.254.169.254',
+    '100.64.0.1',
+    '0.0.0.0',
+    '224.0.0.1',
+    '255.255.255.255',
+    '::1',
+    '::',
+    'fe80::1',
+    'fd12:3456::1',
+    'fc00::1',
+    'ff02::1',
+    '::ffff:127.0.0.1',
+    '::ffff:192.168.0.10',
+    '::ffff:c0a8:a',
+    'not-an-ip',
+  ])('forbids %s', address => {
+    expect(isForbiddenEgressAddress(address)).toBe(true);
+  });
+
+  it.each([
+    '8.8.8.8',
+    '1.1.1.1',
+    '172.15.0.1',
+    '172.32.0.1',
+    '100.63.0.1',
+    '100.128.0.1',
+    '2606:4700:4700::1111',
+    '2001:db8::1',
+    '::ffff:8.8.8.8',
+  ])('allows %s', address => {
+    expect(isForbiddenEgressAddress(address)).toBe(false);
+  });
+});
+
+describe(resolveEgressTargetAsync, () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it.each(['localhost', 'LOCALHOST', 'api.localhost', 'printer.local', '127.0.0.1', '[::1]'])(
+    'refuses %s without resolving it',
+    async host => {
+      await expect(resolveEgressTargetAsync(host, 443)).rejects.toBeInstanceOf(EgressPolicyError);
+    }
+  );
+
+  it('returns a public IP literal unchanged', async () => {
+    await expect(resolveEgressTargetAsync('1.1.1.1', 443)).resolves.toEqual(['1.1.1.1']);
+  });
+
+  it('refuses a DNS name if any record is private', async () => {
+    const lookup = jest.spyOn(dns, 'lookup').mockResolvedValue([
+      { address: '1.1.1.1', family: 4 },
+      { address: '192.168.1.10', family: 4 },
+    ] as never);
+    await expect(resolveEgressTargetAsync('mixed.example', 443)).rejects.toBeInstanceOf(
+      EgressPolicyError
+    );
+    expect(lookup).toHaveBeenCalledTimes(1);
+    expect(lookup).toHaveBeenCalledWith('mixed.example', { all: true, verbatim: true });
+  });
+});
+
+describe(orderEgressAddresses, () => {
+  it('puts IPv4 addresses first and drops duplicates', () => {
+    expect(
+      orderEgressAddresses([
+        { address: '2600:1f13::1', family: 6 },
+        { address: '34.223.124.45', family: 4 },
+        { address: '34.223.124.45', family: 4 },
+        { address: '2600:1f13::2', family: 6 },
+      ])
+    ).toEqual(['34.223.124.45', '2600:1f13::1', '2600:1f13::2']);
+  });
+});
+
+describe(buildChiselClientArgs, () => {
+  it('pins the server key, reconnects forever, and reverse-forwards the loopback proxy port', () => {
+    expect(
+      buildChiselClientArgs({
+        url: 'https://egress-abc.eas-simulator.ngrok.dev',
+        fingerprint: 'fp=',
+        port: 8899,
+      })
+    ).toEqual([
+      'client',
+      '--fingerprint',
+      'fp=',
+      '--keepalive',
+      '25s',
+      '--max-retry-count',
+      '-1',
+      'https://egress-abc.eas-simulator.ngrok.dev',
+      'R:127.0.0.1:8899:127.0.0.1:8899',
+    ]);
+  });
+
+  it('adds one loopback reverse remote per forwarded port after the proxy remote', () => {
+    expect(
+      buildChiselClientArgs({
+        url: 'https://egress-abc.eas-simulator.ngrok.dev',
+        fingerprint: 'fp=',
+        port: 8899,
+        localPort: 51000,
+        forwardPorts: [3000, 8082],
+      }).slice(-3)
+    ).toEqual([
+      'R:127.0.0.1:8899:127.0.0.1:51000',
+      'R:127.0.0.1:3000:127.0.0.1:3000',
+      'R:127.0.0.1:8082:127.0.0.1:8082',
+    ]);
+  });
+});
+
+describe(isChiselRemoteRejectionLine, () => {
+  it('recognizes denied and unbindable reverse remotes', () => {
+    expect(
+      isChiselRemoteRejectionLine("2026/09/10 client: access to 'R:127.0.0.1:8082' denied")
+    ).toBe(true);
+    expect(
+      isChiselRemoteRejectionLine(
+        '2026/09/10 client: Connection error: listen tcp 127.0.0.1:8082: bind: address already in use'
+      )
+    ).toBe(true);
+    expect(isChiselRemoteRejectionLine('2026/09/10 client: Connected (Latency 41ms)')).toBe(false);
+    expect(
+      isChiselRemoteRejectionLine('2026/09/10 client: Connection error: websocket: bad handshake')
+    ).toBe(false);
+  });
+});
+
+describe(classifyChiselClientLogLine, () => {
+  it('recognizes chisel connection state lines', () => {
+    expect(classifyChiselClientLogLine('2026/09/07 client: Connected (Latency 41ms)')).toBe(
+      'connected'
+    );
+    expect(classifyChiselClientLogLine('2026/09/07 client: Disconnected')).toBe('disconnected');
+    expect(classifyChiselClientLogLine('2026/09/07 client: Retrying in 1s...')).toBe(
+      'disconnected'
+    );
+    expect(classifyChiselClientLogLine('2026/09/07 client: Fingerprint fp=')).toBe('other');
+  });
+});
+
+describe(getChiselAssetName, () => {
+  it('maps supported platforms and rejects the rest', () => {
+    expect(getChiselAssetName({ platform: 'darwin', arch: 'arm64' })).toBe(
+      'chisel_1.12.0_darwin_arm64.gz'
+    );
+    expect(getChiselAssetName({ platform: 'linux', arch: 'x64' })).toBe(
+      'chisel_1.12.0_linux_amd64.gz'
+    );
+    expect(() => getChiselAssetName({ platform: 'win32', arch: 'x64' })).toThrow(
+      'not supported on win32/x64'
+    );
+  });
+});
+
+describe(readLocalEgressConfigFromEnv, () => {
+  it('reads the four egress variables', () => {
+    expect(
+      readLocalEgressConfigFromEnv({
+        EAS_SIMULATOR_EGRESS_URL: 'https://egress-abc.eas-simulator.ngrok.dev',
+        EAS_SIMULATOR_EGRESS_TOKEN: 'pw',
+        EAS_SIMULATOR_EGRESS_FINGERPRINT: 'fp=',
+        EAS_SIMULATOR_EGRESS_PORT: '8899',
+      })
+    ).toEqual({
+      url: 'https://egress-abc.eas-simulator.ngrok.dev',
+      token: 'pw',
+      fingerprint: 'fp=',
+      port: 8899,
+      allow: [],
+    });
+  });
+
+  it('reads the allowed local destinations written by --egress-allow', () => {
+    expect(
+      readLocalEgressConfigFromEnv({
+        EAS_SIMULATOR_EGRESS_URL: 'https://egress-abc.eas-simulator.ngrok.dev',
+        EAS_SIMULATOR_EGRESS_TOKEN: 'pw',
+        EAS_SIMULATOR_EGRESS_FINGERPRINT: 'fp=',
+        EAS_SIMULATOR_EGRESS_PORT: '8899',
+        EAS_SIMULATOR_EGRESS_ALLOW: 'localhost:3000, 192.168.1.20:8080',
+      }).allow
+    ).toEqual(['localhost:3000', '192.168.1.20:8080']);
+  });
+
+  it('explains how to start a session with egress when the variables are missing', () => {
+    expect(() => readLocalEgressConfigFromEnv({ EAS_SIMULATOR_SESSION_ID: 'abc' })).toThrow(
+      'was not started with local egress'
+    );
+  });
+});
+
+describe(parseEgressAllowList, () => {
+  it('normalizes exact host and port pairs and drops duplicates', () => {
+    expect(
+      parseEgressAllowList([
+        'localhost:3000',
+        ' LOCALHOST:3000 ',
+        '192.168.1.20:8080',
+        '[::1]:3000',
+        '[0:0:0:0:0:0:0:1]:3000',
+        'dev-box.lan:443',
+      ])
+    ).toEqual(['localhost:3000', '192.168.1.20:8080', '[::1]:3000', 'dev-box.lan:443']);
+  });
+
+  it.each([
+    'localhost',
+    'localhost:0',
+    'localhost:70000',
+    '*.test:80',
+    '10.0.0.0/8:80',
+    'http://localhost:3000',
+    '[not-an-ip]:3000',
+    ':3000',
+    ',localhost:3000',
+    'localhost,:3000',
+    'user@localhost:3000',
+    'localhost#ignored:3000',
+    'localhost?ignored:3000',
+    "local'host:3000",
+    'local\\host:3000',
+  ])('rejects %s', entry => {
+    expect(() => parseEgressAllowList([entry])).toThrow('Invalid --egress-allow value');
+  });
+
+  it('normalizes IDN hostnames containing combining marks', () => {
+    expect(parseEgressAllowList(['cafe\u0301.example:3000'])).toEqual(['xn--caf-dma.example:3000']);
+  });
+});
+
+describe(createEgressTargetResolver, () => {
+  it.each([
+    ['[0:0:0:0:0:0:0:1]:3000', '[::1]', '::1'],
+    ['127.1:3000', '127.0.0.1', '127.0.0.1'],
+    ['[::ffff:127.0.0.1]:3000', '[::ffff:7f00:1]', '::ffff:7f00:1'],
+  ])('matches %s after HTTP URL normalization', async (entry, hostname, address) => {
+    const resolve = createEgressTargetResolver({ allow: parseEgressAllowList([entry]) });
+    await expect(resolve(hostname, 3000)).resolves.toEqual([address]);
+    await expect(resolve(hostname, 3001)).rejects.toBeInstanceOf(EgressPolicyError);
+    await expect(resolve('localhost', 3000)).rejects.toBeInstanceOf(EgressPolicyError);
+  });
+
+  it('returns the default policy when nothing is allowed', () => {
+    expect(createEgressTargetResolver({ allow: [] })).toBe(resolveEgressTargetAsync);
+  });
+
+  it('maps an allowed localhost destination to loopback and reports it', async () => {
+    const allowed: string[] = [];
+    const resolve = createEgressTargetResolver({
+      allow: ['localhost:3000', '192.168.1.20:8080'],
+      onAllowed: destination => allowed.push(destination),
+    });
+    await expect(resolve('LocalHost', 3000)).resolves.toEqual(['127.0.0.1', '::1']);
+    await expect(resolve('192.168.1.20', 8080)).resolves.toEqual(['192.168.1.20']);
+    expect(allowed).toEqual(['localhost:3000', '192.168.1.20:8080']);
+  });
+
+  it('keeps refusing the same host on other ports and unlisted private addresses', async () => {
+    const resolve = createEgressTargetResolver({ allow: ['localhost:3000'] });
+    await expect(resolve('localhost', 3001)).rejects.toBeInstanceOf(EgressPolicyError);
+    await expect(resolve('127.0.0.1', 3000)).rejects.toBeInstanceOf(EgressPolicyError);
+    await expect(resolve('192.168.1.20', 8080)).rejects.toBeInstanceOf(EgressPolicyError);
+    await expect(resolve('93.184.216.34', 443)).resolves.toEqual(['93.184.216.34']);
+  });
+});
+
+describe(startLocalEgressProxyServerAsync, () => {
+  // The default resolver refuses loopback, so tests inject one that maps a fake
+  // public name to the local test servers.
+  let targetHttpServer: http.Server;
+  let targetHttpPort: number;
+  let targetEchoServer: net.Server;
+  let targetEchoPort: number;
+  let proxy: Awaited<ReturnType<typeof startLocalEgressProxyServerAsync>>;
+  const seenHostHeaders: string[] = [];
+
+  beforeAll(async () => {
+    targetHttpServer = http.createServer((req, res) => {
+      seenHostHeaders.push(req.headers.host ?? '');
+      if (req.url === '/truncate') {
+        // Announce a body, send part of it, then drop the connection.
+        res.writeHead(200, { 'content-type': 'text/plain', 'content-length': '100' });
+        res.write('partial');
+        res.socket?.destroy();
+        return;
+      }
+      res.writeHead(200, { 'content-type': 'text/plain' });
+      res.end(`hello from ${req.method} ${req.url}`);
+    });
+    await new Promise<void>(resolve => targetHttpServer.listen(0, '127.0.0.1', resolve));
+    targetHttpPort = (targetHttpServer.address() as net.AddressInfo).port;
+
+    targetEchoServer = net.createServer(socket => socket.pipe(socket));
+    await new Promise<void>(resolve => targetEchoServer.listen(0, '127.0.0.1', resolve));
+    targetEchoPort = (targetEchoServer.address() as net.AddressInfo).port;
+
+    proxy = await startLocalEgressProxyServerAsync({
+      port: 0,
+      resolveTargetAsync: async hostname => {
+        if (hostname === 'target.test') {
+          // The test servers listen on IPv4 loopback only, so the IPv6 loopback
+          // attempt is refused immediately and proves the fallback to the next address.
+          return ['::1', '127.0.0.1'];
+        }
+        throw new EgressPolicyError(hostname);
+      },
+    });
+  });
+
+  afterAll(async () => {
+    await proxy.closeAsync();
+    await new Promise<void>(resolve => {
+      targetHttpServer.close(() => {
+        resolve();
+      });
+    });
+    await new Promise<void>(resolve => {
+      targetEchoServer.close(() => {
+        resolve();
+      });
+    });
+  });
+
+  function rawRequestAsync(request: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const socket = net.connect({ host: '127.0.0.1', port: proxy.port });
+      let response = '';
+      socket.on('data', chunk => (response += chunk.toString()));
+      socket.on('end', () => {
+        resolve(response);
+      });
+      socket.on('error', reject);
+      socket.on('connect', () => socket.write(request));
+    });
+  }
+
+  it('uses the absolute URL authority instead of an inconsistent Host header', async () => {
+    const response = await rawRequestAsync(
+      `GET http://target.test:${targetHttpPort}/path?q=1 HTTP/1.1\r\nHost: wrong.test\r\nProxy-Connection: keep-alive\r\nConnection: close\r\n\r\n`
+    );
+    expect(response).toContain('HTTP/1.1 200');
+    expect(response).toContain('hello from GET /path?q=1');
+    expect(seenHostHeaders).toContain(`target.test:${targetHttpPort}`);
+  });
+
+  it('does not log a completed response as failed when its operation is released', async () => {
+    jest.mocked(Log.debug).mockClear();
+    const response = await rawRequestAsync(
+      `GET http://target.test:${targetHttpPort}/done HTTP/1.1\r\nHost: target.test\r\nConnection: close\r\n\r\n`
+    );
+    expect(response).toContain('hello from GET /done');
+    // Releasing the operation aborts the shared signal after the socket closes.
+    await new Promise(resolve => setTimeout(resolve, 20));
+    const messages = jest.mocked(Log.debug).mock.calls.map(([message]) => String(message));
+    expect(messages).toContain(`[egress] GET target.test:${targetHttpPort}`);
+    expect(messages.filter(message => message.includes('failed:'))).toEqual([]);
+  });
+
+  it('still logs an upstream response that is cut short as failed', async () => {
+    jest.mocked(Log.debug).mockClear();
+    const response = await rawRequestAsync(
+      `GET http://target.test:${targetHttpPort}/truncate HTTP/1.1\r\nHost: target.test\r\nConnection: close\r\n\r\n`
+    );
+    // Depending on timing the client sees a 502 or a truncated 200; never a complete body.
+    expect(response).not.toContain('hello from');
+    await new Promise(resolve => setTimeout(resolve, 20));
+    const messages = jest.mocked(Log.debug).mock.calls.map(([message]) => String(message));
+    expect(messages.some(message => message.includes('failed:'))).toBe(true);
+  });
+
+  it('tunnels CONNECT requests to the resolved address', async () => {
+    const response = await new Promise<string>((resolve, reject) => {
+      const socket = net.connect({ host: '127.0.0.1', port: proxy.port });
+      let buffer = '';
+      socket.on('error', reject);
+      socket.on('connect', () =>
+        socket.write(`CONNECT target.test:${targetEchoPort} HTTP/1.1\r\nHost: target.test\r\n\r\n`)
+      );
+      socket.on('data', chunk => {
+        buffer += chunk.toString();
+        if (buffer.includes('200 Connection Established') && !buffer.includes('ping')) {
+          socket.write('ping');
+        } else if (buffer.includes('ping')) {
+          socket.end();
+          resolve(buffer);
+        }
+      });
+    });
+    expect(response).toContain('HTTP/1.1 200 Connection Established');
+    expect(response.endsWith('ping')).toBe(true);
+    expect(proxy.getStats().total).toBeGreaterThanOrEqual(2);
+  });
+
+  it('refuses destinations the policy rejects with 403', async () => {
+    const connectResponse = await rawRequestAsync(
+      'CONNECT internal.example:443 HTTP/1.1\r\nHost: internal.example\r\n\r\n'
+    );
+    expect(connectResponse).toContain('HTTP/1.1 403');
+
+    const httpResponse = await rawRequestAsync(
+      'GET http://internal.example/ HTTP/1.1\r\nHost: internal.example\r\nConnection: close\r\n\r\n'
+    );
+    expect(httpResponse).toContain('HTTP/1.1 403');
+  });
+
+  it('reaches an allowed local destination and keeps refusing the rest', async () => {
+    const allowedProxy = await startLocalEgressProxyServerAsync({
+      port: 0,
+      resolveTargetAsync: createEgressTargetResolver({ allow: [`localhost:${targetHttpPort}`] }),
+    });
+    const requestAsync = (request: string): Promise<string> =>
+      new Promise((resolve, reject) => {
+        const socket = net.connect({ host: '127.0.0.1', port: allowedProxy.port });
+        let response = '';
+        socket.on('data', chunk => (response += chunk.toString()));
+        socket.on('end', () => {
+          resolve(response);
+        });
+        socket.on('error', reject);
+        socket.on('connect', () => socket.write(request));
+      });
+    try {
+      const allowedResponse = await requestAsync(
+        `GET http://localhost:${targetHttpPort}/allowed HTTP/1.1\r\nHost: localhost:${targetHttpPort}\r\nConnection: close\r\n\r\n`
+      );
+      expect(allowedResponse).toContain('HTTP/1.1 200');
+      expect(allowedResponse).toContain('hello from GET /allowed');
+
+      const otherPortResponse = await requestAsync(
+        `CONNECT localhost:${targetEchoPort} HTTP/1.1\r\nHost: localhost\r\n\r\n`
+      );
+      expect(otherPortResponse).toContain('HTTP/1.1 403');
+
+      const ipResponse = await requestAsync(
+        `GET http://127.0.0.1:${targetHttpPort}/ HTTP/1.1\r\nHost: 127.0.0.1\r\nConnection: close\r\n\r\n`
+      );
+      expect(ipResponse).toContain('HTTP/1.1 403');
+    } finally {
+      await allowedProxy.closeAsync();
+    }
+  });
+
+  it('rejects requests without an absolute URL', async () => {
+    const response = await rawRequestAsync(
+      'GET /relative HTTP/1.1\r\nHost: target.test\r\nConnection: close\r\n\r\n'
+    );
+    expect(response).toContain('HTTP/1.1 400');
+  });
+
+  it.each(['GET', 'CONNECT', 'upgrade'])(
+    'releases a disconnected %s client before DNS completes and never connects afterward',
+    async method => {
+      let resolveDns!: (addresses: string[]) => void;
+      let enteredDns!: () => void;
+      const started = new Promise<void>(resolve => (enteredDns = resolve));
+      const deferredProxy = await startLocalEgressProxyServerAsync({
+        port: 0,
+        resolveTargetAsync: () => {
+          enteredDns();
+          return new Promise(resolve => (resolveDns = resolve));
+        },
+      });
+      const connection = jest.fn();
+      targetHttpServer.on('connection', connection);
+      const client = net.connect(deferredProxy.port, '127.0.0.1');
+      try {
+        const target = `target.test:${targetHttpPort}`;
+        client.write(
+          method === 'CONNECT'
+            ? `CONNECT ${target} HTTP/1.1\r\nHost: ${target}\r\n\r\n`
+            : `GET http://${target}/ HTTP/1.1\r\nHost: ${target}\r\n${method === 'upgrade' ? 'Connection: Upgrade\r\nUpgrade: websocket\r\n' : ''}\r\n`
+        );
+        await started;
+        client.destroy();
+        await waitForAsync(() => deferredProxy.getStats().active === 0);
+        resolveDns(['127.0.0.1']);
+        await new Promise(resolve => setTimeout(resolve, 20));
+        expect(connection).not.toHaveBeenCalled();
+      } finally {
+        client.destroy();
+        targetHttpServer.removeListener('connection', connection);
+        await deferredProxy.closeAsync();
+      }
+    }
+  );
+
+  it('closes established CONNECT sockets without waiting for idle timeout', async () => {
+    const tunnelProxy = await startLocalEgressProxyServerAsync({
+      port: 0,
+      resolveTargetAsync: async () => ['127.0.0.1'],
+    });
+    const client = net.connect(tunnelProxy.port, '127.0.0.1');
+    const reply = once(client, 'data');
+    client.write(`CONNECT target.test:${targetEchoPort} HTTP/1.1\r\nHost: target.test\r\n\r\n`);
+    await reply;
+    const closed = once(client, 'close');
+    await tunnelProxy.closeAsync();
+    await closed;
+    expect(tunnelProxy.getStats().active).toBe(0);
+    await tunnelProxy.closeAsync();
+  });
+
+  it('reframes chunked requests/responses and removes connection-nominated fields on keep-alive', async () => {
+    const received: { headers: http.IncomingHttpHeaders; body: string }[] = [];
+    const target = http.createServer((req, res) => {
+      let body = '';
+      req.on('data', chunk => (body += chunk));
+      req.on('end', () => {
+        received.push({ headers: req.headers, body });
+        res.writeHead(200, {
+          Connection: 'keep-alive, X-Response-Hop',
+          'X-Response-Hop': 'remove-me',
+          'Set-Cookie': ['a=1', 'b=2'],
+        });
+        res.write('response-');
+        res.end(body);
+      });
+    });
+    await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+    const targetPort = (target.address() as net.AddressInfo).port;
+    const agent = new http.Agent({ keepAlive: true });
+    try {
+      for (let i = 0; i < 2; i++) {
+        const result = await new Promise<{ body: string; headers: http.IncomingHttpHeaders }>(
+          (resolve, reject) => {
+            const req = http.request(
+              {
+                host: '127.0.0.1',
+                port: proxy.port,
+                agent,
+                method: 'POST',
+                path: `http://target.test:${targetPort}/`,
+                headers: {
+                  Host: 'wrong.test',
+                  Connection: 'keep-alive, X-Request-Hop',
+                  'X-Request-Hop': 'remove-me',
+                  TE: 'trailers',
+                },
+              },
+              res => {
+                let body = '';
+                res.on('data', chunk => (body += chunk));
+                res.on('error', reject);
+                res.on('end', () => {
+                  resolve({ body, headers: res.headers });
+                });
+              }
+            );
+            req.on('error', reject);
+            req.write('chunk-');
+            req.end(String(i));
+          }
+        );
+        expect(result.body).toBe(`response-chunk-${i}`);
+        expect(result.headers['x-response-hop']).toBeUndefined();
+        expect(result.headers['set-cookie']).toEqual(['a=1', 'b=2']);
+      }
+      expect(received.map(({ body }) => body)).toEqual(['chunk-0', 'chunk-1']);
+      for (const { headers } of received) {
+        expect(headers.host).toBe(`target.test:${targetPort}`);
+        expect(headers['x-request-hop']).toBeUndefined();
+        expect(headers.te).toBeUndefined();
+      }
+    } finally {
+      agent.destroy();
+      target.closeAllConnections();
+      await new Promise<void>(resolve =>
+        target.close(() => {
+          resolve();
+        })
+      );
+    }
+  });
+
+  it.each([
+    ['GET', 'Transfer-Encoding: chunked\r\nConnection: close', '4\r\ntest\r\n0\r\n\r\n'],
+    ['DELETE', 'Transfer-Encoding: chunked\r\nConnection: close', '4\r\ntest\r\n0\r\n\r\n'],
+    ['GET', 'Content-Length: 4\r\nConnection: close, Content-Length', 'test'],
+  ])('preserves a raw %s body after rebuilding its framing (%s)', async (method, framing, body) => {
+    const received: { body: string; headers: http.IncomingHttpHeaders }[] = [];
+    const target = http.createServer((req, res) => {
+      let body = '';
+      req.on('data', chunk => (body += chunk));
+      req.on('end', () => {
+        received.push({ body, headers: req.headers });
+        res.end(`received:${body}`);
+      });
+    });
+    await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+    try {
+      const targetPort = (target.address() as net.AddressInfo).port;
+      const response = await rawRequestAsync(
+        `${method} http://target.test:${targetPort}/ HTTP/1.1\r\nHost: target.test\r\n${framing}\r\n\r\n${body}`
+      );
+      expect(response).toContain('HTTP/1.1 200');
+      expect(response).toContain('received:test');
+      expect(received).toHaveLength(1);
+      expect(received[0].body).toBe('test');
+      expect(received[0].headers['transfer-encoding']).toBe('chunked');
+    } finally {
+      target.closeAllConnections();
+      await new Promise<void>(resolve => {
+        target.close(() => {
+          resolve();
+        });
+      });
+    }
+  });
+
+  it('rejects transfer-coding chains it cannot decode without connecting upstream', async () => {
+    const connection = jest.fn();
+    targetHttpServer.on('connection', connection);
+    try {
+      const response = await rawRequestAsync(
+        `GET http://target.test:${targetHttpPort}/ HTTP/1.1\r\nHost: target.test\r\nTransfer-Encoding: gzip, chunked\r\nConnection: close\r\n\r\n4\r\ntest\r\n0\r\n\r\n`
+      );
+      expect(response).toContain('HTTP/1.1 501');
+      expect(connection).not.toHaveBeenCalled();
+    } finally {
+      targetHttpServer.removeListener('connection', connection);
+    }
+  });
+
+  it('rejects upstream transfer-coding chains instead of forwarding undecoded bytes', async () => {
+    const target = net.createServer(socket => {
+      socket.once('data', () => {
+        socket.end(
+          'HTTP/1.1 200 OK\r\nTransfer-Encoding: gzip, chunked\r\n\r\n4\r\ntest\r\n0\r\n\r\n'
+        );
+      });
+    });
+    await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+    try {
+      const targetPort = (target.address() as net.AddressInfo).port;
+      const response = await rawRequestAsync(
+        `GET http://target.test:${targetPort}/ HTTP/1.1\r\nHost: target.test\r\nConnection: close\r\n\r\n`
+      );
+      expect(response).toContain('HTTP/1.1 502');
+      expect(response).not.toContain('test');
+    } finally {
+      await new Promise<void>(resolve => {
+        target.close(() => {
+          resolve();
+        });
+      });
+    }
+  });
+
+  it('closes a truncated upstream response and releases its operation', async () => {
+    const target = net.createServer(socket => {
+      socket.once('data', () =>
+        socket.end('HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\npartial')
+      );
+    });
+    await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+    try {
+      const targetPort = (target.address() as net.AddressInfo).port;
+      const response = await rawRequestAsync(
+        `GET http://target.test:${targetPort}/ HTTP/1.1\r\nHost: target.test\r\nConnection: close\r\n\r\n`
+      );
+      expect(response).toContain('Content-Length: 100');
+      expect(response).toContain('partial');
+      await waitForAsync(() => proxy.getStats().active === 0);
+    } finally {
+      await new Promise<void>(resolve =>
+        target.close(() => {
+          resolve();
+        })
+      );
+    }
+  });
+
+  it('destroys an in-flight upstream response when the downstream client disconnects', async () => {
+    let upstreamClosed = false;
+    const target = http.createServer((req, res) => {
+      req.socket.once('close', () => (upstreamClosed = true));
+      res.writeHead(200);
+      res.write('partial');
+    });
+    await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+    const targetPort = (target.address() as net.AddressInfo).port;
+    const client = net.connect(proxy.port, '127.0.0.1');
+    try {
+      const reply = once(client, 'data');
+      client.write(`GET http://target.test:${targetPort}/ HTTP/1.1\r\nHost: target.test\r\n\r\n`);
+      await reply;
+      client.destroy();
+      await waitForAsync(() => upstreamClosed && proxy.getStats().active === 0);
+    } finally {
+      client.destroy();
+      target.closeAllConnections();
+      await new Promise<void>(resolve =>
+        target.close(() => {
+          resolve();
+        })
+      );
+    }
+  });
+
+  it('closes promptly while DNS is pending and does not connect after the late answer', async () => {
+    let resolveDns!: (addresses: string[]) => void;
+    const deferredProxy = await startLocalEgressProxyServerAsync({
+      port: 0,
+      resolveTargetAsync: () => new Promise(resolve => (resolveDns = resolve)),
+    });
+    const client = net.connect(deferredProxy.port, '127.0.0.1');
+    client.write(`CONNECT target.test:${targetEchoPort} HTTP/1.1\r\nHost: target.test\r\n\r\n`);
+    await waitForAsync(() => resolveDns !== undefined);
+    const closed = once(client, 'close');
+    await deferredProxy.closeAsync();
+    await closed;
+    expect(deferredProxy.getStats().active).toBe(0);
+    resolveDns(['127.0.0.1']);
+    await new Promise(resolve => setImmediate(resolve));
+    expect(deferredProxy.getStats().active).toBe(0);
+  });
+
+  it('filters both upgrade handshakes and closes upgraded sockets during shutdown', async () => {
+    let seenHeaders: http.IncomingHttpHeaders | undefined;
+    const target = http.createServer();
+    target.on('upgrade', (req, socket) => {
+      seenHeaders = req.headers;
+      socket.write(
+        'HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade, X-Response-Hop\r\nUpgrade: websocket\r\nX-Response-Hop: remove-me\r\n\r\n'
+      );
+      socket.pipe(socket);
+    });
+    await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+    const targetPort = (target.address() as net.AddressInfo).port;
+    const tunnelProxy = await startLocalEgressProxyServerAsync({
+      port: 0,
+      resolveTargetAsync: async () => ['127.0.0.1'],
+    });
+    const client = net.connect(tunnelProxy.port, '127.0.0.1');
+    try {
+      const reply = once(client, 'data');
+      client.write(
+        `GET http://target.test:${targetPort}/ HTTP/1.1\r\nHost: wrong.test\r\nConnection: Upgrade, X-Request-Hop\r\nUpgrade: websocket\r\nX-Request-Hop: remove-me\r\n\r\n`
+      );
+      const [handshake] = await reply;
+      expect(handshake.toString()).toContain('101 Switching Protocols');
+      expect(handshake.toString()).not.toContain('X-Response-Hop');
+      expect(seenHeaders?.host).toBe(`target.test:${targetPort}`);
+      expect(seenHeaders?.['x-request-hop']).toBeUndefined();
+      const echo = once(client, 'data');
+      client.write('ping');
+      expect((await echo)[0].toString()).toBe('ping');
+      const closed = once(client, 'close');
+      await tunnelProxy.closeAsync();
+      await closed;
+      expect(tunnelProxy.getStats().active).toBe(0);
+    } finally {
+      client.destroy();
+      await tunnelProxy.closeAsync();
+      await new Promise<void>(resolve =>
+        target.close(() => {
+          resolve();
+        })
+      );
+    }
+  });
+});
+
+describe(runLocalEgressAsync, () => {
+  afterEach(() => {
+    jest.mocked(spawnAsync).mockReset();
+    jest.mocked(fs.pathExists).mockReset();
+  });
+  it('does not spawn a child when interrupted during the binary cache lookup', async () => {
+    let completeLookup!: (exists: boolean) => void;
+    const exists = jest
+      .mocked(fs.pathExists)
+      .mockImplementation(() => new Promise<boolean>(resolve => (completeLookup = resolve)));
+    const controller = new AbortController();
+    try {
+      const running = runLocalEgressAsync({
+        url: 'https://example.test',
+        token: 'pw',
+        fingerprint: 'fp',
+        port: 8899,
+        signal: controller.signal,
+      });
+      controller.abort();
+      completeLookup(true);
+      await running;
+      expect(spawnAsync).not.toHaveBeenCalled();
+    } finally {
+      exists.mockReset();
+    }
+  });
+
+  it('opens a loopback reverse remote for each forwarded --egress-allow port', async () => {
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    let child: ChildProcess | undefined;
+    jest.mocked(spawnAsync).mockImplementation(() => {
+      child = new ChildProcess();
+      const promise = new Promise<never>((_resolve, reject) => {
+        child!.kill = jest.fn(signal => {
+          Object.defineProperty(child, 'signalCode', { value: signal, configurable: true });
+          reject(new Error('terminated'));
+          return true;
+        });
+      });
+      return Object.assign(promise, { child });
+    });
+    const controller = new AbortController();
+    const running = runLocalEgressAsync({
+      url: 'https://example.test',
+      token: 'pw',
+      fingerprint: 'fp',
+      port: 8899,
+      allow: ['localhost:8082', '127.0.0.1:3000', 'localhost:80', '192.168.1.20:8080'],
+      signal: controller.signal,
+    });
+    try {
+      await waitForAsync(() => child !== undefined);
+      const args = jest.mocked(spawnAsync).mock.calls[0][1] ?? [];
+      expect(args.slice(-3)).toEqual([
+        expect.stringMatching(/^R:127\.0\.0\.1:8899:127\.0\.0\.1:\d+$/),
+        'R:127.0.0.1:3000:127.0.0.1:3000',
+        'R:127.0.0.1:8082:127.0.0.1:8082',
+      ]);
+    } finally {
+      controller.abort();
+      await running;
+    }
+  });
+
+  it('uses distinct ephemeral local ports and stops both proxies and children on abort', async () => {
+    jest.mocked(fs.pathExists).mockResolvedValue(true as never);
+    const children: ChildProcess[] = [];
+    jest.mocked(spawnAsync).mockImplementation(() => {
+      const child = new ChildProcess();
+      children.push(child);
+      const promise = new Promise<never>((_resolve, reject) => {
+        child.kill = jest.fn(signal => {
+          Object.defineProperty(child, 'signalCode', { value: signal, configurable: true });
+          reject(new Error('terminated'));
+          return true;
+        });
+      });
+      return Object.assign(promise, { child });
+    });
+    const controllers = [new AbortController(), new AbortController()];
+    const running = controllers.map(controller =>
+      runLocalEgressAsync({
+        url: 'https://example.test',
+        token: 'pw',
+        fingerprint: 'fp',
+        port: 8899,
+        signal: controller.signal,
+      })
+    );
+    try {
+      await waitForAsync(() => children.length === 2);
+      const localPorts = jest.mocked(spawnAsync).mock.calls.map(([, args, options]) => {
+        expect(options).toMatchObject({ ignoreStdio: true, env: { AUTH: 'eas:pw' } });
+        const remote = args?.[args.length - 1] ?? '';
+        expect(remote).toMatch(/^R:127\.0\.0\.1:8899:127\.0\.0\.1:\d+$/);
+        return Number(remote.split(':').at(-1));
+      });
+      expect(new Set(localPorts).size).toBe(2);
+      expect(localPorts.every(port => port > 0)).toBe(true);
+      controllers.forEach(controller => {
+        controller.abort();
+      });
+      await Promise.all(running);
+      for (const child of children) {
+        expect(child.kill).toHaveBeenCalledWith('SIGTERM');
+      }
+      for (const port of localPorts) {
+        const probe = net.connect(port, '127.0.0.1');
+        const [error] = await once(probe, 'error');
+        expect(error.code).toBe('ECONNREFUSED');
+        probe.destroy();
+      }
+    } finally {
+      controllers.forEach(controller => {
+        controller.abort();
+      });
+      await Promise.all(running);
+    }
+  });
+});
@@ -0,0 +1,85 @@
+import { parse as parseDotenv } from 'dotenv';
+import * as fs from 'fs-extra';
+
+import { readLocalEgressConfigFromEnv } from '../egress';
+import { writeSimulatorEnvAsync } from '../env';
+import {
+  DeviceRunSessionRemoteConfig,
+  formatRemoteSessionInstructions,
+  getRemoteSessionEnvironmentVariables,
+} from '../utils';
+
+jest.mock('fs-extra');
+
+const configs: DeviceRunSessionRemoteConfig[] = [
+  {
+    __typename: 'AgentDeviceRunSessionRemoteConfig',
+    agentDeviceRemoteSessionUrl: 'https://agent.example.test',
+    agentDeviceRemoteSessionToken: 'agent-token',
+  },
+  { __typename: 'ArgentRunSessionRemoteConfig', toolsUrl: 'https://argent.example.test' },
+  {
+    __typename: 'AppiumRunSessionRemoteConfig',
+    appiumUrl: 'https://appium.example.test',
+    capabilities: { platformName: 'iOS' },
+  },
+  {
+    __typename: 'WebPreviewOnlyRunSessionRemoteConfig',
+    previewUrl: 'https://preview.example.test',
+  },
+  { __typename: 'ServeSimRunSessionRemoteConfig', previewUrl: 'https://preview.example.test' },
+];
+
+const egressFields = {
+  egressUrl: 'https://egress.example.test',
+  egressToken: 'test-egress-token',
+  egressFingerprint: 'test-fingerprint',
+  egressPort: 8899,
+};
+
+describe('egress exceptions across simulator controllers', () => {
+  beforeEach(() => {
+    jest.mocked(fs.writeFile).mockResolvedValue(undefined as never);
+  });
+
+  it.each(configs)('persists only the requested exceptions for $__typename', async config => {
+    const remoteConfig = { ...config, ...egressFields };
+    const egressAllow = ['localhost:3000', '[::1]:4000'];
+    const environment = getRemoteSessionEnvironmentVariables(remoteConfig, { egressAllow });
+    await writeSimulatorEnvAsync('/test/project', environment);
+    const content = String(jest.mocked(fs.writeFile).mock.calls.at(-1)?.[1]);
+    expect(readLocalEgressConfigFromEnv(parseDotenv(content))).toEqual({
+      url: egressFields.egressUrl,
+      token: egressFields.egressToken,
+      fingerprint: egressFields.egressFingerprint,
+      port: 8899,
+      allow: egressAllow,
+    });
+    const instructions = formatRemoteSessionInstructions(remoteConfig, 'dotenv', { egressAllow });
+    expect(instructions).toContain('eas simulator:egress');
+    expect(instructions).toContain('localhost:3000, [::1]:4000');
+  });
+
+  it.each(configs)(
+    'explicitly clears exceptions for $__typename when none are requested',
+    config => {
+      const environment = getRemoteSessionEnvironmentVariables({ ...config, ...egressFields });
+      expect(environment.EAS_SIMULATOR_EGRESS_ALLOW).toBe('');
+      expect(
+        readLocalEgressConfigFromEnv({
+          EAS_SIMULATOR_EGRESS_ALLOW: 'localhost:9999',
+          ...environment,
+        }).allow
+      ).toEqual([]);
+    }
+  );
+
+  it.each(configs)('does not grant exceptions without an egress tunnel for $__typename', config => {
+    expect(
+      getRemoteSessionEnvironmentVariables(config, { egressAllow: ['localhost:3000'] })
+    ).not.toHaveProperty('EAS_SIMULATOR_EGRESS_ALLOW');
+    expect(
+      formatRemoteSessionInstructions(config, 'dotenv', { egressAllow: ['localhost:3000'] })
+    ).not.toContain('localhost:3000');
+  });
+});
@@ -0,0 +1,100 @@
+import { once } from 'node:events';
+import http from 'node:http';
+import net from 'node:net';
+
+import { startLocalEgressProxyServerAsync } from '../egress';
+
+jest.mock('../../log');
+
+async function connectAsync(port: number): Promise<net.Socket> {
+  const socket = net.connect(port, '127.0.0.1');
+  socket.on('error', () => {});
+  await once(socket, 'connect');
+  return socket;
+}
+
+async function waitForClosedAsync(socket: net.Socket): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (!socket.destroyed) {
+    if (Date.now() >= deadline) {
+      throw new Error('The proxy did not reject the connection above its socket limit.');
+    }
+    await new Promise(resolve => setTimeout(resolve, 5));
+  }
+}
+
+describe('local egress accepted connection limit', () => {
+  it.each(['CONNECT', 'upgrade'])(
+    'counts idle and %s connections, excludes upstream sockets, and releases capacity',
+    async method => {
+      const upstreamSockets = new Set<net.Socket>();
+      const target = http.createServer((_req, res) => res.end('ok'));
+      target.on('connection', socket => {
+        upstreamSockets.add(socket);
+        socket.once('close', () => upstreamSockets.delete(socket));
+      });
+      target.on('upgrade', (_req, socket) => {
+        socket.write(
+          'HTTP/1.1 101 Switching Protocols\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n'
+        );
+        socket.pipe(socket);
+      });
+      await new Promise<void>(resolve => target.listen(0, '127.0.0.1', resolve));
+      const targetPort = (target.address() as net.AddressInfo).port;
+      const proxy = await startLocalEgressProxyServerAsync({
+        port: 0,
+        resolveTargetAsync: async () => ['127.0.0.1'],
+      });
+      const clients: net.Socket[] = [];
+      try {
+        // Fill the production limit with 511 unparsed sockets and one active tunnel.
+        clients.push(
+          ...(await Promise.all(Array.from({ length: 511 }, () => connectAsync(proxy.port))))
+        );
+        const tunnel = await connectAsync(proxy.port);
+        clients.push(tunnel);
+        const reply = once(tunnel, 'data');
+        const destination = `target.test:${targetPort}`;
+        tunnel.write(
+          method === 'CONNECT'
+            ? `CONNECT ${destination} HTTP/1.1\r\nHost: ${destination}\r\n\r\n`
+            : `GET http://${destination}/ HTTP/1.1\r\nHost: ${destination}\r\nConnection: Upgrade\r\nUpgrade: websocket\r\n\r\n`
+        );
+        expect((await reply)[0].toString()).toContain(
+          method === 'CONNECT' ? '200 Connection Established' : '101 Switching Protocols'
+        );
+        expect(proxy.getStats().active).toBe(1);
+
+        const excess = await connectAsync(proxy.port);
+        clients.push(excess);
+        await waitForClosedAsync(excess);
+        expect(proxy.getStats().refused).toBe(1);
+
+        // A peer-acknowledged close frees a downstream slot even though the tunnel remains.
+        const closed = once(clients[0], 'close');
+        clients[0].end();
+        await closed;
+        const replacement = await connectAsync(proxy.port);
+        clients.push(replacement);
+        const response = once(replacement, 'data');
+        replacement.write(
+          `GET http://${destination}/ HTTP/1.1\r\nHost: ${destination}\r\nConnection: close\r\n\r\n`
+        );
+        expect((await response)[0].toString()).toContain('200 OK');
+      } finally {
+        for (const client of clients) {
+          client.destroy();
+        }
+        await proxy.closeAsync();
+        for (const socket of upstreamSockets) {
+          socket.destroy();
+        }
+        await new Promise<void>(resolve =>
+          target.close(() => {
+            resolve();
+          })
+        );
+      }
+    }
+  );
+});
@@ -1,13 +1,23 @@
 import * as fs from 'fs-extra';
 import { parse as parseDotenv } from 'dotenv';
+import * as realFs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';

 import {
+  EAS_SIMULATOR_EGRESS_ALLOW,
+  EAS_SIMULATOR_EGRESS_FINGERPRINT,
+  EAS_SIMULATOR_EGRESS_PORT,
+  EAS_SIMULATOR_EGRESS_TOKEN,
+  EAS_SIMULATOR_EGRESS_URL,
  EAS_SIMULATOR_SESSION_ID,
  SIMULATOR_DOTENV_FILE_HEADER,
  getSimulatorEnvFilePath,
+  loadSimulatorEnvAsync,
  resetSimulatorEnvAsync,
  writeSimulatorEnvAsync,
 } from '../env';
+import { readLocalEgressConfigFromEnv } from '../egress';

 jest.mock('fs-extra');

@@ -63,6 +73,124 @@ describe(resetSimulatorEnvAsync, () => {
  });
 });

+describe(loadSimulatorEnvAsync, () => {
+  let projectDir: string;
+  let previousEnv: NodeJS.ProcessEnv;
+
+  beforeEach(async () => {
+    previousEnv = { ...process.env };
+    projectDir = await realFs.mkdtemp(path.join(os.tmpdir(), 'eas-simulator-env-'));
+    jest.mocked(fs.readFile).mockImplementation(jest.requireActual('fs-extra').readFile);
+    process.env[EAS_SIMULATOR_EGRESS_ALLOW] = 'localhost:3000';
+    process.env[EAS_SIMULATOR_SESSION_ID] = 'session-a';
+    process.env[EAS_SIMULATOR_EGRESS_URL] = 'https://session-a.example.test';
+    process.env[EAS_SIMULATOR_EGRESS_TOKEN] = 'session-a-token';
+    process.env[EAS_SIMULATOR_EGRESS_FINGERPRINT] = 'session-a-fingerprint';
+    process.env[EAS_SIMULATOR_EGRESS_PORT] = '8899';
+    process.env.AGENT_DEVICE_DAEMON_BASE_URL = 'https://agent-a.example.test';
+    process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN = 'agent-a-token';
+    process.env.EAS_SIMULATOR_ENV_TEST_UNRELATED = 'keep-this';
+  });
+
+  afterEach(async () => {
+    process.env = previousEnv;
+    await realFs.rm(projectDir, { recursive: true, force: true });
+    jest.resetAllMocks();
+  });
+
+  it.each(['', `${EAS_SIMULATOR_EGRESS_ALLOW}=''\n`])(
+    "does not inherit another session's exceptions when the file has no exceptions (%j)",
+    async allowLine => {
+      await realFs.writeFile(
+        getSimulatorEnvFilePath(projectDir),
+        `${EAS_SIMULATOR_SESSION_ID}='session-b'\n` +
+          `${EAS_SIMULATOR_EGRESS_URL}='https://session-b.example.test'\n` +
+          allowLine
+      );
+
+      await loadSimulatorEnvAsync(projectDir);
+
+      expect(process.env[EAS_SIMULATOR_SESSION_ID]).toBe('session-b');
+      expect(process.env[EAS_SIMULATOR_EGRESS_ALLOW]).toBe('');
+    }
+  );
+
+  it('preserves shell-exported exceptions when there is no simulator file', async () => {
+    await loadSimulatorEnvAsync(projectDir);
+
+    expect(process.env[EAS_SIMULATOR_EGRESS_ALLOW]).toBe('localhost:3000');
+    expect(process.env[EAS_SIMULATOR_EGRESS_URL]).toBe('https://session-a.example.test');
+    expect(process.env.AGENT_DEVICE_DAEMON_BASE_URL).toBe('https://agent-a.example.test');
+    expect(process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN).toBe('agent-a-token');
+    expect(process.env.EAS_SIMULATOR_ENV_TEST_UNRELATED).toBe('keep-this');
+  });
+
+  it('loads the file credentials and exceptions together over inherited values', async () => {
+    await realFs.writeFile(
+      getSimulatorEnvFilePath(projectDir),
+      `${EAS_SIMULATOR_SESSION_ID}='session-b'\n` +
+        "AGENT_DEVICE_DAEMON_BASE_URL='https://agent-b.example.test'\n" +
+        "AGENT_DEVICE_DAEMON_AUTH_TOKEN='agent-b-token'\n" +
+        `${EAS_SIMULATOR_EGRESS_URL}='https://session-b.example.test'\n` +
+        `${EAS_SIMULATOR_EGRESS_TOKEN}='session-b-token'\n` +
+        `${EAS_SIMULATOR_EGRESS_FINGERPRINT}='session-b-fingerprint'\n` +
+        `${EAS_SIMULATOR_EGRESS_PORT}='8900'\n` +
+        `${EAS_SIMULATOR_EGRESS_ALLOW}='localhost:4000'\n`
+    );
+
+    await loadSimulatorEnvAsync(projectDir);
+
+    expect(readLocalEgressConfigFromEnv(process.env)).toEqual({
+      url: 'https://session-b.example.test',
+      token: 'session-b-token',
+      fingerprint: 'session-b-fingerprint',
+      port: 8900,
+      allow: ['localhost:4000'],
+    });
+    expect(process.env[EAS_SIMULATOR_SESSION_ID]).toBe('session-b');
+    expect(process.env.AGENT_DEVICE_DAEMON_BASE_URL).toBe('https://agent-b.example.test');
+    expect(process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN).toBe('agent-b-token');
+    expect(process.env.EAS_SIMULATOR_ENV_TEST_UNRELATED).toBe('keep-this');
+  });
+
+  it('replaces an inherited agent session with an Appium session without mixing controls', async () => {
+    const capabilities = JSON.stringify({ platformName: 'iOS' });
+    await realFs.writeFile(
+      getSimulatorEnvFilePath(projectDir),
+      `${EAS_SIMULATOR_SESSION_ID}='session-b'\n` +
+        "APPIUM_URL='https://appium-b.example.test'\n" +
+        `APPIUM_CAPS='${capabilities}'\n`
+    );
+
+    await loadSimulatorEnvAsync(projectDir);
+
+    expect(process.env[EAS_SIMULATOR_SESSION_ID]).toBe('session-b');
+    expect(process.env.APPIUM_URL).toBe('https://appium-b.example.test');
+    expect(process.env.APPIUM_CAPS).toBe(capabilities);
+    expect(process.env.AGENT_DEVICE_DAEMON_BASE_URL).toBeUndefined();
+    expect(process.env.AGENT_DEVICE_DAEMON_AUTH_TOKEN).toBeUndefined();
+    expect(process.env[EAS_SIMULATOR_EGRESS_URL]).toBeUndefined();
+    expect(process.env[EAS_SIMULATOR_EGRESS_ALLOW]).toBe('');
+    expect(process.env.EAS_SIMULATOR_ENV_TEST_UNRELATED).toBe('keep-this');
+  });
+
+  it.each(['', `${EAS_SIMULATOR_EGRESS_URL}='https://session-b.example.test'\n`])(
+    'does not fill missing file credentials from a previous session (%j)',
+    async egressLine => {
+      await realFs.writeFile(
+        getSimulatorEnvFilePath(projectDir),
+        `${EAS_SIMULATOR_SESSION_ID}='session-b'\n${egressLine}`
+      );
+
+      await loadSimulatorEnvAsync(projectDir);
+
+      expect(process.env[EAS_SIMULATOR_EGRESS_TOKEN]).toBeUndefined();
+      expect(process.env[EAS_SIMULATOR_EGRESS_ALLOW]).toBe('');
+      expect(() => readLocalEgressConfigFromEnv(process.env)).toThrow('no egress client to run');
+    }
+  );
+});
+
 describe(writeSimulatorEnvAsync, () => {
  const projectDir = '/test/project';
  const simulatorDotenvPath = getSimulatorEnvFilePath(projectDir);
@@ -3,15 +3,155 @@ import {
  DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE,
  DEVICE_RUN_SESSION_TYPE_BY_FLAG_VALUE,
  DEVICE_RUN_SESSION_TYPE_FLAG_VALUES,
+  DeviceRunSessionRemoteConfig,
  EAS_SIMULATOR_WAITLIST_URL,
  deviceRunSessionTypeToFlagValue,
+  formatLoopbackForwardNotice,
  formatPreviewUrl,
  formatRemoteSessionInstructions,
  formatSimulatorUnavailableMessage,
+  getLocalEgressConfig,
+  getLoopbackForwardPlan,
  getRemoteSessionEnvironmentVariables,
  sanitizeRemoteConfigForJson,
 } from '../utils';

+const agentDeviceConfig = {
+  __typename: 'AgentDeviceRunSessionRemoteConfig' as const,
+  agentDeviceRemoteSessionUrl: 'https://agent-device.example.test',
+  agentDeviceRemoteSessionToken: 'daemon-token',
+  webPreviewUrl: 'https://preview.example.test',
+};
+
+const agentDeviceConfigWithEgress = {
+  ...agentDeviceConfig,
+  egressUrl: 'https://egress-abc.eas-simulator.ngrok.dev',
+  egressToken: 'egress-secret',
+  egressFingerprint: 'fp=',
+  egressPort: 8899,
+};
+
+describe('local egress configuration', () => {
+  it('is absent for sessions without egress', () => {
+    expect(getLocalEgressConfig(agentDeviceConfig)).toBeNull();
+    expect(getRemoteSessionEnvironmentVariables(agentDeviceConfig)).toEqual({
+      AGENT_DEVICE_DAEMON_BASE_URL: 'https://agent-device.example.test',
+      AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'daemon-token',
+    });
+    expect(formatRemoteSessionInstructions(agentDeviceConfig, 'dotenv')).not.toContain(
+      'eas simulator:egress'
+    );
+  });
+
+  it('adds the egress variables and instructions when the worker reported them', () => {
+    expect(getLocalEgressConfig(agentDeviceConfigWithEgress)).toEqual({
+      url: 'https://egress-abc.eas-simulator.ngrok.dev',
+      token: 'egress-secret',
+      fingerprint: 'fp=',
+      port: 8899,
+      allow: [],
+    });
+    expect(getRemoteSessionEnvironmentVariables(agentDeviceConfigWithEgress)).toEqual({
+      AGENT_DEVICE_DAEMON_BASE_URL: 'https://agent-device.example.test',
+      AGENT_DEVICE_DAEMON_AUTH_TOKEN: 'daemon-token',
+      EAS_SIMULATOR_EGRESS_URL: 'https://egress-abc.eas-simulator.ngrok.dev',
+      EAS_SIMULATOR_EGRESS_TOKEN: 'egress-secret',
+      EAS_SIMULATOR_EGRESS_FINGERPRINT: 'fp=',
+      EAS_SIMULATOR_EGRESS_PORT: '8899',
+      EAS_SIMULATOR_EGRESS_ALLOW: '',
+    });
+    const instructions = formatRemoteSessionInstructions(agentDeviceConfigWithEgress, 'dotenv');
+    expect(instructions).toContain('eas simulator:egress');
+    expect(instructions).toContain('Run the egress client to connect the tunnel');
+    expect(instructions).toContain('Keep it running for the life of the session.');
+    expect(instructions).not.toContain('may reach');
+    expect(formatRemoteSessionInstructions(agentDeviceConfigWithEgress, 'env')).toContain(
+      "export EAS_SIMULATOR_EGRESS_ALLOW=''"
+    );
+  });
+
+  it('describes the inline egress client instead of asking the reader to start one', () => {
+    const instructions = formatRemoteSessionInstructions(agentDeviceConfigWithEgress, 'dotenv', {
+      egressClientRunsInline: true,
+    });
+    expect(instructions).toContain('The egress client runs in this terminal');
+    expect(instructions).toContain(
+      'reconnect the tunnel from another shell with:\n\neas simulator:egress'
+    );
+    expect(instructions).not.toContain('Run the egress client to connect the tunnel');
+    expect(instructions).not.toContain('Keep it running');
+
+    expect(
+      formatRemoteSessionInstructions(agentDeviceConfigWithEgress, 'env', {
+        egressClientRunsInline: true,
+      })
+    ).toContain('eas simulator:egress --config-type env');
+  });
+
+  it('carries the allowed local destinations into the config, env file and instructions', () => {
+    const egressAllow = ['localhost:3000', '192.168.1.20:8080'];
+    expect(getLocalEgressConfig(agentDeviceConfigWithEgress, egressAllow)?.allow).toEqual(
+      egressAllow
+    );
+    expect(
+      getRemoteSessionEnvironmentVariables(agentDeviceConfigWithEgress, { egressAllow })
+    ).toMatchObject({ EAS_SIMULATOR_EGRESS_ALLOW: 'localhost:3000,192.168.1.20:8080' });
+    expect(
+      getRemoteSessionEnvironmentVariables(agentDeviceConfig, { egressAllow })
+    ).not.toHaveProperty('EAS_SIMULATOR_EGRESS_ALLOW');
+    const instructions = formatRemoteSessionInstructions(agentDeviceConfigWithEgress, 'dotenv', {
+      egressAllow,
+    });
+    expect(instructions).toContain(
+      "The simulator may reach localhost:3000, 192.168.1.20:8080 on this machine's network."
+    );
+    expect(instructions).toContain(
+      '127.0.0.1:3000 in the simulator reaches the same port on this machine (like adb reverse)'
+    );
+  });
+
+  it('omits the loopback forwarding notice when no allowed destination is loopback', () => {
+    expect(
+      formatRemoteSessionInstructions(agentDeviceConfigWithEgress, 'dotenv', {
+        egressAllow: ['192.168.1.20:8080'],
+      })
+    ).not.toContain('adb reverse');
+  });
+});
+
+describe(getLoopbackForwardPlan, () => {
+  it('forwards unprivileged localhost and 127.0.0.1 ports once each, in order', () => {
+    expect(
+      getLoopbackForwardPlan(
+        ['localhost:8082', '127.0.0.1:3000', 'localhost:3000', '192.168.1.20:8080', '[::1]:4000'],
+        8899
+      )
+    ).toEqual({ ports: [3000, 8082], skipped: [] });
+  });
+
+  it('skips privileged ports and the proxy port, which the device host does not forward', () => {
+    expect(
+      getLoopbackForwardPlan(['localhost:80', '127.0.0.1:8899', 'localhost:1024'], 8899)
+    ).toEqual({ ports: [1024], skipped: ['localhost:80', '127.0.0.1:8899'] });
+  });
+
+  it('returns an empty plan without allow entries', () => {
+    expect(getLoopbackForwardPlan([], 8899)).toEqual({ ports: [], skipped: [] });
+  });
+});
+
+describe(formatLoopbackForwardNotice, () => {
+  it('describes forwarded ports and name-only entries', () => {
+    expect(formatLoopbackForwardNotice({ ports: [3000, 8082], skipped: ['localhost:80'] })).toEqual(
+      [
+        '127.0.0.1:3000, 127.0.0.1:8082 in the simulator reach the same ports on this machine (like adb reverse), so dev server URLs that use 127.0.0.1 work.',
+        'localhost:80 is reachable by name only: privileged ports and the egress proxy port are not forwarded to 127.0.0.1 in the simulator.',
+      ]
+    );
+    expect(formatLoopbackForwardNotice({ ports: [], skipped: [] })).toEqual([]);
+  });
+});
+
 const iosAppiumConfig = {
  __typename: 'AppiumRunSessionRemoteConfig' as const,
  appiumUrl: 'https://appium.example.test',
@@ -290,3 +430,59 @@ describe(formatSimulatorUnavailableMessage, () => {
    expect(message).toContain(EAS_SIMULATOR_WAITLIST_URL);
  });
 });
+
+const controllerConfigs: DeviceRunSessionRemoteConfig[] = [
+  agentDeviceConfig,
+  iosAppiumConfig,
+  { __typename: 'ArgentRunSessionRemoteConfig', toolsUrl: 'https://argent.example.test' },
+  { __typename: 'ServeSimRunSessionRemoteConfig', previewUrl: 'https://preview.example.test' },
+  {
+    __typename: 'WebPreviewOnlyRunSessionRemoteConfig',
+    previewUrl: 'https://preview.example.test',
+  },
+];
+
+describe.each(controllerConfigs)('$__typename local egress', remoteConfig => {
+  const egress = {
+    egressUrl: 'https://egress.example.test',
+    egressToken: 'egress-secret',
+    egressFingerprint: 'fp=',
+    egressPort: 8899,
+  };
+
+  it('preserves controller variables and provides egress credentials and instructions', () => {
+    const withEgress = { ...remoteConfig, ...egress };
+    expect(getRemoteSessionEnvironmentVariables(withEgress)).toEqual({
+      ...getRemoteSessionEnvironmentVariables(remoteConfig),
+      EAS_SIMULATOR_EGRESS_URL: egress.egressUrl,
+      EAS_SIMULATOR_EGRESS_TOKEN: egress.egressToken,
+      EAS_SIMULATOR_EGRESS_FINGERPRINT: egress.egressFingerprint,
+      EAS_SIMULATOR_EGRESS_PORT: '8899',
+      EAS_SIMULATOR_EGRESS_ALLOW: '',
+    });
+    expect(getLocalEgressConfig(withEgress)).toEqual({
+      url: egress.egressUrl,
+      token: egress.egressToken,
+      fingerprint: egress.egressFingerprint,
+      port: 8899,
+      allow: [],
+    });
+    const dotenvInstructions = formatRemoteSessionInstructions(withEgress, 'dotenv');
+    expect(dotenvInstructions).toContain('eas simulator:egress');
+    expect(dotenvInstructions).not.toContain(egress.egressToken);
+    expect(formatRemoteSessionInstructions(withEgress, 'env')).toContain(
+      'eas simulator:egress --config-type env'
+    );
+    expect(formatRemoteSessionInstructions(withEgress, 'env')).toContain(
+      "export EAS_SIMULATOR_EGRESS_TOKEN='egress-secret'"
+    );
+  });
+
+  it('does not start a tunnel from absent or incomplete egress credentials', () => {
+    expect(getLocalEgressConfig(remoteConfig)).toBeNull();
+    expect(getLocalEgressConfig({ ...remoteConfig, ...egress, egressToken: null })).toBeNull();
+    expect(formatRemoteSessionInstructions(remoteConfig, 'dotenv')).not.toContain(
+      'eas simulator:egress'
+    );
+  });
+});
@@ -7,6 +7,13 @@ import Log from '../log';

 export const SIMULATOR_DOTENV_FILE_NAME = '.env.eas-simulator';
 export const EAS_SIMULATOR_SESSION_ID = 'EAS_SIMULATOR_SESSION_ID';
+// Written for sessions started with `--egress local`; read by `eas simulator:egress`.
+export const EAS_SIMULATOR_EGRESS_URL = 'EAS_SIMULATOR_EGRESS_URL';
+export const EAS_SIMULATOR_EGRESS_TOKEN = 'EAS_SIMULATOR_EGRESS_TOKEN';
+export const EAS_SIMULATOR_EGRESS_FINGERPRINT = 'EAS_SIMULATOR_EGRESS_FINGERPRINT';
+export const EAS_SIMULATOR_EGRESS_PORT = 'EAS_SIMULATOR_EGRESS_PORT';
+// Comma-separated host:port destinations from `--egress-allow`.
+export const EAS_SIMULATOR_EGRESS_ALLOW = 'EAS_SIMULATOR_EGRESS_ALLOW';
 export const SIMULATOR_DOTENV_FILE_HEADER =
  '# Do not commit this file.\n# Do not modify these values manually. They are managed by eas-cli.\n# It holds configuration only for the current simulator session.\n\n';

@@ -18,6 +25,38 @@ export async function loadSimulatorEnvAsync(projectDir: string): Promise<void> {
  const simulatorDotenvFilePath = getSimulatorEnvFilePath(projectDir);

  loadProjectEnv(projectDir, { silent: true });
+  try {
+    const simulatorEnv = parseDotenv(await fs.readFile(simulatorDotenvFilePath, 'utf8'));
+    if (simulatorEnv[EAS_SIMULATOR_SESSION_ID] || simulatorEnv[EAS_SIMULATOR_EGRESS_URL]) {
+      // loadEnvFiles never replaces existing variables, even with force: true.
+      // Keep this session's credentials and destination policy together rather
+      // than combining them with values exported for an older session.
+      for (const key of [
+        EAS_SIMULATOR_SESSION_ID,
+        'AGENT_DEVICE_DAEMON_BASE_URL',
+        'AGENT_DEVICE_DAEMON_AUTH_TOKEN',
+        'ARGENT_TOOLS_URL',
+        'ARGENT_AUTH_TOKEN',
+        'APPIUM_URL',
+        'APPIUM_CAPS',
+        EAS_SIMULATOR_EGRESS_URL,
+        EAS_SIMULATOR_EGRESS_TOKEN,
+        EAS_SIMULATOR_EGRESS_FINGERPRINT,
+        EAS_SIMULATOR_EGRESS_PORT,
+      ]) {
+        if (simulatorEnv[key] === undefined) {
+          delete process.env[key];
+        } else {
+          process.env[key] = simulatorEnv[key];
+        }
+      }
+      process.env[EAS_SIMULATOR_EGRESS_ALLOW] = simulatorEnv[EAS_SIMULATOR_EGRESS_ALLOW] ?? '';
+    }
+  } catch (err) {
+    if (!(typeof err === 'object' && err !== null && 'code' in err && err.code === 'ENOENT')) {
+      throw err;
+    }
+  }
  loadEnvFiles([simulatorDotenvFilePath], { force: true });
 }

@@ -4,6 +4,13 @@ import {
  DeviceRunSessionType,
 } from '../graphql/generated';
 import { link } from '../log';
+import {
+  EAS_SIMULATOR_EGRESS_ALLOW,
+  EAS_SIMULATOR_EGRESS_FINGERPRINT,
+  EAS_SIMULATOR_EGRESS_PORT,
+  EAS_SIMULATOR_EGRESS_TOKEN,
+  EAS_SIMULATOR_EGRESS_URL,
+} from './env';

 type DeviceRunSessionByIdResult = DeviceRunSessionByIdQuery['deviceRunSessions']['byId'];
 export type DeviceRunSessionRemoteConfig = NonNullable<DeviceRunSessionByIdResult['remoteConfig']>;
@@ -59,7 +66,134 @@ export const DEVICE_RUN_SESSION_RESOURCE_CLASS_BY_FLAG_VALUE = Object.fromEntrie
  ).map(([resourceClass, value]) => [value, resourceClass])
 ) as Record<string, DeviceRunSessionResourceClass>;

+export type LocalEgressConfig = {
+  url: string;
+  /** Secret for the tunnel server; the client pairs it with the fixed egress username. */
+  token: string;
+  fingerprint: string;
+  port: number;
+  /**
+   * Normalized `host:port` destinations on the developer's machine or network
+   * that the simulator may reach through the proxy (`--egress-allow`).
+   */
+  allow: string[];
+};
+
+export type LocalEgressOptions = {
+  egressAllow?: readonly string[];
+  /**
+   * Whether the calling command runs the egress client itself in the current
+   * terminal, as interactive `simulator:start` does. When false the reader must
+   * start `eas simulator:egress` in another process.
+   */
+  egressClientRunsInline?: boolean;
+};
+
+/**
+ * Connection details for the local egress client, present only for sessions
+ * started with `--egress local`. `allow` comes from the developer's flags, not
+ * from the worker.
+ */
+export function getLocalEgressConfig(
+  remoteConfig: DeviceRunSessionRemoteConfig,
+  allow: readonly string[] = []
+): LocalEgressConfig | null {
+  const { egressUrl, egressToken, egressFingerprint, egressPort } = remoteConfig;
+  if (!egressUrl || !egressToken || !egressFingerprint || egressPort == null) {
+    return null;
+  }
+  return {
+    url: egressUrl,
+    token: egressToken,
+    fingerprint: egressFingerprint,
+    port: egressPort,
+    allow: [...allow],
+  };
+}
+
+export type LoopbackForwardPlan = {
+  /** Ports the tunnel client forwards on the device host's loopback interface. */
+  ports: number[];
+  /** Loopback allow entries that stay reachable by name through the proxy only. */
+  skipped: string[];
+};
+
+/**
+ * Which `--egress-allow` entries also become loopback port forwards. iOS never
+ * sends loopback-literal requests to the system proxy, and Expo CLI rewrites
+ * `localhost` to `127.0.0.1` in manifests, so the proxy alone cannot serve a dev
+ * server allowed as `localhost:<port>`. For each entry naming `localhost` or
+ * `127.0.0.1`, the tunnel client opens a reverse remote that makes
+ * `127.0.0.1:<port>` on the device host reach the same port here, like
+ * `adb reverse`. The device host only permits unprivileged ports, and the proxy
+ * port is already taken by the tunnel server, so those entries are skipped.
+ */
+export function getLoopbackForwardPlan(
+  allow: readonly string[],
+  proxyPort: number
+): LoopbackForwardPlan {
+  const ports = new Set<number>();
+  const skipped: string[] = [];
+  for (const destination of allow) {
+    const match = /^(?:localhost|127\.0\.0\.1):(\d+)$/.exec(destination);
+    if (!match) {
+      continue;
+    }
+    const port = Number(match[1]);
+    if (port < 1024 || port === proxyPort) {
+      skipped.push(destination);
+      continue;
+    }
+    ports.add(port);
+  }
+  return { ports: [...ports].sort((a, b) => a - b), skipped };
+}
+
+export function formatLoopbackForwardNotice({ ports, skipped }: LoopbackForwardPlan): string[] {
+  const lines: string[] = [];
+  if (ports.length > 0) {
+    const addresses = ports.map(port => `127.0.0.1:${port}`).join(', ');
+    lines.push(
+      `${addresses} in the simulator ${ports.length === 1 ? 'reaches' : 'reach'} the same ` +
+        `${ports.length === 1 ? 'port' : 'ports'} on this machine (like adb reverse), so dev server ` +
+        'URLs that use 127.0.0.1 work.'
+    );
+  }
+  if (skipped.length > 0) {
+    lines.push(
+      `${skipped.join(', ')} ${skipped.length === 1 ? 'is' : 'are'} reachable by name only: ` +
+        'privileged ports and the egress proxy port are not forwarded to 127.0.0.1 in the simulator.'
+    );
+  }
+  return lines;
+}
+
+export function getLocalEgressEnvironmentVariables(
+  egress: LocalEgressConfig | null
+): Record<string, string> {
+  if (!egress) {
+    return {};
+  }
+  return {
+    [EAS_SIMULATOR_EGRESS_URL]: egress.url,
+    [EAS_SIMULATOR_EGRESS_TOKEN]: egress.token,
+    [EAS_SIMULATOR_EGRESS_FINGERPRINT]: egress.fingerprint,
+    [EAS_SIMULATOR_EGRESS_PORT]: String(egress.port),
+    [EAS_SIMULATOR_EGRESS_ALLOW]: egress.allow.join(','),
+  };
+}
+
 export function getRemoteSessionEnvironmentVariables(
+  remoteConfig: DeviceRunSessionRemoteConfig,
+  { egressAllow }: LocalEgressOptions = {}
+): Record<string, string> {
+  return {
+    ...getControllerEnvironmentVariables(remoteConfig),
+    ...getLocalEgressEnvironmentVariables(getLocalEgressConfig(remoteConfig, egressAllow)),
+  };
+}
+
+function getControllerEnvironmentVariables(
  remoteConfig: DeviceRunSessionRemoteConfig
 ): Record<string, string> {
  switch (remoteConfig.__typename) {
@@ -128,12 +262,56 @@ export function sanitizeRemoteConfigForJson(
 }

 export function formatRemoteSessionInstructions(
+  remoteConfig: DeviceRunSessionRemoteConfig,
+  configType: RemoteSessionInstructionsConfigType,
+  { egressAllow, egressClientRunsInline = false }: LocalEgressOptions = {}
+): string {
+  const instructions = formatControllerInstructions(remoteConfig, configType);
+  const egress = getLocalEgressConfig(remoteConfig, egressAllow);
+  if (!egress) {
+    return instructions;
+  }
+  const egressCommand =
+    configType === 'env' ? 'eas simulator:egress --config-type env' : 'eas simulator:egress';
+  return [
+    instructions,
+    '',
+    '🔀 This session can route proxied HTTP(S) requests through this machine.',
+    ...(configType === 'env'
+      ? Object.entries(getLocalEgressEnvironmentVariables(egress)).map(
+          ([key, value]) => `export ${key}='${value}'`
+        )
+      : []),
+    ...(egressClientRunsInline
+      ? [
+          'The egress client runs in this terminal for the life of the session. If this process exits, reconnect the tunnel from another shell with:',
+          '',
+          egressCommand,
+        ]
+      : [
+          'Run the egress client to connect the tunnel:',
+          '',
+          egressCommand,
+          '',
+          'Keep it running for the life of the session.',
+        ]),
+    ...(egress.allow.length > 0
+      ? [
+          '',
+          `The simulator may reach ${egress.allow.join(', ')} on this machine's network.`,
+          ...formatLoopbackForwardNotice(getLoopbackForwardPlan(egress.allow, egress.port)),
+        ]
+      : []),
+  ].join('\n');
+}
+
+function formatControllerInstructions(
  remoteConfig: DeviceRunSessionRemoteConfig,
  configType: RemoteSessionInstructionsConfigType
 ): string {
  switch (remoteConfig.__typename) {
    case 'AgentDeviceRunSessionRemoteConfig': {
-      const environmentVariables = getRemoteSessionEnvironmentVariables(remoteConfig);
+      const environmentVariables = getControllerEnvironmentVariables(remoteConfig);
      const lines =
        configType === 'dotenv'
          ? [
@@ -159,7 +337,7 @@ export function formatRemoteSessionInstructions(
      return lines.join('\n');
    }
    case 'ArgentRunSessionRemoteConfig': {
-      const environmentVariables = getRemoteSessionEnvironmentVariables(remoteConfig);
+      const environmentVariables = getControllerEnvironmentVariables(remoteConfig);
      const lines =
        configType === 'dotenv'
          ? [
@@ -197,7 +375,7 @@ export function formatRemoteSessionInstructions(
      return lines.join('\n');
    }
    case 'AppiumRunSessionRemoteConfig': {
-      const environmentVariables = getRemoteSessionEnvironmentVariables(remoteConfig);
+      const environmentVariables = getControllerEnvironmentVariables(remoteConfig);
      const lines =
        configType === 'dotenv'
          ? [
@@ -1,6 +1,6 @@
 {
  "name": "eas-cli-local-build-plugin",
-  "version": "24.0.0",
+  "version": "24.1.0",
  "description": "Tool for running EAS compatible builds on a local machine.",
  "bugs": "https://github.com/expo/eas-cli/issues",
  "license": "BUSL-1.1",
@@ -26,7 +26,7 @@
    "clean": "rimraf node_modules dist coverage \"*.tsbuildinfo\""
  },
  "dependencies": {
-    "@expo/build-tools": "24.0.0",
+    "@expo/build-tools": "24.1.0",
    "@expo/bunyan": "^4.0.1",
    "@expo/eas-build-job": "24.0.0",
    "@expo/logger": "24.0.0",
@@ -1,6 +1,6 @@
 {
  "name": "@expo/worker",
-  "version": "24.0.0",
+  "version": "24.1.0",
  "private": true,
  "scripts": {
    "start": "yarn watch",
@@ -19,7 +19,7 @@
  },
  "dependencies": {
    "@babel/core": "7.24.7",
-    "@expo/build-tools": "24.0.0",
+    "@expo/build-tools": "24.1.0",
    "@expo/config-plugins": "55.0.7",
    "@expo/config-types": "55.0.5",
    "@expo/eas-build-job": "24.0.0",
@@ -2291,7 +2291,7 @@ __metadata:
  languageName: node
  linkType: hard

-"@expo/build-tools@npm:24.0.0, @expo/build-tools@workspace:packages/build-tools":
+"@expo/build-tools@npm:24.1.0, @expo/build-tools@workspace:packages/build-tools":
  version: 0.0.0-use.local
  resolution: "@expo/build-tools@workspace:packages/build-tools"
  dependencies:
@@ -2969,7 +2969,7 @@ __metadata:
  resolution: "@expo/worker@workspace:packages/worker"
  dependencies:
    "@babel/core": "npm:7.24.7"
-    "@expo/build-tools": "npm:24.0.0"
+    "@expo/build-tools": "npm:24.1.0"
    "@expo/config-plugins": "npm:55.0.7"
    "@expo/config-types": "npm:55.0.5"
    "@expo/eas-build-job": "npm:24.0.0"
@@ -10412,7 +10412,7 @@ __metadata:
  version: 0.0.0-use.local
  resolution: "eas-cli-local-build-plugin@workspace:packages/local-build-plugin"
  dependencies:
-    "@expo/build-tools": "npm:24.0.0"
+    "@expo/build-tools": "npm:24.1.0"
    "@expo/bunyan": "npm:^4.0.1"
    "@expo/eas-build-job": "npm:24.0.0"
    "@expo/logger": "npm:24.0.0"
Author	SHA1	Message	Date
Expo CI	0b2cea7bb7	v24.1.1	2026-09-11 00:10:40 +00:00
Brent Vatne	eab4fc3cd5	[eas-cli] describe the inline egress client instead of asking to start one (#4382 )	2026-09-10 17:07:16 -07:00
Brent Vatne	e2e8cd245c	[eas-cli] improve EasCommand test reliability (#4381 )	2026-09-10 17:05:16 -07:00
Expo CI	80d46f0783	bump STAGING and PRODUCTION to 24.1.0 in cli-versions.json	2026-09-10 23:27:17 +00:00
Expo CI	3b6b63a273	update CHANGELOG.md for v24.1.0	2026-09-10 23:24:59 +00:00
Expo CI	8373ae353c	v24.1.0	2026-09-10 23:22:26 +00:00
Brent Vatne	994794dbad	[eas-cli] add --egress-allow to reach local dev servers through local egress (#4369 ) * [eas-cli] add --egress-allow so local egress sessions can reach dev servers on this machine Adds repeatable --egress-allow host:port, requiring --egress local. Entries are normalized and deduplicated; wildcards, ranges, and malformed values are rejected before session creation. Exceptions match the exact host and port; unlisted destinations keep the default policy. Exceptions persist in the session configuration and are shown when starting or reconnecting, across all iOS controllers. Squashes the earlier --egress-allow commits and base-branch sync merges so the branch sits directly on the rebased base. * [eas-cli] forward loopback --egress-allow ports from the simulator host like adb reverse iOS never sends 127.0.0.1 requests to the system proxy and Expo CLI rewrites localhost to 127.0.0.1 in manifests, so --egress-allow localhost:<port> alone could not serve a dev server to Expo Go. For each localhost or 127.0.0.1 entry the egress client now opens a chisel reverse remote so 127.0.0.1:<port> on the device host reaches the same port on this machine. Privileged ports and the proxy port stay name-only. The start output explains the forwarding, and rejected remotes are surfaced instead of looping silently.	2026-09-10 14:12:01 -07:00
Brent Vatne	d103da3bc5	[eas-cli][build-tools] local egress for iOS simulator sessions (--egress local) (#4364 ) * [build-tools] add start_local_egress step for local egress simulator sessions * [eas-cli] add --egress local to simulator:start and add simulator:egress * [eas-cli] update CHANGELOG * [build-tools] drop the pf UDP block from local egress and report direct simulator connections * [eas-cli] harden the local egress proxy and narrow the contract wording * [build-tools][eas-cli] report the egress token separately from the fixed username * [build-tools][eas-cli] harden local egress startup and proxy resource limits * [build-tools][eas-cli] support local egress across iOS simulator controllers * [build-tools] allow local egress reverse remotes on unprivileged loopback ports iOS never sends loopback-literal requests to the system proxy, and Expo CLI rewrites localhost to 127.0.0.1 in manifests, so a dev server allowed as localhost:<port> could not serve bundles through the proxy. Let the EAS CLI open one chisel reverse remote per loopback allow entry (like adb reverse) by permitting reverse remotes on any unprivileged loopback port, not only the proxy port. Other interfaces and privileged ports stay denied. * [eas-cli] stop logging completed proxied responses as failed in the local egress client Releasing a proxy operation aborts its shared signal after the response has been sent, which errors the already-completed upstream request and logged "failed: The operation was aborted" for every successful plain-HTTP request in debug output. Track completion (response end or upgrade handoff) and treat the late abort as cleanup. Truncated upstream responses still log as failed.	2026-09-10 14:12:01 -07:00
Stanisław Chmiela	ee3c62683b	[build-tools] Require project source refresh for remote builds (#4359 ) # Why I want to start skipping authenticated repository URL in the job payload. We never expect to use it — we'd rather use the just-loaded one from www. # How Change fallback to a `SystemError`. # Test Plan CI should pass.	2026-09-10 22:40:41 +02:00
Gabe Debes	8ac9d5f101	[build-tools] gate serve-sim with the session token (#4306 ) * [eas-cli] gate device-run-session serve-sim with the session token * [eas-cli] describe the state the missing-token check actually catches * [eas-cli] match the missing-token test to the message it asserts	2026-09-09 17:40:01 -07:00
Expo CI	1eaa799b9f	bump STAGING and PRODUCTION to 24.0.0 in cli-versions.json	2026-09-09 20:13:34 +00:00
Expo CI	bb0f2dfb21	update CHANGELOG.md for v24.0.0	2026-09-09 20:11:16 +00:00