expo-devbox 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brent Vatne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,180 @@
-# Temporary Holding Version
+# expo-devbox
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build and test your Expo app's native iOS code on an EAS macOS worker instead of your own machine. You, or your coding agent, edit files locally; `expo-devbox build` syncs them to a worker that stays up for the session, runs an incremental Xcode build, launches the app on the worker's iOS Simulator, and reports what happened.
+
+It is for work that rebuilds native code over and over, such as an agent iterating on an [Expo module](https://docs.expo.dev/modules/overview/), when those rebuilds are too heavy for your machine.
+
+**iOS only for now.** Android support, on an EAS Linux worker with the Android Emulator, will be added to this tool shortly.
+
+```
+$ bunx expo-devbox build
+BUILD SUCCEEDED in 5s
+App console output from this launch:
+ LOG  [native-crypto] PASS sha384("abc"): cb00753f…
+ LOG  [native-crypto] DONE 7/7 passed
+Native log from this launch (system libraries excluded):
+2026-10-24 16:59:04.278 Df myapp[6954:97f5] (Foundation) [native-crypto] module created
+Screenshot copied to .devbox/screenshot.png
+```
+
+> [!NOTE]
+> SSH support for EAS Workflows is coming soon (`eas workflow:run --ssh` and `eas workflow:ssh`). It will cover about half of what this tool does: the SSH server, the Cloudflare tunnel, finding the worker, and ending idle sessions. The other half stays: syncing your files, incremental builds, launching the app and checking its logs, crash reports, `devbox.json`, and the instructions for coding agents. When workflow SSH ships, `expo-devbox` will use it.
+
+## Set it up with your coding agent
+
+Paste this into your coding agent, in your Expo app:
+
+```text
+Set up expo-devbox (https://www.npmjs.com/package/expo-devbox) in this Expo app, so that you build and test native iOS code on an EAS macOS worker instead of this machine.
+
+1. Check the requirements: bun 1.3 or later, eas-cli logged in (`eas whoami`), and cloudflared (`brew install cloudflared` if it is missing). If the app has no EAS project ID in its app config, run `eas init`.
+2. Run `bunx expo-devbox init` in the app's root directory.
+3. Read the "Native iOS builds on EAS (expo-devbox)" section that init added to AGENTS.md or CLAUDE.md, and follow it from now on.
+4. If the app logs a line when it is ready or when a self-test passes or fails, set `waitFor` and `failOn` in devbox.json to regular expressions for those lines.
+5. Ask me before you run `bunx expo-devbox start`: a session bills EAS macOS minutes while it runs. Then run `bunx expo-devbox build`, tell me the result, and run `bunx expo-devbox stop` when we are done.
+```
+
+## Requirements
+
+- An Expo app linked to an EAS project (`eas init`), on a plan with macOS workflow minutes. A session holds one macOS concurrency slot and is billed for as long as it runs. Check your plan's price and job time limits.
+- [Bun](https://bun.sh) 1.3 or later, and `eas-cli`, logged in.
+- `cloudflared`: `brew install cloudflared`.
+
+## Set up
+
+In the root of your app:
+
+```sh
+bunx expo-devbox init
+```
+
+`init` does the following:
+
+- writes the workflow to `.eas/workflows/ios-devbox.yml`,
+- writes `devbox.json`,
+- adds `.devbox/` to `.gitignore`,
+- adds instructions for coding agents to `AGENTS.md` or `CLAUDE.md`. If neither file exists, it prints them instead; see [Coding agents](#coding-agents).
+
+Then:
+
+```sh
+bunx expo-devbox start     # start a session: 60 minutes at most, ends after 15 idle minutes
+bunx expo-devbox build     # sync, build, launch, check
+bunx expo-devbox stop      # end the session
+```
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `start [minutes] [idle-minutes]` | Starts the workflow and waits until SSH works (about a minute). The worker then prepares the project: install, `expo prebuild`, `pod install`, simulator, Metro, and a first build. That takes about three more minutes. |
+| `build` | Syncs your files, builds, launches the app, prints its console and native logs, and copies the screenshot to `.devbox/screenshot.png`. |
+| `build --pods` | Same, after adding or removing native source files or editing a podspec. |
+| `build --prebuild` | Same, after changing `package.json`, the app config or a config plugin. |
+| `ssh [command]` | Runs a command in the project directory on the worker, or opens a shell. |
+| `logs [pattern]` | Searches the app's console output from Metro. |
+| `sync` | Copies your files to the worker without building. |
+| `attach [run-id]` | Reconnects to a running session. `build` reconnects on its own. |
+| `joblog` | Prints the workflow job's log. |
+| `stop` | Cancels the session and waits until EAS confirms that it has ended. |
+
+`build` exits non-zero, and says why, when:
+
+- the build fails: it prints the compiler errors with file and line,
+- the app is not running after launch: it prints the exception and the crashing frames,
+- the app does not log a line matching `waitFor`, or logs one matching `failOn`.
+
+## devbox.json
+
+| Key | Meaning |
+| --- | --- |
+| `waitFor` | A regular expression for a line your app logs when it is ready, for example when its self-test finishes. `build` waits for it, up to `waitSeconds`, and fails if it never appears. Without it, `build` waits 8 seconds. |
+| `failOn` | A regular expression for a line that means failure. `build` exits non-zero if the app logs it. |
+| `waitSeconds` | How long to wait for `waitFor`. The default is 60. |
+| `scheme` | The Xcode scheme, when it is not named after the `.xcworkspace`. |
+
+## Coding agents
+
+`init` adds the following to `AGENTS.md` or `CLAUDE.md`. Copy it into your agent's instructions if you use another file:
+
+```markdown
+## Native iOS builds on EAS (expo-devbox)
+
+Compile and test native iOS code on an EAS macOS worker with `bunx expo-devbox`, not on this machine. Do not run `npx expo run:ios` or `xcodebuild` locally.
+
+1. Start a session once: `bunx expo-devbox start`. It bills EAS macOS minutes until `stop`, its time limit (60 minutes by default), or 15 minutes without a connection.
+2. After each change, run `bunx expo-devbox build`. Add `--pods` after adding or removing native source files or editing a podspec, and `--prebuild` after changing package.json, the app config or a config plugin.
+3. `build` syncs your files, compiles, launches the app on the worker's iOS Simulator, and prints the app's console and native logs. It exits non-zero on a compile error (with file and line), a crash at launch (with the crashing frames), or a failed check from devbox.json. Read the output, fix the code, and build again. The screenshot is `.devbox/screenshot.png`.
+4. `bunx expo-devbox ssh '<command>'` runs a command in the project directory on the worker, for example `xcrun simctl list devices booted`.
+5. When you are done, run `bunx expo-devbox stop`.
+```
+
+To check results without reading pixels, have your app log a line when its checks pass or fail, and set `waitFor` and `failOn`.
+
+In a terminal that supports the [Program Status Protocol](https://mitchellh.com/writing/program-status-osc7501) (OSC 7501), such as Ghostty, `start`, `build` and `stop` report their status: working, done, error, or blocked when the run needs approval. The CLI sends these reports only when its stderr is a terminal, so output that an agent captures never contains them.
+
+## How it works
+
+The workflow runs one custom job on `macos-large` in the `development` environment:
+
+1. **SSH.** It starts `sshd` as the build user on `127.0.0.1:2222`. Only the key `~/.ssh/eas_devbox`, created by `start`, can log in. SSH sessions get the toolchain variables (`PATH`, Ruby, nvm) but not the job's EAS environment variables or its `EXPO_TOKEN`. The job itself still has them, and the SSH user is the job user, so do not give a session to someone who should not see the development environment.
+2. **Tunnel.** EAS workers accept no inbound connections, so the worker opens a pinned `cloudflared` [quick tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/), and Cloudflare relays your connection to it. The job log prints the tunnel host and the worker's SSH host key; the CLI reads them with `eas workflow:logs` and pins the key. Quick tunnels have no uptime guarantee. If the tunnel exits, the worker opens a new one and `build` reconnects.
+3. **Preparation.** It runs `expo prebuild` (skipped when the project commits `ios/`) and `pod install`, and boots an iPhone simulator. It starts Metro with `CI` unset, because with `CI=true` Metro ignores file changes. Then it runs a first Debug build.
+4. **Session.** The job stays up until `minutes` after it started, or until no SSH connection has been open for `idle-minutes`. It restarts Metro if Metro stops responding.
+
+`sync` sends what git would track. Patterns from `.gitignore` are excluded, so local secrets such as `.env.local` stay local and files that the worker generated are not deleted. `.gitignore` lines that start with `!` are not supported.
+
+Steps 1 and 2, and the idle shutdown in step 4, exist because EAS Workflows does not offer SSH yet. Workflow SSH is coming soon and will replace them; see the note at the top.
+
+## Limits
+
+- iOS only. Android support will be added shortly.
+- One app per project root. Monorepos with dependencies outside the app directory are not supported.
+- `build --prebuild` reinstalls dependencies with the package manager whose lockfile is present.
+- Private npm packages need their token as an EAS environment variable in the `development` environment.
+
+## Turn off the intro
+
+`expo-devbox` and `expo-devbox init` open with an animated wordmark when you run them in a terminal. Set `EXPO_DEVBOX_INTRO=off` to skip it, or set it to `slider`, `decrypt`, `beams`, `snap` or `slide` to pick one.
+
+## Developing expo-devbox
+
+The CLI is at the root of this repository: `src/` holds the commands and the worker script, `templates/` holds the workflow that `init` writes, and `test/` holds the unit tests.
+
+```sh
+bun install
+bun run typecheck
+bun test
+bun link && bun install -g .    # put this checkout on your PATH as expo-devbox
+```
+
+### The example app
+
+[`example/`](example) is the app to test the CLI against, end to end, on a real EAS worker. It has a local Expo module, [`modules/native-crypto`](example/modules/native-crypto). The module wraps CryptoKit SHA-256, SHA-384, SHA-512 and HMAC-SHA256, and `SecRandomCopyBytes`. On launch, [`App.tsx`](example/App.tsx) checks the module against published test vectors (FIPS 180-2 and RFC 4231). It logs a `[native-crypto] PASS` or `FAIL` line for each check, then `[native-crypto] DONE`. [`devbox.json`](example/devbox.json) makes `build` wait for `DONE` and fail on `FAIL`.
+
+The example does not depend on `expo-devbox`. Run the linked CLI from the example's directory:
+
+```sh
+cd example
+bun install
+expo-devbox start
+expo-devbox build
+expo-devbox stop
+```
+
+To use your own EAS account, delete `owner` and `extra.eas` from `example/app.json` and run `eas init` in `example/`.
+
+Before a release, run these checks in the example. Edit the app, run `expo-devbox build`, and check the exit code and the message; then revert the edit.
+
+| Change | Expected result |
+| --- | --- |
+| None | exit 0, `DONE 7/7 passed`, the `module created` line in the native log |
+| A wrong expected value in `App.tsx` | exit 1, `matching failOn` |
+| A Swift type error | exit 1, the error with file and line |
+| `fatalError()` in the module's `OnCreate` | exit 1, the crash report frames |
+| `build --prebuild` | exit 0 |
+| `.env.local` present, then `sync` | the file is not on the worker |
+| `expo-devbox ssh 'pkill -9 cloudflared'`, then `build` | `build` reconnects on its own, exit 0 |
+| `stop` | `The devbox session is canceled.` |
+
+After you change `templates/ios-devbox.yml`, run `expo-devbox init --force --no-agents` in `example/` to update its workflow.

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "expo-devbox",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Build and test an Expo app's native iOS code on an EAS macOS worker, from your terminal or a coding agent.",
+  "type": "module",
+  "bin": {
+    "expo-devbox": "src/cli.ts"
+  },
+  "files": [
+    "src",
+    "templates"
+  ],
+  "engines": {
+    "bun": ">=1.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.4",
+    "typescript": "^7.0.2"
+  },
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env bun
+import { init } from './init';
+import { playIntro } from './intro';
+import { attach, build, joblog, logs, shell, start, stop, sync, UserError } from './session';
+import { status } from './status';
+
+const HELP = `Build and test an Expo app's native iOS code on an EAS macOS worker,
+from your terminal or a coding agent.
+
+Usage: expo-devbox <command>
+
+  init [--force] [--no-agents]      add the devbox workflow to this Expo app
+  start [minutes] [idle-minutes]    start a session (default 60 and 15); wait until SSH works
+  build [--pods|--prebuild]         sync, build with Xcode, launch, print logs, copy the screenshot
+  ssh [command]                     run a command in the project on the worker, or open a shell
+  logs [pattern]                    search the app's console output
+  sync                              copy local sources to the worker
+  attach [run-id]                   reconnect to a running session
+  joblog                            print the workflow job's log
+  stop                              cancel the session and wait until it has ended
+
+Requires a logged-in eas-cli and cloudflared (brew install cloudflared).
+Docs: https://www.npmjs.com/package/expo-devbox`;
+
+const commands: Record<string, (args: string[]) => unknown> = {
+  init, start, build, ssh: shell, logs, sync, attach, joblog, stop,
+};
+
+const [name, ...args] = process.argv.slice(2);
+if (!name || name === 'help' || name === '--help' || name === '-h') {
+  if (process.stdout.isTTY) await playIntro();
+  console.log(HELP);
+} else if (name === 'version' || name === '--version' || name === '-v') {
+  console.log((await import('../package.json')).version);
+} else if (!commands[name]) {
+  console.error(`Unknown command "${name}". Run expo-devbox help to see the commands.`);
+  process.exitCode = 1;
+} else {
+  try {
+    if (name === 'init' && process.stdout.isTTY) await playIntro();
+    await commands[name](args);
+  } catch (error) {
+    status('error', { msg: error instanceof Error ? error.message.split('\n')[0] : String(error) });
+    if (error instanceof UserError) {
+      console.error(error.message);
+    } else if (error && typeof error === 'object' && 'exitCode' in error && 'stderr' in error) {
+      // A failed shell command: show what it printed.
+      console.error(`${String(error.stderr).trim() || 'A command failed.'} (exit ${error.exitCode})`);
+    } else {
+      throw error;
+    }
+    process.exitCode = 1;
+  }
+}

package/src/init.ts

@@ -0,0 +1,67 @@
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import { UserError, WORKFLOW } from './session';
+
+const TEMPLATE = join(import.meta.dir, '..', 'templates', 'ios-devbox.yml');
+
+/** The section `init` adds to AGENTS.md or CLAUDE.md, and prints when neither exists. */
+export const AGENT_INSTRUCTIONS = `## Native iOS builds on EAS (expo-devbox)
+
+Compile and test native iOS code on an EAS macOS worker with \`bunx expo-devbox\`, not on this machine. Do not run \`npx expo run:ios\` or \`xcodebuild\` locally.
+
+1. Start a session once: \`bunx expo-devbox start\`. It bills EAS macOS minutes until \`stop\`, its time limit (60 minutes by default), or 15 minutes without a connection.
+2. After each change, run \`bunx expo-devbox build\`. Add \`--pods\` after adding or removing native source files or editing a podspec, and \`--prebuild\` after changing package.json, the app config or a config plugin.
+3. \`build\` syncs your files, compiles, launches the app on the worker's iOS Simulator, and prints the app's console and native logs. It exits non-zero on a compile error (with file and line), a crash at launch (with the crashing frames), or a failed check from devbox.json. Read the output, fix the code, and build again. The screenshot is \`.devbox/screenshot.png\`.
+4. \`bunx expo-devbox ssh '<command>'\` runs a command in the project directory on the worker, for example \`xcrun simctl list devices booted\`.
+5. When you are done, run \`bunx expo-devbox stop\`.
+`;
+
+export function init(args: string[]) {
+  const force = args.includes('--force');
+  const skipAgents = args.includes('--no-agents');
+  if (!existsSync('package.json')) throw new UserError('No package.json here. Run expo-devbox init in the root of your Expo app.');
+  const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+  if (!pkg.dependencies?.expo) throw new UserError('This project does not depend on expo. expo-devbox works with Expo apps.');
+
+  const done: string[] = [];
+  if (existsSync(WORKFLOW) && !force) {
+    done.push(`Kept the existing ${WORKFLOW} (use --force to replace it).`);
+  } else {
+    mkdirSync(dirname(WORKFLOW), { recursive: true });
+    copyFileSync(TEMPLATE, WORKFLOW);
+    done.push(`Wrote ${WORKFLOW}.`);
+  }
+
+  if (!existsSync('devbox.json')) {
+    writeFileSync('devbox.json', `${JSON.stringify({ waitFor: '', failOn: '' }, null, 2)}\n`);
+    done.push('Wrote devbox.json. Set waitFor and failOn to regular expressions that match lines your app logs, so build waits for them and fails on them.');
+  }
+
+  const gitignore = existsSync('.gitignore') ? readFileSync('.gitignore', 'utf8') : '';
+  if (!/^\/?\.devbox\/?$/m.test(gitignore)) {
+    appendFileSync('.gitignore', `${gitignore && !gitignore.endsWith('\n') ? '\n' : ''}\n# expo-devbox session state\n.devbox/\n`);
+    done.push('Added .devbox/ to .gitignore.');
+  }
+
+  if (!skipAgents) {
+    const file = ['AGENTS.md', 'CLAUDE.md'].find(name => existsSync(name));
+    if (file && readFileSync(file, 'utf8').includes('expo-devbox')) {
+      done.push(`${file} already mentions expo-devbox.`);
+    } else if (file) {
+      appendFileSync(file, `\n${AGENT_INSTRUCTIONS}`);
+      done.push(`Added instructions for coding agents to ${file}.`);
+    } else {
+      done.push(`No AGENTS.md or CLAUDE.md. Add this to the instructions your coding agent reads:\n\n${AGENT_INSTRUCTIONS}`);
+    }
+  }
+
+  const appJson = existsSync('app.json') ? JSON.parse(readFileSync('app.json', 'utf8')) : undefined;
+  const linked = appJson?.expo?.extra?.eas?.projectId;
+  console.log(done.map(line => `• ${line}`).join('\n'));
+  console.log(`
+Next:
+  ${linked ? '' : 'eas init                    link this project to EAS, if it is not linked yet\n  '}brew install cloudflared    the SSH tunnel client
+  bunx expo-devbox start      start a session (EAS macOS minutes are billed while it runs)
+  bunx expo-devbox build      build, launch and check the app on the worker`);
+}

package/src/intro.ts

@@ -0,0 +1,141 @@
+/**
+ * The "expo devbox" wordmark the CLI opens with when a person runs it in a
+ * terminal, and the five ways it can arrive. One is picked at random each
+ * launch (EXPO_DEVBOX_INTRO names one, or `off`). Each intro is a function of
+ * progress t (0..1) to the wordmark's two rows, so it can be drawn at any
+ * frame rate and tested without a terminal. Adapted from Expo Explore.
+ */
+export type Paint = Record<'white' | 'text' | 'dim' | 'faint' | 'amber' | 'green' | 'yellow' | 'blue' | 'red', (text: string) => string>;
+export type Intro = { duration: number; frame: (t: number, paint: Paint) => string[] };
+
+const sgr = (code: string) => (text: string) => `\x1b[${code}m${text}\x1b[0m`;
+export const COLOR: Paint = {
+  white: sgr('1;97'), text: sgr('97'), dim: sgr('38;5;244'), faint: sgr('38;5;238'), amber: sgr('38;5;214'),
+  green: sgr('38;5;114'), yellow: sgr('38;5;221'), blue: sgr('38;5;111'), red: sgr('38;5;203'),
+};
+export const PLAIN: Paint = {
+  white: s => s, text: s => s, dim: s => s, faint: s => s, amber: s => s, green: s => s, yellow: s => s, blue: s => s, red: s => s,
+};
+
+// A two-row pixel font: one column between letters, three between words.
+const GLYPHS: Record<string, [string, string]> = {
+  b: ['█▄▄', '█▄█'], d: ['█▀▄', '█▄▀'], e: ['█▀▀', '██▄'], o: ['█▀█', '█▄█'],
+  p: ['█▀█', '█▀▀'], v: ['█ █', '▀▄▀'], x: ['▀▄▀', '█ █'],
+};
+export const WORDMARK: string[] = [0, 1].map(row =>
+  'expo devbox'.split(' ').map(word => [...word].map(letter => GLYPHS[letter]![row]).join(' ')).join('   '));
+const WIDTH = WORDMARK[0]!.length;
+const NOISE = [...'░▒▓▚▞▖▗▘▝◆◇○●■□▪▫'];
+
+const ease = (t: number) => 1 - (1 - t) ** 3;
+/** A small seeded random, so an intro plays the same way for the same seed (and in tests). */
+function seeded(seed: number): () => number {
+  let state = seed % 2147483647 || 1;
+  return () => {
+    state = (state * 16807) % 2147483647;
+    return state / 2147483647;
+  };
+}
+const cells = (fn: (ch: string, row: number, column: number) => string) =>
+  WORDMARK.map((row, r) => [...row].map((ch, c) => fn(ch, r, c)).join(''));
+
+export function intros(seed = 7): Record<IntroName, Intro> {
+  const random = seeded(seed);
+  // decrypt: when each letter locks in.
+  const lock = WORDMARK.map(row => [...row].map(() => 0.3 + random() * 0.6));
+  // snap: letters start in each other's places and each snaps home at its own moment.
+  const swaps = WORDMARK.map(row => {
+    const map = [...row].map((_, c) => c);
+    const letters = map.filter(c => row[c] !== ' ');
+    for (let i = 0; i < letters.length * 0.35; i += 1) {
+      const a = letters[Math.floor(random() * letters.length)]!;
+      const b = letters[Math.floor(random() * letters.length)]!;
+      [map[a], map[b]] = [map[b]!, map[a]!];
+    }
+    return map.map((from, c) => ({ from, at: from === c ? 0 : 0.3 + random() * 0.5 }));
+  });
+  const noise = () => NOISE[Math.floor(random() * NOISE.length)]!;
+  return {
+    // A compare slider: the crisp wordmark behind the handle, a faded one ahead of it.
+    slider: { duration: 600, frame: (t, paint) => {
+      const at = Math.round(ease(t) * WIDTH);
+      return cells((ch, _r, c) => c === at && t < 1 ? paint.amber('┃') : c < at ? paint.white(ch) : paint.faint(ch === ' ' ? ' ' : '░'));
+    } },
+    // Every letter cycles through noise, then locks in with an amber flash.
+    decrypt: { duration: 900, frame: (t, paint) => cells((ch, r, c) => {
+      if (ch === ' ') return ' ';
+      const at = lock[r]![c]!;
+      if (t < at) return (t < 0.15 ? paint.faint : paint.blue)(noise());
+      return t < at + 0.07 ? paint.amber(ch) : paint.white(ch);
+    }) },
+    // A diagonal beam of light draws the wordmark as it passes.
+    beams: { duration: 700, frame: (t, paint) => {
+      const beam = t * (WIDTH + 16) - 6;
+      return cells((ch, r, c) => {
+        const distance = c + r * 3 - beam;
+        return distance > 0 ? ' ' : distance > -3 ? paint.amber(ch === ' ' ? '·' : ch) : distance > -6 ? paint.yellow(ch) : paint.white(ch);
+      });
+    } },
+    // A build fixing itself: misplaced letters (amber) snap home (green), then settle.
+    snap: { duration: 900, frame: (t, paint) => cells((ch, r, c) => {
+      const { from, at } = swaps[r]![c]!;
+      const original = WORDMARK[r]![from]!;
+      if (t < 0.12) return paint.faint(original === ' ' ? ' ' : '░');
+      if (at === 0) return paint.text(ch);
+      if (t < at) return paint.amber(original);
+      return t < at + 0.1 ? paint.green(ch) : paint.white(ch);
+    }) },
+    // Letters glide in from the right one after another, gray to white.
+    slide: { duration: 800, frame: (t, paint) => WORDMARK.map(row => {
+      const out = Array.from({ length: WIDTH + 24 }, () => ' ');
+      for (let c = 0; c < WIDTH; c += 1) {
+        if (row[c] === ' ') continue;
+        const local = Math.min(1, Math.max(0, (t - (c / WIDTH) * 0.5) / 0.5));
+        if (local === 0) continue;
+        out[c + Math.round((1 - ease(local)) * 24)] = (local < 1 ? paint.dim : paint.white)(row[c]!);
+      }
+      return out.join('').trimEnd();
+    }) },
+  };
+}
+
+export const INTRO_NAMES = ['slider', 'decrypt', 'beams', 'snap', 'slide'] as const;
+export type IntroName = (typeof INTRO_NAMES)[number];
+
+/** EXPO_DEVBOX_INTRO when it names one (or `off`), otherwise a random one. */
+export function pickIntro(environment: NodeJS.ProcessEnv, random = Math.random): IntroName | undefined {
+  const chosen = environment.EXPO_DEVBOX_INTRO?.trim().toLowerCase();
+  if (chosen === 'off' || chosen === 'none') return undefined;
+  if (chosen && (INTRO_NAMES as readonly string[]).includes(chosen)) return chosen as IntroName;
+  return INTRO_NAMES[Math.floor(random() * INTRO_NAMES.length)];
+}
+
+/**
+ * Plays an intro in place and leaves the finished wordmark on screen. Only for
+ * a person at a color terminal: agents and CI get plain output.
+ */
+export async function playIntro(output: NodeJS.WriteStream = process.stdout): Promise<void> {
+  const color = output.isTTY && !process.env.NO_COLOR && !process.env.CI;
+  const paint = color ? COLOR : PLAIN;
+  // A width of 0 means the terminal did not report one.
+  const name = color && (output.columns || 80) >= WIDTH + 6 ? pickIntro(process.env) : undefined;
+  const indent = (rows: string[]) => rows.map(row => `   ${row}`);
+  if (!name) {
+    output.write(`\n${indent(WORDMARK.map(row => paint.white(row))).join('\n')}\n\n`);
+    return;
+  }
+  const intro = intros(Date.now())[name];
+  const restore = () => output.write('\x1b[?25h');
+  process.once('exit', restore);
+  output.write(`\x1b[?25l\n${'\n'.repeat(WORDMARK.length)}`);
+  const start = Date.now();
+  for (;;) {
+    const t = Math.min(1, (Date.now() - start) / intro.duration);
+    output.write(`\x1b[${WORDMARK.length}A${indent(intro.frame(t, paint)).map(row => `\r${row}\x1b[K`).join('\n')}\n`);
+    if (t === 1) break;
+    await Bun.sleep(16);
+  }
+  restore();
+  process.removeListener('exit', restore);
+  output.write('\n');
+}

package/src/session.ts

@@ -0,0 +1,280 @@
+/**
+ * The session commands: start a devbox workflow run, connect to its worker
+ * over SSH through the Cloudflare tunnel it opens, sync sources, build, and
+ * stop it. Run from the project root.
+ */
+import { $ } from 'bun';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { status } from './status';
+
+export const WORKFLOW = '.eas/workflows/ios-devbox.yml';
+const STATE = '.devbox';
+const SSH_CONFIG = join(STATE, 'ssh_config');
+const RUN_ID = join(STATE, 'run_id');
+const KEY = join(homedir(), '.ssh', 'eas_devbox');
+const WORKER_SCRIPT = join(import.meta.dir, 'worker-build.ts');
+const ACTIVE = new Set(['NEW', 'WAITING', 'IN_PROGRESS', 'ACTION_REQUIRED']);
+
+/** An error whose message is meant for the person or agent running the command. */
+export class UserError extends Error {}
+const fail = (message: string): never => {
+  throw new UserError(message);
+};
+const log = (message: string) => console.error(message);
+const sleep = (seconds: number) => Bun.sleep(seconds * 1000);
+/** Quotes a value for the worker's shell. */
+const quote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
+
+type Run = { status: string; jobs?: { id: string }[] };
+
+async function viewRun(runId: string): Promise<Run | undefined> {
+  const result = await $`eas workflow:view ${runId} --json --non-interactive`.quiet().nothrow();
+  try {
+    return result.exitCode === 0 ? JSON.parse(result.stdout.toString()) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Fails when the run has ended. A run that cannot be read (a network error) counts as running. */
+async function requireActive(runId: string): Promise<Run | undefined> {
+  const run = await viewRun(runId);
+  if (run && !ACTIVE.has(run.status)) {
+    fail(`The devbox session ended with status ${run.status}. See: eas workflow:view ${runId}`);
+  }
+  if (run?.status === 'ACTION_REQUIRED') {
+    status('blocked', { kind: 'permission', msg: 'The devbox workflow run needs approval on expo.dev' });
+  }
+  return run;
+}
+
+function savedRun(): string {
+  if (!existsSync(RUN_ID)) fail('No devbox session. Start one with: expo-devbox start');
+  return readFileSync(RUN_ID, 'utf8').trim();
+}
+
+function requireProject() {
+  if (!existsSync(WORKFLOW)) fail(`${WORKFLOW} is missing. Run expo-devbox init in the project root first.`);
+  mkdirSync(STATE, { recursive: true });
+}
+
+function ssh(remoteCommand: string) {
+  return $`ssh -F ${SSH_CONFIG} devbox ${remoteCommand}`;
+}
+
+/**
+ * Reads the tunnel host, user and host key from the job log and writes an SSH
+ * config for them. The last DEVBOX_SSH_HOST wins, because the worker starts a
+ * new tunnel, with a new host, if the old one exits. A host that does not
+ * answer is skipped until a newer one appears in the log.
+ */
+async function connect(runId: string): Promise<void> {
+  log(`Waiting for the worker to open its tunnel (run ${runId})...`);
+  status('working', { msg: 'Waiting for the EAS worker' });
+  let deadHost = '';
+  const deadline = Date.now() + 15 * 60_000;
+  while (Date.now() < deadline) {
+    const jobId = (await requireActive(runId))?.jobs?.[0]?.id;
+    if (jobId) {
+      const logs = (await $`eas workflow:logs ${jobId} --non-interactive`.quiet().nothrow()).stdout.toString();
+      const last = (pattern: RegExp) => [...logs.matchAll(pattern)].at(-1)?.[1];
+      const host = last(/DEVBOX_SSH_HOST=([a-z0-9.-]+)/g);
+      const user = last(/DEVBOX_SSH_USER=([A-Za-z0-9_-]+)/g);
+      const hostKey = last(/DEVBOX_SSH_HOSTKEY=(ssh-ed25519 [A-Za-z0-9+/=]+)/g);
+      if (host && user && hostKey && host !== deadHost) {
+        writeSshConfig(host, user, hostKey);
+        let error = '';
+        // A new quick tunnel can take a few seconds to resolve in DNS.
+        for (let attempt = 0; attempt < 8; attempt += 1) {
+          const result = await $`ssh -F ${SSH_CONFIG} devbox true`.quiet().nothrow();
+          if (result.exitCode === 0) {
+            log(`Connected to ${user}@${host}.`);
+            return;
+          }
+          error = result.stderr.toString().trim().split('\n').at(-1) ?? '';
+          await sleep(5);
+        }
+        log(`${host} does not answer (${error}). Waiting for the worker to open a new tunnel...`);
+        deadHost = host;
+      }
+    }
+    await sleep(10);
+  }
+  fail(`Could not reach the worker for 15 minutes. See: eas workflow:view ${runId}`);
+}
+
+function writeSshConfig(host: string, user: string, hostKey: string) {
+  writeFileSync(join(STATE, 'known_hosts'), `${host} ${hostKey}\n`);
+  writeFileSync(SSH_CONFIG, `Host devbox
+  HostName ${host}
+  User ${user}
+  ProxyCommand cloudflared access ssh --hostname %h
+  IdentityFile ${KEY}
+  IdentitiesOnly yes
+  StrictHostKeyChecking yes
+  UserKnownHostsFile ${resolve(STATE, 'known_hosts')}
+  ConnectTimeout 20
+  ServerAliveInterval 30
+  ControlMaster auto
+  ControlPath ~/.ssh/cm-devbox-%C
+  ControlPersist 5m
+`);
+}
+
+/** Waits for the worker to finish preparing the project. Reconnects if the worker is unreachable. */
+async function waitUntilReady(runId: string) {
+  const deadline = Date.now() + 20 * 60_000;
+  while (Date.now() < deadline) {
+    const result = await ssh('test -f ~/.devbox/ready').quiet().nothrow();
+    if (result.exitCode === 0) return;
+    if (result.exitCode === 255) {
+      await connect(runId);
+      continue;
+    }
+    await requireActive(runId);
+    log('Waiting for the worker to finish preparing the project...');
+    status('working', { msg: 'The EAS worker is preparing the project' });
+    await sleep(15);
+  }
+  fail('The worker is not ready after 20 minutes. See: expo-devbox joblog');
+}
+
+export async function start(args: string[]) {
+  requireProject();
+  if (!Bun.which('cloudflared')) fail('cloudflared is not installed. Install it with: brew install cloudflared');
+  if (existsSync(RUN_ID)) {
+    const previous = readFileSync(RUN_ID, 'utf8').trim();
+    const run = await viewRun(previous);
+    if (run && ACTIVE.has(run.status)) {
+      fail(`A devbox session is already running (run ${previous}). Use expo-devbox attach or expo-devbox stop.`);
+    }
+  }
+  const [minutes = '60', idleMinutes = '15'] = args;
+  if (!/^\d+$/.test(minutes) || !/^\d+$/.test(idleMinutes)) fail('Usage: expo-devbox start [minutes] [idle-minutes]');
+  if (!existsSync(KEY)) await $`ssh-keygen -q -t ed25519 -N ${''} -C eas-devbox -f ${KEY}`;
+  const publicKey = readFileSync(`${KEY}.pub`, 'utf8').trim();
+
+  status('working', { msg: 'Starting an EAS macOS worker' });
+  const result = await $`eas workflow:run ${WORKFLOW} --non-interactive --json -F ${`ssh_public_key=${publicKey}`} \
+    -F ${`minutes=${minutes}`} -F ${`idle_minutes=${idleMinutes}`}`.env({ ...process.env, EAS_NO_VCS: '1' }).quiet().nothrow();
+  if (result.exitCode !== 0) fail(`eas workflow:run failed:\n${result.stderr.toString().trim()}`);
+  const runId: string = JSON.parse(result.stdout.toString()).id;
+  writeFileSync(RUN_ID, runId);
+  log(`Started run ${runId}: ${minutes} minutes at most, ending after ${idleMinutes} idle minutes.`);
+
+  // Cancel the run if this command fails or is interrupted, so it does not bill with nobody connected.
+  const cancel = () => $`eas workflow:cancel ${runId} --non-interactive`.quiet().nothrow();
+  const onInterrupt = async () => {
+    log(`Cancelling run ${runId}.`);
+    await cancel();
+    status('idle');
+    process.exit(130);
+  };
+  process.once('SIGINT', onInterrupt);
+  try {
+    await connect(runId);
+  } catch (error) {
+    log(`Cancelling run ${runId}.`);
+    await cancel();
+    throw error;
+  } finally {
+    process.removeListener('SIGINT', onInterrupt);
+  }
+  log(`The worker is still preparing the project. 'expo-devbox build' waits for it.`);
+  status('done', { msg: 'Connected to the EAS worker' });
+}
+
+export async function attach(args: string[]) {
+  requireProject();
+  const runId = args[0] ?? savedRun();
+  writeFileSync(RUN_ID, runId);
+  await connect(runId);
+  status('done', { msg: 'Connected to the EAS worker' });
+}
+
+/**
+ * Sends what git would track. .gitignore patterns also protect worker-only
+ * files (such as a generated ios/) from --delete. rsync cannot express
+ * gitignore's `!` re-includes, so those lines are dropped.
+ */
+export async function sync() {
+  requireProject();
+  const gitignore = existsSync('.gitignore')
+    ? readFileSync('.gitignore', 'utf8').split('\n').filter(line => !/^\s*!/.test(line))
+    : [];
+  const ignored = (await $`git ls-files -oi --exclude-standard --directory`.quiet().nothrow()).stdout.toString()
+    .split('\n').filter(Boolean).map(path => `/${path}`);
+  const excludes = join(STATE, 'rsync-excludes');
+  writeFileSync(excludes, [...gitignore, ...ignored].join('\n') + '\n');
+  await $`rsync -az --delete -e ${`ssh -F ${SSH_CONFIG}`} --exclude .git --exclude node_modules --exclude /.devbox \
+    --exclude /ios/Pods --exclude-from=${excludes} ./ devbox:project/`;
+}
+
+export async function build(args: string[]) {
+  requireProject();
+  const [option] = args;
+  if (option && option !== '--pods' && option !== '--prebuild') fail('Usage: expo-devbox build [--pods|--prebuild]');
+  const runId = savedRun();
+  status('working', { msg: 'Waiting for the EAS worker' });
+  await waitUntilReady(runId);
+  status('working', { msg: 'Syncing sources to the EAS worker' });
+  await sync();
+  await $`scp -q -F ${SSH_CONFIG} ${WORKER_SCRIPT} devbox:.devbox/worker-build.ts`;
+
+  status('working', { msg: option ? `Building on the EAS worker (${option.slice(2)})` : 'Building on the EAS worker' });
+  const screenshot = join(STATE, 'screenshot.png');
+  rmSync(screenshot, { force: true });
+  const result = await ssh(`cd ~/project && bun ~/.devbox/worker-build.ts ${option ?? ''}`).nothrow();
+  if ((await $`scp -q -F ${SSH_CONFIG} devbox:.devbox/screenshot.png ${screenshot}`.quiet().nothrow()).exitCode === 0) {
+    console.log(`Screenshot copied to ${screenshot}`);
+  }
+  const summary = result.stdout.toString().match(/BUILD (SUCCEEDED|FAILED)[^\n]*/)?.[0];
+  if (result.exitCode === 0) {
+    status('done', { msg: summary ?? 'Build succeeded' });
+  } else {
+    status('error', { msg: summary?.startsWith('BUILD FAILED') ? summary : 'The app failed its checks; see the output' });
+  }
+  process.exitCode = result.exitCode;
+}
+
+export async function logs(args: string[]) {
+  requireProject();
+  await ssh(`grep -a -E ${quote(args[0] ?? '.')} ~/.devbox/metro.log | tail -50`).nothrow();
+}
+
+export async function shell(args: string[]) {
+  requireProject();
+  if (args.length === 0) {
+    const child = Bun.spawn(['ssh', '-F', SSH_CONFIG, '-t', 'devbox', 'cd ~/project && exec $SHELL'],
+      { stdio: ['inherit', 'inherit', 'inherit'] });
+    process.exitCode = await child.exited;
+    return;
+  }
+  process.exitCode = (await ssh(`cd ~/project && ${args.join(' ')}`).nothrow()).exitCode;
+}
+
+export async function joblog() {
+  requireProject();
+  const jobId = (await viewRun(savedRun()))?.jobs?.[0]?.id;
+  if (!jobId) fail('Could not find the job of the devbox run. See: eas workflow:view ' + savedRun());
+  await $`eas workflow:logs ${jobId} --non-interactive`.nothrow();
+}
+
+export async function stop() {
+  requireProject();
+  const runId = savedRun();
+  status('working', { msg: 'Ending the devbox session' });
+  await $`eas workflow:cancel ${runId} --non-interactive`.quiet().nothrow();
+  // eas workflow:cancel exits 0 even when it fails, so wait for the run's final status instead.
+  const result = await $`eas workflow:status ${runId} --wait --non-interactive`.quiet().nothrow();
+  await $`ssh -F ${SSH_CONFIG} -O exit devbox`.quiet().nothrow();
+  const ended: Record<number, string> = { 0: 'had already finished', 11: 'had already failed', 12: 'is canceled' };
+  if (!(result.exitCode in ended)) {
+    fail(`Could not confirm that run ${runId} ended (eas workflow:status exited ${result.exitCode}). Check: eas workflow:view ${runId}`);
+  }
+  console.log(`The devbox session ${ended[result.exitCode]}.`);
+  status('done', { msg: 'Devbox session ended' });
+}

package/src/status.ts

@@ -0,0 +1,29 @@
+/**
+ * Reports what the CLI is doing to the terminal with the Program Status
+ * Protocol (OSC 7501): https://www.superlogical.com/rex/docs/build/program-status
+ * Terminals that do not implement it ignore the sequence. Reports go to stderr,
+ * and only when stderr is a terminal, so captured output (an agent, CI, a pipe)
+ * never contains them.
+ */
+export type State = 'idle' | 'working' | 'done' | 'blocked' | 'error' | 'clear';
+export type Report = { msg?: string; progress?: number; kind?: 'permission' | 'question' | 'auth' };
+
+const MAX_MSG_BYTES = 2048;
+
+/** Builds the escape sequence for a report. */
+export function formatStatus(state: State, report: Report = {}): string {
+  const pairs = [`state=${state}`, 'app=expo-devbox'];
+  if (report.kind && state === 'blocked') pairs.push(`kind=${report.kind}`);
+  if (report.progress !== undefined) pairs.push(`progress=${Math.max(0, Math.min(100, Math.round(report.progress)))}`);
+  if (report.msg) {
+    // One line of text, without control characters, within the spec's size limit.
+    let bytes = Buffer.from(report.msg.replace(/[\x00-\x1f\x7f]+/g, ' ').trim());
+    if (bytes.length > MAX_MSG_BYTES) bytes = bytes.subarray(0, MAX_MSG_BYTES);
+    pairs.push(`msg=${bytes.toString('base64')}`);
+  }
+  return `\x1b]7501;${pairs.join(':')}\x1b\\`;
+}
+
+export function status(state: State, report: Report = {}): void {
+  if (process.stderr.isTTY) process.stderr.write(formatStatus(state, report));
+}

package/src/worker-build.ts

@@ -0,0 +1,181 @@
+#!/usr/bin/env bun
+/**
+ * Runs on the devbox worker, in the project directory. Builds the iOS app with
+ * Xcode, installs it on the devbox simulator, launches it, and prints its logs.
+ * Exits non-zero when the build fails, the app is not running after launch, or
+ * the checks in devbox.json fail. `expo-devbox build` copies this file to the
+ * worker, so it must not import anything but Bun and Node built-ins.
+ *
+ *   worker-build.ts             incremental build
+ *   worker-build.ts --pods      run `pod install` first
+ *   worker-build.ts --prebuild  install dependencies, run `expo prebuild` and `pod install` first
+ */
+import { $ } from 'bun';
+import { appendFileSync, existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+
+type Config = { waitFor?: string; failOn?: string; waitSeconds?: number; scheme?: string };
+
+const state = join(homedir(), '.devbox');
+const config: Config = existsSync('devbox.json') ? JSON.parse(readFileSync('devbox.json', 'utf8')) : {};
+const waitSeconds = config.waitSeconds ?? (config.waitFor ? 60 : 8);
+const prepareLog = join(state, 'prepare.log');
+
+/** Runs a setup command with its output in prepare.log, which is printed only if the command fails. */
+async function prepare(label: string, command: () => Promise<{ exitCode: number; stdout: Buffer; stderr: Buffer }>) {
+  console.log(`Running: ${label}`);
+  const result = await command();
+  appendFileSync(prepareLog, `$ ${label}\n${result.stdout}${result.stderr}`);
+  if (result.exitCode !== 0) {
+    console.log(readFileSync(prepareLog, 'utf8').trimEnd().split('\n').slice(-30).join('\n'));
+    console.log(`FAILED: ${label}. Full log: ${prepareLog}`);
+    process.exit(1);
+  }
+}
+const podInstall = () => prepare('pod install', () => $`pod install`.cwd('ios').quiet().nothrow());
+
+writeFileSync(prepareLog, '');
+const flag = process.argv[2];
+if (flag === '--prebuild') {
+  const manager = existsSync('bun.lock') || existsSync('bun.lockb') ? 'bun'
+    : existsSync('pnpm-lock.yaml') ? 'pnpm' : existsSync('yarn.lock') ? 'yarn' : 'npm';
+  await prepare(`${manager} install`, () => $`${manager} install`.quiet().nothrow());
+  if (existsSync(join(state, 'cng'))) {
+    await prepare('expo prebuild', () => $`npx expo prebuild --platform ios --no-install`.quiet().nothrow());
+  }
+  await podInstall();
+} else if (flag === '--pods') {
+  await podInstall();
+} else if (flag) {
+  console.log(`Unknown option ${flag}. Use --pods or --prebuild.`);
+  process.exit(1);
+}
+
+const workspace = readdirSync('ios').find(name => name.endsWith('.xcworkspace'));
+if (!workspace) {
+  console.log('No .xcworkspace in ios/. Run the build again with --prebuild.');
+  process.exit(1);
+}
+const scheme = config.scheme || basename(workspace, '.xcworkspace');
+const udid = readFileSync(join(state, 'sim'), 'utf8').trim();
+const derived = join(state, 'DerivedData');
+const buildLog = join(state, 'xcodebuild.log');
+const screenshot = join(state, 'screenshot.png');
+rmSync(screenshot, { force: true });
+
+const start = Date.now();
+const seconds = () => Math.round((Date.now() - start) / 1000);
+const build = await $`xcodebuild -workspace ${`ios/${workspace}`} -scheme ${scheme} -configuration Debug -sdk iphonesimulator \
+  -destination ${`platform=iOS Simulator,id=${udid}`} -derivedDataPath ${derived} build &> ${buildLog}`.nothrow();
+if (build.exitCode !== 0) {
+  const lines = readFileSync(buildLog, 'utf8').split('\n');
+  const errors = [...new Set(lines.filter(line => /(error|fatal error):/.test(line)))].slice(0, 40);
+  console.log((errors.length ? errors : lines.slice(-30)).join('\n'));
+  console.log(`BUILD FAILED after ${seconds()}s. Full log: ${buildLog}`);
+  process.exit(1);
+}
+console.log(`BUILD SUCCEEDED in ${seconds()}s`);
+
+const metroUp = await fetch('http://localhost:8081/status').then(r => r.ok, () => false);
+if (!metroUp) {
+  console.log('Metro is not running. The worker restarts it within a minute; run the build again then.');
+  process.exit(1);
+}
+
+const products = join(derived, 'Build/Products/Debug-iphonesimulator');
+const app = join(products, readdirSync(products).find(name => name.endsWith('.app'))!);
+const plist = join(app, 'Info.plist');
+const plistValue = async (key: string) => (await $`/usr/libexec/PlistBuddy -c ${`Print :${key}`} ${plist}`.text()).trim();
+const bundleId = await plistValue('CFBundleIdentifier');
+const executable = await plistValue('CFBundleExecutable');
+const metroLog = join(state, 'metro.log');
+const nativeLog = join(state, 'native.log');
+const metroStart = readFileSync(metroLog).length;
+
+await $`xcrun simctl install ${udid} ${app}`;
+// Messages logged by code inside the app bundle, plus NSLog (sent from
+// Foundation, with no subsystem); not the system libraries' own logging.
+// `subsystem == ""` never matches, so "no subsystem" is written as no dot.
+const predicate = `process == "${executable}" AND (senderImagePath CONTAINS "/${executable}.app/" `
+  + `OR (senderImagePath ENDSWITH "/Foundation" AND NOT subsystem CONTAINS "."))`;
+const logStream = Bun.spawn(['xcrun', 'simctl', 'spawn', udid, 'log', 'stream', '--style', 'compact', '--predicate', predicate],
+  { stdout: Bun.file(nativeLog), stderr: 'ignore' });
+await $`xcrun simctl launch --terminate-running-process ${udid} ${bundleId}`.quiet();
+
+const appOutput = () => readFileSync(metroLog).subarray(metroStart).toString()
+  .split('\n').filter(line => /^ (LOG|WARN|ERROR) /.test(line)).join('\n');
+// Simulator apps run as processes of the host.
+const appRunning = async () => (await $`pgrep -f ${`/${executable}.app/${executable}`}`.quiet().nothrow()).exitCode === 0;
+const matches = (pattern: string | undefined) => !!pattern && new RegExp(pattern, 'm').test(appOutput());
+
+for (let i = 0; i < waitSeconds; i += 1) {
+  if (matches(config.waitFor)) break;
+  if (config.waitFor && i > 3 && !(await appRunning())) break;
+  await Bun.sleep(1000);
+}
+if ((await $`xcrun simctl io ${udid} screenshot ${screenshot}`.quiet().nothrow()).exitCode !== 0) {
+  console.log('Could not take a screenshot.');
+}
+logStream.kill();
+await logStream.exited;
+
+console.log('App console output from this launch:');
+console.log(appOutput() || '(none)');
+console.log('Native log from this launch (system libraries excluded):');
+const native = readFileSync(nativeLog, 'utf8').split('\n')
+  .filter(line => line && !/^(Filtering the log data|Timestamp |getpwuid_r |Child process terminated)/.test(line));
+console.log(native.slice(-40).join('\n') || '(none)');
+
+let status = 0;
+if (!(await appRunning())) {
+  console.log('The app is not running. It may have crashed at launch.');
+  await printCrashReport(executable, statSync(plist).mtimeMs);
+  status = 1;
+}
+if (config.waitFor && !matches(config.waitFor)) {
+  console.log(`The app did not log a line matching waitFor (${config.waitFor}).`);
+  status = 1;
+}
+if (matches(config.failOn)) {
+  console.log(`The app logged a line matching failOn (${config.failOn}).`);
+  status = 1;
+}
+process.exit(status);
+
+/**
+ * Prints the exception and the crashing thread's frames from the newest crash
+ * report written since the build. macOS writes the report a few seconds after
+ * the crash, so this waits for it.
+ */
+async function printCrashReport(executable: string, since: number) {
+  const dir = join(homedir(), 'Library/Logs/DiagnosticReports');
+  const newest = () => (existsSync(dir) ? readdirSync(dir) : [])
+    .filter(name => name.startsWith(executable) && name.endsWith('.ips'))
+    .map(name => ({ path: join(dir, name), time: statSync(join(dir, name)).mtimeMs }))
+    .filter(report => report.time > since)
+    .sort((a, b) => b.time - a.time)[0];
+  let report = newest();
+  for (let i = 0; !report && i < 10; i += 1) {
+    await Bun.sleep(1000);
+    report = newest();
+  }
+  if (!report) {
+    console.log('No crash report appeared within 10 seconds.');
+    return;
+  }
+  console.log(`Crash report ${report.path}:`);
+  // An .ips file is a JSON header line followed by the JSON report.
+  const text = readFileSync(report.path, 'utf8');
+  try {
+    const crash = JSON.parse(text.slice(text.indexOf('\n') + 1));
+    console.log(`${crash.exception?.type} (${crash.exception?.signal}), ${crash.termination?.indicator ?? ''}`);
+    const thread = crash.threads?.find((t: { triggered?: boolean }) => t.triggered);
+    for (const frame of thread?.frames?.slice(0, 15) ?? []) {
+      const where = frame.sourceFile ? ` (${frame.sourceFile}:${frame.sourceLine})` : '';
+      console.log(`  ${crash.usedImages?.[frame.imageIndex]?.name ?? '?'}  ${frame.symbol ?? '?'}${where}`);
+    }
+  } catch {
+    console.log(text.split('\n').slice(0, 40).join('\n'));
+  }
+}

package/templates/ios-devbox.yml

@@ -0,0 +1,189 @@
+# A macOS worker that stays up so you, or a coding agent, can build and test the
+# iOS app with Xcode over SSH. Written by `expo-devbox init`; start a session
+# with `bunx expo-devbox start`. https://www.npmjs.com/package/expo-devbox
+name: iOS devbox
+
+on:
+  workflow_dispatch:
+    inputs:
+      ssh_public_key:
+        type: string
+        required: true
+        description: OpenSSH public key that may log in to the worker.
+      minutes:
+        type: number
+        description: Maximum session length in minutes, setup included.
+        default: 60
+      idle_minutes:
+        type: number
+        description: End the session after this many minutes with no SSH connection.
+        default: 15
+
+jobs:
+  devbox:
+    name: iOS devbox
+    runs_on: macos-large
+    # Custom jobs default to the production environment and its variables.
+    environment: development
+    env:
+      SSH_PUBLIC_KEY: ${{ inputs.ssh_public_key }}
+    steps:
+      - uses: eas/checkout
+
+      # sshd runs as the build user on localhost only. A Cloudflare quick tunnel
+      # (no account needed) exposes it; clients connect with
+      # `cloudflared access ssh`. Only the key from the input can log in.
+      - name: Start SSH
+        run: |
+          dir="$HOME/.devbox"
+          mkdir -p "$dir" ~/.ssh && chmod 700 ~/.ssh
+          echo $(( $(date +%s) + ${{ inputs.minutes }} * 60 )) > "$dir/deadline"
+          ln -sfn "$PWD" ~/project
+
+          printf '%s\n' "$SSH_PUBLIC_KEY" > ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
+          if ! ssh-keygen -lf ~/.ssh/authorized_keys; then
+            echo "The ssh_public_key input is not an OpenSSH public key. Received: $SSH_PUBLIC_KEY"
+            exit 1
+          fi
+          ssh-keygen -q -t ed25519 -N '' -f "$dir/host_key"
+
+          # SSH sessions get only the toolchain variables, not the job's EAS
+          # variables or its EXPO_TOKEN.
+          echo "Job environment variables: $(env | cut -d= -f1 | sort | tr '\n' ' ')"
+          env | grep -E '^(PATH|LANG|LC_[A-Z]+|DEVELOPER_DIR|NVM_[A-Z_]+|GEM_[A-Z_]+|RUBY[A-Z_]*|BUNDLE_[A-Z_]+)=' > ~/.ssh/environment
+          chmod 600 ~/.ssh/environment
+          echo "SSH session variables: $(cut -d= -f1 ~/.ssh/environment | tr '\n' ' ')"
+
+          cat > "$dir/sshd_config" <<EOF
+          Port 2222
+          ListenAddress 127.0.0.1
+          HostKey $dir/host_key
+          PidFile $dir/sshd.pid
+          AuthorizedKeysFile .ssh/authorized_keys
+          PasswordAuthentication no
+          KbdInteractiveAuthentication no
+          UsePAM no
+          StrictModes no
+          PermitUserEnvironment yes
+          Subsystem sftp /usr/libexec/sftp-server
+          LogLevel VERBOSE
+          EOF
+          /usr/sbin/sshd -f "$dir/sshd_config" -E "$dir/sshd.log"
+
+          # Log in once with a throwaway key so an sshd problem fails here, with its log, instead of at the client.
+          ssh-keygen -q -t ed25519 -N '' -f "$dir/selftest_key"
+          cp ~/.ssh/authorized_keys "$dir/authorized_keys.orig"
+          cat "$dir/selftest_key.pub" >> ~/.ssh/authorized_keys
+          if ssh -p 2222 -i "$dir/selftest_key" -o IdentitiesOnly=yes -o BatchMode=yes \
+            -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null 127.0.0.1 'echo SSH self-test passed'; then
+            selftest=ok
+          fi
+          cp "$dir/authorized_keys.orig" ~/.ssh/authorized_keys
+          if [ "${selftest:-}" != ok ]; then
+            echo "SSH self-test failed. sshd log:"
+            cat "$dir/sshd.log"
+            exit 1
+          fi
+
+          curl -fsSL -o "$dir/cloudflared.tgz" \
+            https://github.com/cloudflare/cloudflared/releases/download/2026.10.3/cloudflared-darwin-arm64.tgz
+          echo "1165d14b6f6360a3b8c283d7d1100024d6ec7cd9bc9e32519e96150645f3ec55  $dir/cloudflared.tgz" | shasum -a 256 -c -
+          tar -xzf "$dir/cloudflared.tgz" -C "$dir"
+
+          # The keep-alive step reruns this if the tunnel exits. A new tunnel gets a new host.
+          cat > "$dir/tunnel.sh" <<'EOF'
+          #!/bin/bash
+          dir="$HOME/.devbox"
+          "$dir/cloudflared" tunnel --no-autoupdate --protocol http2 --url ssh://localhost:2222 > "$dir/cloudflared.log" 2>&1 &
+          echo $! > "$dir/cloudflared.pid"
+          for _ in $(seq 60); do
+            host=$(grep -oE '[a-z0-9-]+\.trycloudflare\.com' "$dir/cloudflared.log" | head -1 || true)
+            if [ -n "$host" ]; then
+              echo "DEVBOX_SSH_HOST=$host"
+              exit 0
+            fi
+            sleep 2
+          done
+          cat "$dir/cloudflared.log"
+          echo "The Cloudflare tunnel did not start."
+          exit 1
+          EOF
+          chmod +x "$dir/tunnel.sh"
+          "$dir/tunnel.sh"
+          echo "DEVBOX_SSH_USER=$(whoami)"
+          echo "DEVBOX_SSH_HOSTKEY=$(cut -d' ' -f1,2 "$dir/host_key.pub")"
+
+      - uses: eas/install_node_modules
+
+      - name: Prebuild and install pods
+        run: |
+          if [ -d ios ]; then
+            echo "Using the committed ios directory."
+          else
+            npx expo prebuild --platform ios --no-install
+            touch ~/.devbox/cng
+          fi
+          cd ios && pod install
+
+      - name: Boot simulator
+        run: |
+          udid=$(xcrun simctl list devices available --json | node -e '
+            const { devices } = JSON.parse(require("fs").readFileSync(0, "utf8"));
+            const version = (runtime) => (runtime.match(/iOS-(\d+)-(\d+)/) ?? [0, 0, 0]).slice(1).map(Number);
+            const iphones = Object.keys(devices)
+              .filter((r) => r.includes("iOS"))
+              .sort((a, b) => version(b)[0] - version(a)[0] || version(b)[1] - version(a)[1])
+              .flatMap((r) => devices[r])
+              .filter((d) => d.name.startsWith("iPhone"));
+            const d = iphones.find((d) => /^iPhone \d+ Pro$/.test(d.name)) ?? iphones[0];
+            console.log(d.udid);')
+          xcrun simctl boot "$udid"
+          xcrun simctl bootstatus "$udid" -b
+          echo "$udid" > ~/.devbox/sim
+          xcrun simctl list devices booted
+
+      - name: Keep the worker up
+        run: |
+          dir="$HOME/.devbox"
+          start_metro() {
+            # EAS sets CI=true, which makes Metro ignore file changes.
+            env -u CI npx expo start --localhost > "$dir/metro.log" 2>&1 < /dev/null &
+          }
+          start_metro
+          # The same xcodebuild arguments as `expo-devbox build`, so its first build is incremental.
+          workspace=$(ls -d ios/*.xcworkspace | head -1)
+          scheme=$(node -p 'try { require("./devbox.json").scheme || "" } catch { "" }')
+          xcodebuild -workspace "$workspace" -scheme "${scheme:-$(basename "$workspace" .xcworkspace)}" \
+            -configuration Debug -sdk iphonesimulator -destination "platform=iOS Simulator,id=$(cat "$dir/sim")" \
+            -derivedDataPath "$dir/DerivedData" build > "$dir/xcodebuild.log" 2>&1 \
+            || echo "The warm-up build failed. Run expo-devbox build to see why."
+          touch "$dir/ready"
+          echo "Devbox ready at ~/project."
+
+          deadline=$(cat "$dir/deadline")
+          idle_limit=$(( ${{ inputs.idle_minutes }} * 60 ))
+          last_active=$(date +%s)
+          while [ "$(date +%s)" -lt "$deadline" ]; do
+            sleep 20
+            now=$(date +%s)
+            if netstat -an -p tcp | grep -q '127\.0\.0\.1\.2222 .*ESTABLISHED'; then
+              last_active=$now
+            elif [ $(( now - last_active )) -ge "$idle_limit" ]; then
+              echo "No SSH connection for ${{ inputs.idle_minutes }} minutes. Ending the session."
+              exit 0
+            fi
+            if ! kill -0 "$(cat "$dir/cloudflared.pid")" 2> /dev/null; then
+              echo "The tunnel exited. Starting a new one."
+              "$dir/tunnel.sh" || true
+            fi
+            # Two misses in a row, so a Metro that is still starting is left alone.
+            if curl -sf http://localhost:8081/status > /dev/null; then
+              metro_misses=0
+            elif [ $(( metro_misses = ${metro_misses:-0} + 1 )) -ge 2 ]; then
+              echo "Metro is not responding. Restarting it."
+              pkill -f "expo start" || true
+              start_metro
+              metro_misses=0
+            fi
+          done
+          echo "Reached the ${{ inputs.minutes }}-minute limit. Ending the session."