Install agents

The Botream Agent is the robot that runs tasks on a Windows machine; you install it with one MSI on every machine that runs tasks or that you build tasks on.

#Requirements

You do not install .NET: it is included in the package.

#How the agent runs

The agent consists of two parts:

Tasks run in the tray app because Windows services run in Session 0, which has no desktop: a service cannot see or operate windows, so desktop automation, element capture and recording need a signed-in session. The same applies to the AI Task Generator's exploration in a browser: only an agent with its tray app running can do it.

In practice this means:

• A machine runs tasks only while a user is signed in to Windows. For robots that must run around the clock, install the agent as an Unattended robot: Windows then signs in automatically on every start.
• If a user exits the tray app on a workstation, it stays closed until the next sign-in. It can also be started with the Botream Agent shortcut in the Start menu. On robot machines it is always restarted.

There is one agent identity per machine, shared by all its users.

#Get the installer and the details

As an administrator, open Administration → Agents in the web app and click Install an agent. The dialog offers:

1. Download the installer — the Botream-Agent-<version>.msi this server offers.
2. Run it on the machine and enter — the Server address and the Registration token (click Show token).
3. Or install silently (software deployment) — a ready msiexec command for a Workstation or an Unattended robot.

Warning: If you opened the web app as localhost, the dialog's server address is localhost too. Other machines cannot reach it: use the server's name or IP address with the same port.

#Run the agent installer

Run the MSI on the agent machine:

1. Welcome — click Next.
2. Destination Folder — default C:\Program Files\Botream Agent.
3. Botream server
   • Server address: the address of the web app, for example http://rpa-server:3000.
   • Registration token: the token from the Install an agent dialog.
   • Test connection tries it; Next checks it as well.
4. This machine

   • Agent name: the name shown in the web app when you choose where a task runs.

   • How the agent runs:

     Option	Behavior	For
     Workstation	The agent runs while someone is signed in to Windows.	Developer and user computers
     Unattended robot	Windows signs in automatically on every start and the agent runs all the time.	Machines that run scheduled tasks

   • Install the Botream extension in Chrome and Edge: needed to capture web elements; leave it checked. See Install the browser extension.

5. Automatic sign-in (only for Unattended robot)
   • Windows account: robot for a local account, COMPANY\robot for a domain account. Preferably an account used only by the robot.
   • Password: the account is verified with Windows before the installation. Windows keeps the password encrypted (as an LSA secret); it is not written to a file or the registry.
6. Ready to install — click Install, then Finish.

After the installation the BotreamAgent service runs, and the agent starts on the signed-in user's desktop (in the notification area) and connects to the server. On robot machines, restart Windows to test the automatic sign-in.

Warning: Anyone who can reach a robot machine's screen gets to the robot account's desktop. Keep robot machines in a locked place or use them only through Remote Desktop. When a Remote Desktop session ends, the agent moves the desktop back to the console.

#Silent installation

From an elevated command prompt:

msiexec /i Botream-Agent-<version>.msi /qn SERVER=http://rpa-server:3000 TOKEN=<token> [AGENTNAME=<name>]
        [MODE=robot ROBOTUSER=.\robot ROBOTPASSWORD=<password>] [EXTENSION=0]

#Approve the agent

If Require approval for new agents is on under Administration → Settings (Agents settings), a new machine waits until an administrator approves it, and no task runs on it until then.

• The tray icon shows Waiting for administrator approval and Windows shows one notification about it.
• Under Administration → Agents, the agent has the tag Waiting for approval. Click Approve.

The actions menu of an agent also offers Reject (disconnects it and refuses it from then on), Deactivate and Activate. See Agents.

#Check the connection

The tray icon's colour and tooltip show the state:

Right-click the icon for Open dashboard, View logs, Settings, Reconnect and Exit. The dashboard shows the current task (with Stop), the agent's name, server, machine, IP address, Windows version and agent version, and the recent runs.

In the web app, the Dashboard and Administration → Agents show which agents are online.

#Change the server address or token

Open Settings from the tray icon. The settings belong to the machine, so a standard user sees them read-only and clicks Change as administrator to edit them. Change Server address, Agent name or Registration token (leave the token box empty to keep the stored one) and click Save and connect. The running agent reconnects without a restart.

#Agent groups

Under Administration → Agents → Groups you can group agents, for example "Finance robots". A schedule that targets a group runs on the first free, online member. See Agents.

#Keep robot machines available

A schedule runs only on a machine that is switched on, awake and signed in, with its agent connected. On an unattended robot machine the agent keeps the machine from sleeping and the screen from locking while it runs, signs in again by itself after a restart (Windows updates, power cuts), and moves a closed Remote Desktop session back to the console. What it cannot do is start a machine that is switched off or asleep. For that:

• Keep robot machines on around the clock if you can (virtual machines are the simplest), and set the power plan to never sleep or hibernate.
• On physical machines, turn on the firmware (BIOS/UEFI) setting that starts the machine when power returns.
• If a group policy locks idle sessions, exempt the robot account from it: a locked desktop cannot be automated.
• Or let schedules wait for an agent and wake the machine with Wake-on-LAN.

#Waking machines with Wake-on-LAN

Each agent reports its wired network cards (MAC address and network) when it connects. The server can then wake the machine: from a schedule, or by hand under Administration → Agents (row menu → Wake (Wake-on-LAN), for offline agents). The packets go out from the server, and through up to two online agents of the same network, because routers seldom pass them between networks.

What the machine needs:

When woken, the machine starts Windows; an unattended robot machine signs in by itself and its agent connects a few minutes later. A workstation without automatic sign-in waits at the sign-in screen, so its agent does not connect until someone signs in.

#Updates

Installed agents update themselves when the server offers a newer agent installer and no task is running. See Upgrade, back up and uninstall.

#Files and service

#Troubleshooting