macOS Setup Guide

Step-by-step instructions for installing AgentOne on macOS, including solutions for common installation issues

There are two primary ways to install AgentOne on macOS. We recommend installing from agent-one.dev.

Install from agent-one.dev

Download the desktop app

Click the Download app button in the bottom left of your account dashboard or head to: https://www.agent-one.dev/download

AgentOne sidebar showing Download app button

You'll be redirected to a download page, which will attempt to automatically detect your operating system. Make sure the macOS tab at the top of the page is selected:

AgentOne download page showing macOS tab

You'll see two download options:

Download Apple Silicon (.dmg): for Macs with Apple Silicon chips (M1, M2, M3, M4, or newer).
Download Intel (.dmg): for older Macs with Intel processors.

Click the button that matches your Mac.

Not sure which one to pick?

Click the Apple menu in the top-left corner of your screen and select About This Mac. Look at the Chip or Processor field:

If it says something like Apple M1, Apple M2, Apple M3, Apple M4, or newer, choose Apple Silicon.
If it says something like Intel Core i5 or Intel Core i7, choose Intel.

If you pick the wrong one, AgentOne may not open correctly or may run more slowly than it should. To learn more, read Apple's support article.

If macOS or your browser warns you about the download or blocks the app from opening, see the Troubleshooting section below.

Open the `dmg` file

When the download finishes, open the .dmg file from your browser or from the Downloads folder in Finder.

Move AgentOne to Applications

In the installer window, drag AgentOne.app into the Applications folder.

Open AgentOne

Open the Applications folder and double-click AgentOne.

The first time you launch the app, macOS may ask you to confirm that you want to open something downloaded from the internet. Click Open to continue.

Install from GitHub

If you followed the steps in the Install from agent-one.dev section, you can skip this section.

Find AgentOne on GitHub Releases

Open https://github.com/AgentOne-Dev/agent-one-public/releases.

Usually, the latest release is the first release on the list. You'll see a green Latest badge next to the latest stable release. If the release has a Pre-release badge or title, don't use it unless you're a developer.

GitHub Releases page showing the latest release with a green "Latest" badge

Once you've found the latest release, click on its title (for example, AgentOne 1.0.0) to navigate to that release.

Download the correct `dmg` file

Scroll to the bottom of the release page and expand the Assets accordion.

Download the macOS .dmg file that matches your Mac's processor:

Apple Silicon for Macs with M1, M2, M3, M4, or newer chips
Intel for Macs with Intel processors

Make sure you download the .dmg file, not a signature file or source code archive.

Install and open AgentOne

Open the downloaded .dmg file, drag AgentOne.app into Applications, then open AgentOne from your Applications folder.

If macOS blocks the app from opening or says the file is damaged, see the Troubleshooting section below.

Troubleshooting

"AgentOne.app" was downloaded from the internet

This is a normal macOS warning shown the first time you open many apps downloaded outside the App Store. If you downloaded AgentOne from agent-one.dev or the official GitHub releases page, click Open.

"AgentOne.app" is damaged and can't be opened

This is a common macOS Gatekeeper message for apps downloaded outside the App Store. To fix this, first try to go to System Settings > Privacy & Security and click 'Open Anyway' next to the security warning. If that doesn't work, try these steps.

Delete the old .dmg file and delete AgentOne.app from your Applications folder if it is already there.
Download a fresh copy of the correct macOS version.
Open the new .dmg file.
Drag AgentOne.app into the Applications folder.
Open the Applications folder, but do not open AgentOne yet.
Open the Terminal app on your Mac. You can do this by pressing Command + Space, typing Terminal, and pressing Return.
Copy and paste this command into Terminal:

xattr -cr /Applications/AgentOne.app

Press Return on your keyboard to run the command.
Close Terminal.
Go back to Applications and open AgentOne again.

What this command does: it removes the macOS quarantine flag from the app so macOS will re-check it normally.

Only do this if you downloaded AgentOne from agent-one.dev or the official GitHub releases page.

If you still see the same message after doing this, join our Discord server for live support.

"AgentOne.app" cannot be opened because the developer cannot be verified

macOS Gatekeeper may block new or newly updated apps until you explicitly allow them.

To resolve the issue, follow these steps:

Double-click AgentOne.app once so macOS shows the warning.
Open System Settings.
Go to Privacy & Security.
Scroll down to the Security section.
Click Open Anyway for AgentOne.
Confirm by clicking Open.

Apple notes that the Open Anyway button is only available for about one hour after you try opening the app.

"Apple could not verify "AgentOne.app" is free of malware"

This is another version of the same Gatekeeper warning. Follow the steps in "AgentOne.app" cannot be opened because the developer cannot be verified.

The app says it is from an unidentified developer or an unknown developer