> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Omni Desktop

> Fixes for the common Omni Desktop problems: macOS will not open the app, the keychain asks for access, computer control cannot see or click, the shell is unavailable, Could not reach, sign-in does not return to the app, and a folder is not trusted.

## macOS says the app is damaged or will not open

Builds that are not yet signed by Apple are quarantined by Gatekeeper. Move **Omni** to **Applications**, then right-click it and choose **Open** once. If macOS still refuses, run this in Terminal and open the app again:

```bash theme={"dark"}
xattr -dr com.apple.quarantine "/Applications/xpander.ai.app"
```

Unsigned builds also cannot update themselves: Settings > **About** shows the new version with **Download** instead.

## The keychain asks for access

The app keeps your session in the macOS keychain. If macOS asks to allow **xpander.ai Safe Storage**, enter your Mac password and choose **Always Allow**. On builds not yet signed by Apple, macOS may ask again after an update; choose **Always Allow** again.

## Voice input records nothing

macOS asks once whether Omni may use the microphone. If you chose **Don't Allow**, open System Settings > Privacy & Security > Microphone, turn **Omni** on and restart the app.

## "Could not reach" on first run

The app could not reach the address you entered. Check its spelling (for example `chat.xpander.ai`, or your company's address), your network, and for a self-hosted xpander your VPN, then choose **Try again**.

## Sign-in finished in the browser but the app did not open

The app is not registered to open sign-in links yet, usually because it was never opened from **Applications**. Copy the code the browser page shows, paste it into the app under **Sign-in code** and choose **Continue**. The code works once and expires after a minute; if it expired, choose **Open the browser again**.

## The browser says Omni Desktop is not available

Your organization's Desktop policy is off for you. Ask an admin to turn it on for you or your group.

## The status says Mac offline

Check your network and the address in [Settings](https://docs.xpander.ai/desktop/settings.md). The app retries on its own. See [Offline and reconnect](https://docs.xpander.ai/desktop/offline.md).

## The status says Mac turned off or Mac removed

An admin turned Omni Desktop off for you or revoked this Mac, or it was forgotten in Settings. Ask your admin; after a revoke, sign in again to register the Mac as a new device.

## An agent says a folder is not trusted

Trust the folder in [Settings](https://docs.xpander.ai/desktop/settings.md) or the composer, with the access the agent needs, or answer the agent's request when it asks. If the folder reads **Outside what your organization allows**, your organization's policy does not allow it.

## An agent cannot write a file or run a command

Check the folder's access (**Read and write** is needed to change files), whether your organization's policy is read only or has the shell off, and your own switches in Settings > **Shell & files**. The composer's laptop strip shows **Shell on** when commands are allowed. If you chose **Not now** when the app asked **Run a command?** or **Write a file?**, the agent continues without it; ask it to try again.

## The strip says Shell unavailable

Commands cannot run safely on this computer, so the app does not run them. On Windows, the shell is not available yet. Agents still work with your files directly.

## Computer control cannot see the screen or click

Open Settings > **Computer control** and check that **Screen Recording** and **Accessibility** both read on. Screen Recording takes effect only after the app reopens: choose **Reopen Omni**. If a permission is switched on in System Settings but still off in the app, remove **xpander.ai** from that list in Privacy & Security with the minus button, then choose **Allow again**. See [Computer control](https://docs.xpander.ai/desktop/computer-control.md).

## The agent does not use my browser or my Mac

* The ability may be **Not allowed** by your organization, or off in your own Settings > **Shell & files**. See [Your settings and the policy](https://docs.xpander.ai/desktop/your-controls.md).
* **Prefer this Mac's browser** or **Prefer this Mac's files and apps** may be off, so agents start in the cloud. Ask the agent to use this computer, or turn the switch back on.
* You may have chosen **Not now** in this conversation. Ask the agent to try again, and allow it when the app asks.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.