Sign-ins and API keys

Most providers connect with either a sign-in or an API key. Do it once and the provider's models appear in the model picker for every project.

Sign in with a subscription

ChatGPT Plus or Pro, GitHub Copilot and SuperGrok work without an API key.

haarness auth login openai           # ChatGPT, in your browser
haarness auth login github-copilot   # GitHub, with a device code
haarness auth login xai              # SuperGrok, with a device code

The browser opens and, for GitHub and xAI, Haarness shows a code to enter. When you finish, the terminal says you are connected. Sign-ins renew themselves.

On a machine without a browser, such as over SSH, add --method headless. Haarness prints a link and a code to use on any other device. In the terminal UI and Desktop this is Sign in with a code.

In the terminal UI, /connect offers the same choices; in Desktop, use Settings → Providers → Connect a provider. Both also work when you are connected to a remote Haarness server; the sign-in is then kept on that server.

Use an API key

haarness auth set anthropic

Paste the key at the hidden prompt. You see Stored anthropic credential in owner-only auth.json.

In the terminal UI (/connect) and in Desktop, Haarness asks the provider about a new key before it saves it:

• A key the provider refuses is not saved. The error names the provider and gives its reason, for example Anthropic rejected this API key (invalid x-api-key). Check that you copied all of it.
• If the provider cannot be reached, the key is saved with a warning that it could not be checked. Replace it if chats then fail to sign in.

haarness auth set saves the key without checking it.

Or set the provider's environment variable before you start Haarness:

For GitHub Copilot, a key is a GitHub personal access token with Copilot access. Every other built-in provider is in All built-in providers; /connect in the terminal UI also shows each one's variable and where to get a key.

Use Azure OpenAI, Google Vertex AI or Amazon Bedrock

These use your cloud account's own credentials. Tell Haarness where your account is, then give it a credential; the first one found is used.

Azure OpenAI (azure)

• Where: AZURE_RESOURCE_NAME, or the full AZURE_OPENAI_BASE_URL.
• Credential: AZURE_OPENAI_API_KEY (or AZURE_API_KEY), then a key stored with haarness auth set azure, then az login.

Google Vertex AI (google-vertex)

• Where: GOOGLE_VERTEX_PROJECT (or GOOGLE_CLOUD_PROJECT), and GOOGLE_VERTEX_LOCATION if not us-central1.
• Credential: GOOGLE_OAUTH_ACCESS_TOKEN (or GOOGLE_ACCESS_TOKEN), then a token stored with haarness auth set google-vertex, then gcloud.

Amazon Bedrock (amazon-bedrock)

• Where: AWS_REGION (or AWS_DEFAULT_REGION), if not us-east-1.
• Credential: a Bedrock API key in AWS_BEARER_TOKEN_BEDROCK or stored with haarness auth set amazon-bedrock, then AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (with AWS_SESSION_TOKEN if you have one), then the AWS_PROFILE in your shared credentials file.

Haarness falls back to az or gcloud only when it sends a request. Azure and Vertex then show as not connected, and the model pickers do not offer them, so set a key or token if you want to pick their models in the apps.

Haarness never contacts cloud metadata endpoints on its own. For SSO, instance roles or role assumption, use a tool that exports credentials into the environment.

Each platform starts with two example models. To use your own Azure deployments, other Vertex models or other Bedrock model ids, add them as a custom provider.

Which credential is used

• An environment variable wins over a stored key or sign-in. If OPENAI_API_KEY is set, Haarness uses it even when you signed in with ChatGPT. Unset it to use your subscription.
• Environment variables are read when the Haarness server starts. Haarness starts one in the background the first time you use a project. If you set a variable later, stop that server with haarness serve --stop (this interrupts running work) and start Haarness again.
• Desktop opened from the Dock or an app launcher usually does not see variables exported in your shell profile. Store the key with haarness auth set or in Desktop instead.
• Stored keys and sign-ins apply at once. auth set, auth login and auth logout take effect in a running server without a restart.

See, change or remove credentials

haarness auth list              # stored credentials and their kind
haarness providers              # every provider and whether it is connected
haarness auth logout anthropic  # remove a stored credential

Stored credentials live in an owner-only auth.json in your Haarness data folder, never in project configuration. They stay on the machine that runs the Haarness server. Who else can read them is in Data and storage.

Troubleshooting

haarness models lists a model but the app does not. The command checks with your current shell's environment, while the app uses the server's. See the second point under Which credential is used.

"is not available on this ChatGPT account". Your plan does not include that model. The error lists the ones it does; pick one of those, or connect an OpenAI API key instead.

"rejected this API key". The provider refused the key you pasted, and nothing was saved. Copy the whole key again; some providers show it only once, so create a new one if you need to.

All built-in providers

Every provider here connects with an API key, stored with haarness auth set ID or read from its environment variable.

Ollama and LM Studio on your own computer need no key; see Local models.

Next

• Local models and custom endpoints
• Haarness Cloud models — no provider account needed