# Testsigma Agent

> Install, register, configure, upgrade, and remove the Testsigma Agent, from a ZIP or executable to Docker, Kubernetes, and Argo CD.

The Testsigma Agent is a Java utility that runs on a test machine and orchestrates local test execution: queueing tests, running them, and returning results. Install it wherever you want to run tests on your own machines and devices rather than on Testsigma Cloud.

The agent bundles everything a local run needs: a Java JRE, so you install no Java yourself, the browser drivers from each browser vendor, Appium for mobile tests, and the mobile test recorder with its Android and iOS libraries.

## What the agent makes possible

**Local applications.** A corporate firewall blocks outside communication into a private network, so Testsigma's cloud servers cannot reach an application deployed inside it. The agent sits on a machine inside that network and relays between the cloud and the local machine over HTTPS, without opening the network up.

**The local mobile recorder.** Automating a mobile app needs the app's element attributes. With the device connected to the agent machine, the agent collects them and sends them to your browser, where you save them to Testsigma. The cloud recorder needs no local setup but runs with more delay.

The agent communicates in a pull model. It queries Testsigma's servers and receives responses, and Testsigma never pushes data to it, so no incoming connections are accepted. You do not need to whitelist any IPs for this, though outgoing connections to `*.testsigma.com` on port 443 must be allowed.

## System requirements

| Component | Requirement |
|---|---|
| Memory | 8 GB, dedicated to the tests |
| Disk space | Around 20 GB, including reserved space for screenshots and downloaded files |
| Processor | Dual-core or better |

## Install the agent

Go to **Agents** and click **Download Agent**, or take the direct download for your machine:

| Operating system | Executable | ZIP |
|---|---|---|
| Windows |  |  |
| macOS (Apple silicon) |  |  |
| macOS (Intel) |  |  |
| Linux |  |  |

![The download menu on the Agents page, listing the executable and ZIP for each operating system](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/Download_Agent.png)

The agent comes in 4 forms: a ZIP file, an executable, a DMG, or a Docker image. A ZIP or an executable installs on the machine and is then started and registered separately. A Docker image does all three at once. It also runs on Kubernetes as a Helm release. Deploying to managed devices at scale goes through PatchMyPC rather than any of these.

1. Select the ZIP for your machine from the dropdown.
2. Extract it to a location of your choice.

Put the folder in your home directory, which avoids file permission and ownership problems, and avoids corruption from iCloud or Google Drive syncing:

| OS | Location |
|---|---|
| Windows | `C:\Users\\` |
| macOS | `/Users//` |
| Linux | `/Users//` |

1. Select the file for your machine: `exe` for Windows, `dmg` for macOS, or `bin` for Linux.
2. Double-click the download.
3. Choose an installation path.
4. Let the installer finish.

A Docker agent starts and registers itself when the container boots, so the next 2 sections do not apply to it.

It registers 2 ways: with an activation key from an agent you created in Testsigma, or by creating and registering a new agent as the container boots.

**With an activation key.** Register the agent with **Activate later**, go to **Agents**, select the agent, open **Config**, and copy the **Activation Key**. Then create a `docker-compose.yml` with `TS_ACTIVATION_KEY` set to it.

**Registering as the container boots.** Set 4 variables instead of the activation key, and the container creates and registers its own agent:

| Variable | What it holds |
|---|---|
| `TS_AUTO_REGISTRATION_KEY` | Your Testsigma API key |
| `TS_AUTO_REGISTRATION_TITLE` | The name the agent appears under |
| `TS_AUTO_REGISTRATION_HTTP_PORT` | HTTP port for agent-to-Testsigma communication |
| `TS_AUTO_REGISTRATION_HTTPS_PORT` | HTTPS port for agent-to-Testsigma communication |

Everything else in the compose file below stays the same, with those 4 lines replacing `TS_ACTIVATION_KEY`.

This compose file uses the activation key, and starts the agent alongside headless Chrome, Firefox, and Edge:

```yaml
version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
      - firefox
      - edge
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "http://chrome:4444"
      FIREFOX: "http://firefox:4444"
      EDGE: "http://edge:4444"
  chrome:
    image: selenium/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp
  firefox:
    image: selenium/standalone-firefox:latest
    shm_size: 1gb
    ports:
      - "4445:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp
  edge:
    image: selenium/standalone-edge:latest
    shm_size: 1gb
    ports:
      - "4446:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp
```

Deploy the agent as a Helm release instead of installing it on a machine. The chart runs the agent together with the Selenium browsers it drives, so one install gives a working local execution environment. Like Docker, this route starts and registers the agent itself, so the next 2 sections do not apply.

The chart deploys a single pod holding the Testsigma Agent and one or more Selenium browsers as sidecars, plus a PersistentVolumeClaim that keeps the agent registered across restarts.

The agent and the browsers share a pod deliberately. They exchange files through a shared directory during upload and download steps, and the agent reaches each browser on `localhost`. Splitting them apart breaks file upload steps.

The same chart sits in 2 public registries, and neither needs credentials.

| Registry | Chart location | Container images |
|---|---|---|
| Azure Container Registry | `oci://testsigmaregistry.azurecr.io/charts/testsigma-agent` | Mirrored into the same registry |
| GitHub Container Registry | `oci://ghcr.io/testsigmainc/charts/testsigma-agent` | Pulled from Docker Hub |

Choose based on what your cluster is allowed to reach. Azure Container Registry with `global.imageRegistry` suits restricted egress, because the chart and every image come from one host. GitHub Container Registry suits a cluster that already reaches Docker Hub, and `global.imageRegistry` does not apply there.

The examples below use Azure Container Registry. For GitHub Container Registry, swap the chart address and drop the `global.imageRegistry` flag.

### Check the cluster prerequisites

1. A Kubernetes cluster running 1.23 or later. 1.29 or later is recommended, so the browsers start as native sidecars.
2. Helm 3.8 or later, for OCI chart support.
3. A default StorageClass, or the name of one you want to use. Check with `kubectl get storageclass`.
4. A node with enough free capacity for the whole pod. Chrome alone requests 1 CPU and 3Gi; with Firefox and Edge it requests 2 CPU and 5Gi. The pod is scheduled as a unit, so it has to fit on one node.
5. Outbound access from the cluster to your Testsigma instance and to the registry serving the chart and images.

The agent image runs as root, so a namespace enforcing the `restricted` Pod Security Standard rejects the pod. Use `baseline` for that namespace.

### Install the chart with an activation key

1. Go to **Agents** in Testsigma and create an agent with **Activate Later**. Select it, open the **Config** tab, and copy the **Activation Key**.

   ![The Config tab of an agent, showing the activation command with the TS_ACTIVATION_KEY value](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/Agent_Key.png)

2. Create a namespace and store the key in a secret. Write the key to a temporary file rather than passing it on the command line, so it stays out of your shell history and the process list.

   ```bash
   kubectl create namespace testsigma
   umask 077 && cat > activation-key.txt   # paste the key, then press Ctrl+D
   kubectl -n testsigma create secret generic testsigma-agent-auth \
     --from-file=TS_ACTIVATION_KEY=./activation-key.txt
   rm activation-key.txt
   ```

3. Install the chart.

   ```bash
   helm install ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
     --version 0.2.0 -n testsigma \
     --set global.imageRegistry=testsigmaregistry.azurecr.io \
     --set agent.auth.existingSecret=testsigma-agent-auth
   ```

4. Wait for the pod with `kubectl -n testsigma rollout status statefulset/ts-agent-testsigma-agent`.

5. The agent appears under **Agents** once it registers.

Managing secrets with External Secrets Operator or Sealed Secrets instead? Create `testsigma-agent-auth` through that tool.

The first start takes a few minutes. Each browser image is over 1 GB, and the browsers pass their readiness checks before the agent container starts.

For GitHub Container Registry, replace step 3 with the same command against `oci://ghcr.io/testsigmainc/charts/testsigma-agent`, without the `global.imageRegistry` flag. Every other flag applies to both registries.

### Install the chart with auto registration

The agent can register itself on startup instead, which suits environments where agents are created and destroyed often.

1. Get an API key from Testsigma.

2. Create the namespace and store the key in a secret, keeping it off the command line as above.

   ```bash
   kubectl create namespace testsigma
   umask 077 && cat > api-key.txt          # paste the key, then press Ctrl+D
   kubectl -n testsigma create secret generic testsigma-agent-auth \
     --from-file=TS_AUTO_REGISTRATION_KEY=./api-key.txt
   rm api-key.txt
   ```

3. Install with auto registration enabled.

   ```bash
   helm install ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
     --version 0.2.0 -n testsigma \
     --set global.imageRegistry=testsigmaregistry.azurecr.io \
     --set agent.auth.mode=autoRegistration \
     --set agent.auth.existingSecret=testsigma-agent-auth
   ```

Each agent registers under its own pod name, so `--set agent.replicaCount=3` runs three at once. `agent.auth.autoRegistration.title` sets the name shown in the application.

An activation key binds to one agent record, so `agent.replicaCount` stays at `1` in that mode. Auto registration is the only way to run more than one agent.

### Select your Testsigma region

The agent image is built against a specific Testsigma region, and the 3 builds are not interchangeable. Set `agent.region` to match the address you sign in to.

| Sign-in address | `agent.region` |
|---|---|
| `app.testsigma.com` | `us`, the default |
| `app-eu.testsigma.com` | `eu` |
| `app-in.testsigma.com` | `in` |

Add it to the install command with `--set agent.region=eu`.

### Enable more browsers on Kubernetes

Chrome is enabled by default. Firefox and Edge are available and disabled.

To enable them at install, add `--set browsers.firefox.enabled=true` and `--set browsers.edge.enabled=true` to the install command. To add them to an existing release:

```bash
helm upgrade ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent \
  --version 0.2.0 -n testsigma --reuse-values \
  --set browsers.firefox.enabled=true \
  --set browsers.edge.enabled=true
```

The pod is recreated, so the agent goes offline briefly and returns with the extra browsers registered.

Each browser you enable is reported to Testsigma as available on that agent, and adds 0.5 CPU and 1Gi to the pod's requests. Enable only the browsers you plan to use.

Edge is published for `amd64` only. On a cluster with `arm64` nodes, keep the pod on `amd64` with `--set nodeSelector."kubernetes\.io/arch"=amd64`.

### Install the chart using Argo CD

Argo CD does not detect OCI registries automatically, so register the repository first.

1. Go to **Settings > Repositories > CONNECT REPO > VIA HTTPS** and enter the details below.

   | Field | Value |
   |---|---|
   | Type | `helm` |
   | Name | `testsigma-charts` |
   | Repository URL | `testsigmaregistry.azurecr.io/charts`, or `ghcr.io/testsigmainc/charts` |
   | Enable OCI | Selected |
   | Username and Password | Leave empty |

2. Create the credential secret in the destination namespace, as in the activation key steps above.

3. Create the application.

   ```yaml
   apiVersion: argoproj.io/v1alpha1
   kind: Application
   metadata:
     name: testsigma-agent
     namespace: argocd
   spec:
     project: default
     source:
       repoURL: testsigmaregistry.azurecr.io/charts
       chart: testsigma-agent
       targetRevision: 0.2.0
       helm:
         releaseName: ts-agent
         values: |
           tests:
             enabled: false
           global:
             imageRegistry: testsigmaregistry.azurecr.io
           agent:
             region: us
             auth:
               mode: activationKey
               existingSecret: testsigma-agent-auth
     destination:
       server: https://kubernetes.default.svc
       namespace: testsigma
     syncPolicy:
       syncOptions:
         - CreateNamespace=true
   ```

4. Sync the application, from the UI with **SYNC** or from the CLI with `argocd app sync testsigma-agent`.

`CreateNamespace=true` changes how a sync behaves rather than starting one, so a new application stays **OutOfSync** until you trigger it. To have Argo CD deploy and self-heal without manual syncs, add `automated` with `prune: true` and `selfHeal: true` to `syncPolicy`.

Three things catch people out:

- `repoURL` holds the registry path only. The chart name belongs in `chart`, and there is no `oci://` prefix.
- `targetRevision` is the chart version, not the agent version.
- Argo CD does not run Helm test hooks, so set `tests.enabled` to `false`.

### Verify the Kubernetes installation

After a Helm install, run the bundled checks, which confirm the agent and every enabled browser are responding:

```bash
helm test ts-agent -n testsigma
```

After an Argo CD install, check the application state with `argocd app get testsigma-agent` instead. **Synced** and **Healthy** means the chart is applied and the pod is ready.

To inspect the agent directly, on either kind of install:

```bash
kubectl -n testsigma logs ts-agent-testsigma-agent-0 -c agent
kubectl -n testsigma exec ts-agent-testsigma-agent-0 -c agent -- \
  curl -sf http://127.0.0.1:8383/agent/health
```

Then confirm the agent is listed under **Agents** in Testsigma, and run a test against it.

### Helm configuration reference

Pass these with `--set`, or collect them in a values file and use `-f values.yaml`. `helm show values` on the chart lists every available setting.

| Setting | Default | What it does |
|---|---|---|
| `agent.region` | `us` | Testsigma region: `us`, `eu`, or `in` |
| `agent.auth.mode` | `activationKey` | `activationKey` or `autoRegistration` |
| `agent.auth.existingSecret` | | Secret holding the activation or API key |
| `agent.replicaCount` | `1` | Above 1 requires `autoRegistration` |
| `agent.resources` | 2Gi and 500m CPU | Agent requests. The JVM heap derives from the memory limit |
| `agent.persistence.enabled` | `true` | Keeps the agent registered across restarts |
| `agent.persistence.size` | `10Gi` | Volume size |
| `agent.persistence.storageClass` | | Leave empty to use the cluster default |
| `browsers.chrome.enabled` | `true` | |
| `browsers.firefox.enabled` | `false` | |
| `browsers.edge.enabled` | `false` | |
| `global.imageRegistry` | | Pull every image from one registry |
| `proxy.enabled` | `false` | Set with `proxy.httpProxy` and `proxy.noProxy` |
| `caBundle.existingConfigMap` | | Mounts a corporate CA certificate |
| `imagePullSecrets` | `[]` | For registries that require authentication |

Keep `agent.persistence.enabled` set to `true`. The agent stores its registration on that volume, so disabling it makes every restart create a new agent and leave the previous record unused in your account.

Manage the release with whichever tool installed it. Helm commands do not apply to an application deployed by Argo CD, and editing an Argo CD application by hand is reverted on the next sync.

**Installed with Helm.** Upgrade with `helm upgrade ts-agent oci://testsigmaregistry.azurecr.io/charts/testsigma-agent --version  -n testsigma --reuse-values`, and remove it with `helm uninstall ts-agent -n testsigma`.

**Installed with Argo CD.** Change `targetRevision` to the new chart version and sync, or remove it with `argocd app delete testsigma-agent`.

The volume is kept, so the agent can be reinstalled with the same registration. To delete it, run `kubectl -n testsigma delete pvc data-ts-agent-testsigma-agent-0`.

### Troubleshoot the Kubernetes install

| Symptom | Cause and resolution |
|---|---|
| Pod stays `Pending` | No node has enough free CPU or memory, or the volume cannot be provisioned. Run `kubectl -n testsigma describe pod` and `kubectl -n testsigma get pvc` |
| `ImagePullBackOff` | The image is not available at the configured registry. Confirm `agent.region`, and remove `global.imageRegistry` to pull from Docker Hub |
| `CreateContainerConfigError` | The secret named in `agent.auth.existingSecret` does not exist in that namespace |
| The pod runs but no agent appears in Testsigma | Usually the wrong `agent.region`, or an activation key from a different region. Check the agent logs |
| The pod is rejected on creation | The namespace enforces the `restricted` Pod Security Standard. The agent image requires `baseline` |
| A browser crashes mid test | The browser needs more shared memory. Raise `browsers.chrome.shmSize` and its memory limit together |

For agent startup and registration errors themselves, see the [frequently asked questions](#frequently-asked-questions) at the end of this page.

## Start the agent

### As a process

On Windows, go to the installation folder and double-click `start.bat`, or run it from the command line. On macOS and Linux, drag `start.sh` into a new terminal window and press **Return**.

Startup takes a few minutes, and the agent registration page opens when it finishes.

Double-clicking the executable in the installation folder starts the agent directly. On Windows that file is `TestsigmaAgent.exe`.

### As a service

1. Open a command line on Windows, or a terminal on macOS and Linux.

2. Go to the installation folder, then into **Wrapper > Bin**.

3. On macOS and Linux, run `TestsigmaAgent start`. On Windows, run `TestsigmaAgent install`.

4. To stop it, run `TestsigmaAgent stop` from the same location.

Starting automatically at system boot is supported on Windows only.

`TestsigmaAgent` accepts these commands from **Wrapper > Bin**:

```text
console      Launch in the current console
start        Start in the background as a daemon process
stop         Stop if running as a daemon or in another console
restart      Stop if running and then start
condrestart  Restart only if already running
status       Query the current status
install      Install to start automatically when system boots
installstart Install and start running as a daemon process
remove       Uninstall
dump         Request a Java thread dump if running
```

## Register the agent

1. Click **Register** on the **Agent Registration** page, which opens once the agent is running.

2. Enter a **Name** for the machine.

3. Enter a value in **Max sessions for this machine**, which limits parallel executions so the machine does not slow down. It cannot exceed the parallels available to your account, and the field needs enabling by Testsigma support.

4. Select **Public** or **Private** for the agent's visibility.

5. Select **Activate now** or **Activate later**.

6. Click **Register & Activate**.

![The Add new Agent dialog, with fields for the device name, visibility, and activation](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/Agent_Details.png)

The agent then appears on the **Agents** page with the browsers available on that machine. The operating system version and browser names take a couple of minutes to appear. If they have not appeared after 10 minutes, the agent has a setup problem.

**Activate later** takes you to the agent configuration page, which carries the command for activating the agent when you are ready.

## Connect a local device

A local Android or iOS device connects to the machine running the agent, and then appears under **Devices** on that agent's page in Testsigma.

Developer options have to be enabled on the device first.

1. Open **Settings** and tap **About Phone**.
2. Go to **Software information** and tap **Build number** 7 times.
3. Open **Developer Options** from **Settings**.
4. Turn on **USB Debugging**.
5. Connect the device to the machine running the agent, and accept the **Allow USB Debugging** alert. Select **Always allow from this computer** if it appears.
6. Go to **Agents** in Testsigma and click the registered agent.
7. The device appears under **Devices**.

   ![The Devices tab of an agent, listing a connected Android device with its ID, model, OS, and resolution](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_android_device_2.png)

To run a test on it, select the **Connected Machine** and the **Device**.

Device-level settings differ by brand, and some block local execution until they are changed. See [Run tests](https://testsigma.com/docs/v2/run-tests/test-runs/#why-do-local-runs-on-a-real-android-device-fail-with-a-permission-error) for the settings Realme, Oppo, OnePlus, and Xiaomi need.

An iOS device needs a provisioning profile configured in Testsigma before it will run tests. On Windows, it also needs iTunes installed to connect the device.

Install iTunes from Apple's own `.exe` installer. Uninstall it first if it came from the Microsoft Store, and confirm that Apple Mobile Device Service is running in Task Manager.

Creating a provisioning profile moves between Testsigma and the Apple Developer portal:

1. Go to **Settings > iOS Settings**, open the **Provisional Profile** tab, and click **+ Create new profile**.
2. Enter a **Profile Name**.
3. Click **Generate Request** to create a Certificate Signing Request, then **Download Request** to save the CSR file.
4. In the Apple Developer portal, go to **Certificates, Identifiers & Profiles** and click **+** next to **Certificates**.
5. Select **iOS App Development** under **Software** and click **Continue**.
6. Upload the CSR file and click **Continue**.
7. Click **Download** to save the certificate.
8. Back in Testsigma, click **Upload Signed file** under **Upload Certificate** and select it.
9. In the Apple Developer portal, go to **Profiles** and click **+**.
10. Select **iOS App Development** under **Development** and click **Continue**.
11. Select an **App ID** and click **Continue**.
12. Select the certificates to include and click **Continue**.
13. Select the **Devices** to include and click **Continue**.
14. Name the provisioning profile and click **Generate**.
15. Click **Download** to save it.
16. In Testsigma, click **Upload Certificate** next to **Provisioning Profile**, select the file, and click **Create**.

Then go to **Agents**, select the agent, and find the device under **Devices**. To run a test on it, select **Local Devices** as the **Test Lab**, then the machine and device under **Test Machine**.

The CSR and provisioned certificates can be downloaded from the same screen, for checking the provisioning profile's validity. **Delete** removes a certificate.

These are the errors the setup produces:

| Error | What it means |
|---|---|
| "Invalid certificate uploaded, please upload a valid certificate." | The certificate is wrong or corrupted. Generate it from the CSR created in the iOS Settings profile in Testsigma |
| "Certificate uploaded is not included in this provisioning profile." | The provisioning profile was built with a different certificate. Use the one uploaded in iOS Settings |
| "Upload is not resigned" | Re-signing is still in progress. Track it in the **Provisioning Profile Details** dialog, and select the upload once it finishes |
| "Device initializing" | The agent is still setting the device up. Setup errors appear on the **Devices** tab of the agent details page |

## Command-line arguments

Arguments passed at startup configure registration, logging, memory, browsers, and proxies:

```bash
./start.sh --TS_AUTO_DETECT_PROXY=true
```

Pass these the first time you start the agent only. After that, start it by double-clicking the executable in the agent folder.

| Argument | What it does |
|---|---|
| `--TS_AUTO_DETECT_PROXY` | Detects and uses a network proxy, including proxies configured through PAC files |
| `--TS_USE_SYSTEM_PROXY` | Uses the system's own proxy configuration |
| `--TS_NON_PROXY_HOSTS` | Hosts that bypass the proxy |
| `--TS_DELEGATE_SSL_VALIDATION` | Hands SSL validation to your SSL inspection tools instead of Java, bypassing certificate validation errors |
| `--TS_TRUST_STORE_TYPE` | The trust store type to use |
| `--TS_ACTIVATION_KEY` | Registers the agent with an activation key |
| `--TS_ADDITIONAL_JVM_ARGS` | Extra JVM arguments |
| `--TS_AGENT_JAR_PATH` | Path to the agent JAR |
| `--TS_JAVA_HOME` | Path to a Java installation, instead of the bundled JRE |
| `--TS_DATA_DIR` | The agent's data directory |
| `--TS_ROOT_DIR` | The agent's root directory |
| `--TS_LOGGING_LEVEL` | Log verbosity |
| `--TS_ENABLE_GC_LOG` | Writes garbage collection logs |
| `--TS_ENABLE_HEAP_DUMP` | Writes a heap dump |
| `--TS_IS_HEADLESS` | Runs browsers headless |
| `--TS_IS_MOBILE_DISABLED` | Disables mobile support |
| `--TS_CHROME_PATH` | The Chrome executable path, for when the agent cannot find the browser itself |

### Bypass the proxy for specific hosts

Where the agent must use a proxy for most traffic but connect directly to internal or trusted domains, set the non-proxy hosts in the agent's configuration.

1. Open the **TestsigmaAgent** installation directory.

2. Go to **agent_data** and open `args.yml`.

3. Add or update these properties, separating domains with a pipe:

   ```text
   http.nonProxyHosts: "localhost|127.0.0.1|*.testsigma.com|*.amazonaws.com"
   https.nonProxyHosts: "localhost|127.0.0.1|*.testsigma.com|*.amazonaws.com"
   ```

## Configure logs

The log level controls what the agent writes to the command line and to its local log files. The default is INFO.

Open an agent from the **Agents** list page, click the **Agent Settings** icon in the right navigation bar, and select the level for the CLI and for local files.

![The agent Settings panel with the log level options for the CLI and local files](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_agent_3.png)

| Level | What it logs |
|---|---|
| ERROR | Critical issues that cause the agent to fail |
| WARN | Warnings and errors, to catch problems early |
| INFO | General information, warnings, and errors. The default |
| DEBUG | Detailed information for debugging, plus everything above |
| TRACE | Traces of the execution flow for deep debugging, plus everything above |
| ALL | Every message the agent produces |

Restart the agent after changing the log level, or the new setting does not take effect.

To send logs to Testsigma, go to **Agents**, hover over the agent, and click **Report Agent**. Describe the problem in the dialog and click **Report**.

## Keep the agent up to date

Automatic upgrades are on by default. Start the agent, and it downloads a higher version if one exists, then restarts itself and reports **Upgrade Success**. Nothing is required from you.

A network interruption during the download restarts it from the beginning once the connection is stable.

To control when upgrades happen, go to **Agents > Agent > Settings > Agent upgrade settings** and select **Manual**. The interface then shows the current and latest versions when an upgrade is available, and **Upgrade** installs it.

![The agent Settings panel set to manual upgrades, showing the current and latest versions with an Upgrade link](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/Current_Latest_Version_Agent.png)

### Update the agent manually

Use this when an automatic upgrade fails, usually from network conditions or a misconfiguration.

1. Check whether the agent is running. Its icon sits in the system tray on Windows, and in the status bar on macOS and Linux. If it is not running, skip to step 3.

2. Stop it from the agent directory. On Windows, open a command prompt there and run `./stop.bat`. On macOS and Linux, open a terminal there and run `./stop.sh`.

3. Delete the contents of the `TestsigmaAgent` folder.

4. Click **Download Agent** on the **Agents** page to get the latest ZIP.

5. Extract the `TestsigmaAgent` folder from the ZIP into the same location on your machine.

6. Start the agent from that directory. On Windows, run `./start.bat`. On macOS and Linux, run `./start.sh`.

If the agent will not connect after an update, delete it completely and reinstall. See [Force delete](#force-delete).

### Update browser drivers manually

The agent talks to each browser through a driver file, and driver updates ship with the agent's automatic updates. A failed update, from network conditions or a firewall, leaves you to replace the file yourself.

Download the driver for your browser version and operating system from the SeleniumHQ downloads page, then place it in the matching directory inside the agent folder:

| Browser | Directory |
|---|---|
| Google Chrome | `/drivers/googlechrome` |
| Microsoft Edge | `/drivers/edge` |
| Mozilla Firefox | `/drivers/mozilla` |
| Internet Explorer | `/drivers/internetexplorer` |

The `internetexplorer` folder exists in the Windows agent only.

## Trigger tests on a local agent from another machine

Tests can run on one machine's agent while you work from another, on the same Testsigma account.

1. Install and register the agent on the target machine.

2. Go to **Test Plans**, open the plan, and click **Edit**.

3. On **Add Test Suites & Link Machine Profiles**, click **Link Test Machine** and select the target machine.

   ![The second step of Edit Test Plan, with the Link Test Machine option beside the linked test machines](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_trigger_4.png)

## Delete an agent

A long agent list makes picking the right machine harder, so an agent can be pushed to an obsolete state instead of deleted.

To obsolete one, go to **Agents**, click the ellipsis icon (⋮) beside the agent, click **Obsolete**, then click **Obsolete Agent** in the dialog. **Restore** brings it back.

An obsolete agent cannot execute tests.

To delete one for good, click the ellipsis icon (⋮), click **Delete Permanently**, then confirm in the **Delete Agent Permanently?** dialog.

![The Restore and Delete Permanently options on an obsolete agent in the Agents list](https://s3.amazonaws.com/website-static-docs.testsigma.com/new_images/projects/Updated_Doc_Images/update_agents_5.png)

### Force delete

Where an agent will not come off cleanly, remove it in 4 places:

1. Click the **Testsigma Agent** icon in the status bar on macOS and Linux, or the system tray on Windows, and click **Quit**.

2. Delete the folder the agent was started from.

3. Delete the agent's entry in the Testsigma agents list.

4. Delete the `agent.properties` file.

`agent.properties` lives in the agent's config directory:

| OS | Location |
|---|---|
| Windows | `%userprofile%\AppData\Roaming\Testsigma\Agent\config\` |
| Linux | `$HOME/.testsigma/agent/config/` |
| macOS | `$HOME/Library/Application Support/Testsigma/Agent/config/` |

## Frequently asked questions

### How does Testsigma communicate with the agent?

The agent queries Testsigma's servers and receives responses. Testsigma never initiates a connection to it, so no inbound firewall rule and no IP whitelisting is needed. Outgoing connections to `*.testsigma.com` on port 443 have to be allowed.

### What are the resource requirements?

8 GB of memory dedicated to the tests, around 20 GB of disk including space for screenshots and downloads, and a dual-core processor or better. See [System requirements](#system-requirements).

### Do I need a Windows machine to run the agent?

No. The agent runs on Linux, Windows, or macOS.

### Can I run the agent without installing it on a machine?

Yes. A Docker image and a Helm chart both run it as a container, and both register the agent themselves. See the Docker and Kubernetes tabs under [Install the agent](#install-the-agent).

### How do I run more tests at once on one machine?

Raise **Max sessions for this machine**, set when you register the agent. See [Register the agent](#register-the-agent) for its limits.

### How do I make the agent bypass our proxy for internal domains?

Add the domains to `http.nonProxyHosts` and `https.nonProxyHosts` in `args.yml`, in the agent's `agent_data` directory. See [Bypass the proxy for specific hosts](#bypass-the-proxy-for-specific-hosts).

### How do I make the agent log more detail?

Change the log level from **Agent Settings** on the agent's page, and restart the agent. DEBUG and TRACE add progressively more detail. See [Configure logs](#configure-logs).

### How do I stop the agent upgrading itself?

Set **Agent upgrade settings** to **Manual**, under **Agents > Agent > Settings**. See [Keep the agent up to date](#keep-the-agent-up-to-date).

### Why won't the agent start?

An agent that fails to start, or starts and terminates immediately, records the cause in its logs, so read those first. A common one is a port conflict: the agent detects available ports automatically, and an error reading "Port not available" means 8383 or 8484 is taken.

Check them with `lsof -i :8383` on Linux and macOS, or on Windows with:

```text
Get-Process -Id (Get-NetTCPConnection -LocalPort 8383).OwningProcess
```

Repeat for 8484, and free whichever port is held. If the logs are unclear, send them to support@testsigma.com.

### Why doesn't the agent detect my installed browsers?

The agent could not find the web driver during startup, so its browser scan failed. Give it the browser path directly.

Open `chrome://version` in Chrome, copy the executable path, then start the agent with it:

```bash
sudo sh start.sh --TS_CHROME_PATH=<chrome_executable_path>
```

On Windows, use `start.bat --TS_CHROME_PATH=`. The agent scans that path, writes it into `args.yml`, and detects the browser on later runs without reconfiguration.

### Why is the agent download blocked?

Your network is blocking the domains and IPs the agent needs. Whitelist these:

| Purpose | Domain | IPs |
|---|---|---|
| Local agent and cloud services | `app.testsigma.com` | 166.117.52.243, 166.117.190.246 |
| Testsigma Tunnels | `connect.testsigma.com` | 166.117.49.200, 166.117.156.234 |
| Mobile Recorder | `mobilerecorder.testsigma.com` | 166.117.86.235, 166.117.227.251 |
| Asset Proxy | `asset-proxy.testsigma.com` | 166.117.67.252, 166.117.170.206 |
| Test lab incoming connections | | 35.174.92.188, 34.204.63.14, 74.50.105.97 |

The agent also downloads browser drivers, so whitelist their sources: `googlechromelabs.github.io`, `chromedriver.storage.googleapis.com`, `storage.googleapis.com`, `registry.npmmirror.com`, and `raw.githubusercontent.com` for Chrome and Firefox, and `msedgewebdriverstorage.blob.core.windows.net` for Edge and Internet Explorer. Two more Testsigma services need allowing as well: `static-id.testsigma.com` and `id.testsigma.com`.