Testsigma
BOOK A DEMOGET STARTED FREE

Setting Up Testsigma Agent Locally

With Testsigma Agent you can run tests on local machines/devices in addition to Testsigma Cloud. This article discusses how to set up the Testsigma agent on your local machine.

Download Formats Available

The Testsigma Agents are available in the following forms:

  1. ZIP files
  2. Executable files
  3. DMG files
  4. Docker image

Steps to Download Testsigma Agent as a ZIP File

  1. Navigate to Agents and click Download Agent. Agents Page
  2. From the dropdown that appears, download the ZIP file as per your machine. ZIP Files

  3. After downloading the agent ZIP file, extract the Testsigma Agent ZIP file to a location of your choice. Some suggested locations to place the Testsigma agent folder are mentioned in the table below:

    Operating System Preferred Agent location
    Windows C:\Users<your_username>\
    Mac /Users/<your_username>/
    Linux /Users/<your_username>/

    Replace the <your_username> part with your account username.

    The home directory is recommended so as to avoid hassles of setting file permissions and ownership and also to avoid file corruption due to syncing with iCloud or Google Drive.

You can either start the Testsigma agent server as a process via the command line or terminal when needed. Or, you can run the Testsigma agent server as a server. For more information, refer to the below sections to see how to start the Testsigma Agent as a process or as a service.

Steps to Download Testsigma Agent as Executable File

  1. Navigate to Agents and click Download Agent.

  2. From the dropdown that appears, select the executable file supported by your machine.

    • For Windows, select exe,
    • For mac, select dmg,
    • For Linux, select bin to download the latest version of Testsigma Agent.
  3. Double click on the downloaded file.
  4. Choose the path where you would like to install the agent.
  5. Let the installer run till completion.

Once the installation is complete, you can either run the Testsigma Agent server as a process via the command line/terminal when needed.

Start the Testsigma Agent Server as a Process

For Windows

  1. Navigate to the Testsigma Agent installation folder and double click the start.bat or run start.bat in the command line file to start the Testsigma Agent.
  2. Wait for a few minutes for the Testsigma Agent to start up. Agent Start Windows
  3. After starting up you will be directed to the agent registration page. Redirect to Registration

For Mac/Linux

  1. Navigate to the Testsigma Agent installation folder and drag start.sh to a new terminal window and click on Return. New Terminal
  2. Wait for a few minutes for the Testsigma Agent to start up. Start Agent
  3. After starting up you will be directed to the agent registration page. Reg page

For more information on how to register Testsigma Agent, refer to the documentation on registering the Testsigma Agent.

NOTE:
  • You can also double-click the executable file in the installation folder to start the agent directly. Exe File
  • For Windows, locate TestsigmaAgent.exe and double-click to start the agent.

Start the Testsigma Agent Server as a Service

  1. For Windows: Go to the command line. For Mac/Linux: Go to the terminal.
  2. Navigate to the Testsigma Agent installation folder.
  3. Inside the Testsigma Agent installation folder, navigate to Wrapper > Bin.
  4. For Mac/Linux, if you want to install the agent as a service, use the command TestsigmaAgent start.
  5. For Windows, if you want to install the agent as a service, use the command TestsigmaAgent install.
NOTE:

At present, the option to install Testsigma Agent to start automatically when system boots is only supported for windows.

  1. To stop the service, run the command - TestsigmaAgent stop from the same location.

Commands that work with TestsigmaAgent:

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 Testsigma Agent

  1. Once your Testsigma agent is up and running, you will be directed to the Agent Registration page. Click Register to start the registration process. Register Button

  2. On the Add new Agent dialog,

    • Enter a Name for your machine.
    • Specify the maximum sessions in the textbox provided.
    • To set your agent’s visibility, select either the Public or Private radio button.
    • For agent activation, choose either Activate now or Activate later.
    • Click on Register & Activate Register & Activate
  3. Once the agent registration is successful, the dialog will display a success message.. Successful Message
  4. On the Agents page, the agent you registered will be displayed along with all the available browsers on that agent machine. Available Browsers
NOTE:
  1. There may be instances when you want to add the Testsigma agents to your Testsigma account but want to activate them later. Make sure to select the Activate Later radio button on the Add new Agent dialog. Activate Later
  2. On successfully adding the agent, you will be taken to the agent configuration page that contains the command that you can use to activate the agent later. Config page

It might take a couple of minutes for the operating system version and the browser names to appear. For more information on troubleshooting setting up Testsigma Agent, refer to the documentation on troubleshooting setting up Testsigma Agent if the details does not show up after 10 minutes.

Run Testsigma Agent Using Docker

There are two ways of starting the testsigma local agent using docker:

  • Create an Agent in Testsigma application, obtain the Activation Key, and use it to register the agent while the Docker container is booting.
  • Create and register a New Agent entirely while booting the Docker container.
NOTE:

Refer to the section above to add an agent using the Activate Later option.

  1. Once the Agent is registered, navigate to Agents > select the agent > Config, and copy the Activation Key. Activation Key
  2. Create a docker-compose.yml file with TS_ACTIVATION_KEY environment variables.

The following docker-compose snippet can be used to start a Testsigma Agent with headless Chrome, Firefox & Edge browsers: 

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
      - ./<foldername>:/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

This docker-compose snippet spins up four containers:

  1. Testsigma Agent
  2. Standalone Selenium with pre-installed Chrome
  3. Standalone Selenium with pre-installed Firefox
  4. Standalone Selenium with pre-installed Edge

Testsigma Agent will detect browser versions through the Environment Variables CHROME, FIREFOX, and EDGE. Note that these Environment Variables are all optional.


If you plan to run your test solely on the Chrome browser, there's no need to specify the FIREFOX and EDGE environment variables. Here's an example docker-compose file: 

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "http://chrome:4444"

  chrome:
    image: selenium/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp



If your system lacks sufficient resources, you can distribute browser containers across multiple systems and specify a remote debugging URL. Here's an example docker-compose file: 

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "<REMOTE_CHROME_URL>"
      FIREFOX: "<REMOTE_FIREFOX_URL>"
      EDGE: "<REMOTE_EDGE_URL>"



Testsigma Agent container allows controlling minimum and maximum heap memory settings using MIN and MAX environment variables. The default values for MIN and MAX will be 1GB and 8GB, respectively. Here's an example docker-compose file:

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      MIN: "-Xms1g"
      MAX: "-Xmx8g"
      CHROME: "<CHROME_URL>"
      FIREFOX: "<FIREFOX_URL>"
      EDGE: "<EDGE_URL>"



For ARM-based Systems (Mac M1 processors):
Google does not build Chrome for Linux ARM platforms. Instead, docker-seleniarm uses the open-source Chromium browser built for ARM. Here's an example docker-compose file: 

version: "3.9"
services:
  testsigma-agent:
    image: testsigmainc/testsigma-agent:latest
    container_name: testsigma-agent
    depends_on:
      - chrome
      - firefox
    volumes:
      - ./data/agent_data:/var/ts/agent
      - ./data/agent_temp:/tmp/agent_temp
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_ACTIVATION_KEY: "REPLACE_WITH_YOUR_ACTIVATION_KEY"
      CHROME: "http://chrome:4444"
      FIREFOX: "http://firefox:4444"
      EDGE: "<REMOTE_EDGE_URL>"
  chrome:
    image: seleniarm/standalone-chrome:latest
    shm_size: 1gb
    ports:
      - "4444:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

  firefox:
    image: seleniarm/standalone-firefox:latest
    shm_size: 1gb
    ports:
      - "4445:4444"
    volumes:
      - ./data/agent_temp:/tmp/agent_temp

  1. Save the docker-compose.yml file in an appropriate directory.
  2. Open a command-line interface and navigate to the directory. Execute the command docker-compose up, which will download the necessary images and start the Testsigma Agent.

Register a New Agent While Booting the Docker Container.

To create and register the Agent Automatically in one step, you must specify the environment variables below instead of TS_ACTIVATION_KEY.

TS_AUTO_REGISTRATION_KEY - Testsigma API key
TS_AUTO_REGISTRATION_TITLE - Title of the Agent
TS_AUTO_REGISTRATION_HTTP_PORT - HTTP Port for internal communication between Agent and Testsigma TS_AUTO_REGISTRATION_HTTPS_PORT - HTTPS Port for internal communication between Agent and Testsigma

Here's an example docker-compose file:

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
      - ./<foldername>:/root/.testsigma/agent/logs
    environment:
      TS_AUTO_REGISTRATION_KEY: "REPLACE_WITH_API_KEY"
      TS_AUTO_REGISTRATION_TITLE: "REPLACE_WITH_TITLE"
      TS_AUTO_REGISTRATION_HTTP_PORT: "REPLACE_WITH_ANY_AVAILABLE_PORT_NUMBER"
      TS_AUTO_REGISTRATION_HTTPS_PORT: "REPLACE_WITH_ANY_AVAILABLE_PORT_NUMBER"
      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

Please refer to the Activation Key sections for alternative methods of configuring the docker-compose file and starting the Agent using the docker-compose file.
Previous

Prerequisites for Testsigma Agent

Next

Setting up Android Local Devices

Did you find it helpful?

Learn how to execute low code tests across 3000+ device / browser environments.

Schedule a free demo
Testsigma

Want to contribute or report missing content?

Edit this Page on GitHub

Contributing Guidelines

Report an Issue

Testsigma See License

www.testsigma.com

©2026 Copyright , Testsigma Technologies Inc