# Connect a local app

> Let Rehearsal's browsers reach an app that runs on your computer.

Source: https://rehearsal.dev/docs/cli/connect-a-local-app

Rehearsal's browsers run on Rehearsal's servers, so they cannot open `localhost` on your computer by themselves. The CLI connects your app to Rehearsal while the command runs.

## Before you start

- The CLI is [installed](https://rehearsal.dev/docs/cli/install.md) and [signed in](https://rehearsal.dev/docs/cli/log-in.md) with the `tunnel` scope. `rehearsal login` asks for it by default.
- Your role has **Manage projects** for the workspace.
- Your app is running on your computer.

## Connect

```sh
rehearsal connect http://localhost:3000
```

Use your app's own address and port. If you have more than one project or app, the CLI lists them and asks for a number. Name them to skip the questions:

```sh
rehearsal connect http://localhost:3000 --project parcel --app web
```

`--project` takes the project's slug, name or identifier. `--app` takes the app's name or identifier.

The app prints these commands with your project's names already in them. Open the project menu in the top bar and choose **Terminal and coding agents**.

## The connection panel

While it runs, the terminal shows a panel like this one:

```text
  Rehearsal v1.0.1

  ● Connected

  Project    Parcel
  App        web
  Local      http://localhost:3000

  Local app responded (HTTP 200)
  Observed requests   14     Errors   1
  Traffic    61.4 KB sent / 1.8 MB received
  Active connections   2     Errors   0

  Last activity: 2s ago
  12s ago    GET     200     63 ms  /cart
  9s ago     POST    200     118 ms  /api/cart
  8s ago     GET     200     52 ms  /checkout
  3s ago     POST    500     204 ms  /api/orders
  2s ago     GET     200     41 ms  /checkout/confirmation

  Ctrl+C to disconnect
```

- Every 10 seconds, the CLI checks that your app answers at its address. The line below the address says what it found.
- The last five requests from Rehearsal's browser appear at the bottom, with their status and time.
- Only the path of a request is shown. Query strings are dropped, and paths that look like sign-in or reset links end in `[redacted]`.

These lines describe traffic, not test results. A run's result is in Rehearsal.

## More than one port

If your app calls another local server, such as an API on port 3001, allow it too:

```sh
rehearsal connect http://localhost:3000 --allow http://localhost:3001
```

The CLI reaches only the addresses you list. Each one uses `localhost`, `127.0.0.1` or `[::1]`, with a port and no path.

## Your local address in Rehearsal

The first connection adds a local address to the app, and that address is yours. Connecting again with the same address comes back to it, so your tests and runs keep their history.

The CLI names your computer after the app, such as `web local`. Choose another name with `--name`. You can then pick this address by name when you [start a run](https://rehearsal.dev/docs/cli/run-tests.md).

While nothing is connected, a run at this address does not start. The CLI answers `ENVIRONMENT_OFFLINE` and names the `rehearsal connect` command that fixes it.

## Stay connected

Keep the terminal open while tests run. Press `Ctrl+C` to disconnect. Your local address stays in Rehearsal for next time.

If the connection drops, the CLI tries again and the panel counts the attempts. It waits 1, 2, 5 and 10 seconds, then 30 seconds between tries. After 30 minutes without success, it stops.

> [!NOTE]
> The CLI stops at once if your sign-in ends or you lose permission to connect the app. It says why. Run `rehearsal login`, then connect again.

## From a script or a coding agent

`rehearsal connect` has no JSON form, because it holds the terminal open. Give it a terminal of its own, then run tests from another one.

A coding agent can start it too. See [Use Rehearsal from your coding agent](https://rehearsal.dev/docs/coding-agents/use-rehearsal.md).

## Next steps

- [Run tests from the terminal](https://rehearsal.dev/docs/cli/run-tests.md) against your local address.
- Read the [Command reference](https://rehearsal.dev/docs/cli/commands.md) for every flag of `rehearsal connect`.