> For the complete documentation index, see [llms.txt](https://docs.desktop.faros.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.desktop.faros.ai/getting-started/install-and-set-up.md). # Installation and Setup Install Faros Desktop on your Mac, choose the AI tools it can analyze, and complete the tour to reach For You. ## Before You Begin * Ensure you're using an Apple Silicon Mac running macOS 26.5 or newer. Some local models may require a newer macOS version or compatible hardware. * Get the Faros Desktop disk image supplied for your release or by your administrator. * Have at least one supported AI coding tool with local session history. Setup offers the tools Faros detects on your Mac; collection support and integrations can differ by tool. The Desktop release includes **Faros Agent** and **Faros Helper**. A separate developer installation is not needed. ## Install Faros Desktop 1. Open the supplied Faros Desktop disk image. 2. Drag **Faros Desktop** into **Applications**. Place the app directly in `/Applications` or `~/Applications` so it can register its background services. 3. Open **Faros Desktop from Applications**. 4. Follow the installation check and any macOS approval guidance. If approval is required, open **System Settings → General → Login Items & Extensions** and approve the Faros background components identified by the app. Run the installed copy from Applications rather than the mounted disk image. ## Complete Setup 1. Choose which of the detected AI tools Faros can analyze. 2. Review the privacy choices. 3. Select the offered Power Ups. New-user Power Ups begin in **Observe** where applicable; automatic actions are controlled per Power Up. 4. Complete the tour to reach **For You**. Faros checks, reads, and analyzes the selected history. Initial results can arrive in stages. A reading or analyzing message means work is still in progress. ## Check That Setup is Working * Open **Settings → General → AI tools** and confirm the tools you want are enabled. * Open **Sessions** and check the date range, provider, search, and filters. If a tool has no local history yet, start a session in that tool and return to Faros. * If Faros reports an Agent connection problem, check **Settings → Advanced → App** for background-service status. * Check **Settings → General → About** for the installed Desktop build when you need support. Allow the initial analysis to finish before expecting complete activity figures or recommendations. ## If the Installation Check Needs Attention If Faros shows **“Faros Agent could not finish updating”**, use **Try again**. If the message returns: 1. Confirm you opened the installed app from Applications. 2. Retry after rebooting the Mac. 3. Follow any background-component approval guidance in **System Settings → General → Login Items & Extensions**. 4. If settings are accessible, inspect **Settings → Advanced → App** and use any recovery action offered by the connection notice. 5. Follow [Updates and Support](/troubleshooting/updates-and-support.md) to report the exact message and installed build if the check still cannot finish. The Desktop release bundles its Agent and Helper and reconciles them on reopening. Follow any approval or active-session guidance shown during that process. ## Update an Existing Installation Use **Settings → General → Updates** when available. Your organization's policy can restrict manual checks, automatic checks, downloads, or updates entirely. For a manual disk-image update, replace the installed app with the supplied copy and reopen it. If updates are centrally managed, use the installation supplied by your administrator. See [Updates and Support](/troubleshooting/updates-and-support.md) for details. ## Change Setup Choices Later | Choice | Where to change it | | ---------------------------------- | --------------------------------- | | AI tool collection | Settings → General → AI tools | | Analytics and crash reports | Settings → General → Privacy | | Capabilities and automatic actions | Power Ups | | Revisit onboarding | Restart setup and tour in General | **Restart setup and tour** keeps installed profile settings. ## Faros Desktop - The Fast Path to a Baseline Faros Desktop's paradigm of local data collection and analysis means it does not require any external connection. You can try out Faros Desktop without using Faros Control Plane or Faros Gateway, and Faros Desktop does not require changing your coding assistant's model endpoint. This makes it an easy first step for organizations to start evaluating how they use AI. For an initial evaluation: 1. Confirm Faros Desktop starts and your expected coding assistant is enabled. 2. Review recent activity on **For You** and view the details of a recent session. 3. Compare the session's trace and classifications to the work you remember doing. 4. Inspect token, estimated cost, and cache information. 5. Try an approved recommendation or supported Power Up, then record your feedback. ## Plan a Managed Pilot Choose the release, approved assistants, participants, and enabled features before rollout. Select a pilot cohort through your organization's device-management process. MDM tools such as Jamf or Intune can target existing user or device groups where supported; installer packaging and tested deployment instructions remain release-specific. Compare expected sessions with discovered sessions, assess whether recommendations are useful, and record responsiveness, resource impact, and compatibility with normal workflows. Include the Desktop build, Agent version, expected result, and observed result when reporting issues. Today, profiles are manually configured. We plan to offer MDM profile deployment, central enforcement, and directory integration in future releases. ## Related Guides * [Understand Your Data](/settings-and-privacy/understand-your-data.md) * [Solve Common Problems](/troubleshooting/solve-common-problems.md) * [Updates and Support](/troubleshooting/updates-and-support.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.desktop.faros.ai/getting-started/install-and-set-up.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.