# 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.

| Feature | macOS | Windows | Notes |
|---|---|---|---|
| Unattended job execution | Supported | Supported | Requires auto-login on macOS |
| Job recording | Supported | Supported | Requires Screen Recording permission on macOS |
| Command-line interface (CLI) connection to Orchestrator | Supported | Supported | Runs `UiRobot.dll` with the .NET runtime bundled in Assistant on macOS |
| Proxy configuration | Supported | Supported | Uses macOS system proxy, not `uipath.config` |
| Remote debugging from Studio | Supported | Supported | — |
| Browser automations (Chrome) | Supported | Supported | Requires manual Chrome Extension install on macOS |
| Apple Silicon (ARM64) | Supported | — | Native support |
| Local package feeds | Supported | Supported | — |
| Diagnostic Tool | Supported | Supported | — |
| Service mode | Not supported | Supported | macOS has no Robot service; uses user-mode Assistant |
| User session switching | Not supported | Supported | Single user per machine on macOS |
| Picture in Picture | Not supported | Supported | — |
| Live streaming | Not supported | Supported | — |
| Remote control | Not supported | Supported | — |
| NuGet package signing verification | Not supported | Supported | Limited by .NET platform on macOS |

## Prerequisites

- 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](mac-installation.md).

## 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](https://support.apple.com/en-us/102316). Navigate to **System Settings** > **Users & Groups** > **Automatic Login** and select the user account.

- **CLI with kcpassword (recommended for automation):** Use the [kcpassword](https://github.com/xfreebird/kcpassword) open-source tool to enable auto-login from the command line. This approach is suitable for scripted provisioning.

  ```bash
  # 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](https://www.brunerd.com/blog/2021/08/24/automating-automatic-login-for-macos/) for a bash-based method.

:::note
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.
:::

### Security considerations

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](mac-installation.md).

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:

```bash
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

:::note
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:

    ```bash
    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.

:::warning
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:

```bash
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.

```bash
# 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.

```bash
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`:

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

## Verification

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/`

## Limitations and workarounds

### 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](#step-5-connect-to-orchestrator-via-cli).

### 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.