Skip to content

Desktop app — install and first run

The OpenAdapt desktop app is the local cockpit being built for the record → compile → replay → teach loop: record a workflow on your own machine, compile it into a deterministic bundle with openadapt flow, and replay, review, and teach corrections — all locally. Nothing leaves your machine unless you explicitly push it to a cloud workspace.

Experimental preview — the CLI is the working path today

The currently published installers are an Experimental preview that validates native packaging, install, and removal. The desktop shell is not yet wired to workflow recording and replay in the released build — check the release notes attached to your installer for exactly what it exercises. For the working record → compile → certify → replay → repair path, use the open-source openadapt flow CLI.

Prefer the command line?

Everything the desktop app is being built to do, the openadapt flow CLI does today. If you would rather stay in a terminal, start with the five-minute tour and skip this page. The desktop app is a graphical wrapper around the same engine.

1. Download and install

Get the installer for your operating system from openadapt.ai/download. The page detects your OS and architecture and offers the right build.

OS Installer
Windows .msi or .exe
macOS (Apple Silicon / Intel) .dmg
Linux .AppImage or .deb

2. Get past the first-launch OS warning

The current builds are not code-signed yet, so your OS shows a one-time warning before the first launch. This is expected for unsigned software and does not indicate a problem with the download.

macOS will say the app is from an unidentified developer. To open it the first time: right-click (or Control-click) OpenAdapt in Applications → Open → Open. macOS remembers your choice, so you will not see this again. Signed and notarized builds are planned; the release pipeline is signing-ready and switches over when credentials are provisioned.

Windows SmartScreen may show a blue "Windows protected your PC" banner. Click More info → Run anyway to install. This appears because the installer is not code-signed yet; signing is on the roadmap.

3. Grant OS permissions (the step everyone misses)

This is the #1 silent-failure mode

Until you grant the permissions below, screen capture returns a blank or black frame and input may go nowhere — the app looks like it is recording but captures nothing. There is no error dialog from the OS; recordings just come out empty. Grant these before your first recording.

OpenAdapt needs two permissions to record: Screen Recording (to capture what is on screen) and Accessibility (to observe and replay mouse and keyboard input).

  1. Open System Settings (on macOS 12 Monterey and earlier this is System Preferences → Security & Privacy → Privacy).
  2. Go to Privacy & Security → Screen Recording. Toggle OpenAdapt on.
  3. Go to Privacy & Security → Accessibility. Toggle OpenAdapt on.
  4. Quit and reopen OpenAdapt. macOS only applies a newly granted Screen Recording permission after the app restarts — this is a macOS requirement, not an app bug.

If OpenAdapt is not in the list, click +, then add it from /Applications. If a recording still comes out blank, confirm both toggles are on and that you restarted the app after granting Screen Recording.

On Windows, capture and UI Automation work out of the box for ordinary windows — no permission prompt is needed for a first recording.

The one exception is elevated (administrator) windows. Windows blocks a normally-privileged app from seeing or driving a window that is running as administrator (UAC elevation). If the app you want to automate runs elevated, run OpenAdapt as administrator too (right-click → Run as administrator), so both processes are at the same integrity level. Otherwise capture of that window comes back blank and input is ignored.

For remote-session substrates (Citrix / RDP), see the troubleshooting guide for the session-0 / interactive-session caveat.

4. Verify with a test recording

Once your build includes recording (see the experimental-preview note above — until then, use openadapt flow record from the CLI): record a few seconds of any app, then stop. If the captured frames show your screen (not a blank or black image), permissions are correct and you are ready to record a real workflow.

  • Blank / black frames on macOS → Screen Recording is not granted, or you did not restart the app after granting it. Redo step 3.
  • Clicks not captured on macOS → Accessibility is not granted.
  • One specific window is blank on Windows → that window is elevated; see the UAC note in step 3.

The troubleshooting guide covers these and other first-week failure modes.

Where to go next