---
title: "HitKeep AI Model Provider Configuration | HitKeep"
description: "Configure optional HitKeep AI model routing for self-hosted deployments with goAI provider variables, token budgets, status checks, and audit boundaries."
canonical: "https://hitkeep.com/guides/admin/ai-model-configuration/"
---

# HitKeep AI Model Provider Configuration

HitKeep can use an optional AI model for features that need structured summarization, recommendation copy, or dashboard-session analytics assistance. Saved-output features include [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/). Dashboard-session features include [Ask AI](https://hitkeep.com/guides/analytics/ask-ai/).

AI is off by default. Ask AI is also off by default and requires `HITKEEP_ASK_AI_ENABLED=true` in addition to the shared AI provider route. HitKeep Cloud manages the model route for cloud customers. Self-hosted operators choose the HitKeep provider/model route and local budget settings through `HITKEEP_AI_*` variables. Provider credentials are resolved by the wrapped [goAI](https://github.com/zendev-sh/goai) provider, so set the provider’s own environment variables for keys, base URLs, or platform credentials unless you are using a HitKeep-specific override.

Route production AI through a gateway

HitKeep has a rudimentary global AI request and token limiter. It is a coarse process-level safeguard, not per-user, per-site, per-provider-key, or a security policy engine. For production use, route model traffic through an AI gateway or provider policy layer that can enforce detailed quotas, model allowlists, key isolation, audit logging, redaction, and network controls. See GoAI’s [supported provider options](https://goai.sh/providers/) and [generic OpenAI-compatible provider](https://goai.sh/providers/compat.html) docs for the underlying base URL, token, header, and custom endpoint patterns.

## What The Model Does

For Opportunity Recommendations, HitKeep does not ask the model to discover facts from scratch. HitKeep reads aggregate analytics first, runs deterministic detectors, and then asks the model for a small structured response.

For Ask AI, HitKeep keeps the assistant inside the human dashboard session. The model can call approved aggregate analytics tools for the active site and return streamed answer text, tool-call progress, citations, charts, and safe dashboard actions. Ask AI does not add an MCP surface, does not show a saved history tab, and does not expose raw prompts or full model responses through takeout exports.

The model may choose:

- approved title, summary, action, and digest translation keys
- allowed interpolation params for those keys
- cited evidence IDs from the detector output
- small metadata fields such as action type and effort

The model may not create new evidence, make unsupported source claims, write free-form customer prose, expose raw prompts, or add financial promises. HitKeep validates the structured response before saving it.

## Cloud And Self-Hosted Behavior

| Deployment | Who configures the model | What the customer sees |
| --- | --- | --- |
| HitKeep Cloud | HitKeep operates the provider/model route and budget policy. | System Status can show non-secret state, provider/model labels when exposed, usage, caps, and safe error categories. |
| Self-hosted | The instance operator sets the HitKeep route/budget fields and the selected goAI provider’s credential environment. | The same System Status fields are available without exposing secrets. |
| AI disabled | No provider call is made. | Detector-backed Opportunities can still be generated when the feature has enough aggregate evidence. |

## Choose A Model

Choose a model for reliable structured output, not marketing copy. A good model route for HitKeep should be fast, cost-controlled, and strong at JSON schema following.

Useful model traits:

- supports structured output or consistently returns valid JSON
- handles short analytical instructions without adding prose
- has enough context for aggregate evidence snapshots
- reports token usage when possible
- has latency and cost that fit scheduled recommendation generation
- can be pinned to the deployment region or gateway policy you need

HitKeep does not require one provider. You can use any provider supported by the HitKeep goAI wrapper, an OpenAI-compatible gateway, a region-scoped provider, or a local model if it can pass validation.

For AWS-credit-friendly self-hosted deployments, the recommended default route is OpenAI GPT OSS 120b through the Amazon Bedrock Mantle OpenAI-compatible endpoint:

- `HITKEEP_AI_PROVIDER=openai-compatible`
- `HITKEEP_AI_MODEL=openai.gpt-oss-120b`
- `HITKEEP_AI_BASE_URL=https://bedrock-mantle.<region>.api.aws/v1`
- `HITKEEP_AI_REGION=<region>`

Mantle keeps the OpenAI-compatible request shape while routing inference through AWS billing and Bedrock access controls. HitKeep signs Mantle requests with the EC2 instance or task role when no explicit `HITKEEP_AI_API_KEY` is set, so production cloud deployments do not need a static Bedrock bearer token.

Direct Amazon Bedrock remains supported through `HITKEEP_AI_PROVIDER=bedrock`. Use `amazon.nova-lite-v1:0` for a lower-cost direct Bedrock model, or `amazon.nova-pro-v1:0` when you want stronger Amazon Nova responses through Bedrock Converse.

Bedrock’s Converse API supports tool configuration, and Amazon Bedrock tool use is client-side for the common case: the model asks for a tool, then the application executes it and sends the result back. HitKeep uses that client-side pattern for direct Bedrock models. With Mantle, HitKeep uses the same local tool loop through goAI’s OpenAI-compatible path, so all analytics tools still run inside HitKeep’s permission and aggregate-data boundary.

Anthropic models on Bedrock can be a stronger option when schema/tool reliability matters more than cost. Current Bedrock model cards list `anthropic.claude-haiku-4-5-20251001-v1:0` and `anthropic.claude-sonnet-4-5-20250929-v1:0` with Converse support. Model access, Marketplace subscription, regional availability, or cross-region inference setup may be required in your AWS account.

## HitKeep Environment Variables

Set these on the HitKeep process. Values can also be passed as matching CLI flags. Keep provider secrets in your process manager, container secret store, or cloud secret manager.

| Environment variable | Default | Required when | Meaning |
| --- | --- | --- | --- |
| HITKEEP_AI_ENABLED | false | Always, to enable AI | Enables optional AI-assisted features. |
| HITKEEP_ASK_AI_ENABLED | false | Ask AI enabled | Enables the optional dashboard Ask AI drawer. Requires HITKEEP_AI_ENABLED=true and a configured provider/model route. |
| HITKEEP_AI_PROVIDER | "" | AI enabled | Provider key used by HitKeep’s goAI wrapper. Common choices include openai, openai-compatible, bedrock, litellm, bifrost, gateway, anthropic, google, mistral, openrouter, groq, and ollama. |
| HITKEEP_AI_MODEL | "" | AI enabled | Provider-specific model ID or gateway route name. |
| HITKEEP_AI_BASE_URL | "" | OpenAI-compatible routes | Gateway or custom endpoint base URL. Required for openai-compatible, compat, gateway, bifrost, and litellm. For direct providers, prefer the provider’s goAI base URL variable such as OPENAI_BASE_URL. |
| HITKEEP_AI_REGION | "" | Optional override | Region override passed to providers that support it. For AWS Bedrock, goAI also reads AWS_REGION or AWS_DEFAULT_REGION. |
| HITKEEP_AI_API_KEY | "" | Optional override | Static token passed to goAI providers that support WithAPIKey or bearer-token options. Prefer provider-native variables such as OPENAI_API_KEY, ANTHROPIC_API_KEY, or OPENROUTER_API_KEY. Redacted in logs and status. |
| HITKEEP_AI_TIMEOUT_SECONDS | 30 | Optional | Provider request timeout. |
| HITKEEP_AI_REQUEST_LIMIT | 100 | Optional | Maximum AI requests per budget window. 0 disables the local request cap. |
| HITKEEP_AI_TOKEN_LIMIT | 100000 | Optional | Maximum counted provider tokens per budget window. 0 disables the local token cap. |
| HITKEEP_AI_BUDGET_WINDOW | 1440 | Optional | Budget window in minutes. The default is one day. |

## Provider Credential Environment

HitKeep does not rename every provider’s credential variables. It builds the selected goAI provider and lets that provider resolve its documented environment variables. Use the [goAI supported providers documentation](https://goai.sh/providers/) as the source of truth for provider-specific auth variables, base URL overrides, and provider pages.

Common variables are:

| Provider | Environment variables goAI reads |
| --- | --- |
| OpenAI | OPENAI_API_KEY, optional OPENAI_BASE_URL |
| Anthropic | ANTHROPIC_API_KEY, optional ANTHROPIC_BASE_URL |
| Google Gemini | GOOGLE_GENERATIVE_AI_API_KEY or GEMINI_API_KEY, optional GOOGLE_GENERATIVE_AI_BASE_URL |
| Bedrock Mantle | EC2/task role or AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, plus HITKEEP_AI_REGION or AWS_REGION. Optional HITKEEP_AI_API_KEY for a temporary bearer-token override. |
| AWS Bedrock | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_REGION or AWS_DEFAULT_REGION, optional AWS_BEARER_TOKEN_BEDROCK and AWS_BEDROCK_BASE_URL |
| OpenRouter | OPENROUTER_API_KEY |
| Mistral | MISTRAL_API_KEY, optional MISTRAL_BASE_URL |
| Groq | GROQ_API_KEY |
| xAI | XAI_API_KEY, optional XAI_BASE_URL |
| Cohere | COHERE_API_KEY |
| DeepSeek | DEEPSEEK_API_KEY, optional DEEPSEEK_BASE_URL |
| Fireworks | FIREWORKS_API_KEY, optional FIREWORKS_BASE_URL |
| Together | TOGETHER_AI_API_KEY or TOGETHER_API_KEY |
| Perplexity | PERPLEXITY_API_KEY |
| Cerebras | CEREBRAS_API_KEY, optional CEREBRAS_BASE_URL |

Check the [goAI provider documentation](https://goai.sh/providers/) for the exact provider you select. If you set `HITKEEP_AI_API_KEY`, HitKeep passes it as an explicit option and it can override provider env resolution for providers that support static keys.

## Setup With A Direct Provider

Use this when HitKeep should call the provider directly. Set the HitKeep route fields plus the provider’s goAI credential environment.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai
HITKEEP_AI_MODEL=your-json-capable-model
OPENAI_API_KEY=provider_key_from_your_secret_store
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

Replace `openai` and `your-json-capable-model` with the provider and model you want to use. See the [Configuration Reference](https://hitkeep.com/reference/configuration/#optional-ai-model-configuration) for the supported provider keys.

### Common Provider Examples

Use these as starting points for popular hosted model routes. Model IDs, access tiers, and pricing change, so confirm the selected model in the [OpenAI model list](https://developers.openai.com/api/docs/models), [OpenRouter model catalog](https://openrouter.ai/models), [Anthropic model list](https://platform.claude.com/docs/en/about-claude/models/overview), or [Gemini model list](https://ai.google.dev/gemini-api/docs/models) before pinning production.

- OpenAI / ChatGPT
- OpenRouter
- Anthropic Claude
- Google Gemini

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai
HITKEEP_AI_MODEL=gpt-5.4-mini
OPENAI_API_KEY=provider_key_from_your_secret_store
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

Start here when you want a direct OpenAI route that is close to the ChatGPT model family but still configured through the API. Use a stronger OpenAI model only after checking latency, cost, and structured-output validation on your own data.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openrouter
HITKEEP_AI_MODEL=anthropic/claude-haiku-4.5
OPENROUTER_API_KEY=provider_key_from_your_secret_store
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

Use OpenRouter when you want one account to test multiple model families. Replace `anthropic/claude-haiku-4.5` with the exact OpenRouter slug you allow in production.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=anthropic
HITKEEP_AI_MODEL=claude-sonnet-5
ANTHROPIC_API_KEY=provider_key_from_your_secret_store
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

Use a Sonnet-class model when structured responses and tool-use reliability matter more than minimum cost. Use Haiku after validating that it passes HitKeep’s output checks for your workflow.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=google
HITKEEP_AI_MODEL=gemini-2.5-flash
GEMINI_API_KEY=provider_key_from_your_secret_store
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

Use Gemini Flash when you want a cost-controlled hosted route with good latency. If your environment uses `GOOGLE_GENERATIVE_AI_API_KEY`, keep that variable instead of `GEMINI_API_KEY`.

## Setup With An AI Gateway

Use this when an internal gateway owns routing, provider choice, policy, and billing.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai-compatible
HITKEEP_AI_MODEL=hitkeep-ai
HITKEEP_AI_BASE_URL=https://ai-gateway.example.com/v1
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

The gateway can route `hitkeep-ai` to any model it supports. Authentication is optional for the generic goAI-compatible provider. If your gateway expects a bearer token, set `HITKEEP_AI_API_KEY` as an explicit gateway token. HitKeep still validates output locally and still enforces its local request and token budgets before provider calls.

## Setup With Bedrock Mantle

Use this for the default AWS-billed GPT OSS route. On EC2, ECS, or another AWS runtime, prefer an instance or task role that can call Bedrock. Set `HITKEEP_AI_REGION` so HitKeep can sign Mantle requests for the right region.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=openai-compatible
HITKEEP_AI_MODEL=openai.gpt-oss-120b
HITKEEP_AI_BASE_URL=https://bedrock-mantle.eu-central-1.api.aws/v1
HITKEEP_AI_REGION=eu-central-1
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

For local smoke tests with a temporary Bedrock bearer token, export `AWS_BEARER_TOKEN_BEDROCK` into your shell and pass it through as `HITKEEP_AI_API_KEY` only for that process. Production should normally use IAM role credentials and SigV4 signing instead of a static token.

## Setup With Direct Amazon Bedrock

Use this when you want inference to run through AWS account billing and IAM. Configure AWS credentials or an instance/task role that can call Bedrock Runtime, enable model access in Bedrock as required, then set the HitKeep provider/model fields.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=bedrock
HITKEEP_AI_MODEL=amazon.nova-lite-v1:0
AWS_REGION=eu-central-1
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
HITKEEP_AI_REQUEST_LIMIT=100
HITKEEP_AI_TOKEN_LIMIT=100000
HITKEEP_AI_BUDGET_WINDOW=1440
```

For stronger responses, use `amazon.nova-pro-v1:0`. For Anthropic-on-Bedrock, use a model ID such as `anthropic.claude-haiku-4-5-20251001-v1:0` or `anthropic.claude-sonnet-4-5-20250929-v1:0` after your AWS account has the required model access.

AWS announced that Activate credits can be redeemed for third-party models on Amazon Bedrock. AWS Billing documentation says eligible credits are applied automatically to eligible service charges until they are exhausted or expire. HitKeep does not decide credit eligibility, sharing, expiration, or which linked account consumes credits. Confirm the AWS billing account, credit sharing settings, Bedrock model access, and current Bedrock pricing before enabling this on a production self-hosted instance.

Useful AWS references:

- [Amazon Bedrock tool use](https://docs.aws.amazon.com/bedrock/latest/userguide/tool-use.html)
- [Amazon Bedrock Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html)
- [Amazon Nova tool use](https://docs.aws.amazon.com/nova/latest/nova2-userguide/using-tools.html)
- [AWS Activate credits for third-party Bedrock models](https://aws.amazon.com/blogs/startups/aws-activate-credits-now-accepted-for-third-party-models-on-amazon-bedrock/)
- [Applying AWS credits](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/useconsolidatedbilling-credits.html)

Use `HITKEEP_AI_REGION` only when you want HitKeep to pass an explicit region override to a provider that supports it.

## Setup With A Local Model

Local models are useful for development and offline checks. They are not automatically release-quality for customer-facing recommendations. Use a model that can return strict JSON reliably.

```
HITKEEP_AI_ENABLED=true
HITKEEP_ASK_AI_ENABLED=true
HITKEEP_AI_PROVIDER=ollama
HITKEEP_AI_MODEL=llama3.1
HITKEEP_AI_BASE_URL=http://127.0.0.1:11434
```

If validation fails, HitKeep keeps detector-backed output and records a safe `invalid_output` category.

## Token Limits

`HITKEEP_AI_TOKEN_LIMIT` is a local usage budget. It is not the model context window and it is not the per-response output cap.

Three different limits can apply:

| Limit | Owner | Meaning |
| --- | --- | --- |
| Model context window | Provider or gateway | Maximum input plus output size the model can handle. |
| Provider output cap | HitKeep request and provider | Opportunities asks for at most 900 output tokens. |
| Local token budget | HitKeep | Maximum counted provider tokens per HITKEEP_AI_BUDGET_WINDOW. |

Start with a small budget and raise it after System Status shows normal usage.

| Use case | Suggested request limit | Suggested token limit | Window |
| --- | --- | --- | --- |
| Small self-hosted instance | 20 | 50000 | 1440 |
| Medium self-hosted instance | 100 | 100000 | 1440 |
| Active smoke testing | 80 | 240000 | 60 |
| Disabled provider calls | Leave HITKEEP_AI_ENABLED=false | Leave default | Leave default |

Request limits count provider calls. Token limits count usage reported by the provider or gateway. Some providers may omit token usage for failed calls or tool steps, so keep upstream provider limits as a second guardrail.

Set either local cap to `0` only when another enforced system owns the same limit.

## Verify System Status

The **Administration -> System Status** page and `/api/admin/system/ai` endpoint show non-secret AI status:

- enabled/configured state
- provider and model label
- `self_hosted` or `cloud_managed` configuration mode
- request and token usage in the current budget window
- cap state, including budget exhaustion
- last safe success or error category

Status never returns provider secrets, raw prompts, raw provider responses, raw external error bodies, or unrestricted tool output.

## Audit And Storage Boundary

AI run records keep the operational facts needed for audit:

- team, site, actor, and feature
- provider and model label
- prompt template version
- cited evidence IDs
- input and output hashes
- final validated structured output
- request and token usage when available
- lifecycle events for request and tool start/finish, latency, status, and safe error category

HitKeep does not persist raw prompts or raw provider payloads. For Opportunities, public API, MCP, share links, takeout, and email digests use the saved customer-visible output, not raw model text.

## Troubleshooting

| Status or symptom | What to check |
| --- | --- |
| disabled | HITKEEP_AI_ENABLED is false or missing. Deterministic Opportunity detectors can still run. |
| not_configured | Provider/model is missing, provider is unsupported, or an OpenAI-compatible provider is missing HITKEEP_AI_BASE_URL. |
| budget_exhausted | Raise HITKEEP_AI_REQUEST_LIMIT, raise HITKEEP_AI_TOKEN_LIMIT, shorten the generation window, or wait for the HITKEEP_AI_BUDGET_WINDOW to reset. |
| auth_failed | Check the selected goAI provider’s environment variables, platform credentials, provider model access, region, and gateway token policy. |
| rate_limited | Lower generation frequency or raise provider/gateway quotas. |
| timeout | Increase HITKEEP_AI_TIMEOUT_SECONDS, reduce gateway latency, or use a faster model route. |
| invalid_output | Use a model with better structured-output support or route through a gateway/model profile tuned for JSON schema compliance. |

## Related

- [Configuration Reference](https://hitkeep.com/reference/configuration/#optional-ai-model-configuration)
- [System Status and Settings](https://hitkeep.com/guides/admin/system-administration/)
- [Opportunity Recommendations](https://hitkeep.com/guides/analytics/opportunities/)
- [Open Exports and Takeout](https://hitkeep.com/guides/data/takeout/)
- [MCP Server](https://hitkeep.com/guides/integrations/mcp/)

[Previous System status and settings](https://hitkeep.com/guides/admin/system-administration/)[Next Social sign-in](https://hitkeep.com/guides/security/social-sign-in/)