> For the complete documentation index, see [llms.txt](https://docs.bugbug.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bugbug.io/running-tests/in-cloud-on-server.md).

# Run in cloud

Run BugBug tests in the cloud: how to start a cloud run, how it differs from a local run, timeouts and maximum duration, parallel runs and the queue, the Cloud Proxy and its IP addresses, testing non-

A cloud run runs your test on BugBug's servers instead of in your own Chrome. You don't need your computer, the Chrome extension or an open browser window, so cloud runs are what you use for [schedules](/running-tests/schedules.md), CI/CD pipelines and [parallel runs](/running-tests/parallel-mode.md).

{% hint style="info" %}
**In short**

* Click **Run in cloud** in a test, in the tests list or in a suite, or start the run from a schedule, the CLI, the Public API or an AI agent.
* Every cloud run gets a fresh Chrome browser, with no cookies, local storage or sessions from earlier runs. It's a regular browser, not headless mode.
* The default step timeout is 60 seconds in the cloud, and a single cloud test can run for 10 to 30 minutes, depending on your plan.
* Cloud runs reach your site through the **Cloud Proxy** set in project settings, from a fixed IP address you can allow in a firewall.
* Cloud runs are available on all paid plans and during the trial. See [pricing](https://bugbug.io/pricing/).
  {% endhint %}

## Run a test in the cloud

1. Open the test.
2. Click **Run in cloud**.
3. Follow the run in the test: each step shows its status and, once it's done, its [screenshots](/debugging-tests/screenshots.md).

![Run in cloud button in the test editor](https://3168433179-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MKixgeBPbLvnD0l1eiV%2Fuploads%2FhbPFg3yk32Ft0T59i4ey%2Fimage.png?alt=media\&token=5a7fa9a4-fecc-44f7-abb2-f0e359995905)

You can also run tests in the cloud from the tests list: choose **Run in cloud** in a test's options, or select several tests and choose **Run in cloud**.

When the run ends, open it in [runs history](/debugging-tests/runs-history.md) to see the result of every step, with [screenshots](/debugging-tests/screenshots.md), the [DOM snapshot](/debugging-tests/dom-snapshot.md) of a failed step and, if they're enabled, [console](/debugging-tests/console-logs.md) and [network logs](/debugging-tests/network-logs.md).

## Other ways to start a cloud run

| From                                                                        | How                                                                                                           |
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| A [suite](/organizing-tests/suites.md)                                      | **Run in cloud** in the suite. Its tests run in parallel if the suite's **Parallel cloud runs** option is on. |
| A [schedule](/running-tests/schedules.md)                                   | Automatically at set times, or **Run in cloud** in the schedule's menu.                                       |
| The [CLI](/integrations/cli.md)                                             | In your CI/CD pipeline. The CLI only runs tests in the cloud. Pro plan and higher.                            |
| The [Public API](/integrations/public-api.md)                               | `POST /v2/testruns/` or `/v2/suiteruns/`. Business plan.                                                      |
| [BugBug MCP](/ai-testing/mcp.md)                                            | `bugbug_run_test` or `bugbug_run_suite` from an AI agent. Pro plan and higher.                                |
| [Vercel](/integrations/vercel.md) and [webhooks](/integrations/webhooks.md) | After a deployment or a `POST` request from another tool.                                                     |

All of these runs are cloud runs. Only runs you start with **Run** in the app run locally.

## How a cloud run differs from a local run

|                                                   | Local run                                                                   | Cloud run                                                          |
| ------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| Where it runs                                     | Your Chrome, with the BugBug extension                                      | Chrome on BugBug's servers, not headless                           |
| Browser state                                     | New incognito window, or your Chrome profile when **Incognito mode** is off | Always a fresh browser                                             |
| Network and IP address                            | Your network and IP address                                                 | The Cloud Proxy's IP address                                       |
| Default step timeout                              | 30 seconds                                                                  | 60 seconds                                                         |
| Maximum duration of one test                      | No limit                                                                    | 10 minutes on Core, 15 on Pro, 30 on Business and during the trial |
| Several tests at once                             | No, one after another                                                       | Yes, up to your [parallel runs](/running-tests/parallel-mode.md)   |
| `runMode` [variable](/editing-tests/variables.md) | `local`                                                                     | `server`                                                           |
| Plan                                              | All plans, including Free                                                   | Paid plans and trial                                               |

The window size is the same in both: the **Desktop** or **Mobile** size from [project settings](/preventing-failed-tests/project-settings.md#screen-sizes). The Chrome version in the cloud is updated over time.

Cloud machines can be slower than your computer. If a test passes locally but sometimes fails in the cloud, raise the timeout of the slow steps, or the **Default cloud run timeout** in project settings. See [Timeout](/preventing-failed-tests/timeout.md) and [Cloud tests sometimes failing](/troubleshooting/cloud-tests-sometimes-failing.md).

## Parallel runs and the queue

Your organization can run as many cloud tests at the same time as it has [parallel runs](/running-tests/parallel-mode.md): 1 by default, more if you buy them. Parallel runs are shared by all projects, schedules and API runs of the organization. Other tests wait in the queue with the **Queued** status.

* Up to 1000 tests can be queued or running at once. A run that would go over this limit is rejected.
* A test that waits in the queue for too long ends with the **Error** status and `TEST_RUN_QUEUE_TIME_EXCEEDED`. See [Statuses](/running-tests/statuses.md).

## Cloud Proxy and IP addresses

All traffic of a cloud run's browser goes through a proxy, so your site sees requests from a known IP address. Choose the proxy in **Project settings → General → Cloud Proxy**. Each option is a location with its own public IP address. The list and the default are in [Cloud runner IP addresses](/preventing-failed-tests/project-settings.md#cloud-runner-ip-addresses), and the current list is also at `https://api.bugbug.io/v2/config/ips/`.

Choose the location closest to your servers, or the one your site expects, for example for content that depends on the visitor's country. To let cloud runs through a firewall or allowlist, allow the IP address of the selected proxy. See [VPN or a Firewall](/troubleshooting/vpn-or-a-firewall.md).

**Dedicated proxy.** If you need a proxy in another region or an IP address used only by your organization, we can add a private proxy for you. It's a paid add-on, available on all paid plans. See the dedicated IP add-on on the [pricing](https://bugbug.io/pricing/) page and [contact us](https://bugbug.io/contact/).

## Test a site that isn't public

Cloud runs can only reach sites that are reachable from the internet through the Cloud Proxy. They can't open `localhost` or a page in your private network.

* **Firewall or allowlist:** allow the Cloud Proxy's IP address, or send an extra HTTP header with every request. See [VPN or a Firewall](/troubleshooting/vpn-or-a-firewall.md).
* **Local build:** expose it with a tunnel. See [Test your local build or protected web page using ngrok](/running-tests/test-your-local-build-or-protected-web-page-using-ngrok.md).
* **Basic auth:** turn on **Password protected** in the Go to URL step. See [Testing basic auth password protected websites](/troubleshooting/testing-basic-auth-password-protected-websites.md).
* **Vercel preview deployments:** use the [Vercel integration](/integrations/vercel.md) with a protection bypass secret.

## FAQ

<details>

<summary>Can I run tests in the cloud on the Free plan?</summary>

No. The Free plan has local runs only. Cloud runs are available on all paid plans, starting from Core, and during the free trial. See [pricing](https://bugbug.io/pricing/).

</details>

<details>

<summary>Do cloud runs need my computer or the Chrome extension?</summary>

No. Cloud runs run on BugBug's servers. You can close the app and your computer while they run.

</details>

<details>

<summary>Do cloud runs use headless Chrome?</summary>

No. Cloud runs use a regular Chrome browser, not headless mode. The Chrome version is updated over time.

</details>

<details>

<summary>Can I watch a cloud run live?</summary>

Yes, step by step. While the test runs, each step shows its status and, once it's done, its screenshots. There's no live browser window or video. After the run you also get the DOM snapshot and logs in [runs history](/debugging-tests/runs-history.md).

</details>

<details>

<summary>Do cloud runs keep cookies or sessions between tests?</summary>

No. Every cloud run starts with a fresh browser, whatever the **Incognito mode** setting is. Log in within each test, for example with a [component](/editing-tests/components.md).

</details>

<details>

<summary>Why does my test pass locally but fail in the cloud?</summary>

Most often the page is slower in the cloud, the site blocks the Cloud Proxy's IP address, or the test depends on something only your browser has, such as a session or your network. Check the failed step's screenshot and error code, raise the timeout of slow steps, and allow the [Cloud Proxy's IP address](/preventing-failed-tests/project-settings.md#cloud-runner-ip-addresses). See [Cloud tests sometimes failing](/troubleshooting/cloud-tests-sometimes-failing.md).

</details>

<details>

<summary>Which IP address do cloud runs use?</summary>

The IP address of the Cloud Proxy selected in project settings. See [Cloud runner IP addresses](/preventing-failed-tests/project-settings.md#cloud-runner-ip-addresses).

</details>

<details>

<summary>Can I get a proxy in another country or a dedicated IP address?</summary>

Yes, as a paid add-on on all paid plans. We can add a private proxy in another region on request. See [pricing](https://bugbug.io/pricing/) and [contact us](https://bugbug.io/contact/).

</details>

<details>

<summary>How many tests can run in the cloud at the same time?</summary>

As many as your organization's [parallel runs](/running-tests/parallel-mode.md): 1 by default. The other tests wait in the queue.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bugbug.io/running-tests/in-cloud-on-server.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
