> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes

> Give your coding agent a cloud device to check its work on.

<video controls playsInline preload="metadata" aria-label="Coding agent using BugRadar sandboxes with the Fitney app" poster="/images/fitney-sandboxes-poster.jpg" src="https://mintcdn.com/BugRadar/9ly1_I_oX7rpnvf6/images/fitney-sandboxes.mp4?fit=max&auto=format&n=9ly1_I_oX7rpnvf6&q=85&s=b900bc2ccfc56c355c813b8e22744993">
  Your browser does not support video playback. [Download the video](/docs/images/fitney-sandboxes.mp4).
</video>

Watch a coding agent use BugRadar sandboxes with the Fitney app.

A sandbox is a cloud iOS Simulator, Android Emulator or real device that your coding agent drives with the `BugRadar` CLI. Watch sandboxes live, or replay them, on the [Sandboxes](https://usebugradar.com/sandboxes) page.

## Start with your coding agent

Paste this into Claude Code, Codex, Cursor or another coding agent:

```text wrap theme={null}
Try BugRadar sandboxes: install the CLI (curl -fsSL https://get.usebugradar.com | sh), run BugRadar login, read BugRadar sandbox --help, then spin up a sandbox on iOS and Android (or whatever is available), do something cool on each (show me the magic), send me the links, and show me screenshots/videos of the coolest parts in-chat. When you're done, end the sandboxes and offer to add a line to AGENTS.md (or CLAUDE.md) so other agents know to use sandboxes for future end-to-end verifications and to post proof (eg screenshots, videos, logs) to chats and on PRs.
```

The agent learns the commands from `BugRadar sandbox --help`.

## Set up

[Install the CLI](/docs/install-cli.md) (or run `BugRadar update`), then log in from your project's folder:

```bash theme={null}
curl -fsSL https://get.usebugradar.com | sh
cd path/to/your-project
BugRadar login
```

The login is saved per git repository. `BugRadar whoami` shows which workspace is in use.

## Choose the app

`BugRadar sandbox start` leases a device, then installs and launches your app. Pick the app with:

| Option | Installs |
| - | - |
| `--upload <path>` | A local build. It isn't added to your apps. |
| `--platform ios --bundle-id <id>` (or `android`) | The active build of an app in BugRadar. |
| `--app-id <id>` | The same, by app ID. |
| `--app-build-id <id>` | A specific build. |
| Only `--platform` | Nothing. Install later with `BugRadar sandbox upload <path>`. |

`--device "iPhone 17 Pro" --os 26.0` picks the model and OS (default: latest).

### Builds

| Device | Build |
| - | - |
| iOS Simulator | `.app` or `.zip` |
| Real iPhone | `.ipa` |
| Android Emulator or real device | `.apk` |

See [Building your app](/docs/app-build-guide.md). After a native change, run `BugRadar sandbox upload <path>`. `--reset` installs clean.

## Commands

Commands after `start` act on the current sandbox, one per git worktree. `--sandbox <id>` picks another. Once a worktree has more than one sandbox, every command needs `--sandbox <id>`, so agents sharing a worktree never drive each other's device.

| Command | What it does |
| - | - |
| `BugRadar sandbox look` | Takes a screenshot |
| `BugRadar sandbox tap 603,1311` | Taps. `--count 2` double-taps |
| `BugRadar sandbox long-press 603,1311` | Presses and holds |
| `BugRadar sandbox type "jane@example.com" --into 603,880` | Replaces a field's text. `--submit` presses return |
| `BugRadar sandbox scroll down` | Scrolls |
| `BugRadar sandbox swipe 600,1200 100,1200` | Swipes |
| `BugRadar sandbox press home` | Presses a device button |
| `BugRadar sandbox open myapp://orders/42` | Opens a link or deep link |
| `BugRadar sandbox launch` | Brings the app back. `--cold` restarts it, `--reset` reinstalls it |
| `BugRadar sandbox wait 2s` | Waits, then takes a screenshot |
| `BugRadar sandbox set location 37.77,-122.41` | Sets location, orientation, clipboard, locale or network |
| `BugRadar sandbox push --title "Shipped" --body "On its way"` | Sends a push notification (iOS Simulator) |
| `BugRadar sandbox upload <path>` | Installs a new build |
| `BugRadar sandbox forward 8081 3000` | Forwards ports to your machine |
| `BugRadar sandbox list` | Lists your sandboxes |

* Each action waits for the screen to settle, then saves a screenshot to `.BugRadar/.sandboxes/<sandbox-id>/`.
* Coordinates are pixels in the latest screenshot.
* `--description "Open settings"` titles the step on the sandbox's page.
* Every command takes `--json`.

## Local development

`forward` connects ports on the device to the same ports on your machine, so the app reaches your local backend at `localhost:<port>`:

```bash theme={null}
BugRadar sandbox forward 8081 3000
```

* `3000:8000` sends the device's port 3000 to your port 8000.
* **Metro:** start Metro, then forward its port. Saved changes hot reload. Debug builds, including Expo development builds, load from it.
* Native changes still need `BugRadar sandbox upload <path>`.

## Logs, network, performance and video

Each command takes `--since <step>` and saves its output next to the screenshots.

| Command | Shows |
| - | - |
| `BugRadar sandbox logs --since 4 --grep "error"` | App logs, including crashes |
| `BugRadar sandbox network --failed` | Failed requests (iOS Simulator only) |
| `BugRadar sandbox perf --since 4` | Memory and CPU per step |
| `BugRadar sandbox video --last 30s` | A screen recording, up to 5 minutes |
| `BugRadar sandbox video --sandbox <id>` | After the sandbox ends: its whole screen recording |

After a sandbox ends, `logs`, `network` and `perf` with `--sandbox <id>` show what it kept, step by step. The kept log is the app's own, so `--all` doesn't apply.

## Watch and replay

`start` opens the sandbox's page in your browser (`--no-open` skips it). The [Sandboxes](https://usebugradar.com/sandboxes) page lists live and recent sandboxes.

* **Live:** each step appears as it happens. **Extend** keeps the sandbox longer.
* **Ended:** replay each step with its screenshot, a screen recording, and [**Performance**](/docs/performance-monitoring.md), **Logs** and **Network** tabs.

## End a sandbox

Run `BugRadar sandbox end` when you're done.

* A sandbox ends 30 minutes after its last command, and lasts at most 12 hours.
* `BugRadar sandbox extend 1h` holds it through a long pause, like a native build.
* Your plan limits how many sandboxes can be live at once.

## Real devices

`start --physical` uses a real iPhone or Android device. Message us on Slack or [email us](mailto:founders@usebugradar.com) to turn this on. On a real device:

* There's no `forward`, so point the app at public URLs.
* `upload` always installs clean.
* On a real iPhone, performance and the screen recording are only available after the sandbox ends. `BugRadar sandbox perf --sandbox <id>` shows performance, and `BugRadar sandbox video --sandbox <id>` saves the recording. A real device's recording arrives a few minutes after the end.
* Idle and total time limits are shorter. `BugRadar sandbox status` shows the time left.

## Add it to your agent instructions

To have your agent check its work in a sandbox every time, add this to its instructions file (`AGENTS.md`, `CLAUDE.md`, etc.):

```markdown wrap theme={null}
After a user-facing change to the mobile app, check it in an BugRadar sandbox: start one with your latest build (`BugRadar sandbox start --upload <path>`), run `BugRadar sandbox forward 8081` if Metro is running, walk through the change with a `--description` on each step, then run `BugRadar sandbox end`.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.