Proton Runner

Proton Runner is the app that connects a machine to Proton and runs automations on it. It runs on Windows and Linux, on a physical or virtual machine.

Download

In the Proton portal, open Help > Proton Runner. The page shows the current version, what changed in each version, and the Download for Windows and Download for Linux buttons.

System	File
Windows	proton-runner-<versão>-setup.exe
Linux	proton-runner-<versão>.AppImage

Install

Windows

Run proton-runner-<versão>-setup.exe and follow the wizard. If the browser warns that the file isn't commonly downloaded, keep the download.

Install and run the Runner with the Windows user that will run the automations: desktop and SAP GUI automations open their windows in that user's session.

Linux

Make the file executable and open it:

chmod +x proton-runner-<versão>.AppImage

./proton-runner-<versão>.AppImage

On a server without a graphical interface, use Proton Runner CLI.

The Runner updates itself: when a new version comes out, it takes effect when you restart the app. Under Runners > Manage, the portal flags outdated runners.

Connect

To connect, the Runner asks for a connection with:

Field	What to enter
Connection Name	Optional. Without a name, the Runner uses the server address.
Server	https://app.protoncloud.com.br
Email or robot identifier	The robot account identifier, or the email of a personal account. See Runner account.
Password	The account password. It goes to the operating system's secure store (Credential Manager on Windows, keyring on Linux), never to a file.
Organization	Shown when the account belongs to more than one organization: choose which one the runner will join.

You can also create the connection from the portal: in My Profile, the Open in Runner button opens the Runner with the server and account already filled in, and Copy details copies the same details. The password is always entered in the Runner.

Once connected, the runner shows up in the portal, under Runners > Manage, as Free, waiting for a run. The organization in use appears in the Runner's top bar.

Settings

Setting	What it does
Parallel Runs	How many automations the runner runs at the same time. The others wait in the queue.
Private Mode	Only the connection owner can send runs to this runner.
Status Notification	A system notification each time the runner's status changes.

In the portal, under Runners > Manage, Proton administrators can give the runner an alias (without an alias, the owner's name is shown). Under Runners > Cluster, they group runners into a cluster, which splits runs among them.

How a run happens

1. Proton sends the run to the runner, which puts it in the queue.
2. The runner downloads the code from the project's repository, on the branch chosen when the run was triggered, through the git integration registered in Proton. The code is cached: the next run of the same commit doesn't download it again.
3. The runner recognizes the project by the file at the root of the repository and runs:
   • Java (pom.xml): mvn -B test -DidDatasetRun=<id>;
   • Python (pytest.ini): uv run pytest tests/test_proton_script.py::test_run_proton_execution --id_dataset_run=<id>.
4. The automation receives, in the process environment, the Proton address (PROTON_HOST), the run id (idDatasetRun), and a token that is valid only for that run (PROTON_TOKEN). The Proton Cloud SDK reads these values on its own.
5. At the end, the runner uploads the process output as the run's log file.

Each stage (downloading the project, waiting for preparation, the start and end of the automation) appears in the run log, so you can follow it in the portal.

The first run of a repository on a runner downloads the code and prepares the dependencies before the first step, and can take a few minutes.

Stop a run

You can stop a run in the portal or in the Runner window. In both cases, the automation process is terminated on the machine.

Unstable connection

If the connection to Proton drops, the Runner tries to reconnect on its own and keeps the session for a few minutes. The run in progress keeps running in the meantime.

Connected devices

The phone icon in the top bar opens the list of Android devices the machine can see, with what each one still needs to be ready. See Mobile (Android).