Skip to content
aarness.
DocsStart here
On this page

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, 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 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 walks through it.

Connect from the command line

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:

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 or LM Studio 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:

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 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