Local AI Configuration Reference

Reference for configuring the Local AI endpoint, master enable, tool-category bits, and pointing at alternative LLM endpoints (cloud or alternate local).

AI Integration → Local AI → Configuration

Where the configuration lives

Local AI reads its full configuration from two surfaces: the Solution Capabilities row for LocalAI (the master enable and the endpoint JSON)

Editing in the Designer

The canonical edit surface is Solution → Capabilities. The Local AI capability row carries:

• Enabled checkbox — toggles SolutionCapabilities[LocalAI].Enabled. Master kill-switch.
• Status indicator — reachability probe against the configured endpoint URL. Cached for 30 seconds.
• Endpoint URL — read-only display of the resolved URL. The URL points to the chat-completions endpoint (/v1/chat/completions), which accepts POST requests only and returns a browser error if opened directly. The link icon next to the URL opens /v1/models in your browser instead — a GET endpoint supported by Ollama, LM Studio, vLLM, and all OpenAI-compatible servers that lists installed models and confirms the server is reachable.
• Settings link, labeled Edit Configuration in the Designer — opens the Edit Local AI Endpoint dialog for SolutionCapabilities[LocalAI].Settings.
• Model name — read-only display of the configured Name field.
• Secure Gateway IP — optional egress routing (10.1.5+). Set to the IP or host of a SecureGateway egress TServer to route this solution’s AI traffic through it; leave blank to call the endpoint directly. See Remote and Cloud LLM Models.

The same Local AI tile is also surfaced on the Data Servers page (sibling of the OPC UA, DataHub, MQTT Broker, and MCP for Runtime tiles) as a convenience shortcut for engineers who reach for Data Servers first — both routes edit the same row.

The Settings JSON

Seven fields, all defensive — an empty/missing/malformed Settings value transparently resolves to defaults. Unknown extra keys are preserved across edit cycles, so future revisions stay forward-compatible.

Replace 192.168.1.50 with the IP of the machine running your model. The model must not run on the FrameworX/TServer host — run it on a separate networked machine (ideally with a GPU).

{
  "URL": "http://192.168.1.50:11434/v1/chat/completions",
  "Name": "qwen2.5:7b-instruct",
  "Authorization": "NoAuth",
  "Headers": "",
  "Info": "Recommended default model. Apache 2.0, ~4.7 GB.",
  "TimeoutSeconds": 60
}

The configuration is parsed defensively on every Local AI call — the parse cost is negligible compared with the LLM round-trip, and there is no caching layer to invalidate when the JSON changes.

The ModelOptions bitmask

An integer column on SolutionSettings carrying independent enable bits. The bitmask is shared with the AI Runtime Connector and the AI Designer connector — the same bits gate the same tool categories regardless of which transport the LLM uses to call them.

The five tool-category bits (0x04–0x20) are AND-gated against the master bit. A category bit ON without the master bit ON leaves the category effectively OFF.

Master gate order

Both consumer paths apply the gates in a fixed order:

1. SolutionCapabilities[LocalAI].Enabled — if false, return status="disabled" immediately. No HTTP traffic. latencyMs = 0.
2. SolutionSettings.ModelOptions bit 0x02 — ChatRequest only: if the master tool-surface bit is OFF, return status="disabled". AI.Execute skips this gate (no tools to expose).
3. Per-category bits — ChatRequest only: AND-ed against the master bit when assembling the tool catalog the LLM sees during a chat turn.

Pointing at a different LLM endpoint

Replace the URL and Name fields. Any OpenAI-compatible chat-completions endpoint works.

Ollama on a separate host (LAN)

The model must run on a separate machine — replace 192.168.1.50 with the IP of that machine. Do not use localhost or 127.0.0.1 as the recommended value; loopback means the model would need to run on the FrameworX/TServer host, which is not supported.

{
  "URL": "http://192.168.1.50:11434/v1/chat/completions",
  "Name": "qwen2.5:7b-instruct",
  "Authorization": "NoAuth",
  "Headers": ""
}

Remote Ollama on a GPU server

{
  "URL": "http://gpu-server-01.lan:11434/v1/chat/completions",
  "Name": "qwen2.5:32b-instruct",
  "Authorization": "NoAuth",
  "Headers": ""
}

The remote Ollama must be started with OLLAMA_HOST=0.0.0.0:11434 and the firewall opened on TCP 11434.

OpenAI-compatible cloud endpoint with Bearer token

{
  "URL": "https://api.example-llm-provider.com/v1/chat/completions",
  "Name": "the-cloud-model-name",
  "Authorization": "BearerToken\n/secret:CloudLLMApiKey",
  "Headers": ""
}

The /secret:CloudLLMApiKey token resolves at call time from the SecuritySecrets vault — the actual API key never appears in the configuration. See SecuritySecrets Authentication for Local AI.

Endpoint with extra HTTP headers

Some providers require extra request headers (organization ID, project ID, region). Add them via the Headers field, one Key: Value pair per line:

{
  "URL": "https://api.example-llm-provider.com/v1/chat/completions",
  "Name": "the-cloud-model-name",
  "Authorization": "BearerToken\n/secret:CloudLLMApiKey",
  "Headers": "X-Organization-Id: org-12345\nX-Project-Id: /secret:CloudLLMProjectId"
}

Header values also accept /secret:<Name> tokens.

Anthropic (Claude) endpoint

In the Edit Local AI Endpoint dialog, set Provider to Claude (Anthropic). This is the field that engages the Anthropic Messages API dialect: the combo is free-text, and any value containing anthropic (case-insensitive) selects it. Leave it on the OpenAI-compatible preset and the request is built in the wrong shape no matter how the headers are set. Anthropic authenticates with an x-api-key header rather than a bearer token, and requires an API version header on every request, so both go in the Headers box while Authorization stays NoAuth and Auth Value is left empty. The BearerToken shape shown in the previous examples does not apply here.

Type one header per line in the Headers box, exactly as below. This is the form you enter in the Designer:

x-api-key: /secret:AnthropicApiKey
anthropic-version: 2023-06-01
anthropic-workspace-id: wrkspc_01ABC...

The same endpoint as a SolutionCapabilities[LocalAI].Settings blob, for anyone editing the JSON directly rather than using the dialog. The line breaks typed in the Headers box appear here as \n escapes, because a JSON string cannot contain a literal newline:

{
  "Provider": "Claude (Anthropic)",
  "URL": "https://api.anthropic.com/v1/messages",
  "Name": "claude-opus-4-8",
  "Authorization": "NoAuth",
  "Headers": "x-api-key: /secret:AnthropicApiKey\nanthropic-version: 2023-06-01\nanthropic-workspace-id: wrkspc_01ABC...",
  "Info": "Anthropic Claude endpoint; key held in SecuritySecrets.",
  "TimeoutSeconds": 60
}

The third header, anthropic-workspace-id, is needed only for some keys. Anthropic issues three kinds, and the kind the site holds decides whether the header is required:

Omitting the header with an unbound key returns HTTP 400: anthropic-workspace-id is required when authenticating with an identity-linked API key; send the id of the workspace this request acts in. The Local AI status indicator surfaces this as a failed test, and no chat or AI.Execute call succeeds until it is set.

Find the workspace ID in the Anthropic Console under Settings → Workspaces, in the ID column; it always carries the wrkspc_ prefix. The Default Workspace does not list an ID there, so name one of the other workspaces. If the API key is linked to a service account, that service account must be a member of the workspace named in the header, or the call returns HTTP 404 Workspace not found instead.

The alternative is to create an API key bound to a single workspace, which needs no header at all. Both approaches work; the header is the one that leaves an existing organization-wide key in place.

Routing AI traffic through the SecureGateway

Instead of this runtime calling the LLM endpoint directly, a solution can hand the AI call to a designated egress TServer reached through the SecureGateway Services Reference. Set Secure Gateway IP (the SecureGatewayIP field, persisted in SolutionCapabilities[LocalAI].SettingsExt) to the egress server’s IP or host. The AI request is then forwarded to that server, which holds the endpoint configuration and credentials and makes the outbound LLM call on this solution’s behalf — so the provider API key never leaves the egress host, and the control-zone runtime never opens the outbound connection. This is the same per-solution ServerIP pattern used by Datasets database connections and remote Device channels. Leave the field blank to call the endpoint directly from this runtime (the default). For the zone-crossing rationale and topologies, see Remote and Cloud LLM Models.

Configuration safety nets

The platform applies several safety nets to prevent silent misconfiguration:

• Defensive defaults. Empty / null / malformed SolutionCapabilities[LocalAI].Settings falls back to the recommended local Ollama defaults. A solution with a corrupted JSON blob still works against the local default.
• Status probe. The Local AI tile in the Designer probes the resolved URL on a 30-second cache, surfacing a red indicator when the endpoint is unreachable. Use it before deploying.
• Master kill-switch precedes everything. A solution can be staged with full configuration and shipped with SolutionCapabilities[LocalAI].Enabled = false. No LLM traffic flows until the customer toggles it ON in Solution → Capabilities.
• Off-server short-circuit. Secret resolution is a server-side operation. Calls reaching Local AI from a thin-client context cannot resolve secrets and fall through to a normal HTTP error reply — no silent unauthenticated POST.

What this page does NOT cover

• Bringing up Local AI on a fresh machine. See Local AI - First Install Walkthrough.
• SecuritySecrets reference syntax and examples. See SecuritySecrets Authentication for Local AI.
• Reply envelope shape and status semantics. See Local AI Reply Envelope Schema.
• The ChatRequest Display action. See ChatRequest Action Reference.
• The AI.Execute script API. See AI.Execute API Reference.

In this section...