Knowledge base

Start here

Install ChatHarbor

ChatHarbor connects AI models to one Mac app. It does not include model files or a cloud subscription.

1. Get the latest ChatHarbor release. Download the DMG, open it, and drag ChatHarbor into Applications. The download does not require Xcode.
2. Open ChatHarbor. The Getting Started guide highlights the controls and walks through connecting your first model.
3. Skip whenever you want. Help → Getting Started resumes your place; finishing the tour hides its sidebar shortcut.

Requires macOS 14 or later. Individual providers may need newer hardware or software.

Already installed? Learn how updates work.

Start here

Update ChatHarbor

Updates in v2.3.2 and later: ChatHarbor checks daily while running. Use ChatHarbor → Check for Updates… to check now. You approve each installation and relaunch; turn automatic checks off in Settings → General → Updates if you prefer. Users on v2.3.1 or earlier need one manual download to get this updater.

Checks contact GitHub even when your conversations use local models. They do not upload chats or API keys; Sparkle system profiling is disabled. App updates do not update Ollama, LM Studio, or their model files.

If a check fails, check your internet connection and try again. You can also download the latest DMG, quit ChatHarbor, and replace the app in Applications. Replacing the app does not reset its stored data. Export important conversations before any upgrade.

Start here

Choose a connection

Open Settings → Models. Choose one route to start:

• Ollama or LM Studio: download models and run them locally without a cloud API key.
• OpenAI, Anthropic, or Google Gemini: connect a provider account with its API key.
• Other Servers: connect another OpenAI compatible service.
• Apple Intelligence: use Apple's on-device model when the app build and Mac support it.

When models appear, select one from the model picker. Connected means the server answered; a model must also be available before you can chat.

In version 2.3.0, LM Studio and other servers share one settings section. Version 2.3.1 and later show separate LM Studio and Other Servers sections. Existing connections are preserved.

Connect models

Ollama

1. Get Ollama from its official download page and start it.
2. Browse the current model library. Choose an on-device model that fits your Mac's memory. Copy its model name.
3. In Settings → Models → Ollama, use http://localhost:11434 unless you changed the server address. Select Test.
4. Enter the model name under Pull a model and select Pull. Wait for it to finish, then choose the installed model.

Use Ollama's official site for current releases and model tags. Downloading or updating models needs internet access. For local-only conversations, avoid cloud-hosted models.

Ollama's setup guide

Connect models

LM Studio

1. Get LM Studio. Download a model inside LM Studio and load it.
2. Open LM Studio's Developer tab and start the local server.
3. In ChatHarbor's Settings → Models → LM Studio, check the prefilled name and server address. Usually this is http://localhost:1234/v1. Use the address displayed by your server if it differs.
4. Leave the key blank unless you enabled server authentication. Select Add, then select an available model from the model picker.

In v2.3.0, open the combined LM Studio & Other Servers section and select its LM Studio preset first. Version 2.3.1 and later have separate sections.

Download and update models in LM Studio. Use Refresh in ChatHarbor after loading a different model. ChatHarbor does not download LM Studio models itself.

LM Studio's server guide

Connect models

Other Servers

Use this option for an OpenAI compatible server such as LocalAI, vLLM, or Jan. These links lead to each project's current software and setup instructions.

1. Install and start your chosen server, load a model, and enable its OpenAI compatible API.
2. In Settings → Models → Other Servers, enter a name, its base URL including /v1, and its key if required. In v2.3.0, use the combined LM Studio & Other Servers section.
3. Select Add, then choose a discovered model. Use Connect or Refresh to retry discovery.

The server must expose /v1/models and /v1/chat/completions. A website or chat-interface URL alone is not enough. A server on another machine receives your messages; use HTTPS and the server's authentication when connecting remotely.

Connect models

Cloud providers and API keys

Get a key from your chosen provider: OpenAI, Anthropic, or Google Gemini.

1. Open that provider's section in Settings → Models.
2. Paste the API key and select Connect.
3. Select an available model. If none appear, check the account's API access, billing, and model permissions.

A consumer chat subscription does not necessarily include API usage. Provider charges and limits apply. Keys are stored in macOS Keychain. Your prompts and included reference material are sent to the chosen provider.

Connect models

Apple Intelligence and Xcode

ChatHarbor's Apple Intelligence provider needs a compatible Apple Silicon Mac, macOS 26 or later, and Apple Intelligence enabled and ready in System Settings. Check Apple's current requirements and availability.

The v2.3.4 download does not include this provider. It was built with an older SDK. Installing Xcode alone cannot add the provider to an already-built app. When a compatible build includes it, end users do not need Xcode to use it.

Everyday use

Chat and compare answers

Select an available model, choose Chat, type a question, and send it. The tour waits for your message; it never sends one for you.

Use Compare to ask two to four models the same question. Compare their responses, generation time, usage, and available cost estimates. Right-click a message and choose Fork to Model to explore a different answer while keeping the original conversation.

Use the sidebar's chat history to find older conversations. Export a conversation as Markdown when you want a copy outside the app.

Everyday use

Build a reusable assistant with Ships

A Ship combines a model, instructions, and reference material so you can reuse an assistant. For example, create a Writing Coach with instructions about tone and the documents it should use.

1. Choose Build your first Ship or the + beside Ships.
2. Give it a name and select a model. Add instructions and optional reference material, called cargo.
3. Save the Ship and start a conversation with it. You can edit the Ship later.

Reference material included in a request goes to the selected model provider. Fetching web references uses the internet, even when the model runs locally.

Everyday use

Separate Personal, Work, and other Harbors

A Harbor groups chats, Ships, and brainstorms for one area of life. Open the harbor menu in the sidebar to create, rename, or switch harbors. Your existing content starts in Personal.

Right-click an item and choose Move to Harbor to reorganize it. Chat forks move together; a Ship's conversation history moves with it.

Harbors share provider connections, app settings, and one local database. They organize content; they are not separate accounts or security boundaries.

Everyday use

Brainstorm with local or cloud models

1. Open Brainstorm, enter a topic, and choose a method.
2. Assign a model to every active role. One model can play several roles; you can also mix models or providers.
3. Start the session, review checkpoints, and use the shortlist and disagreement pass to narrow ideas and challenge assumptions.
4. Save decision notes and outcomes, ask follow-up questions, or export the report as Markdown or PDF.

For fully local model processing, choose downloaded models served on this Mac for every role and follow-up question. Keep Ollama or LM Studio running. Several loaded models can require more memory, so start with one model across roles if necessary. Software and model downloads need internet access first.

Everyday use

Understand tokens and cost estimates

Tokens are pieces of text processed by a model. Input covers the prompt and included context; output covers generated content. Provider reporting varies, so an unknown count is not the same as zero. Estimates are labeled.

Cache and reasoning counts are subsets where reported, not extra tokens to add again. Dollar amounts use supported pricing entries; unmatched models show cost as unavailable. Your provider's billing is the final record.

Brainstorming shortens older contributions and reuses the decision brief for follow-up questions. Full transcripts and exports remain stored. Shortening context can omit detail, and savings vary by session; no fixed reduction is promised.

Privacy and support

Delete conversations or reset local data

Deleting a chat asks for confirmation. You can explicitly skip chat confirmations for five minutes; restarting clears that choice. Other destructive actions still ask. Deleting a Ship removes its conversations and cargo.

For a full reset, open Settings → General → Data & Storage → Delete all ChatHarbor data. Type DELETE, then choose Delete & Quit. Reopen the app to finish the reset before data loads. If cleanup fails, the app offers Retry or Quit.

Reset removes every Harbor, conversation, Ship, brainstorm, saved template, app preference, app cache, and ChatHarbor Keychain credential. This is not secure SSD erasure. Exports, backups, original reference files, provider copies, and local model installations remain. Export anything you need before resetting.

Privacy policy

Privacy and support

Connected, but no models or replies?

• Server unavailable: open Ollama or LM Studio and start its server. Check the address and port. On another machine, localhost refers to that machine, not yours.
• No models: download a model; in LM Studio, load it. Refresh the connection in ChatHarbor and choose a discovered model.
• Unauthorized: check the key and API access. Local servers need a key only when their authentication is enabled.
• Slow responses: try a smaller model or fewer simultaneous models. Available memory and context length affect performance.
• Apple unavailable: read the status in Settings and the Apple Intelligence guide; upgrading macOS cannot add a provider missing from the app build.

Still stuck? Report a bug with your app version, provider, and error text. Remove API keys and private conversation content first.