Configuration

Providers

hara is provider-agnostic. It ships with first-class support for Anthropic Claude and Qwen (free OAuth tier), and talks to anything OpenAI-compatible — OpenAI, GLM, DeepSeek, or a local model server.

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
hara config set provider anthropic
hara config set model claude-opus-4-8
 
# Qwen — free device login (no key)
hara login qwen
 
# Any OpenAI-compatible endpoint
hara config set provider openai
hara config set baseURL https://your-endpoint/v1
hara config set apiKey  sk-...
hara config set model   your-model-id

Run hara doctor any time to check that your provider, auth, and model resolve.

The config file

Global config lives in ~/.hara/config.json (written 0600 — it may hold an API key). A repository may provide .hara/config.json, but it is untrusted by default: only validated model, theme, vimMode, autoCompact, and reasoningEffort preferences are read. Provider routes, credentials, hooks, MCP, sandbox, guardian, approval, and automation settings are ignored. For a repository you have reviewed, set HARA_TRUST_PROJECT_CONFIG=1 before starting hara to enable those privileged keys. Changing it after startup cannot widen trust.

hara config set <key> <value>   # write a value
hara config get [key]           # read config (apiKey masked)
hara config path                # print the config file path

Keys worth knowing

Environment overrides

Every config key has an HARA_<KEY> env override (uppercased), which wins over the config file — handy for CI, cron, and one-offs.

HARA_MODEL=claude-haiku-4-5 HARA_APPROVAL=full-auto hara -p "bump the version"

Common ones: HARA_PROVIDER, HARA_MODEL, HARA_API_KEY, HARA_BASE_URL, HARA_APPROVAL, HARA_SANDBOX, HARA_MAX_CONCURRENCY, HARA_TUI=0 (classic readline), HARA_PROFILE.

Security opt-ins are deliberately process-scoped: HARA_TRUST_PROJECT_CONFIG=1 trusts privileged project config/profile pins, HARA_ALLOW_TRUSTED_EXTENSIONS=1 enables reviewed MCP/external agents in non-interactive runs, and HARA_ALLOW_SENSITIVE_FILES=1 exposes protected files to one launched process. Do not persist these for repositories you do not control.

Profiles

A profile is a named identity — how hara reaches a model. There are two kinds:

• BYOK — your own provider + key (the Personal path).
• Gateway — a hara-control gateway your org runs (the Company / Team path); the real key stays server-side.

# BYOK: your own key
hara profile add personal --byok --provider anthropic --key sk-ant-... --model claude-opus-4-8
# --provider: anthropic | openai | qwen | qwen-oauth
# --base-url <url> points openai at any OpenAI-compatible endpoint (GLM, DeepSeek, local…)
 
# Gateway: join your org's fleet (--code comes from your admin)
hara profile add work --gateway https://gw.example.com --code ABC123
# `hara enroll <url> --code <code>` is a shorthand for adding the default-org gateway profile

Use the public HTTPS origin supplied by the administrator, without /v1. Remote plain-HTTP origins, redirects, and URLs containing credentials are rejected. The one-time code is cleared after exchange; only the scoped device credential remains in Hara's protected profile store. Desktop exposes the same flow under Settings → AI & models → Enterprise managed.

The server-authorized catalog constrains an enterprise profile; a local setting cannot add an unauthorized model. Starting with Hara Control 0.1.15, one enrollment and device credential receive the complete allowed catalog, so the same named profile can switch between deepseek-v4-flash and deepseek-v4-pro without a new code or Key. Keep separate profiles for separate companies or gateways, not for models inside the same company connection. Both models offer off, high, and max thinking controls.

Then manage and switch:

hara profile list        # all profiles + which is active
hara profile use <id>    # set the default profile
hara profile pin <id>    # lock a profile to the current directory
hara --profile <id> -p "…"   # use one profile for a single run

The pin is stored locally in .hara-profile. A Git-tracked pin is ignored by default because a repository must not silently select an identity; explicitly trusted project config enables it.

You can also stash lighter, settings-only bundles in ~/.hara/config.json and select them with --profile (or HARA_PROFILE) — handy for tweaking model/approval without a full identity:

{
  "provider": "anthropic",
  "model": "claude-opus-4-8",
  "profiles": {
    "fast": { "model": "claude-haiku-4-5", "approval": "full-auto" },
    "review": { "model": "claude-opus-4-8", "approval": "suggest" }
  }
}

hara --profile fast -p "regenerate the snapshot tests"

Where hara keeps things