Turning Iris on

This page takes a gateway from "Iris is off" to "people can use it": add a model, switch on the features you want, and set the limits. You need the Iris administration capability (AiAdmin; the built-in Admin role has it), a license that includes the modules in Iris, and a model to connect to.

Everything on the Iris AI page takes effect immediately. Nothing needs a restart.

1. Add a model

1. Sign in to the Nexus web page as an administrator and open Security › Iris AI.

2. Under Providers, click Add provider….

3. In Start from, pick OpenAI, Anthropic (Claude), Azure OpenAI, Ollama, vLLM or LM Studio. It fills in the address and whether a key is needed. You can change anything.

4. Set Name, Base URL and Model (for Azure OpenAI, the Deployment name and the Azure api-version).

5. Set Where it runs truthfully. Operators and designers are shown it next to every Iris feature:

   Choice	Means
   Local	This machine or this network. Nothing leaves the site.
   Private	An endpoint your organization controls.
   Cloud	A third party. Plant data leaves your network.

6. Paste the API key, if the model needs one. It is write-only: Nexus stores it in its secrets store, never shows it again, and never puts it in a prompt, a transcript, a log or a backup. To replace it, paste a new one; to remove it, tick Remove the stored key.

7. Leave Supports tool calling ticked unless you know the model lacks it. A model without tool calling is Chat only: it cannot look anything up in the plant, so most features are of little use with it.

8. Click Add provider, then Test connection on its row. The test sends one short message and checks whether the model calls a tool.

9. If you have more than one provider, Make default on the one Iris should use.

The optional Proxy, CA bundle path, Timeout, Retries and the provider's own token and request limits are under the same form.

Using Claude

Pick Anthropic (Claude) and paste an API key from the Anthropic Console. The address is https://api.anthropic.com, with no /v1 on the end, and the API style is Anthropic (Claude): Nexus speaks Anthropic's own Messages API, not an OpenAI look-alike. The preset fills in claude-opus-5-5; other valid model IDs include claude-sonnet-5-5 and claude-haiku-5-5. Claude thinks before it answers, and that thinking counts against the reply's token limit, so choosing Anthropic starts Max output tokens at 4096 (other providers start at 1024). If answers still come back cut short, raise it. Test connection checks the key, the model name and tool calling in one go. Claude is a Cloud provider: plant data leaves your network.

A model on your own network

Ollama's address is http://<host>:11434/v1 and needs no key. Whether a model supports tool calling varies by model: use Test connection, and expect a small model to be much weaker at it than a hosted one. Choosing a Local provider (a preset or by hand) starts it with Needs an API key off. Test tells apart a model that rejects tools (mark it Chat only) from one that answered the probe without calling the tool (Tool call not observed), and gives thinking models room to think before the call.

2. Turn on the features you want

Under Features, each switch is off until you turn it on. The text under each switch lists what that feature can send to the model. Turning one on lets the people who hold the AI Use capability (AiUse) use it.

Switch	Surface
Designer assistant	Studio assistant
Subsystem summaries	Summaries
Operator chat	Operator chat
Agents	Agents
Gateway scripts	raylux.ai.ask(), under its own Gateway scripts card

By default the Admin and Designer roles hold AI Use. Operator and Viewer do not: grant it to a role under Security › Roles when you want those people to use the operator chat or summaries.

3. Set limits

Where	Limit	Default
Limits per person	Daily tokens, monthly tokens, requests per minute for each signed-in person or API key	30 requests a minute; no token limit
Operator chat limits	Requests per minute and tokens for one session (one browser tab or Lens window)	10 a minute, 100,000 tokens
Gateway scripts	Calls and tokens for all gateway scripts together	30 calls a minute
Each provider	Daily tokens, monthly tokens, requests per minute for everyone together	None

0 means no limit. Days and months are UTC. When a limit is reached the call fails with a message that names the limit and when it resets; nothing else is affected. Tokens are what the provider reports, or an estimate when it reports none, and the call that crosses a limit can overshoot it by its own size.

Writes need restricted tag access

Under Change proposals:

• AI may propose tag writes lets Iris file a proposal to write a tag. It is off by default. While it is off, no surface is offered the tool, and a pending tag proposal cannot be approved.
• Require e-signature to approve AI changes asks the approver to type their password again and records a tamper-evident signature (21 CFR Part 11). It works only while the Advanced Security module is licensed.
• Proposal time limit (minutes): a proposal nobody approves in this time expires. The default is 15.

Neither switch does anything while the gateway's tag access is open, which is the default. Tools that file proposals are then absent, and a key that could file them is refused with the reason. Set tag access to restricted under Nexus Settings first; switching back to open suspends them again at once. Approvals covers what happens next.

4. Keep what you need to

Under Transcripts, set how many days to keep conversations (30 by default; 0 keeps none, and the audit-log row for each call is always written). Usage shows today's and this month's tokens for each provider and each person. See Data, limits and records.

When Iris refuses

What the person sees	What it means
"Using Iris needs the AiUse capability."	Their role lacks AI Use.
LICENSE_NOT_ENTITLED (HTTP 402), naming the module	The license lacks aiCore, or aiOperator for operator chat, or aiAgents for agents.
"The … feature is not enabled"	Its switch under Features is off.
"Not configured" (503)	There is no provider, or the default is disabled or has no key.
BUDGET_EXCEEDED or RATE_LIMITED (429)	A limit above was reached; the message says which and when it resets.
BUSY (503)	Iris's workers are full. Try again in a moment.
PROVIDER_TIMEOUT, PROVIDER_UNREACHABLE, PROVIDER_ERROR	The model did not answer. Check Test connection.
STEP_LIMIT	The model kept calling tools and was stopped after six rounds. Ask a narrower question.