> For the complete documentation index, see [llms.txt](https://docs.nimbalyst.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nimbalyst.com/detailed-install-guides/mac-detailed-install-guide.md).

# Mac: Detailed Install Guide

Install Nimbalyst on macOS, open a project, and connect Claude Agent or OpenAI Codex using a plan login or API key.

This guide takes you from the macOS disk image to your first agent session. Download the current installer from the [Nimbalyst download page](https://nimbalyst.com/download/).

## Install the App

1. Open the downloaded Nimbalyst `.dmg` file.
2. Drag Nimbalyst into **Applications**.
3. Open Nimbalyst from **Applications**.
4. If macOS asks whether you want to open an app downloaded from the internet, click **Open**.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FRlRD5cc8N284ThTTmDzY%2Fimage.png?alt=media&amp;token=5c7d0776-4fb6-421f-88cd-c116dbf57597" alt="The Nimbalyst disk image with an arrow from the app to the Applications folder"><figcaption><p>Drag Nimbalyst into Applications, then launch it from there.</p></figcaption></figure>

Nimbalyst updates itself after installation. If macOS blocks the first launch, open **System Settings > Privacy & Security** and use the option to open Nimbalyst there.

## Open a Project

A project is a folder on your Mac. It can be a Git repository or any other folder containing the documents and files you want to work with.

1. On the Project Manager screen, choose **Open Folder** or **New Folder**.
2. Complete the welcome screen. Choose Standard Mode for a simpler writing workspace or Developer Mode for Git, terminal, and worktree features; you can change this later.
3. Use **Start tutorial** if you want a disposable example project, or **Get started…** to open your own folder.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2FI6MthAn6ZWD1patQ1pTY%2Fimage.png?alt=media&amp;token=669e5a74-571b-4e59-b38d-c2081eb27198" alt="Nimbalyst Project Manager for choosing or creating a project folder"><figcaption><p>Each project is backed by a folder on your filesystem.</p></figcaption></figure>

## Connect an Agent

The standard Claude Agent and OpenAI Codex integrations are included with Nimbalyst. You do not need to install a separate CLI for either one.

1. Open **Settings > Application > AI Providers**.
2. Select **Claude Agent** or **OpenAI Codex** and enable it.
3. Authenticate with a supported subscription login, or choose the API-key option and enter your own key.
4. Return to the workspace, create a session, and select that provider in the composer.

<figure><img src="https://562749618-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiVUeHZHlFlZrZt02syRC%2Fuploads%2Fgit-blob-ac8887ab7b6a64356819625db804833002e94f48%2Fdocs-ai-providers.png?alt=media" alt="Nimbalyst Application Settings with Claude Agent selected and other agent providers listed in the sidebar"><figcaption><p>The AI Providers settings on macOS. Leave Custom Claude Installation empty to use Nimbalyst's bundled runtime.</p></figcaption></figure>

Claude plan login opens Terminal for the OAuth flow and may ask you to type `/login`; return to Settings and click **Refresh** when authentication finishes. Codex plan login opens the ChatGPT sign-in flow in your browser.

{% hint style="info" %}
Nimbalyst also offers separate CLI providers for users who deliberately want a locally installed command-line agent. Those providers have their own installation checks. See [AI Provider Setup](/setup-nimbalyst/ai-provider-setup-and-notifications.md).
{% endhint %}

## Start Working

Type a request in the agent panel. The agent can research, write and edit files, build mockups and diagrams, and work with the project context that you give it. You review file changes in Nimbalyst before accepting them.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nimbalyst.com/detailed-install-guides/mac-detailed-install-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.