Models: turning the AI features on#

AI is off by default. Until you name a provider, nothing calls a model host, and the UI says so in a notice: "AI features are off until a model provider is configured". The assistant, the ownership agents and the detector and analytics agents need a model. Dashboards, detectors and ownership by hand work without one.

Turn it on#

Two providers are accepted in core.env.AI_PROVIDER.

OpenAI:

helm upgrade hyvop ./hyvop -n hyvop --reuse-values \
  --set core.env.AI_PROVIDER=openai \
  --set core.env.OPENAI_API_KEY=<your key>

The endpoint is https://api.openai.com/v1 and the model gpt-4o-mini unless you set core.env.OPENAI_BASE_URL and core.env.AI_OPENAI_MODEL.

An OpenAI-compatible endpoint (Azure OpenAI, OpenRouter, Ollama, vLLM and the like):

core:
  env:
    AI_PROVIDER: openai-compatible
    OPENAI_BASE_URL: https://openrouter.ai/api/v1   # the endpoint with its version path
    AI_OPENAI_MODEL: <the model id>
    OPENAI_API_KEY: <your key>

Core adds only /chat/completions to the base URL, so give the URL with its version path (OpenRouter https://openrouter.ai/api/v1, Ollama http://ollama:11434/v1). helm refuses the install when the base URL or the model is missing in this mode, and when a provider is named with no key and no core.existingSecret. For an endpoint that asks for no key, give any word as the key.

The key is kept in the Secret hyvop-core-secrets (key ai-key), or in your own Secret named by core.existingSecret.

An organisation's own model#

core.env.AI_PROVIDER is the model of the install. An administrator can also bring a model of the organisation's own from the settings screen: a provider (OpenAI, Azure OpenAI or an OpenAI-compatible endpoint), the address, the model or deployment, and a key, for each tier (good and small). The key is stored encrypted under the install's data key and is never shown again. A saved configuration is not used until it has passed a test: one short question, counted on the usage page like any call. Changing the provider, the address, the model or the key clears the test. Until a configuration has passed, and for an organisation that brought none, the install model answers. Once an organisation has one in use, all its AI calls go to it.

Things to know:

• An address inside the cluster or network (Ollama, vLLM) must be named in core.env.OUTBOUND_ALLOWED_HOSTS; public HTTPS addresses are accepted as they are. The network policy still decides what core can reach (next section).
• AI_TIMEOUT also bounds the calls to an organisation's model.

The remediation agent drafts a plan with this model when one is available. core.env.REMEDIATION_AGENT_MODEL=false has the plans written by the rules alone; the rules decide either way.

Reaching the model from the cluster#

Every pod is denied network access by default. Core may reach the internet on port 443 once a provider is named (networkPolicy.egress.core.internet is unset: yes when a model provider is configured). That rule excludes the private ranges 10.0.0.0/8, 172.16.0.0/12 and 192.168.0.0/16. A model on a private address, or inside the cluster, is therefore not reachable by that rule: add its address range to networkPolicy.egress.extraCidrs.

An install with no internet access names a model inside, and sets networkPolicy.egress.core.internet=false; see air-gapped.md. A recipe for a model served in the cluster is in model-in-cluster.md.

Limits on use#

Every call to a model passes one check inside core. These settings in core.env bound it. Each left empty keeps core's own default.

An administrator can set a budget for the organisation in the screen; that budget wins over the values here. Tokens, estimated cost, duration and outcome of every call are recorded per feature, organisation and run, and the administrator reads them on the usage page.

Three ownership settings sit in the same place. OWNERSHIP_AUTO_VALIDATION is off in core, so no resource is validated without a person's answer; two-sources lets the validation agent accept an owner that two independent sources name. OWNERSHIP_RECERTIFY_AFTER_DAYS (180 in core) is when an owner's confirmation is asked for again. INVESTIGATOR_MODEL_FOR_DECLARED_TEAMS (true in core) keeps asking the model for a person when a workload declares only a team; false stops at the team and saves those calls.

What is sent to the model#

In short:

• No rows of your data. A prompt carries the names and types of tables and columns, never a row. Two things carry values, both produced by Hyvop: a finding (resource identifier, saving, state) when the assistant is asked about findings, and the identifier and tags of a resource under investigation, with the name of a team declared for it.
• No names of people, unless you say so. core.env.AI_PERSONAL_DATA is stand-ins by default: a person goes out as person-3 (and address-2 for an e-mail address found in a tag), and Hyvop puts the people back in the answer before it stores or shows anything. Set as-is to send names, addresses and handles as the integrations give them.
• What a user types in the assistant is sent as typed. Team, repository, channel and resource names are not treated as personal data and are sent.
• The model is the one you chose, reached with your key, at the address you gave.

The log at its normal level says that a question was asked, which agent took it and which tool was called. It does not contain the question, the answer, a prompt or what a tool returned.