expo-devbox 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # expo-devbox
 
-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 that has your app prebuilt, its pods installed, an iOS Simulator booted, Metro running, and a first build done. Then you, or your agent, copy files over with `expo-devbox sync` and run commands on it with `expo-devbox ssh`.
+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.
 
@@ -19,102 +19,90 @@ Set up expo-devbox (https://www.npmjs.com/package/expo-devbox) in this Expo app.
 
 **iOS only for now.** Android support, on an EAS Linux worker with the Android Emulator, will be added to this tool shortly.
 
-## Requirements
+<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
 ```
 
-`init` writes the workflow to `.eas/workflows/ios-devbox.yml` and adds `.devbox/` to `.gitignore`; the CLI keeps the session's run ID and SSH config there. It also adds a short section for coding agents to `AGENTS.md` or `CLAUDE.md`, or prints it if neither file exists (see [Coding agents](#coding-agents)).
-
-## Commands
-
 | Command | What it does |
 | --- | --- |
-| `init [--force] [--no-agents]` | Adds the devbox workflow to the app, as in [Set up](#set-up). `--force` replaces an existing workflow; `--no-agents` leaves `AGENTS.md` and `CLAUDE.md` alone. |
-| `start [minutes] [idle-minutes]` | Starts a session and waits until the worker is ready, about 4 minutes. The session ends after `minutes` (default 60) or after `idle-minutes` with no SSH connection (default 15). |
-| `sync` | Copies your files to the worker: what git would track, so `.gitignore` applies. Run it after each change. |
-| `ssh ['command']` | Runs a command in the app's directory on the worker, or opens a shell. If the connection drops while the command runs, it exits 255 and does not run the command again. |
-| `attach [run-id]` | Reconnects to a running session. `sync` and `ssh` also reconnect on their own when the worker's tunnel has moved. |
-| `joblog` | Prints the workflow job's log. |
-| `stop` | Ends the session and waits until EAS confirms that it has ended. |
+| `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 these commands and the steps in [On the worker](#on-the-worker).
+`expo-devbox help` prints all of this and the steps below.
 
-## On the worker
-
-After each change, run `expo-devbox sync`, then run these with `expo-devbox ssh '<command>'`. The `DEVBOX_*` variables are set in every SSH session.
+<details>
+<summary id="sessions"><strong>Several sessions</strong></summary>
 
-For example:
+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 sync
-$ bunx expo-devbox ssh 'set -o pipefail; xcodebuild … build 2>&1 | tee ~/.devbox/build.log | grep -E ": (fatal )?error:|\*\* BUILD" | sort -u'
-** BUILD SUCCEEDED **
-$ bunx expo-devbox ssh 'tail -n 3 ~/.devbox/metro.log'
- LOG  [native-crypto] PASS sha384("abc"): cb00753f…
- LOG  [native-crypto] DONE 7/7 passed
+$ 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
 ```
 
-**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`. After the worker's first build, an incremental build takes a few seconds.
+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.
 
-```sh
-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
-```
+</details>
+
+## On the worker
 
-**Install and launch** the app on the simulator:
+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
-xcrun simctl install booted "$DEVBOX_APP" && xcrun simctl launch --terminate-running-process booted "$DEVBOX_BUNDLE_ID"
-```
+# 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
 
-**JavaScript console output and errors**, from Metro:
+# Install and launch the app on the simulator.
+xcrun simctl install booted "$DEVBOX_APP" && xcrun simctl launch --terminate-running-process booted "$DEVBOX_BUNDLE_ID"
 
-```sh
+# 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. Swift's `print` writes to stdout and does not appear here.
 
-```sh
+# 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**, and if it crashed, read the exception and crashing frames from the newest crash report:
 
-```sh
+# 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 copy it to your machine (the second command runs locally):
 
-```sh
-xcrun simctl io booted screenshot ~/.devbox/screenshot.png
-scp -F .devbox/ssh_config devbox:.devbox/screenshot.png .devbox/
-```
-
-**After adding or removing native files, or editing a podspec:**
+# Screenshot. Then, on your machine: expo-devbox pull .devbox/screenshot.png .devbox/
+mkdir -p .devbox && xcrun simctl io booted screenshot .devbox/screenshot.png
 
-```sh
+# 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, and skip prebuild if you commit `ios/`:
 
-```sh
+# 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
 ```
 
-### The variables
+<details>
+<summary id="variables"><strong>The <code>DEVBOX_*</code> variables</strong></summary>
 
 | Variable | Value |
 | --- | --- |
@@ -122,9 +110,16 @@ bun install && npx expo prebuild --platform ios --no-install && cd ios && pod in
 | `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. |
+| `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
+
+<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:
 
@@ -138,37 +133,51 @@ 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. When the user is done with the devbox, run `bunx expo-devbox stop`.
+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`.
 ```
 
 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.
 
-## How it works
+</details>
+
+<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) 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` and `ssh` reconnect.
+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.
 
 > [!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: preparing the worker (prebuild, pods, simulator, Metro, a first build), syncing your files safely, the variables and commands for building and running the app, and the instructions for coding agents. Steps 1 and 2, and the idle shutdown in step 4, exist because EAS Workflows does not offer SSH yet. When workflow SSH ships, `expo-devbox` will use it.
+> 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.
-- The `DEVBOX_*` 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.
 - 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.
 
-## Developing expo-devbox
+</details>
+
+## Contributing
+
+<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.
 
@@ -179,19 +188,9 @@ 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), 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.
 
-[`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`, and `NSLog`s `[native-crypto] module created` from Swift.
-
-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
-```
-
-To use your own EAS account, delete `owner` and `extra.eas` from `example/app.json` and run `eas init` in `example/`.
+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.
 
 Before a release, run these checks in the example with the commands from [On the worker](#on-the-worker), and revert each edit afterwards:
 
@@ -204,6 +203,11 @@ Before a release, run these checks in the example with the commands from [On the
 | 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 `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 |
-| `stop` | `The devbox session is canceled.` |
+| `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.2.0",
+  "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,22 +1,30 @@
 #!/usr/bin/env bun
 import { init } from './init';
 import { playIntro } from './intro';
-import { attach, joblog, 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 = `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.
 
-Session:
+Commands:
   init [--force] [--no-agents]    add the devbox workflow to this app
-  start [minutes] [idle-minutes]  start a session and wait until the worker is ready (about 4 minutes).
+  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
-  attach [run-id]                 reconnect to a running session
-  joblog                          print the workflow job's log
-  stop                            end the session and wait until EAS confirms it ended
+  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
+
+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>'.
@@ -41,8 +49,8 @@ On the worker:
   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, on your machine: scp -F .devbox/ssh_config devbox:.devbox/screenshot.png .devbox/):
-    xcrun simctl io booted screenshot ~/.devbox/screenshot.png
+  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
@@ -54,9 +62,12 @@ On the worker:
 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, sync, ssh: shell, attach, joblog, stop };
+const commands: Record<string, (args: string[]) => unknown> = {
+  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

@@ -15,7 +15,8 @@ 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. When the user is done with the devbox, run \`bunx expo-devbox stop\`.
+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[]) {

package/src/session.ts

@@ -2,18 +2,23 @@
  * The session commands: start a devbox workflow run, connect to its worker
  * 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, 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 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. */
@@ -27,7 +32,41 @@ const fail = (message: string): never => {
 const log = (message: string) => console.error(message);
 const sleep = (seconds: number) => Bun.sleep(seconds * 1000);
 
-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();
@@ -39,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}. Start a new one with: expo-devbox start`);
+    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' });
@@ -50,14 +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 app's root directory first.`);
-  mkdirSync(STATE, { recursive: true });
 }
 
 /**
@@ -66,13 +100,13 @@ function requireProject() {
  * 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];
@@ -80,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;
@@ -101,16 +135,17 @@ async function connect(runId: string): Promise<void> {
   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,25 +159,25 @@ function writeSshConfig(host: string, user: string, hostKey: string) {
  * 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() {
-  const probe = await $`ssh -F ${SSH_CONFIG} devbox true`.quiet().nothrow();
-  if (probe.exitCode === SSH_FAILED) await connect(savedRun());
+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(runId: string) {
+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 -F ${SSH_CONFIG} devbox ${'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 === SSH_FAILED) {
-      await connect(runId);
+      await connect(session);
       continue;
     }
-    await requireActive(runId);
+    await requireActive(session);
     await sleep(15);
   }
   fail('The worker is not ready after 20 minutes. See: expo-devbox joblog');
@@ -151,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 it, or end it with: 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}`;
@@ -167,43 +195,68 @@ 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} minutes without an SSH connection.`);
+  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 waitUntilReady(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);
   }
-  console.log('The worker is ready. Run expo-devbox help and follow "On the worker" to build and run the app.');
+  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);
-  await waitUntilReady(runId);
-  console.log('The worker is ready.');
+  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.');
+}
+
 /**
  * Sends what git would track. .gitignore patterns also protect worker-only
  * files (such as a generated ios/) from --delete. rsync cannot express
@@ -211,15 +264,16 @@ 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 ensureConnected();
-  const { exitCode } = await $`rsync -az --delete -e ${`ssh -F ${SSH_CONFIG}`} \
+  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.`);
@@ -227,37 +281,71 @@ export async function sync() {
 
 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;
   }
-  await ensureConnected();
-  const { exitCode } = await $`ssh -F ${SSH_CONFIG} devbox ${`cd ~/project && ${args.join(' ')}`}`.nothrow();
+  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' });
 }