Setting up unattended robots on macOS

Configure macOS auto-login, UiPath Assistant, and client credentials so that Orchestrator can run unattended jobs on a Mac in user mode.

Unattended automation on macOS works differently than on Windows. On Windows, the Robot runs as a system service that can create and manage user sessions independently. On macOS, no equivalent service mode exists. Instead, the Robot runs as UiPath Assistant in user mode, connected to Orchestrator via client credentials.

For unattended execution to work, a macOS desktop session (Aqua session) must be active. The recommended approach is to configure macOS auto-login, which automatically creates a graphical user interface (GUI) session for a predefined user at boot time. Combined with Assistant set to launch at login, this enables Orchestrator to trigger jobs without human intervention.

This setup mirrors how Continuous Integration (CI) agents such as Jenkins and TeamCity operate on macOS in headless environments.

Supported and unsupported features

The following table compares unattended automation capabilities between macOS and Windows.

Funktionen	macOS	Windows	Hinweise
Unattended job execution	Wird unterstützt	Wird unterstützt	Requires auto-login on macOS
Job recording	Wird unterstützt	Wird unterstützt	Requires Screen Recording permission on macOS
Command-line interface (CLI) connection to Orchestrator	Wird unterstützt	Wird unterstützt	Runs UiRobot.dll with the .NET runtime bundled in Assistant on macOS
Proxykonfiguration	Wird unterstützt	Wird unterstützt	Uses macOS system proxy, not uipath.config
Remote debugging from Studio	Wird unterstützt	Wird unterstützt	–
Browser automations (Chrome)	Wird unterstützt	Wird unterstützt	Requires manual Chrome Extension install on macOS
Apple Silicon (ARM64)	Wird unterstützt	–	Native support
Local package feeds	Wird unterstützt	Wird unterstützt	–
Diagnosetool	Wird unterstützt	Wird unterstützt	–
Dienstmodus	Nicht unterstützt	Wird unterstützt	macOS has no Robot service; uses user-mode Assistant
User session switching	Nicht unterstützt	Wird unterstützt	Single user per machine on macOS
Bild in Bild	Nicht unterstützt	Wird unterstützt	–
Livestreaming	Nicht unterstützt	Wird unterstützt	–
Remotesteuerung	Nicht unterstützt	Wird unterstützt	–
NuGet package signing verification	Nicht unterstützt	Wird unterstützt	Limited by .NET platform on macOS

Voraussetzungen

• macOS 14 (Sonoma) or later on a Mac with Apple silicon
• Admin access to the machine
• FileVault disabled (auto-login is incompatible with FileVault disk encryption)
• Network connectivity to your Orchestrator instance
• An Orchestrator tenant with a machine template configured for client credentials (client ID and client secret)
• The UiPath Assistant installer for macOS. For where to get it, see Installing on Mac.

Step 1: Enable auto-login

Auto-login configures macOS to automatically log in a specific user when the machine boots, creating the GUI desktop session that the Robot requires.

Choose one of the following methods:

• System Settings (recommended for single machines): Follow the Apple documentation at Set your Mac to automatically log in during startup. Navigate to System Settings > Users & Groups > Automatic Login and select the user account.

• CLI with kcpassword (recommended for automation): Use the kcpassword open-source tool to enable auto-login from the command line. This approach is suitable for scripted provisioning.

  # Install and run kcpassword to set the auto-login user
  # Replace <password> with the user's login password
  sudo enable_autologin <username> <password>
  

• Scripted approach: For fully automated provisioning, see Automating Automatic Login for macOS for a bash-based method.

Hinweis:

Auto-login only bypasses the macOS login screen. Remote access via SSH and VNC still requires credentials. In datacenter or cloud environments (such as AWS EC2) where physical access is already restricted, auto-login does not introduce additional security risk.

Sicherheitsüberlegungen

Auto-login is acceptable when the machine meets all of the following conditions:

• The machine runs in a physically secure environment (datacenter, cloud provider)
• Remote access is restricted to SSH or VNC with authentication
• The auto-login user has the minimum permissions required for the automations

If your security policy prohibits auto-login, unattended execution on macOS is not possible with the current Robot version because the Robot cannot create user sessions independently.

Step 2: Install UiPath Assistant

Install UiPath Assistant on the machine so that it is in the Applications folder. For the installation steps, see Installing on Mac.

The commands in the following steps assume that UiPath Assistant is installed at /Applications/UiPath Assistant.app.

Step 3: Configure Assistant to start at login

Configure UiPath Assistant to launch automatically when the user logs in. This ensures that after a reboot with auto-login enabled, the Assistant starts without manual intervention.

1. Open System Settings.
2. Navigate to General > Login Items.
3. Select + under Open at Login and add UiPath Assistant from the Applications folder.

Alternatively, configure this from the command line:

osascript -e 'tell application "System Events" to make login item at end with properties {path:"/Applications/UiPath Assistant.app", hidden:false}'

Step 4: Grant security permissions

macOS requires explicit permission grants for automation capabilities. Grant the following permissions to UiPath Assistant in System Settings > Privacy & Security:

• Accessibility - Required for UI automation interactions
• Full Disk Access - Required for file system operations
• Screen & System Audio Recording - Required for job recording and certain UI Automation features

Hinweis:

The Screen Recording permission triggers a system prompt the first time a job requires it. You must grant this permission manually. A Mobile Device Management (MDM) profile cannot grant it; it can only allow a standard user to approve it.

For fleet deployments, use an MDM solution to distribute a configuration profile that pre-grants Accessibility and Full Disk Access to UiPath Assistant. Screen Recording still needs a manual grant on each machine, and there is no CLI command to grant it silently.

Step 5: Connect to Orchestrator via CLI

Connect the Robot to Orchestrator using client credentials through the UiRobot command-line interface.

1. Open a Terminal window within the GUI session (not via SSH).

2. Run the connection command:

   cd /Applications/UiPath\ Assistant.app/Contents
   Robot/dotnet/dotnet Robot/UiRobot.dll connect \
     --url https://cloud.uipath.com/org/tenant \
     --clientId <your-client-id> \
     --clientSecret <your-client-secret>
   

3. Verify the connection by checking the Assistant status indicator.

Result: The Assistant connects to Orchestrator and appears as available in the Orchestrator machine pool. You can now trigger unattended jobs from Orchestrator.

Warnung:

The connection command must run from within a GUI session. Running it from a remote SSH session fails with a ConnectWithClientCredentials timed out error because the SSH session does not initialize the macOS Aqua (graphical) session.

If you need to run this command remotely, use an AppleScript wrapper that opens a Terminal inside the GUI session:

ssh user@mac-host 'osascript -e "tell application \"Terminal\" to do script \"cd /Applications/UiPath\\ Assistant.app/Contents && Robot/dotnet/dotnet Robot/UiRobot.dll connect --url https://cloud.uipath.com/org/tenant --clientId <your-client-id> --clientSecret <your-client-secret>\""'

Use --clientId and --clientSecret for authentication. The --key (machine key) parameter is a legacy authentication method. UiPath recommends OAuth-based client credentials for all new deployments.

Step 6: Configure proxy (optional)

If your macOS machine requires a proxy to reach Orchestrator or external package feeds, configure the proxy at the OS level. The uipath.config file used for proxy configuration on Windows does not work on macOS.

Option A: macOS system proxy

Configure the proxy using networksetup. The Robot (.NET runtime) automatically uses macOS system proxy settings.

# Identify your network service name
networksetup -listallnetworkservices

# Set HTTP and HTTPS proxy (replace "Ethernet" with your service name)
networksetup -setwebproxy "Ethernet" proxy.example.com 8080
networksetup -setsecurewebproxy "Ethernet" proxy.example.com 8080

# Enable the proxies
networksetup -setwebproxystate "Ethernet" on
networksetup -setsecurewebproxystate "Ethernet" on

# Set bypass domains (optional)
networksetup -setproxybypassdomains "Ethernet" "*.local" "169.254/16"

# Verify
scutil --proxy

Option B: Environment variables

Set proxy environment variables before launching Assistant. This approach takes precedence over system proxy settings.

export http_proxy=http://proxy.example.com:8080
export https_proxy=http://proxy.example.com:8080
export no_proxy="localhost,127.0.0.1,.internal.example.com"

Assistant reads these variables only when it is launched from a shell where they are set. When Assistant starts from Login Items (Step 3), it does not read shell profile files such as ~/.zshrc, so on unattended machines use Option A.

NuGet feed proxy

If the Orchestrator package feed or public NuGet feeds are behind a separate proxy, configure a NuGet-specific proxy in the user-level NuGet configuration file, ~/.nuget/NuGet/NuGet.Config:

<configuration>
  <config>
    <add key="http_proxy" value="http://proxy.example.com:8080" />
  </config>
</configuration>

Überprüfung

After completing the setup, verify that the unattended configuration works end-to-end:

1. Restart the macOS machine.
2. Confirm that auto-login activates and the desktop session loads automatically.
3. Confirm that UiPath Assistant launches and connects to Orchestrator (check the status indicator in the menu bar).
4. Trigger a test job from Orchestrator targeting the macOS machine.
5. Verify the job completes successfully in the job history in Orchestrator.

Log locations

If jobs fail, check the following log files:

• Assistant logs: ~/Library/Application Support/UiPath/Logs/combined.log
• Robot internal logs: ~/Library/Application Support/UiPath/Logs/internal/

Einschränkungen und Problemumgehungen

No service mode

Unlike Windows, where the Robot Service runs independently and creates user sessions, macOS requires an active GUI session. The auto-login configuration described in this tutorial is the recommended workaround.

Single-user execution

macOS does not support user session switching for unattended robots. Each machine runs jobs under a single user account: the auto-login user. To run jobs under different user contexts, provision separate macOS machines.

CLI requires GUI session

The UiRobot.dll connect command must execute within a GUI (Aqua) session. If you need to configure machines remotely, use the AppleScript workaround described in Step 5.

Non-persistent machines

If your macOS machines are ephemeral (destroyed and recreated regularly), combine the steps in this tutorial into a provisioning script that runs on each new machine. Use a golden image with Assistant pre-installed and permissions pre-configured to reduce setup time. The CLI connection command can be included in the provisioning script using the AppleScript wrapper for remote execution.

NuGet package signing verification

NuGet signature verification is not fully supported on macOS by the .NET platform. Packages on the UiPath Official feed that are signed with Symantec-chain certificates fail verification, because macOS explicitly distrusts that chain. If your organization requires package signing for compliance, contact UiPath Support for the latest guidance on available workarounds.