expo-devbox 0.1.1 → 0.2.1

package/README.md

@@ -1,145 +1,185 @@
 # expo-devbox
 
-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.
+A macOS EAS worker for building and testing your Expo app's native iOS code, for you or your coding agent, instead of your own machine. `expo-devbox start` brings up a worker with your app prebuilt, its pods installed, an iOS Simulator booted, Metro running and a first build done. Then you copy files over with `sync`, run commands with `ssh`, and copy results back with `pull`.
 
 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.
+Set up expo-devbox (https://www.npmjs.com/package/expo-devbox) in this Expo app. It is a tool I will ask you to use when I want to 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.
+3. Read the "Native iOS builds on EAS (expo-devbox)" section that init added to AGENTS.md or CLAUDE.md. If neither file exists, init prints the section instead; add it to the instructions file you read. Then run `bunx expo-devbox help`. Keep building the app the way you do now; use expo-devbox only when I ask you to.
+4. Do not start a session; a session bills EAS macOS minutes while it runs. Tell me what you set up.
 ```
 
-## Requirements
+**iOS only for now.** Android support, on an EAS Linux worker with the Android Emulator, will be added to this tool shortly.
+
+<details>
+<summary><strong>Requirements</strong></summary>
 
 - 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
+</details>
+
+## Quick start
 
 In the root of your app:
 
 ```sh
-bunx expo-devbox init
+bunx expo-devbox init      # add the workflow, a .gitignore line and the agent instructions
+bunx expo-devbox start     # start a session; returns when the worker is ready (about 4 minutes)
+bunx expo-devbox sync      # after each change: copy your files to the worker
+bunx expo-devbox ssh '<command>'   # build, launch and check the app: see "On the worker"
+bunx expo-devbox stop      # end the session
+```
+
+| Command | What it does |
+| --- | --- |
+| `init [--force] [--no-agents]` | Writes `.eas/workflows/ios-devbox.yml`, adds `.devbox/` (session state) to `.gitignore`, and adds the [agent instructions](#coding-agents) to `AGENTS.md` or `CLAUDE.md`. |
+| `start [minutes] [idle-minutes]` | Starts a new session and waits until its worker is ready. It ends after `minutes` (default 60) or `idle-minutes` with no SSH connection (default 15). |
+| `sync` | Copies your files to the worker: what git would track, so `.gitignore` applies. |
+| `ssh ['command']` | Runs a command in the app's directory on the worker, or opens a shell. |
+| `pull <path> [local-path]` | Copies a file from the worker. A relative path is in the app's directory there. |
+| `sessions`, `attach [id]` | Lists this directory's sessions; reconnects to one and makes it current. |
+| `joblog` | Prints the session's workflow job log. |
+| `stop [--all]` | Ends the session, or every session in this directory, and waits until EAS confirms it. |
+
+`expo-devbox help` prints all of this and the steps below.
+
+<details>
+<summary id="sessions"><strong>Several sessions</strong></summary>
+
+Sessions work like Claude Code's. Each `start` begins a new session and makes it the current one, and the other commands use the current session, so with one session you never name it. To use another one, add `--session <id>` (or `-s <id>`) before the command's arguments, or set `EXPO_DEVBOX_SESSION=<id>`. Any unique prefix of the ID works:
+
+```
+$ bunx expo-devbox sessions
+* 01a170ec-7181  IN_PROGRESS     10/24/2026, 7:38:26 PM
+  01a170e8-b2c6  IN_PROGRESS     10/24/2026, 7:34:20 PM
 ```
 
-`init` does the following:
+Several sessions in one directory help when two agents share a checkout. Each session is its own worker, holds its own macOS concurrency slot and is billed separately. Separate directories, such as git worktrees, keep separate sessions too.
+
+</details>
 
-- 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).
+## On the worker
 
-Then:
+After each change, run `expo-devbox sync`, then run these with `expo-devbox ssh '<command>'`. The `DEVBOX_*` variables are set in every SSH session. After the worker's first build, an incremental build takes a few seconds.
 
 ```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
+# Build. Prints errors with file and line, then ** BUILD SUCCEEDED ** or ** BUILD FAILED **, and exits
+# non-zero on failure. The full log is ~/.devbox/build.log.
+set -o pipefail; xcodebuild -workspace "$DEVBOX_WORKSPACE" -scheme "$DEVBOX_SCHEME" -configuration Debug -destination "id=$DEVBOX_SIMULATOR" -derivedDataPath "$DEVBOX_DERIVED_DATA" build 2>&1 | tee ~/.devbox/build.log | grep -E ": (fatal )?error:|\*\* BUILD" | sort -u
+
+# Install and launch the app on the simulator.
+xcrun simctl install booted "$DEVBOX_APP" && xcrun simctl launch --terminate-running-process booted "$DEVBOX_BUNDLE_ID"
+
+# JavaScript console output and errors (Metro).
+tail -n 50 ~/.devbox/metro.log
+
+# Native log: NSLog, and os_log or Logger output from the app's own code, from the last minute.
+xcrun simctl spawn booted log show --last 1m --style compact --predicate "$DEVBOX_LOG_PREDICATE" 2>/dev/null
+
+# Check that the app is still running; if it crashed, the newest crash report's exception and frames.
+pgrep -lf "$DEVBOX_EXECUTABLE.app/$DEVBOX_EXECUTABLE" || echo "The app is not running."
+tail -n +2 "$(ls -t ~/Library/Logs/DiagnosticReports/$DEVBOX_EXECUTABLE*.ips | head -1)" | jq "{exception, termination, frames: [.threads[] | select(.triggered) | .frames[:12][] | {symbol, sourceFile, sourceLine}]}"
+
+# Screenshot. Then, on your machine: expo-devbox pull .devbox/screenshot.png .devbox/
+mkdir -p .devbox && xcrun simctl io booted screenshot .devbox/screenshot.png
+
+# After adding or removing native files, or editing a podspec.
+cd ios && pod install
+
+# After changing package.json, the app config or a config plugin. Use your package manager;
+# skip prebuild if you commit ios/.
+bun install && npx expo prebuild --platform ios --no-install && cd ios && pod install
 ```
 
-## Commands
+<details>
+<summary id="variables"><strong>The <code>DEVBOX_*</code> variables</strong></summary>
 
-| Command | What it does |
+| Variable | Value |
 | --- | --- |
-| `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`. |
+| `DEVBOX_WORKSPACE`, `DEVBOX_SCHEME` | The Xcode workspace (`ios/<name>.xcworkspace`) and scheme. |
+| `DEVBOX_SIMULATOR` | The booted simulator's UDID. |
+| `DEVBOX_DERIVED_DATA` | The DerivedData folder of the worker's first build. Build with it to keep builds incremental. |
+| `DEVBOX_APP`, `DEVBOX_BUNDLE_ID`, `DEVBOX_EXECUTABLE` | The built `.app`, its bundle identifier, and its executable's name. |
+| `DEVBOX_LOG_PREDICATE` | A `log` predicate for messages from the app's own code and `NSLog`, without system libraries' logging. Swift's `print` writes to stdout and does not appear in the log. |
+
+The values assume prebuild's naming, where the scheme, the app and its executable share a name. A project that commits `ios/` with different names can use its own values in the commands.
+
+</details>
 
-## Coding agents
+## Additional information
 
-`init` adds the following to `AGENTS.md` or `CLAUDE.md`. Copy it into your agent's instructions if you use another file:
+<details>
+<summary id="coding-agents"><strong>Instructions for coding agents</strong></summary>
+
+`init` adds this to `AGENTS.md` or `CLAUDE.md`. It tells agents to use the devbox only when you ask. 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.
+`bunx expo-devbox` gives you a macOS EAS worker to build and test this app's native iOS code instead of this machine. Use it only when the user asks for it, for example "build this on the devbox". Otherwise, build and run the app as you normally would.
+
+When the user asks for it:
 
-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`.
+1. Run `bunx expo-devbox help` and follow its "On the worker" section. It has the command for each step: build, install and launch, logs, crash reports and screenshots.
+2. Start a session with `bunx expo-devbox start`. It returns when the worker is ready, and EAS macOS minutes are billed until the session ends.
+3. After each change, run `bunx expo-devbox sync`, then the commands from the help with `bunx expo-devbox ssh '<command>'`.
+4. Commands use the session you started last in this directory. If another agent works in the same directory, pass your session's ID, which `start` prints, to every command: `bunx expo-devbox ssh --session <id> '<command>'`.
+5. When the user is done with the devbox, 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`, `attach` and `stop` report their status: working, done, or blocked when the run needs approval on expo.dev; any command that fails reports an error. The CLI sends these reports only when its stderr is a terminal, so output that an agent captures never contains them.
 
-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.
+</details>
 
-## How it works
+<details>
+<summary id="how-it-works"><strong>How it works</strong></summary>
 
 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.
+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) and the `DEVBOX_*` variables, 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 `sync`, `ssh` and `pull` reconnect. A command is never run twice: if the connection drops while it runs, `ssh` exits 255.
+3. **Preparation.** It runs `expo prebuild` (skipped when the project commits `ios/`) and `pod install`, and boots an iPhone simulator. It writes the `DEVBOX_*` variables for SSH sessions. It starts Metro with `CI` unset, because with `CI=true` Metro ignores file changes. Then it runs the build command above once, so that later builds are incremental.
 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.
+> [!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 (steps 1 and 2, and the idle shutdown in step 4). The other half stays: preparing the worker, syncing your files safely, the variables and commands for building and running the app, and the instructions for coding agents. When workflow SSH ships, `expo-devbox` will use it.
+
+</details>
 
-## Limits
+<details>
+<summary><strong>Known limitations</strong></summary>
 
 - 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
+</details>
+
+<details>
+<summary><strong>The intro animation</strong></summary>
+
+`expo-devbox help` (or `expo-devbox` with no command) 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.
 
-`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.
+</details>
 
-## Developing expo-devbox
+## Contributing
 
-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.
+<details>
+<summary><strong>Develop, test, and check a release</strong></summary>
+
+The CLI is at the root of this repository: `src/` holds the commands, `templates/` holds the workflow that `init` writes, and `test/` holds the unit tests.
 
 ```sh
 bun install
@@ -148,33 +188,26 @@ 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:
+[`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), that 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), logs a `[native-crypto] PASS` or `FAIL` line for each check, then `[native-crypto] DONE`, and `NSLog`s `[native-crypto] module created` from Swift.
 
-```sh
-cd example
-bun install
-expo-devbox start
-expo-devbox build
-expo-devbox stop
-```
+The example does not depend on `expo-devbox`; run the linked CLI from `example/` (`bun install`, then `expo-devbox start`). To use your own EAS account, delete `owner` and `extra.eas` from `example/app.json` and run `eas init` in `example/`. After you change `templates/ios-devbox.yml`, run `expo-devbox init --force --no-agents` in `example/` to update its workflow.
 
-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.
+Before a release, run these checks in the example with the commands from [On the worker](#on-the-worker), and revert each edit afterwards:
 
 | 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 |
+| None: sync, build, install and launch | `** BUILD SUCCEEDED **`; Metro log ends with `DONE 7/7 passed`; the native log has `module created` |
+| A Swift type error | the build prints the error with file and line, `** BUILD FAILED **`, and exits non-zero |
+| `fatalError()` in the module's `OnCreate` | `The app is not running.`; the crash report frames point at `NativeCryptoModule.swift` |
+| A wrong expected value in `App.tsx` | Metro log has a `FAIL` line |
+| Prebuild and pod install, then build | `** BUILD SUCCEEDED **` |
 | `.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.` |
+| `expo-devbox ssh 'pkill -9 cloudflared'`, then `expo-devbox ssh 'true'` | the first exits 255 with the dropped-connection message and is not run again; the second reconnects on its own and exits 0 |
+| `start` twice, then `sessions`, `ssh --session <first id> 'true'` and `stop --all` | two sessions listed, the newer one current; the command runs on the first; both sessions end |
+| `stop` | `The devbox session <id> is canceled.` |
+
+</details>
+
+## License
 
-After you change `templates/ios-devbox.yml`, run `expo-devbox init --force --no-agents` in `example/` to update its workflow.
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-devbox",
-  "version": "0.1.1",
+  "version": "0.2.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": {

package/src/args.ts

@@ -0,0 +1,49 @@
+/** Command-line parsing, kept apart from the commands so it can be tested. */
+export type Parsed = { command?: string; args: string[]; session?: string };
+
+/**
+ * Splits argv into the command, its arguments and a --session value.
+ * `--session <id>`, `--session=<id>` and `-s <id>` are read before the command
+ * and before the command's first argument, so a remote command passed to `ssh`
+ * is never parsed: `expo-devbox ssh -s 01a1 'ls --session'`.
+ */
+export function parseArgs(argv: string[]): Parsed {
+  let session: string | undefined;
+  let command: string | undefined;
+  const args: string[] = [];
+  let i = 0;
+  const readFlags = () => {
+    while (i < argv.length) {
+      const arg = argv[i]!;
+      if (arg === '--session' || arg === '-s') {
+        session = argv[i + 1];
+        i += 2;
+      } else if (arg.startsWith('--session=')) {
+        session = arg.slice('--session='.length);
+        i += 1;
+      } else {
+        return;
+      }
+    }
+  };
+  readFlags();
+  if (i < argv.length) command = argv[i++];
+  readFlags();
+  args.push(...argv.slice(i));
+  return { command, args, ...(session ? { session } : {}) };
+}
+
+/** Finds the one session ID that starts with the prefix. */
+export function matchSession(ids: string[], prefix: string): string {
+  const matches = ids.filter(id => id.startsWith(prefix));
+  if (matches.length === 1) return matches[0]!;
+  if (matches.length === 0) {
+    throw new Error(`No devbox session in this directory starts with "${prefix}". See: expo-devbox sessions`);
+  }
+  throw new Error(`"${prefix}" matches ${matches.length} sessions: ${matches.map(shortId).join(', ')}. Use more of the ID.`);
+}
+
+/** The part of a session (workflow run) ID that is shown: unique per millisecond of start time. */
+export function shortId(id: string): string {
+  return id.slice(0, 13);
+}

package/src/cli.ts

@@ -1,32 +1,73 @@
 #!/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 { parseArgs } from './args';
+import { attach, joblog, pull, selectSession, sessions, 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.
+const HELP = `A macOS EAS worker for building and testing an Expo app's native iOS code,
+for you or a coding agent. Run these in the app's root directory.
 
-Usage: expo-devbox <command>
+Commands:
+  init [--force] [--no-agents]    add the devbox workflow to this app
+  start [minutes] [idle-minutes]  start a new session and wait until its worker is ready (about 4 minutes).
+                                  It ends after [minutes] (default 60) or after [idle-minutes] without
+                                  an SSH connection (default 15). EAS macOS minutes are billed until then.
+  sync                            copy your files to the worker (what git would track; .gitignore applies)
+  ssh ['command']                 run a command in the app's directory on the worker, or open a shell
+  pull <path> [local-path]        copy a file from the worker; a relative path is in the app's directory
+  sessions                        list this directory's sessions
+  attach [id]                     reconnect to a session and make it the current one
+  joblog                          print the session's workflow job log
+  stop [--all]                    end the session (or all of them) and wait until EAS confirms it ended
 
-  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
+Sessions:
+  Each start begins a new session and makes it the current one. The other commands use the current
+  session. To use another, add --session <id> (or -s <id>) before the command's arguments, or set
+  EXPO_DEVBOX_SESSION=<id>. Any unique prefix of an ID works; expo-devbox sessions lists them.
+
+On the worker:
+  After each change, run expo-devbox sync, then the commands below with expo-devbox ssh '<command>'.
+  The DEVBOX_* variables are set in every SSH session.
+
+  Build. Prints errors with file and line, then ** BUILD SUCCEEDED ** or ** BUILD FAILED **.
+  The full log is ~/.devbox/build.log.
+    set -o pipefail; xcodebuild -workspace "$DEVBOX_WORKSPACE" -scheme "$DEVBOX_SCHEME" -configuration Debug -destination "id=$DEVBOX_SIMULATOR" -derivedDataPath "$DEVBOX_DERIVED_DATA" build 2>&1 | tee ~/.devbox/build.log | grep -E ": (fatal )?error:|\\*\\* BUILD" | sort -u
+
+  Install and launch the app on the simulator:
+    xcrun simctl install booted "$DEVBOX_APP" && xcrun simctl launch --terminate-running-process booted "$DEVBOX_BUNDLE_ID"
+
+  JavaScript console output and errors (Metro):
+    tail -n 50 ~/.devbox/metro.log
+
+  Native log (NSLog, and os_log or Logger output from the app's own code; last minute):
+    xcrun simctl spawn booted log show --last 1m --style compact --predicate "$DEVBOX_LOG_PREDICATE" 2>/dev/null
+
+  Check that the app is still running:
+    pgrep -lf "$DEVBOX_EXECUTABLE.app/$DEVBOX_EXECUTABLE" || echo "The app is not running."
+
+  If it crashed, the exception and crashing frames from the newest crash report:
+    tail -n +2 "$(ls -t ~/Library/Logs/DiagnosticReports/$DEVBOX_EXECUTABLE*.ips | head -1)" | jq "{exception, termination, frames: [.threads[] | select(.triggered) | .frames[:12][] | {symbol, sourceFile, sourceLine}]}"
+
+  Screenshot. Then copy it to your machine with: expo-devbox pull .devbox/screenshot.png .devbox/
+    mkdir -p .devbox && xcrun simctl io booted screenshot .devbox/screenshot.png
+
+  After adding or removing native files, or editing a podspec:
+    cd ios && pod install
+
+  After changing package.json, the app config or a config plugin (use your package manager;
+  skip prebuild if you commit ios/):
+    bun install && npx expo prebuild --platform ios --no-install && cd ios && pod install
 
 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,
+  init, start, sync, ssh: shell, pull, sessions, attach, joblog, stop,
 };
 
-const [name, ...args] = process.argv.slice(2);
+const { command: name, args, session } = parseArgs(process.argv.slice(2));
+selectSession(session ?? process.env.EXPO_DEVBOX_SESSION);
 if (!name || name === 'help' || name === '--help' || name === '-h') {
   if (process.stdout.isTTY) await playIntro();
   console.log(HELP);

package/src/init.ts

@@ -1,4 +1,4 @@
-import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 
 import { UserError, WORKFLOW } from './session';
@@ -8,13 +8,15 @@ 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.
+\`bunx expo-devbox\` gives you a macOS EAS worker to build and test this app's native iOS code instead of this machine. Use it only when the user asks for it, for example "build this on the devbox". Otherwise, build and run the app as you normally would.
 
-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\`.
+When the user asks for it:
+
+1. Run \`bunx expo-devbox help\` and follow its "On the worker" section. It has the command for each step: build, install and launch, logs, crash reports and screenshots.
+2. Start a session with \`bunx expo-devbox start\`. It returns when the worker is ready, and EAS macOS minutes are billed until the session ends.
+3. After each change, run \`bunx expo-devbox sync\`, then the commands from the help with \`bunx expo-devbox ssh '<command>'\`.
+4. Commands use the session you started last in this directory. If another agent works in the same directory, pass your session's ID, which \`start\` prints, to every command: \`bunx expo-devbox ssh --session <id> '<command>'\`.
+5. When the user is done with the devbox, run \`bunx expo-devbox stop\`.
 `;
 
 export function init(args: string[]) {
@@ -33,11 +35,6 @@ export function init(args: string[]) {
     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`);
@@ -62,6 +59,6 @@ export function init(args: string[]) {
   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`);
+  bunx expo-devbox help       the commands, and how to build and run the app on the worker
+  bunx expo-devbox start      start a session (EAS macOS minutes are billed while it runs)`);
 }

package/src/session.ts

@@ -1,22 +1,28 @@
 /**
  * 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.
+ * over SSH through the Cloudflare tunnel it opens, sync files, run commands,
+ * and stop it. Run from the app's root directory.
+ *
+ * A directory can have several sessions. Each one is a workflow run, and its
+ * files are in .devbox/sessions/<run ID>/. Commands use the current session,
+ * the one started or attached last, unless --session names another.
  */
 import { $ } from 'bun';
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
 
+import { matchSession, shortId } from './args';
 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 SESSIONS = join(STATE, 'sessions');
+const CURRENT = join(STATE, 'current');
 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']);
+/** ssh's exit code when it could not connect, as opposed to the remote command's own code. */
+const SSH_FAILED = 255;
 
 /** An error whose message is meant for the person or agent running the command. */
 export class UserError extends Error {}
@@ -25,10 +31,42 @@ const fail = (message: string): never => {
 };
 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 }[] };
+type Run = { status: string; createdAt?: string; jobs?: { id: string }[] };
+type Session = { id: string; dir: string; sshConfig: string };
+
+const sessionAt = (id: string): Session => ({ id, dir: join(SESSIONS, id), sshConfig: join(SESSIONS, id, 'ssh_config') });
+
+/** Session IDs in this directory, newest first. Workflow run IDs sort by start time. */
+function sessionIds(): string[] {
+  return existsSync(SESSIONS) ? readdirSync(SESSIONS).sort().reverse() : [];
+}
+
+let selected: string | undefined;
+/** Sets the session that commands use, from --session or EXPO_DEVBOX_SESSION: an ID or a unique prefix of one. */
+export function selectSession(prefix: string | undefined) {
+  selected = prefix || undefined;
+}
+
+/** The session named with --session, else the current one, else the newest. */
+function resolveSession(prefix = selected): Session {
+  const ids = sessionIds();
+  if (prefix) {
+    try {
+      return sessionAt(matchSession(ids, prefix));
+    } catch (error) {
+      fail((error as Error).message);
+    }
+  }
+  if (ids.length === 0) fail('No devbox session in this directory. Start one with: expo-devbox start');
+  const current = existsSync(CURRENT) ? readFileSync(CURRENT, 'utf8').trim() : '';
+  return sessionAt(ids.includes(current) ? current : ids[0]!);
+}
+
+function forget(session: Session) {
+  rmSync(session.dir, { recursive: true, force: true });
+  if (existsSync(CURRENT) && readFileSync(CURRENT, 'utf8').trim() === session.id) rmSync(CURRENT);
+}
 
 async function viewRun(runId: string): Promise<Run | undefined> {
   const result = await $`eas workflow:view ${runId} --json --non-interactive`.quiet().nothrow();
@@ -40,10 +78,11 @@ async function viewRun(runId: string): Promise<Run | 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);
+async function requireActive(session: Session): Promise<Run | undefined> {
+  const run = await viewRun(session.id);
   if (run && !ACTIVE.has(run.status)) {
-    fail(`The devbox session ended with status ${run.status}. See: eas workflow:view ${runId}`);
+    forget(session);
+    fail(`The devbox session ${shortId(session.id)} ended with status ${run.status}. Start a new one with: expo-devbox start`);
   }
   if (run?.status === 'ACTION_REQUIRED') {
     status('blocked', { kind: 'permission', msg: 'The devbox workflow run needs approval on expo.dev' });
@@ -51,18 +90,8 @@ async function requireActive(runId: string): Promise<Run | undefined> {
   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}`;
+  if (!existsSync(WORKFLOW)) fail(`${WORKFLOW} is missing. Run expo-devbox init in the app's root directory first.`);
 }
 
 /**
@@ -71,13 +100,13 @@ function ssh(remoteCommand: string) {
  * 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})...`);
+async function connect(session: Session): Promise<void> {
+  log(`Waiting for the worker to open its tunnel (session ${shortId(session.id)})...`);
   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;
+    const jobId = (await requireActive(session))?.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];
@@ -85,11 +114,11 @@ async function connect(runId: string): Promise<void> {
       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);
+        writeSshConfig(session, 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();
+          const result = await $`ssh -F ${session.sshConfig} devbox true`.quiet().nothrow();
           if (result.exitCode === 0) {
             log(`Connected to ${user}@${host}.`);
             return;
@@ -103,19 +132,20 @@ async function connect(runId: string): Promise<void> {
     }
     await sleep(10);
   }
-  fail(`Could not reach the worker for 15 minutes. See: eas workflow:view ${runId}`);
+  fail('Could not reach the worker for 15 minutes. See: expo-devbox joblog');
 }
 
-function writeSshConfig(host: string, user: string, hostKey: string) {
-  writeFileSync(join(STATE, 'known_hosts'), `${host} ${hostKey}\n`);
-  writeFileSync(SSH_CONFIG, `Host devbox
+function writeSshConfig(session: Session, host: string, user: string, hostKey: string) {
+  const knownHosts = join(session.dir, 'known_hosts');
+  writeFileSync(knownHosts, `${host} ${hostKey}\n`);
+  writeFileSync(session.sshConfig, `Host devbox
   HostName ${host}
   User ${user}
   ProxyCommand cloudflared access ssh --hostname %h
   IdentityFile ${KEY}
   IdentitiesOnly yes
   StrictHostKeyChecking yes
-  UserKnownHostsFile ${resolve(STATE, 'known_hosts')}
+  UserKnownHostsFile ${resolve(knownHosts)}
   ConnectTimeout 20
   ServerAliveInterval 30
   ControlMaster auto
@@ -124,19 +154,30 @@ function writeSshConfig(host: string, user: string, hostKey: string) {
 `);
 }
 
-/** Waits for the worker to finish preparing the project. Reconnects if the worker is unreachable. */
-async function waitUntilReady(runId: string) {
+/**
+ * Reconnects first if the worker is unreachable, for example because its
+ * tunnel moved. A command is never run twice: if the connection drops while
+ * it runs, it may already have done its work.
+ */
+async function ensureConnected(session: Session) {
+  const probe = await $`ssh -F ${session.sshConfig} devbox true`.quiet().nothrow();
+  if (probe.exitCode === SSH_FAILED) await connect(session);
+}
+const droppedMessage = 'The connection to the worker dropped while the command ran. It may have finished on the worker; check before you run it again.';
+
+/** Waits for the worker to prepare the app: install, prebuild, pods, simulator, Metro and a first build. */
+async function waitUntilReady(session: Session) {
+  log('Waiting for the worker to prepare the app (about 3 minutes)...');
+  status('working', { msg: 'The EAS worker is preparing the app' });
   const deadline = Date.now() + 20 * 60_000;
   while (Date.now() < deadline) {
-    const result = await ssh('test -f ~/.devbox/ready').quiet().nothrow();
+    const result = await $`ssh -F ${session.sshConfig} devbox ${'test -f ~/.devbox/ready'}`.quiet().nothrow();
     if (result.exitCode === 0) return;
-    if (result.exitCode === 255) {
-      await connect(runId);
+    if (result.exitCode === SSH_FAILED) {
+      await connect(session);
       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 requireActive(session);
     await sleep(15);
   }
   fail('The worker is not ready after 20 minutes. See: expo-devbox joblog');
@@ -145,13 +186,6 @@ async function waitUntilReady(runId: string) {
 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}`;
@@ -161,38 +195,66 @@ export async function start(args: string[]) {
   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.`);
+  const session = sessionAt(JSON.parse(result.stdout.toString()).id);
+  mkdirSync(session.dir, { recursive: true });
+  writeFileSync(CURRENT, session.id);
+  log(`Started session ${shortId(session.id)}: ${minutes} minutes at most, ending after ${idleMinutes} minutes without an SSH connection.`);
 
   // 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 cancel = async () => {
+    await $`eas workflow:cancel ${session.id} --non-interactive`.quiet().nothrow();
+    forget(session);
+  };
   const onInterrupt = async () => {
-    log(`Cancelling run ${runId}.`);
+    log(`Cancelling session ${shortId(session.id)}.`);
     await cancel();
     status('idle');
     process.exit(130);
   };
   process.once('SIGINT', onInterrupt);
   try {
-    await connect(runId);
+    await connect(session);
+    await waitUntilReady(session);
   } catch (error) {
-    log(`Cancelling run ${runId}.`);
+    log(`Cancelling session ${shortId(session.id)}.`);
     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' });
+  const others = sessionIds().filter(id => id !== session.id).length;
+  console.log(`Session ${shortId(session.id)} is ready and is now the current session.${others ? ` This directory has ${others} other session${others === 1 ? '' : 's'}; see expo-devbox sessions.` : ''}`);
+  console.log('Run expo-devbox help and follow "On the worker" to build and run the app.');
+  status('done', { msg: 'The EAS worker is ready' });
 }
 
 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' });
+  const session = resolveSession(args[0] ?? selected);
+  writeFileSync(CURRENT, session.id);
+  await connect(session);
+  await waitUntilReady(session);
+  console.log(`Session ${shortId(session.id)} is ready and is now the current session.`);
+  status('done', { msg: 'The EAS worker is ready' });
+}
+
+/** Lists this directory's sessions, newest first, and forgets the ones that have ended. */
+export async function sessions() {
+  requireProject();
+  const ids = sessionIds();
+  if (ids.length === 0) {
+    console.log('No devbox sessions in this directory. Start one with: expo-devbox start');
+    return;
+  }
+  const current = resolveSession('').id;
+  for (const id of ids) {
+    const run = await viewRun(id);
+    const started = run?.createdAt ? new Date(run.createdAt).toLocaleString() : '';
+    const state = run?.status ?? 'UNKNOWN';
+    console.log(`${id === current ? '*' : ' '} ${shortId(id)}  ${state.padEnd(15)} ${started}`);
+    if (run && !ACTIVE.has(run.status)) forget(sessionAt(id));
+  }
+  console.log('\n* the current session. Pick another with --session <id> or EXPO_DEVBOX_SESSION=<id>; any unique prefix works.');
 }
 
 /**
@@ -202,79 +264,88 @@ export async function attach(args: string[]) {
  */
 export async function sync() {
   requireProject();
+  const session = resolveSession();
   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');
+  const excludes = join(session.dir, '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();
+  await ensureConnected(session);
+  const { exitCode } = await $`rsync -az --delete -e ${`ssh -F ${session.sshConfig}`} \
+    --exclude .git --exclude node_modules --exclude /.devbox --exclude /ios/Pods --exclude-from=${excludes} \
+    ./ devbox:project/`.nothrow();
+  if (exitCode !== 0) fail(`rsync exited ${exitCode}. Run expo-devbox sync again; it only sends what changed.`);
 }
 
 export async function shell(args: string[]) {
   requireProject();
+  const session = resolveSession();
   if (args.length === 0) {
-    const child = Bun.spawn(['ssh', '-F', SSH_CONFIG, '-t', 'devbox', 'cd ~/project && exec $SHELL'],
+    const child = Bun.spawn(['ssh', '-F', session.sshConfig, '-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;
+  await ensureConnected(session);
+  const { exitCode } = await $`ssh -F ${session.sshConfig} devbox ${`cd ~/project && ${args.join(' ')}`}`.nothrow();
+  if (exitCode === SSH_FAILED) console.error(droppedMessage);
+  process.exitCode = exitCode;
+}
+
+/** Copies a file from the worker. A relative path is relative to the app's directory there. */
+export async function pull(args: string[]) {
+  requireProject();
+  const [path, destination = '.'] = args;
+  if (!path) throw new UserError('Usage: expo-devbox pull <path on the worker> [local directory or file]');
+  const session = resolveSession();
+  await ensureConnected(session);
+  const remote = path.startsWith('/') || path.startsWith('~') ? path : `project/${path}`;
+  const { exitCode } = await $`scp -q -F ${session.sshConfig} ${`devbox:${remote}`} ${destination}`.nothrow();
+  if (exitCode !== 0) fail(`Could not copy ${path} from the worker (scp exited ${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());
+  const session = resolveSession();
+  const jobId = (await viewRun(session.id))?.jobs?.[0]?.id;
+  if (!jobId) fail(`Could not find the job of session ${shortId(session.id)}. See: eas workflow:view ${session.id}`);
   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();
+async function stopOne(session: Session): Promise<string> {
+  await $`eas workflow:cancel ${session.id} --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 result = await $`eas workflow:status ${session.id} --wait --non-interactive`.quiet().nothrow();
+  await $`ssh -F ${session.sshConfig} -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}`);
+    fail(`Could not confirm that session ${shortId(session.id)} ended (eas workflow:status exited ${result.exitCode}). Check: eas workflow:view ${session.id}`);
+  }
+  forget(session);
+  return `The devbox session ${shortId(session.id)} ${ended[result.exitCode]}.`;
+}
+
+export async function stop(args: string[]) {
+  requireProject();
+  const all = args.includes('--all');
+  const targets = all ? sessionIds().map(sessionAt) : [resolveSession()];
+  if (targets.length === 0) {
+    console.log('No devbox sessions in this directory.');
+    return;
+  }
+  status('working', { msg: all ? 'Ending all devbox sessions' : 'Ending the devbox session' });
+  // With --all, one session that cannot be confirmed does not stop the others from ending.
+  const failures: string[] = [];
+  for (const session of targets) {
+    try {
+      console.log(await stopOne(session));
+    } catch (error) {
+      if (!(error instanceof UserError)) throw error;
+      failures.push(error.message);
+    }
   }
-  console.log(`The devbox session ${ended[result.exitCode]}.`);
-  status('done', { msg: 'Devbox session ended' });
+  if (failures.length) fail(failures.join('\n'));
+  status('done', { msg: all ? 'All devbox sessions ended' : 'Devbox session ended' });
 }

package/templates/ios-devbox.yml

@@ -139,9 +139,26 @@ jobs:
             console.log(d.udid);')
           xcrun simctl boot "$udid"
           xcrun simctl bootstatus "$udid" -b
-          echo "$udid" > ~/.devbox/sim
           xcrun simctl list devices booted
 
+          # Values that the commands in `expo-devbox help` use, set in every SSH
+          # session. Prebuild names the scheme, the app and its executable alike.
+          workspace=$(ls -d ios/*.xcworkspace | head -1)
+          scheme=$(basename "$workspace" .xcworkspace)
+          bundle_id=$(npx expo config --type public --json | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).ios?.bundleIdentifier ?? ""')
+          derived="$HOME/.devbox/DerivedData"
+          cat >> ~/.ssh/environment <<EOF
+          DEVBOX_SIMULATOR=$udid
+          DEVBOX_WORKSPACE=$workspace
+          DEVBOX_SCHEME=$scheme
+          DEVBOX_DERIVED_DATA=$derived
+          DEVBOX_APP=$derived/Build/Products/Debug-iphonesimulator/$scheme.app
+          DEVBOX_BUNDLE_ID=$bundle_id
+          DEVBOX_EXECUTABLE=$scheme
+          DEVBOX_LOG_PREDICATE=process == "$scheme" AND (senderImagePath CONTAINS "/$scheme.app/" OR (senderImagePath ENDSWITH "/Foundation" AND NOT subsystem CONTAINS "."))
+          EOF
+          grep '^DEVBOX_' ~/.ssh/environment
+
       - name: Keep the worker up
         run: |
           dir="$HOME/.devbox"
@@ -150,13 +167,11 @@ jobs:
             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."
+          # The build command from `expo-devbox help`, so the first build there is incremental.
+          devbox() { grep "^$1=" ~/.ssh/environment | cut -d= -f2-; }
+          xcodebuild -quiet -workspace "$(devbox DEVBOX_WORKSPACE)" -scheme "$(devbox DEVBOX_SCHEME)" -configuration Debug \
+            -destination "id=$(devbox DEVBOX_SIMULATOR)" -derivedDataPath "$(devbox DEVBOX_DERIVED_DATA)" build \
+            > "$dir/warm-up-build.log" 2>&1 || echo "The warm-up build failed. Run the build command from expo-devbox help to see why."
           touch "$dir/ready"
           echo "Devbox ready at ~/project."
 

package/src/worker-build.ts

@@ -1,181 +0,0 @@
-#!/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'));
-  }
-}