---
title: "Connect your app"
section: "Quick Start"
description: "Connect SmartestQA to the app under test: install the Chrome or Edge extension, add start page URLs per environment, set up mobile and desktop apps, and install an agent when you need one."
url: https://docs.smartestqa.ai/en/quick-start-connect.html
audience: [customer, admin]
updated: 2026-11-07
keywords: "extension chrome edge plugin start page url environment dev test prp agent api key online offline run on server mobile desktop"
---
# Quick Start: Connect your app

Before SmartestQA can record, it needs a way into your app and the address to open.

## In short

**On this page you can**

- Install the SmartestQA browser extension in Chrome or Edge.
- Add a start page URL with one address per environment: DEV, TEST, PRP.
- Set up mobile apps in Mobile Config and desktop apps through an agent.
- Decide whether you need an agent, then install one.
- Learn when an agent counts as Online , with a worked example.

**How to use it**

1. Click Add to Chrome , pin the extension and refresh open SmartestQA tabs.
2. In Start Page URLs , click + Add , enter a Name and the environment URLs.
3. Mark the main start page with Set as default .
4. Need an agent? Get it from Download Client and paste the host’s API key.
5. Wait until the host’s dot turns green with Online .

SmartestQA needs two things before it can record: a way into the app, and the address to open. For web apps that is the browser extension plus a start page URL. Mobile and desktop apps connect through the agent.

## Install the browser extension (web)

1. **Add it from the Chrome Web Store**

   Open [SmartestQA in the Chrome Web Store](https://chromewebstore.google.com/detail/smartest/gbmfljopgioefnghmjdcefolgbfpfaph) and click **Add to Chrome**. The same listing works in Edge.
2. **Pin it**

   Click the puzzle icon in the browser toolbar and pin SmartestQA so you can see it is active.
3. **Refresh the SmartestQA tab**

   Press `F5` on every SmartestQA tab that was already open. A newly installed extension cannot talk to tabs that were open before it was installed.

   The **Connect** step of the [Setup Roadmap](https://docs.smartestqa.ai/en/quick-start-progress.html#setup-roadmap) moves forward, and recording buttons open a new tab instead of the Web Store.

> **Note: How the app knows the extension is there**
>
> When you [start a recording](https://docs.smartestqa.ai/en/automate-add-steps.html#record-web), the page sends the extension a ping and waits 1.2 seconds for an answer. No answer means “not installed”: the Web Store opens in a new tab, and when you come back the page reloads and starts the recording by itself. If it still gets no answer after that reload, you see “Browser extension still not detected.” See [the fix](https://docs.smartestqa.ai/en/quick-start-troubleshooting.html#fix-extension-not-detected).

## Add a start page URL (web)

A start page URL is a named address with one value per [environment](https://docs.smartestqa.ai/en/concepts.html#environments). [Recording](https://docs.smartestqa.ai/en/discover-your-app.html), [AI generation](https://docs.smartestqa.ai/en/automate-ai.html#generate-from-prompt) and [new test cases](https://docs.smartestqa.ai/en/automate-test-cases.html#create-test-case) open it.

1. **Open the list**

   Go to **Configuration** › **Project Panel** › **Start Page URLs** and click **+ Add**. You can also use **Manage URLs** next to any start page selector.
2. **Fill in the addresses**

   Give it a **Name** and at least one of **DEV Environment URL**, **TEST Environment URL**, **PRP Environment URL**. Addresses must start with `http://` or `https://` and contain no spaces.

   | Name | DEV | TEST | PRP |
   | --- | --- | --- | --- |
   | Login | `https://dev.portal.example.com/login` | `https://test.portal.example.com/login` | *leave empty* |
3. **Set as default**

   Mark the one most tests start from with **Set as default**. New test cases, [pipelines](https://docs.smartestqa.ai/en/schedule-create.html#defaults) and AI use it.

> **Warning: Environments are DEV, TEST and PRP**
>
> PRP is the production-side environment. [Runs default to TEST](https://docs.smartestqa.ai/en/schedule-where.html#environment). An environment with no URL is greyed out in recording settings with “No URL defined for this environment”. Keep PRP empty unless you really mean to test production.

## Mobile and desktop apps

| Project type | Do this | Where |
| --- | --- | --- |
| MOBILE | Choose [where the app runs](https://docs.smartestqa.ai/en/project-settings-mobile.html#modes): [**Local device**](https://docs.smartestqa.ai/en/project-settings-mobile.html#local) (through your agent), [**AWS Device Farm**](https://docs.smartestqa.ai/en/project-settings-mobile.html#aws), [**BrowserStack**](https://docs.smartestqa.ai/en/project-settings-mobile.html#browserstack) or [**SmartTest Device Farm**](https://docs.smartestqa.ai/en/project-settings-mobile.html#device-farm) (an add-on; shows “Locked — upgrade plan” without it). Then upload the APK or IPA. | **Configuration** › **Project Panel** › [**Mobile Config**](https://docs.smartestqa.ai/en/project-settings-mobile.html) |
| DESKTOP | Install the agent on the [Windows](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop) or [macOS](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop) computer that has the app and Appium (with the Windows driver or the Mac2 driver). Then [configure the desktop application](https://docs.smartestqa.ai/en/project-settings-desktop.html#applications) and mark one as default. | **Device Farm** › **Test Agents** › [**Download Client**](https://docs.smartestqa.ai/en/agent-pool-agents.html#download-client), then [**Desktop Configuration**](https://docs.smartestqa.ai/en/project-settings-desktop.html) |

## Do you need an agent?

An **agent** is a small program you install on a computer you control. It runs tests there and streams the results back. You only need one when SmartestQA’s own servers cannot reach your app, or when the test needs a device or desktop app.

| Your situation | Run tests with | Agent needed? |
| --- | --- | --- |
| Web app reachable from the internet | **Run on Server**: headless on the [Smartest Server](https://docs.smartestqa.ai/en/schedule-where.html#server), always online | No |
| You want to watch the browser while a test runs | **Run on your Agent** on your own computer | Yes, on your machine |
| Web app behind a VPN, firewall or on an intranet | An agent on a machine inside that network | Yes, inside the network |
| Mobile app on a local phone or emulator | An agent on the computer the [device is plugged into](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#android-emulator) | Yes |
| Desktop app | An agent on the [Windows](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#windows-desktop) or [macOS](https://docs.smartestqa.ai/en/agent-pool-local-setup.html#macos-desktop) computer with the app | Yes, next to the app |
| Runs started from [CI/CD](https://docs.smartestqa.ai/en/integrations-cicd.html) | Self-hosted runners (admin page **Runners**, token based) | A runner instead |

### Install an agent

1. **Open Test Agents**

   Go to **Device Farm** › [**Test Agents**](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-list). Under **Localhost** you already have a [host](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-list) named after your email address. Each user gets one automatically. Use [**New Host**](https://docs.smartestqa.ai/en/agent-pool-agents.html#new-agent) only for shared machines such as a VM (names must be unique in the company).
2. **Download the client**

   In the [**Download Client**](https://docs.smartestqa.ai/en/agent-pool-agents.html#download-client) tab pick **Windows**, **Mac** or **Linux** and unzip the file. On servers, the [**Install Via CLI**](https://docs.smartestqa.ai/en/agent-pool-agents.html#install-cli) tab gives a one-line command that already contains the API key.
3. **Give it the API key**

   Copy the key with the [**Copy API Key**](https://docs.smartestqa.ai/en/agent-pool-agents.html#api-key) icon on the host row and paste it when the agent asks. Each host has its own key.
4. **Wait for green**

   Leave the agent running. The page refreshes [host status](https://docs.smartestqa.ai/en/agent-pool-agents.html#agent-status) every 5 seconds.

   The dot next to the host turns **green and pulses** with **Online**. Grey means **Offline**.

**When is an agent Online?** — How the status dot is decided

```text
Online   = the agent holds an open connection AND sent a heartbeat in the last 90 s
Offline  = connection closed, OR no heartbeat for 90 s (checked every 30 s)
Heartbeat: every 5 s while the agent runs
```

**Example:** a laptop with an agent goes to sleep at 10:00:00. Its last heartbeat was 09:59:58. The next sweep after 10:01:28 marks it Offline, so the dot turns grey between about 10:01:28 and 10:01:58. [Pipelines that start in that window and target it](https://docs.smartestqa.ai/en/schedule-where.html#agent) fail with “[The following agent(s) are currently offline](https://docs.smartestqa.ai/en/quick-start-troubleshooting.html#fix-agent-offline)”.

When the SmartestQA backend restarts, every host is set to Offline until its agent reconnects, which running agents do on their own.
