Setup as a Background Service
This article instructs how to set up the Robocorp Workforce Agent Core background process on a Windows or Linux machines so that you get a new Unattended Worker into your Control Room.
The primary purpose of running Robocorp Workforce Agent Core as a service is to set up your machine as a constant Environment resource in Control Room just by having the machine powered on.
Prerequisites
- If you are not familiar with Windows Services, this might not be relevant for you.
- To follow along, you will need a Robocorp account for accessing Control Room and Robocorp Workforce Agent Core. If you haven't already, you might want to first follow the Quickstart guide to get familiar with Control Room.
- You need to have administrator permissions on the machine to set up the Windows Service.
Limitations
A Windows Service does not have UI access to applications; this means that you can run so-called headless operations and access the machine and user resources, but you cannot, for example, take screenshots of Windows application UI's.
Set up the user for the Windows Service
The setup is simple if you log in to Windows as the user you want the Windows Service to run. The permissions of this user determine what the Windows Service can access.
The reason for running robots on local machines is to have access to some user-level resources or permissions, so running the Robocorp Workforce Agent Core as a Windows Service requires you to use some existing user account that can log in to the machine. You can set up a separate local user or use an Active Directory user.
Note: Setting up this user's permissions on the machine with the principle of least privilege is the most effective way of introducing better security.
Installing the Windows Service
To help out in the setup, we provide a simple CLI helper tool to avoid as much hassle as possible on setting up Windows Services. The helper tool downloads the Robocorp Workforce Agent Core and all needed tools and sets up the service.
Steps below detail the setup.
1. Get the helper tool to the target machine
Get the Robocorp Service Helper here
2. Fill in the arguments for the helper command
The installation command will interactively ask for the logged-in user's password; it can be left empty to be set later via Windows GUI.
robocorp-service-helper.exe setup-background
Optional arguments:
--name "Robocorp Workforce Agent"
Name for the Windows Service / Windows task / Control Room Worker--instance-path "C:\robocorp\wfa-service"
Path the service uses to store run data--robocorp_home "C:\robocorp\wfa-service\home"
Path the service uses for environment caching--domain
Domain of the user the service runs as.- If you are running these as the targetted user %USERDOMAIN% should be a reliable way to get the right domain.
--username
Username of the user the service runs as.- If you are running these as the targetted user %USERNAME% variable holds the correct name
--link-token <link token from Control Room>
- Get the link token from Control Room:
Go to correct workspace > Workers > Link token
Token is only used for linking and only valid for 1 hour, so no need to store this anywhere.
- Get the link token from Control Room:
--ci
when running from CI system to make sure the tool is non-interactive--log-level DEBUG
In error cases adding this will printout more details.
3. Run the helper command
4. Define the user for the service
You can use the default Windows Services
application to set the user for the service.
- Start menu > type
Services
- Find the service name you gave to the command and open Properties.
- Give the username and password to
Log On > This account
Note: You can also set Recovery options for the service as you choose.
5. Start the service
- You can do this via the default Services application
6. All done
You should now see a new Worker in Control Room with the name you gave in Idle
state, ready for work.
Prerequisites
- You should be familiar with Systemctl Utility in Linux, systemd and command line use of Linux.
- The target machine must have at least
curl
or similar to download needed files and a text-editor of your choosing. - To follow along, you need a Robocorp account to access Control Room and Robocorp Workforce Agent Core.
- If you haven't already, you might want first to follow the Quickstart guide to get familiar with Control Room.
- You must have
sudo
permissions on the machine to set up the service.
Limitations
On Linux, you will not get UI access via this service setup; it is limited to so-called "headless" runs that do not need UI-level actions. It is good to note that a lot can be done even at this level; browser automation, excel data handling, etc., do NOT require any UI.
Officially we are testing the setups on Ubuntu distros; as there are so many different Linux distros, the guides here cannot cover all, but the setup is quite simple and should be adaptable in most cases.
The guide below does not cover the installation of other components your robot might need, e.g., chromium-browser
Setup and test Workforce Agent Core
Replace <link token>
below with a link token created from the Control Room Workers
-page. Note that Workforce Agent is always linked to a specific workspace in Control Room to avoid accidental runs between development and production Workers.
mkdir ~/.robocorp
curl https://downloads.robocorp.com/workforce-agent-core/releases/latest/linux64/robocorp-workforce-agent-core -o ~/.robocorp/robocorp-workforce-agent-core
chmod +x ~/.robocorp/robocorp-workforce-agent-core
~/.robocorp/robocorp-workforce-agent-core -v
~/.robocorp/robocorp-workforce-agent-core link <link token>
~/.robocorp/robocorp-workforce-agent-core start --service
At this point, you should be able to see the Environment in the Idle
state in Control Room, and you can test executing a simple bot like Python template.
This setup, however, will shut down once you log out of the machine or the terminal, so you should move on to the service setup next.
Setup service
- Create the service config file
touch /etc/systemd/system/RobocorpAgentCore.service sudo chmod 664 /etc/systemd/system/RobocorpAgentCore.service
- Add the following content to the config file
- Edit the file
/etc/systemd/system/RobocorpAgentCore.service
with your favorite text editor.[Unit] Description=Robocorp Agent [Service] User=<user> ExecStart=/home/centos/.robocorp/robocorp-workforce-agent-core start --service Restart=always PrivateDevices=true ProtectControlGroups=true ProtectKernelTunables=true ProtectSystem=full RestrictSUIDSGID=true PrivateTmp=yes [Install] WantedBy=default.target
- Replace
<user>
with actual user - The
ExecStart
needs to have the absolute path
- Replace
- Edit the file
- Setup and start the service:
sudo systemctl daemon-reload sudo systemctl start RobocorpAgentCore.service sudo systemctl status RobocorpAgentCore.service
Maintain the service
The typical maintenance task is to update the Agent Core executable.
For that, you need to:
- Stop the service
- Download the latest Agent Core
- Restart the service
sudo systemctl stop RobocorpAgentCore.service
curl https://downloads.robocorp.com/workforce-agent-core/releases/latest/linux64/robocorp-workforce-agent-core -o ~/.robocorp/robocorp-workforce-agent-core
sudo systemctl start RobocorpAgentCore.service
sudo systemctl status RobocorpAgentCore.service