Configuration

Providers

hara is provider-agnostic. It ships with first-class support for Alibaba Token Plan, Volcengine Ark Agent Plan, MiniMax Token Plan, Anthropic Claude, DeepSeek, and Qwen (free OAuth tier), and talks to anything OpenAI-compatible — OpenAI, GLM, 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
 
# Alibaba Token Plan — Personal or Team subscription key
hara profile add aliyun --byok --provider token-plan --model qwen3.8-flash
 
# MiniMax Token Plan
hara profile add minimax --byok --provider minimax-token-plan --model MiniMax-M3
 
# Volcengine Ark Agent Plan — dedicated Plan key, Beijing Responses route
hara profile add ark-agent-plan --byok --provider volcengine-agent-plan --model ark-code-latest
 
# DeepSeek — direct official API
export DEEPSEEK_API_KEY=...
hara config set provider deepseek
hara config set model deepseek-v4-pro
# For conversations with uploaded images:
hara config set model deepseek-v4-flash-vision-exp
 
# 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

Ark Agent Plan has two client-specific routes; it is not one URL that should be copied into every tool. Hara and Codex use the Responses route https://ark.cn-beijing.volces.com/api/plan/v3 with ARK_API_KEY. Claude Code uses the Anthropic-compatible route https://ark.cn-beijing.volces.com/api/plan with ANTHROPIC_AUTH_TOKEN. Hara selects its fixed Responses route automatically; the profile command asks for the dedicated Agent Plan key through a masked prompt. Do not substitute an ordinary pay-as-you-go Ark key or a legacy Coding Plan key. See the official Codex setup and official Claude Code setup.

Alibaba Token Plan uses its fixed Beijing OpenAI-compatible endpoint; do not replace it with a pay-as-you-go Workspace URL. Hara reads the Key-authorized live model catalog and uses the documented Responses route for current Qwen 3.8/3.7/3.6, DeepSeek V4, and GLM 5.2 Agent models. Image-generation, audio, and video models stay outside the conversation picker. When vision-first routing is off, qwen3.8-max, qwen3.8-flash, qwen3.7-plus, and qwen3.6-flash accept image attachments directly. Hara never sends an image to another model or provider unless you explicitly configure that route.

Normal chat exposes the supported thinking levels. Off sends only enable_thinking:false, because that is the Token Plan behavior verified to produce zero reasoning tokens; enabled levels use reasoning.effort. Message Flows default to Off for predictable latency and cost, but a Flow can explicitly inherit chat behavior or select another level. Hara sends store:false, keeps the durable transcript locally, and enables Alibaba's Session prefix cache. Provider-hosted Harness tools are not silently enabled: local approval, company policy, and Hara's audit trail remain the execution boundary.

Both commands request the Key through Hara's masked prompt; do not put credentials directly in shell history. Token Plan subscription keys are licensed for supported interactive coding and Agent tools, not arbitrary application backends or batch scripts. Keep the key personal to its subscriber and follow the current Alibaba Token Plan terms.

On the official https://api.deepseek.com endpoint, deepseek-v4-flash and deepseek-v4-pro use DeepSeek's stateless Responses API for text. The exact deepseek-v4-flash-vision-exp model additionally accepts uploaded PNG, JPEG, GIF, and WebP files through Responses input_image; Hara inlines a local attachment instead of requiring a public image URL. Hara accepts semantic streamed reasoning, text, and function-call events, and validates their order and terminal state. Flash and Pro are not marked as visual merely because they share the same provider.

A custom endpoint or a managed Hara Control profile follows that gateway's advertised protocol instead; it is not assumed to support /v1/responses. Explicitly turning thinking off uses DeepSeek's Chat route with thinking disabled. See DeepSeek's official vision guide for the upstream model and media boundary.

Vision-first routing

Set visionModel when every attached image should first be read by one dedicated visual model. Hara passes only that model's text description to the conversation model, even when the conversation model can also see images natively:

hara config set visionModel deepseek-v4-flash-vision-exp
# In an interactive session, inspect or change the route:
/vision
/vision deepseek-v4-flash-vision-exp
/vision off

For a Personal connection, Desktop's Settings → AI & models can store an optional dedicated vision endpoint and key through masked credential input. For a company connection, Hara ignores personal endpoint/key overrides: the visual model must be in that Space's server-advertised allow-list and uses the same managed device credential. /vision off returns to the conversation model's native image behavior.

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: token-plan | minimax-token-plan | anthropic | deepseek | 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