This is the documentation for the development version. There are no official binaries for it; build it from the source code in git. Download links on these pages work only after the release. For the current release, see version 7.0.

AI Assistant Reference

Features marked with EE badge require Enterprise Edition.

This page provides configuration reference for the NetXMS AI assistant.

For setup instructions, see Getting Started with the AI Assistant. For task-oriented guides, see AI Assistant How-to Guides. For architecture and concepts, see AI Assistant Concepts.

Server Configuration

Provider and global AI settings are placed in netxmsd.conf. Runtime limits are set through server configuration variables (see Server Configuration Variables).

Global Settings

The [AI] section supports the following parameters:

Parameter Default Description

DefaultProvider

(auto)

Name of the default provider. If not set, the first provider with the default slot is used automatically.

PromptInjectionGuard

true

Enable or disable the prompt injection guard.

Provider Settings

Each provider is configured in a [AI/Provider/<name>] section.

Parameter Type Default Description

Type

String

openai

Provider type: openai, anthropic, mistral, or ollama. Any unrecognized value is treated as ollama.

URL

String

(varies)

API endpoint URL. Defaults: https://api.openai.com/v1/chat/completions (OpenAI), http://127.0.0.1:11434/api/chat (Ollama), https://api.anthropic.com/v1/messages (Anthropic), https://api.mistral.ai/v1/chat/completions (Mistral).

Model

String

(varies)

Model name. Defaults: gpt-6-luna (OpenAI), llama3.2 (Ollama), claude-sonnet-5-5 (Anthropic), mistral-large-latest (Mistral).

Token

String

(empty)

API authentication token. Sent as a Bearer token in the Authorization header for openai, mistral, and ollama providers. Anthropic providers send it in the x-api-key header together with an anthropic-version header.

Temperature

Number

-1

Sampling temperature. Set to -1 to use the provider default.

TopP

Number

-1

Nucleus sampling parameter. Set to -1 to use the provider default. Values above 1 are clamped to 1.0.

VerifySSL

Boolean

true

Verify the provider’s TLS certificate.

ContextSize

Integer

(auto)

Context window size of the model, in tokens. When not set, the server reads it from the provider API for the configured model. The OpenAI API does not report it, but many OpenAI-compatible servers do. If no size is available, chat context usage is shown as a token count only. For ollama providers, the value is sent as num_ctx. When it is not set, the num_ctx of the model file is used, otherwise the model’s maximum context length limited to 32768, or 32768 if the model reports none. For other provider types, the value only affects the context usage display.

MaxOutputTokens

Integer

32768

Maximum response size in tokens (max_tokens). Used by anthropic providers only. Lowered automatically to the model’s output limit when the provider API reports one.

Timeout

Integer

180

HTTP request timeout in seconds.

Slots

String

default

Comma-separated list of slots this provider serves (e.g., default,interactive,analytical).

Provider Slots

Slots route different types of AI requests to appropriate providers. Assign one or more slots to each provider using the Slots parameter.

Slot Description

default

General-purpose slot used when no specific slot is requested. A provider becomes the default when its name matches DefaultProvider in the [AI] section or when its slot list contains default. Without a default provider, model-dependent features (chat, memory, tasks, messages, operators, and workers) are not initialized. The server’s built-in tools and script-defined tools remain available through the MCP endpoint.

interactive

Used for interactive chat sessions with users.

background

Used for background AI task execution.

analytical

Used for deep analysis tasks such as incident investigation.

worker

Used by workers started with the run-workers tool (see Workers).

fast

Used for quick operations where low latency is preferred over capability (e.g., prompt injection guard fallback).

guard

Used by the prompt injection guard. If not defined, the fast slot is used as fallback.

A request to a slot with no assigned provider falls back to the default provider (except the prompt injection guard, which falls back to the fast slot as noted above).

Configuration Examples

Single cloud provider:

[AI/Provider/openai]
Type = openai
URL = https://api.openai.com/v1/chat/completions
Model = gpt-4o
Token = sk-your-api-key
Slots = default

Multi-provider setup with slots:

[AI/Provider/claude]
Type = anthropic
Model = claude-sonnet-4-20250514
Token = sk-ant-your-key
Slots = default,analytical

[AI/Provider/ollama-fast]
Type = ollama
Model = mistral
Slots = fast

[AI]
DefaultProvider = claude

Local-only deployment with Ollama:

[AI/Provider/local]
Type = ollama
URL = http://127.0.0.1:11434/api/chat
Model = llama3.2
ContextSize = 32768
Slots = default

Server Configuration Variables

The following server configuration variables (stored in the database, changed at runtime from the management client) control the AI subsystem:

Variable Default Description

AI.MaxInteractiveSteps

30

Number of steps (LLM round trips with tool calls) in an interactive chat request after which the user is asked whether to continue. Continuing grants a fresh step budget, so this is not a hard cap. Changes take effect without server restart. The database upgrade renames the former AI.MaxInteractiveIterations variable to this name and keeps its value.

AI.MaxBackgroundSteps

64

Maximum number of steps (LLM round trips with tool calls) per request in a non-interactive chat (AI task runs, AI operator cycles, workers, event processing, incident analysis). Changes take effect without server restart. The database upgrade renames the former AI.MaxBackgroundIterations variable to this name and keeps its value.

AI.Memory.EnvironmentMaxSize

16384

Maximum total size (bytes) of environment memory entries placed into AI assistant prompts. Entries beyond this size are available to the model only on request.

AI.Memory.UserMaxSize

8192

Maximum total size (bytes) of per-user memory entries placed into AI assistant prompts.

AI.Memory.ObjectMaxSize

8192

Maximum total size (bytes) of per-object memory entries placed into AI assistant prompts.

AI.Workers.MaxParallel

4

Maximum number of workers a single run-workers call can start (minimum 1). A call that requests more workers fails without starting any. Changes take effect without server restart.

AI.Workers.Timeout

600

Maximum time (seconds) to wait for the workers of a single run-workers call (minimum 10). Workers that do not finish in time are cancelled and reported with status timeout. Changes take effect without server restart.

AIOperator.Enabled

1

Enable the AI operator subsystem (global switch for all operator instances).

AIOperator.MaxConsecutiveFailures

3

Number of consecutive execution failures after which an AI operator instance is disabled automatically.

AIOperator.InterruptCooldown

60

Minimum time (seconds) between an AI operator cycle and the next cycle started by a standing check with the wake action. Interrupts arriving sooner are queued until it elapses.

AIOperator.Checks.ExecutionTimeLimit

10

Maximum execution time (seconds) of a single run of an AI operator standing check script.

AIOperator.Checks.MaxConsecutiveErrors

5

Number of consecutive script errors after which a standing check is disabled automatically.

AIOperator.Checks.MaxPerInstance

32

Maximum number of standing checks per AI operator instance.

AIOperator.Instructions.HistoryDepth

20

Number of standing instruction history records kept per AI operator instance.

AIOperator.Instructions.MaxSize

8192

Maximum size (bytes of UTF-8 text) of AI operator standing instructions; longer text, written by the operator or by an administrator, is truncated at a character boundary (0 for no limit).

Expired AI messages are cleaned up at the interval given by AI.MessageCleanupInterval (default: 60 minutes). This variable is read directly at runtime and is not visible in the Server Configuration view.

Background AI tasks run in the AI-TASKS thread pool, sized by the ThreadPool.AITasks.BaseSize (default: 4) and ThreadPool.AITasks.MaxSize (default: 16) server configuration variables. AI operators run in the dedicated AI-OPERATOR thread pool, sized by ThreadPool.AIOperator.BaseSize (default: 4) and ThreadPool.AIOperator.MaxSize (default: 16). Workers run in the AI-WORKERS thread pool, sized by ThreadPool.AIWorkers.BaseSize (default: 4) and ThreadPool.AIWorkers.MaxSize (default: 16). Changes to the thread pool variables take effect after server restart.

MCP Endpoint

The mcp server module (Module=mcp in netxmsd.conf) adds the Model Context Protocol endpoint /mcp to the server’s web API listener. Address, port, and TLS come from the [WEBAPI] section (see Enabling the API); the module has no settings of its own and does not need the webapi module. With the default listener settings, the endpoint URL is http://127.0.0.1:8000/mcp. For the setup procedure, see How to Connect an MCP Client.

Transport

The endpoint implements the stateless variant of the streamable HTTP transport, protocol revision 2025-06-18:

  • Each request is an HTTP POST with one JSON-RPC 2.0 message and Content-Type: application/json; other content types are rejected with 415.

  • Each response with a body is a single application/json document. The endpoint does not use server-sent events; GET and other methods return 405.

  • No session is created, and no Mcp-Session-Id header is used.

  • Batch requests (a JSON array) are rejected with 400 and JSON-RPC error -32600.

  • Notifications and JSON-RPC responses sent by the client are accepted with 202 and no body.

Method Description

initialize

Returns the protocol revision, the server name and version, and the tools and prompts capabilities.

ping

Returns an empty result.

tools/list

Lists the available tools with their input schemas and annotations.

tools/call

Calls a tool with the given arguments object.

prompts/list

Lists the enabled skills as prompts (name and description).

prompts/get

Returns a skill’s prompt as a single user message.

Other methods return JSON-RPC error -32601.

Authentication and Access Control

Every request must carry a web API authentication token in the Authorization: Bearer <token> header. Use a persistent token (see Authentication Tokens); a token from /v1/login also works, but expires at the latest after WebAPI.AuthTokenMaxLifetime (24 hours by default). Single-use tokens are rejected.

HTTP status Cause

401

The token is missing, invalid, or expired. Deleting a user revokes all of the user’s tokens, so requests of a deleted user get 401.

403

The user account is disabled, or the user does not have the Use AI assistant system access right.

Tools run with the access rights of the user the token belongs to. tools/list and prompts/list are not filtered by these rights: every user gets the same lists, and access checks apply when a tool runs. Calls that reach a known, enabled tool are recorded in the audit log under the AI subsystem, with the tool name and a success flag. A call is recorded as failed only when the tool’s result text starts with Error:; a tool that reports a failure in other words, such as Access denied, is recorded as successful. Requests rejected before that, including calls to unknown or disabled tools, are not recorded.

Tools and Prompts

tools/list contains the global tools and the tools of all enabled skills; an MCP client does not need to load a skill before it calls one of the skill’s tools. Tools that serve only the AI assistant are not listed (see Tools Through MCP). Tools and skills disabled in the AI Skills & Tools view of the Configuration perspective are left out of tools/list and prompts/list, and a call to a disabled tool fails as a call to an unknown tool.

A call to an unknown tool returns JSON-RPC error -32602. The result of tools/call carries the tool’s result text. isError is true only when that text starts with Error:, so some failures, such as Access denied, arrive with isError: false.

Use the mcp debug tag to trace the endpoint: level 5 logs tool calls, level 6 logs every request method.

nxai Command-Line Reference

nxai [options] [message]

nxai is nxshell started under another name and accepts the same options, except -c.

Connection options:

Option Description

-s, --server HOST

Server hostname or URL (e.g., netxms.local or https://netxms.local:8443). Include a non-default port in the URL.

-u, --user USER

Username for authentication.

-p, --password PASS

Password. Prefer using the NETXMS_PASSWORD environment variable.

--no-verify-ssl

Disable SSL certificate verification.

--no-save-session

Do not save the session token for reuse.

--clear-session

Clear saved session token and exit.

Context options (mutually exclusive):

Option Description

-n, --node NAME

Bind the chat session to an object by name.

-o, --object ID

Bind the chat session to an object by ID.

-i, --incident ID

Bind the chat session to an incident.

Display options:

Option Description

--plain

Force plain text output (no colors or formatting).

General options:

Option Description

-h, --help

Show usage information and exit.

-V, --version

Show version information and exit.

Environment variables:

Variable Description

NETXMS_SERVER

Default server hostname.

NETXMS_USER

Default username.

NETXMS_PASSWORD

Password (avoids passing on command line).

Session tokens are saved to sessions.json in the nxshell configuration directory for automatic reconnection: $XDG_CONFIG_HOME/nxshell if XDG_CONFIG_HOME is set, otherwise ~/.config/nxshell (%APPDATA%\nxshell on Windows). Saved sessions expire after 4 hours. Command history is stored in the history file in the same directory. Use --clear-session to remove saved tokens.

Debug Tags

The following debug tags can be used for troubleshooting the AI subsystem:

Tag Description

ai.assistant

General AI assistant operations (chat, tool calls, incident analysis).

ai.chat

Low-level message assembly traces (debug level 8), for both interactive and background chats.

ai.provider

LLM provider base class (HTTP requests, response parsing).

ai.prov.openai

OpenAI-compatible provider operations.

ai.prov.anthropic

Anthropic provider operations.

ai.prov.ollama

Ollama provider operations.

ai.prov.mistral

Mistral provider operations.

ai.memory

AI memory store (environment, per-user, and per-object entries).

ai.operator

AI operator management and execution.

ai.skills

Skill loading and management.

ai.tasks

Background task scheduling and execution.

ai.messages

AI message lifecycle and cleanup.

ai.anomaly

Anomaly detection profile generation.

ai.tools

AI tools (server and agent side).

ai.workers

Workers started by the run-workers tool.

webapi.ai

Web API endpoints for AI chat sessions, memory, and operators.

mcp

MCP endpoint requests and tool calls (see MCP Endpoint).

chatbot

Chat bot sessions, user mapping, and commands (see Chat Bots).

ai.extensions EE

Operations of the aiext module.

ai.extensions.filemgr EE

File management skill operations.

ai.ssh EE

SSH command execution skill operations.

On the agent side, the ai.tools debug tag in nxagentd covers AI tools provided by agent subagents, which the AI assistant discovers and calls with the get-node-ai-tools and execute-agent-tool tools. The aifileops subagent, which provides file search and editing tools, logs under the aifileops tag; it does not start without at least one RootFolder entry in its [aifileops] configuration section (same path[;ro][;nofollow] format as the filemgr subagent), and its file-modifying tools are available only to master servers. The file management skill of the aiext module does not use aifileops: its requests are served by the agent’s filemgr subagent.

Enable debug output by adding the DebugTags parameter to the global section of netxmsd.conf (before any named section):

DebugTags = ai.*:6