Skip to content
Docs
Arcus
Popular questions
↑↓ to navigate↵ to selectesc to close
Book a demo

Install the Arcus Agent

The Arcus Agent is a desktop app that lets Arcus author, debug, and run tests against the browsers and devices on your own machine. You need it to use Copilot on your machine, to run tests against a local build or an application that isn’t publicly accessible, or to test on a phone or emulator connected to your computer. Cloud runs don’t need it.

TaskIn the cloudOn your machine
Copilot on a web applicationNothing to installArcus Agent running
Copilot on an Android or iOS appNothing to installArcus Agent running, with a device or emulator connected
Copilot on a Windows desktop appNot availableArcus Agent running on a Windows computer
Test runs that use a Local Agent run configurationNot applicableArcus Agent running, signed in, and on a profile used for execution

The agent must be running, not only installed, for a session or run to use it.

When a newer version is available, the Copilot configuration shows Agent update available with Update Arcus Agent, and a test that needs the newer version shows “This test needs a newer Arcus Agent” until you update.

The Arcus Agent runs on macOS, Windows, and Linux. My Local Device detects your operating system and offers the matching download. On a Mac, you choose between Apple Silicon and Intel.

Once installed, the agent runs in the background with an icon in the menu bar on a Mac, or in the system tray on Windows and Linux. You check and manage it from My Local Device and from the menu bar app.

  1. In the left navigation, click My Local Device. If no agent is running on your machine, the page shows Not running and the download options.

  2. Click Download for Apple Silicon or Download for Intel. The installer is a .pkg file of about 500 MB.

  3. Open the downloaded file. The Install Arcus Agent installer opens.

  4. Click Continue through Introduction and Destination Select.

  5. In Installation Type, click Install. A standard install takes about 1.35 GB and goes in your home folder, so only you can use the agent on this Mac. To install it somewhere else, click Change Install Location… first.

    The Install Arcus Agent installer at Installation Type, saying the install takes 1.35 GB in your home folder for the current user only, with Install outlined.

  6. When the installer says The installation was successful, click Close. The Arcus Agent starts and its icon appears in the menu bar. If it doesn’t, open Arcus Agent from Spotlight or your Applications folder.

    The Install Arcus Agent installer at Summary, saying The installation was successful, with Close outlined.

  7. When macOS asks whether arcus.testsigma.com can access other apps and services on this device, allow it. Arcus uses this local network access to reach the agent.

  8. Go back to My Local Device. The page fills in on its own once the agent responds. To check straight away, click Re-check.

The Windows installer sets up the agent for your Windows user account, in your AppData\Local folder. It doesn’t ask for administrator rights.

  1. In the left navigation, click My Local Device. If no agent is running, the page shows “The Agent isn’t running on this device” and the download options.

  2. Under Download it, check that Windows is selected.

  3. (Optional) In Profile, select the profile your admin set up for this machine. If you keep Default, you don’t need a profile file.

  4. Click Download for Windows.

  5. Open the downloaded installer. The Setup - Arcus Agent wizard opens.

  6. In Agent profile, click Next. Setup uses the profile you downloaded from Arcus if it finds one in your Downloads folder. To choose a profile file yourself, click Browse… before you click Next. If Profile file is empty, the agent keeps this computer’s current profile or uses the defaults.

  7. In Select Additional Tasks, select or clear Create a desktop shortcut and Start Arcus Agent at sign-in, then click Next.

  8. If Setup lists applications that are using files it needs to update, select Automatically close the applications and click Next.

  9. On the last screen, keep Start Arcus Agent selected and click Finish. The agent starts, and its icon appears in the system tray.

  10. Go back to My Local Device. Once the agent responds, the page shows your computer’s name with Not signed in. To check now, click Re-check.

Copilot can use the agent now. To run test plans on this computer, sign in the agent.

The Linux installer is a self-extracting ArcusAgent-Linux.run file. It installs the agent for your user in ~/.local/share/testsigma/agent/install and doesn’t need root.

  1. In the left navigation, click My Local Device, and check that Linux is selected under Download it.

  2. Click Download for Linux.

  3. Open a terminal in the folder you downloaded it to, and run it as yourself, not as root:

    Terminal window
    chmod +x ArcusAgent-Linux.run
    ./ArcusAgent-Linux.run
  4. If the folder has an .arcusprofile file, the installer asks whether to connect the machine with it. Press Enter to connect it, or type n to skip.

The installer adds Arcus Agent to your applications menu, sets it to start at sign-in, and starts it. Its icon appears in the system tray. On Linux, the icon opens a menu rather than the panel described in Use the menu bar app. On a machine with no desktop session, the installer sets the agent up as a systemd user service instead.

To pass options, add them after --, for example ./ArcusAgent-Linux.run -- --desktop-shortcut:

  • --desktop-shortcut: also adds an icon to the desktop.
  • --headless: runs the agent as a background service, with no menu entry or tray icon.
  • --profile=FILE: connects the machine with this profile file.
  • --no-connect: connects no profile.
  • --all-users: run as root to install the agent in /opt for every user on the machine.

To run the agent without installing it, download the Portable zip from My Local Device. Unzip it and start the agent from the ArcusAgent folder:

  • macOS and Linux: open a terminal in the folder and run ./ArcusAgent.
  • Windows: open ArcusAgent.exe.

Keep it running while you use Arcus.

Click the Arcus Agent icon in the menu bar on a Mac, or in the system tray on Windows. The top of the panel shows the agent’s version and a status card. The card shows the machine’s name, how many browsers and devices it found, and anything that needs your attention, such as Profile updated: restart to apply. Click Open Arcus to open Arcus in your browser.

The Arcus Agent menu bar app at version 3.0.1, with the status card Profile updated: restart to apply, the This machine tab outlined, and the browsers and devices it found

The panel has 4 tabs:

TabShows
This machineThe Browsers the agent found, with their versions, and connected Devices. With no device, it says to connect an Android phone with USB debugging on, or a paired iPhone.
ProfileThe profile this machine is on, with its version and what it’s used for, such as Default · Authoring. Click Open to open the profile in Arcus, or What Default sets on this machine to see its settings. Other profiles lists the account’s other profiles.
ActivityThe test runs and Copilot sessions running on this machine. When nothing is running, it says so.
LogsUnder Agent, the agent’s own logs: Agent, Tray, Appium, and Agent Pilot, with their sizes. Under Runs and sessions, a log for each recent run and Copilot session. A log that’s being written now shows Live.

The Logs tab of the menu bar app, with the Agent, Tray, Appium, and Agent Pilot logs outlined and Agent Pilot marked Live

Click a log to read it. Type in Filter lines to search it, or show All lines, Warn+, or only Error. The viewer follows new lines as they arrive, and the footer reads Following. Use the pause control to stop following, and Jump to latest to go back to the newest lines. The other controls wrap long lines, copy the lines, and clear the view.

The agent.log viewer showing Warn+ lines, with the All, Warn+, and Error filters outlined

To follow a log in the Terminal app instead, click the terminal icon beside it, then click Open in Terminal. To run the command yourself, click Copy command. Terminal starts from the log’s last 500 lines.

The Open Tray in Terminal prompt, with the warning that Terminal shows raw lines and credentials are not masked outlined, and Copy command and Open in Terminal

At the bottom of the panel, Quit Arcus Agent stops the agent. Copilot sessions and runs on this machine can’t use it until you start it again. The profile name and version are shown beside it.

Click the settings icon at the top of the panel:

  • Start at login: start the agent when you sign in to your computer.
  • Import profile…: apply a profile file an admin gave you. See Change the machine’s profile.
  • Edit arguments…: open the agent’s args.yml file in a text editor to change the arguments the agent starts with. Save the file, then restart the agent.
  • Open folder: open the agent’s Install, Data, or Logs folder. Support may ask for files from the logs folder.
  • Troubleshoot, for when restarting the agent doesn’t fix a problem. Each option asks you to confirm, and the agent restarts once its current runs finish.
    • Clear cache…: removes temporary files, browser data, and run artifacts. The machine’s sign-in, settings, and logs are kept.
    • Reset Arcus Agent…: removes everything the agent keeps on the computer, including its sign-in, settings, arguments, and paired iPhones. Only its logs are kept. Sign the machine in again afterwards.
    • Uninstall Arcus Agent…: removes the agent from your Mac. Uninstall and delete all data… also removes the machine from Arcus and deletes the agent’s logs, run logs, profile, sign-in, and downloaded tools. This can’t be undone.

The bottom of the settings shows the agent’s version and the machine’s name.

The menu bar app settings, with Start at login, Import profile, Edit arguments, and Open folder, and the Troubleshoot options outlined

Copilot can use your machine as soon as the agent is running. Until the agent is signed in, My Local Device shows “This Agent isn’t signed in. Copilot works. Sign in to run tests and show it to your team.” To run tests on the machine or let your team see it, sign it in.

  1. On My Local Device, click Sign in.

  2. In Sign in this Agent, enter the code the agent shows in its window, in the form XXXX-XXXX, then click Continue. To show the code in a terminal, run ArcusAgent connect.

    The Sign in this Agent dialog, with the XXXX-XXXX code field outlined

  3. In Sign in this device to your account?, check the Machine, System, and Account, then click Sign in.

    The Sign in this device to your account? dialog listing the machine, system, and account, with Sign in outlined

Arcus shows “Signed in”, and the header changes to Connected · Idle. The machine appears under Agents on this account, marked This device, and in Settings > Profiles and agents > Agents. You can then pick it as the Agent in a run configuration. See Run Configurations.

If the header shows Needs attention instead, see Needs attention.

If an admin gave you a profile file, importing it signs the machine in too. See Change the machine’s profile.

If the agent is signed in to another account

Section titled “If the agent is signed in to another account”

If the agent on your machine is signed in to a different Arcus account, My Local Device shows Other account and “The Agent is on another account”. Click Reset and sign in, then sign in as above.

If the reset doesn’t work, run this in Terminal, then start the agent again:

Terminal window
ArcusAgent reset --hard

This removes the other account from the machine.

My Local Device shows the agent on the computer your browser is running on. The header shows the machine’s name, its status, the agent’s version, and, once it’s signed in, its profile and what the profile is used for, such as Authoring:

To check the agent again, click the refresh icon in the header.

My Local Device for a signed-in machine, with the Connected · Idle, Default, and Authoring chips outlined, the This device details, a Profile updated notification, and Agents on this account

  • This device: how many of the agent’s 4 application services are running, the agent’s version, and when Arcus last heard from it. Below that are the machine’s hostname, IP address, operating system, who signed it in and when, and its Profile and version.
  • Notifications: anything that needs your attention, such as a service that isn’t running, with what to do about it. After a profile changes, it shows “Profile updated: restart to apply” until the agent restarts. When all is well, it says “Nothing needs your attention on this machine.”
  • Agents on this account: every machine with the agent on your account, with when each last made contact. A green dot means the machine’s agent is in contact now, and a grey dot means it isn’t. This list is for visibility only. Arcus always uses the agent on the machine you’re working on.

Arcus recognizes a machine by the sign-in its agent saved. If an update or reinstall loses that sign-in, the agent signs in as a new machine, for example MACHINE.local (2), and the old entry stays offline. Click Delete on the old entry to remove it.

The Services tab lists the agent’s application services, with each one’s state and version:

ServiceNeeded for
Web testingWeb authoring
Mobile testing: AndroidAndroid authoring
Mobile testing: iOSiOS authoring
Agentic AI capabilitiesEvery Copilot session

A service that’s ready shows Idle. One that has stopped shows Not running.

Below them, System services lists the agent’s own services: Agent core, Debugger stream, and Log collector, with each one’s status and how long it has been running.

The Services tab of My Local Device. Callouts mark (1) Application services, (2) System services, and (3) Restart all services.

To restart them all, click Restart all services, then Restart. Arcus shows “All services restarted”. Each service can take a few minutes to come back, and the status shows Needs attention until they all have.

  • Mobile devices: the phones and emulators connected to this machine over USB or Wi-Fi. After you connect one, click Scan for devices.
  • Browsers on this machine: each browser the agent found, with its version and whether it’s Ready or Not ready. A Local Agent run configuration offers these browsers.

On a Mac, Safari shows Not ready until the agent has downloaded WebKit, the engine Safari tests run on. The agent downloads it once the machine is signed in, and checks again every hour. iOS simulators also need Xcode: the Summary tab shows “iOS simulators need Xcode” with Open App Store. Install Xcode, open it once, then restart the agent. Real iPhones work without it.

The emulator build note and Browsers on this machine, listing Google Chrome, Safari, and Chrome for Testing, each Ready.

A build recorded on an emulator doesn’t run on a real device. An emulator records on x86_64, and cloud real devices run arm64, so upload a build for each. See Apps.

The Active sessions tab counts the Test plans and Copilot runs using this machine now. If the machine’s profile is used for authoring only, the tab says “This device is for authoring, so it doesn’t run test plans.”

The Active sessions tab of My Local Device for an authoring machine, with the Default and Authoring chips, the tab, the Test plans and Copilot runs counts, and the message This device is for authoring, so it doesn't run test plans outlined

Connect the phone or emulator to your machine, then click Scan for devices on the Devices tab. The agent looks for devices over USB and Wi-Fi.

To use a real iPhone, first create a provisioning profile in Settings > iOS Settings. Arcus uses it to re-sign your iOS builds so they run on your iPhone.

A machine’s settings, such as who can pick it and how much its agent logs, come from its profile. Every machine starts on the Default profile, which is used for authoring. To see which profile a machine uses, check Profile on the Summary tab, or click the settings icon in the header.

To change them, go to Settings > Profiles and agents and edit the profile, or create one with New profile. A profile sets:

  • Used for: Authoring, Authoring + Execution, or Execution only. A machine runs test plans only when its profile is used for execution.
  • The agent’s log level in its CLI and local files: ERROR, WARN, INFO, DEBUG, TRACE, or ALL.
  • How the machine reaches Arcus: Connection (Arcus cloud or self-hosted, and a proxy), Certificates, and Packages.
  • Updates and logs, and Authentication for setup links and machine sign-in.
  • Scope, for a profile used for execution: Global shares the machine with everyone in the account, and Local keeps it to the person who set it up.

See Agent profiles for every setting.

A changed profile applies when the agent restarts. The menu bar app then shows Profile updated: restart to apply. Click Restart to apply the profile.

In the menu bar app, open the Profile tab. Other profiles lists the profiles this machine can switch to. Click Switch on a profile, check what changes, and click Switch again. The agent moves to that profile once its current runs finish. If the new profile can’t reach Arcus from the machine, the machine stays on its current profile. To undo a move before it happens, click Cancel.

The Profile tab of the menu bar app, showing the machine on Default · Authoring, with Other profiles and Import a profile file outlined

To use a profile an admin sent you as a file, click Import a profile file… and choose the .arcusprofile file. Importing a profile also signs the machine in.

To remove another machine, find it under Agents on this account on the Summary tab, click Delete, and click Delete in the dialog.

Agents on this account on My Local Device, with this device and Delete on an older agent outlined

  1. In Windows, open Settings > Apps > Installed apps.
  2. Click the more options icon (⋯) beside Arcus Agent, then click Uninstall.
  3. Click Uninstall again to confirm.
  4. When the uninstaller asks “Are you sure you want to completely remove Arcus Agent and all of its components?”, click Yes.
  5. When it asks “Also remove Arcus Agent’s logs, settings and sign-in from this computer?”, click Yes to remove them, or No to keep them. If you keep them, you can reinstall without signing in again.
  6. Click OK to close the uninstaller.

Uninstalling also removes the machine from Agents on this account and from Settings > Profiles and agents > Agents.

Click the Arcus Agent icon in the system tray, then click Uninstall Arcus Agent… and confirm. The agent’s logs and settings are kept. To delete them too, click Uninstall and delete all data… instead. These options need zenity or kdialog installed to ask you to confirm, and don’t appear for the portable zip.

You can also uninstall from a terminal:

Terminal window
~/.local/share/testsigma/agent/install/uninstall.sh

Add --purge to also delete the logs and settings. For an install with --all-users, run sudo /opt/testsigma/agent/install/uninstall.sh.

As on Windows, uninstalling removes the machine from your account.

My Local Device shows this when the agent doesn’t respond.

  • Check that the Arcus Agent icon is in the menu bar on a Mac, or in the system tray on Windows. If it isn’t, start the agent again from where you installed it, or from the portable zip. To restart it, click Quit Arcus Agent in the menu bar app, then open Arcus Agent again.
  • If your browser blocks access to your local network, allow it for arcus.testsigma.com in the browser’s site settings, then refresh the page.
  • Click Re-check.

Open the Summary tab and read Notifications. If a service isn’t running, click Restart all services on the Services tab. Allow a few minutes for each service to come back. If that doesn’t help, quit the agent from the menu bar app and open it again. If the problem continues, open the menu bar app’s settings and use Troubleshoot > Clear cache…, or check the Logs tab for errors.

Check that the phone or emulator is connected, then click Scan for devices on the Devices tab. For an iPhone, check that a provisioning profile exists, as in Connect a mobile device. To author on a mobile app without a device, use a cloud device instead.

Was this page helpful?