Skip to main content
You’re running agents unattended in a pipeline or on remote infrastructure. The install method depends on whether you need OS service capabilities (RDP resilience, SYSTEM privileges) or standalone mode is sufficient.

​
Windows VM

Run automation directly on a Windows VM that is part of your CI/CD pipeline. AgentOS runs as an OS service with SYSTEM privileges. When to use: Your CI runner is the Windows machine you want to automate. Install: Service on the VM. The Python SDK and AgentOS both run on the same VM. The OS service ensures automation continues even if no user is logged in or the RDP session disconnects.

​
Remote Windows VM

Automate a Windows VM from a separate CI runner. The SDK runs on the CI runner and connects to AgentOS on the remote VM over the network. When to use: Your CI runner is Linux/macOS but you need to automate a Windows desktop. Or your pipeline orchestrates work across multiple machines. Install: Service on the remote VM. The SDK connects to AgentOS over the network via gRPC. The OS service on the remote VM handles desktop control independently — RDP disconnects, logon screens, and headless operation are all supported.
By default, the SDK starts a local AgentOS instance. To connect to a remote VM instead, disable autostart and point the SDK to the remote address.
1

Disable local autostart

Set ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART to false so the SDK doesn’t start a local AgentOS instance.
$env:ASKUI_CONTROLLER_CLIENT_SERVER_AUTOSTART="false"
2

Set the remote address

Point ASKUI_CONTROLLER_CLIENT_SERVER_ADDRESS to the AgentOS service on the remote VM. Replace 192.168.1.100 with your VM’s IP address.
$env:ASKUI_CONTROLLER_CLIENT_SERVER_ADDRESS="192.168.1.100:26000"
3

Verify the connection

Run your agent code. The SDK should connect to the remote AgentOS instance instead of starting a local one. Check that the remote VM’s port 26000 is reachable from your CI runner.

​
macOS / Linux CI Runner

Run automation on a macOS or Linux CI runner. AgentOS runs in standalone mode. When to use: Your CI pipeline runs on macOS or Linux and you want to automate the desktop on that same runner. Install: pip install askui-agent-os Same as local development — AgentOS runs in standalone mode alongside your test code. Ensure the CI runner has a display (real or virtual) available.

​
Mobile Device in CI

Automate Android or iOS devices connected to your CI runner via USB. When to use: Mobile testing in your pipeline — the device is physically connected to the CI runner. Install: pip install askui-agent-os on the CI runner. AgentOS runs on the CI runner and communicates with the connected device over USB. The CI runner needs physical USB access to the device (or a USB-over-network solution).
ADB (Android Debug Bridge) must be available on your PATH. ADB works with both physical devices and emulators. See Google’s guide on running apps on the Android Emulator to get started with emulators.
1

Download SDK Platform Tools

Download from developer.android.com and unzip to a folder (e.g. C:\platform-tools or ~/platform-tools).
2

Add to PATH

Add the unzipped folder to your User or System PATH environment variable.
3

Verify

Open a new terminal and run:
adb version
You should see the ADB version output.
iOS automation requires macOS with Xcode and the Facebook IDB companion. IDB currently only works with iOS Simulators, not physical devices. See Apple’s guide on running your app in Simulator to get started.
1

Install Xcode with iOS Simulators

Install Xcode from the App Store and configure iOS Simulators. Verify they are visible:
xcrun xctrace list devices
2

Install IDB companion

brew tap facebook/fb
brew install idb-companion
3

Verify

Open a new terminal and run:
idb_companion --list 1
You should see your available simulators or devices listed.