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

# Connect a provider

Haarness needs one model it can talk to before it can do anything. Connect the one you already
pay for. You do it once, and the terminal UI, Desktop and the CLI on this computer all use it.

**You need:** Haarness [installed](https://haarness.ai/docs/start/install.md), and a subscription, an API key or a local
model. **Next you will:** start your first chat.

## Pick a way in

| You have | Do this |
| --- | --- |
| ChatGPT Plus or Pro, GitHub Copilot, or SuperGrok | Sign in with that subscription |
| An API key from OpenAI, Anthropic, Google, OpenRouter, Groq, DeepSeek, Mistral or others | Paste the key |
| Ollama or LM Studio on this computer | Nothing: Haarness finds it |
| Another model server, local or remote | Add it as a custom endpoint |
| A Haarness Cloud plan | Sign in to Haarness |

Only the last one needs a Haarness account. [Local or Cloud](https://haarness.ai/docs/start/local-or-cloud.md) explains
what an account adds.

## Connect in the terminal UI

1. Run `haarness` in a project folder. If nothing is connected yet, **Welcome to Haarness** opens
   by itself. Later, type `/connect` and press Enter to open the same list.
2. Pick a provider. **Popular** lists Haarness Cloud, OpenAI, Anthropic, Google Gemini, GitHub
   Copilot, xAI, OpenRouter, Groq, DeepSeek and Mistral; **More providers** has the rest.
3. Pick how to connect, such as **Sign in with ChatGPT** or **Use an API key**.
4. **To use a key:** paste it and press Enter. The screen shows where to create a key and the
   environment variable that also works.
5. **To sign in:** finish in the browser that opens. If a code is shown, enter it on the sign-in
   page. Press `c` to copy the code, or `o` to open the browser again.
6. You see **<provider> connected · pick a model**. Choose a model and press Enter.

`/connect openai` jumps straight to one provider. Under **Something else** at the end of the list
are **Custom endpoint…**, **Haarness Router…** and **Manage providers…**, where you can disconnect
a provider. `/providers` opens the same management screen.

## Connect in Desktop

Desktop opens **Welcome to Haarness** when you open a project and nothing is connected. You can
also open it with **Connect a provider** in the message box, or from **Settings → Providers**.
[Install and first run](https://haarness.ai/docs/desktop/install.md#connect-a-model) walks through it.

## Connect from the command line

```sh
haarness auth login openai          # sign in with ChatGPT in your browser
haarness auth login github-copilot  # sign in with GitHub
haarness auth login xai             # sign in with your SuperGrok subscription
haarness auth set anthropic         # store an API key (you are asked for it)
haarness login                      # sign in to Haarness Cloud
```

`auth set` also takes the key with `--key <key>` or from a pipe. To check what you have:

```sh
haarness providers         # each provider and whether it is connected
haarness models            # every model you can use right now
haarness auth list         # credentials stored by Haarness
haarness auth logout openai
```

A running Haarness picks up a new sign-in or key straight away. You do not need to restart it.

## Sign in over SSH or on a server

When the browser is on another device, sign in with a code instead:

- In the terminal UI, choose **Sign in with a code**. Over SSH it is already selected.
- On the command line, add `--method headless` to `haarness auth login`, or use
  `haarness login --device` for Haarness Cloud.

You get a link and a code to enter on any device with a browser.

## What happens to a key you paste?

When you paste a key in the terminal UI or Desktop, Haarness first asks the provider for its model
list with it. If the provider refuses the key, the reason shows under the field and nothing is
saved. If the provider cannot be reached, the key is saved with a warning. `haarness auth set`
saves the key without checking it.

The key is saved on the computer that runs Haarness, in a file only your user can read, and never
in your project.

## Use a model on your own machine

If [Ollama](https://ollama.com) or [LM Studio](https://lmstudio.ai) is running on this computer
on its usual port, Haarness finds it and lists its models. Start it before you start Haarness.

For any other OpenAI-compatible server, add it once:

```sh
haarness provider add my-llm --url http://127.0.0.1:8080/v1 --no-auth
```

Haarness lists the server's models when the server offers a list; add `--model <id>` to name them
yourself. In the terminal UI or Desktop, choose **Custom endpoint** instead.
[Custom providers](https://haarness.ai/docs/providers/custom-providers.md) covers keys, headers and other API formats.

## Use Haarness Cloud models

Sign in with `haarness login`, with **Haarness Cloud** in the terminal UI's provider list
(`/connect haarness`), or with **Use Haarness Cloud** in Desktop. You do not need an API key:
signing in is enough. Cloud models then appear in the model picker (F2 in the terminal UI) and use
credits from your plan.

## Use an environment variable instead

You can skip storing a key and set the provider's variable before you start Haarness:

| Provider | Variable |
| --- | --- |
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` |
| GitHub Copilot | `GITHUB_COPILOT_TOKEN`, `GH_TOKEN` or `GITHUB_TOKEN` |
| xAI | `XAI_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |

The connect screen shows the variable for every other provider. Two things to know:

- **A variable wins over anything stored.** If `OPENAI_API_KEY` is set, Haarness uses it even if
  you signed in with ChatGPT. Likewise, a `GH_TOKEN` or `GITHUB_TOKEN` in your environment
  connects GitHub Copilot.
- **Haarness reads variables when its background server starts.** If Haarness is already running
  in that folder, wait until nothing is running, stop it with `haarness serve --stop`, then start
  it again.

## Why is a model missing?

Each sign-in or key only offers the models that account can use. A ChatGPT sign-in, for example,
lists the models your plan includes; if you choose one it does not include, the error names the
ones you can use. Run `haarness models` to see the full list for everything you have connected.

## Next

- [Your first chat](https://haarness.ai/docs/start/first-session.md): ask a question, make a change, review it
- [How providers work](https://haarness.ai/docs/providers/overview.md): native providers, custom endpoints and the router