Some users may encounter issues when installing or running the Oneleet Agent, such as a blank screen, failure to register, or errors during installation. This article outlines the recommended steps to resolve common Oneleet Agent installation and setup issues on macOS and Windows.

Answer

Please follow the steps below to troubleshoot and resolve issues with the Oneleet Agent:

1. Check the troubleshooting documentation. Start by reviewing the official Oneleet Agent Troubleshooting Guide. Many common issues are covered there.

2. Ensure you are using the latest version of the installer. Older versions of the installer can cause issues during installation. Make sure you are downloading the latest version directly from the Oneleet portal at portal.oneleet.com. Delete any older installer files from your Downloads folder before proceeding.

3. Fully uninstall the existing agent before reinstalling. Follow the official uninstall instructions to completely remove the agent, then reinstall using the latest installer.

4. (macOS) Check Automation permissions. If the agent installs but shows a blank screen or fails to sync, verify that the required permissions are enabled:

   1. Open System Settings → Privacy & Security → Automation

   2. Click on Oneleet to expand it

   3. Make sure both System Settings and System Events are toggled on

   Some users do not have these permissions enabled by default, which can prevent the agent from functioning correctly.

5. Grant workspace access in the portal. If a user's device is not appearing in the portal, an admin can grant workspace access by navigating to the People page, finding the affected user, hovering over the rightmost column, clicking the three-dot menu (...), and selecting Grant Workspace Access.

6. Collect and share logs if the issue persists. If none of the above steps resolve the issue, collect the agent logs and share them with Oneleet support for further investigation. Logs can be accessed via: Agent → Help → View Logs. On macOS, logs can also be found at /var/log/oneleet/ (accessible via Finder → Go → Go to Folder).

If you have followed all of the above steps and are still experiencing issues, please reach out to Oneleet support with your logs attached so the engineering team can investigate further.