Configuration Options

The installer configures OpsIQ for you, and most deployments never need to change anything afterwards. This page documents the settings you can adjust after install, grouped by the service they belong to.

How to change a setting

Adjustable settings for the AI server go in a file of your own, .env.local, inside the install directory:

<install-root>/apps/opsiq-server/.env.local

For the default install that is /QOpenSys/opsiq/opsiq/apps/opsiq-server/.env.local. The installer creates it once, with instructions in it and no settings, and never writes to it again — so what you put there survives every upgrade.

Edit it on the IBM i (in a PASE shell), add one KEY=value per line, then restart the affected service — a change does not take effect until the service is restarted. See Managing the Services for how (the exact command depends on whether OpsIQ runs under a dedicated profile or your own). The AI server logs which settings your file supplied as it starts, so the log confirms the edit was picked up.

Edit .env.local, not .env

The .env beside it is the installer's own file, and every upgrade rewrites it. An edit made there is lost at the next upgrade. Values in .env.local win over .env, so there is never a reason to change .env by hand.

WARNING

Only the settings documented on this page are intended to be changed. A handful of values are owned by the installer, because the web UI, the health check and the upgrade read them too: PORT, TLS_CERT_FILE, TLS_KEY_FILE, NODE_EXTRA_CA_CERTS, NODE_TLS_REJECT_UNAUTHORIZED, OPSIQ_DB_URL, AUTH_TOKEN, JWT_SECRET, SESSION_TOKEN_KEY and TOOLS_API_KEY. The AI server ignores these in .env.local and says so in its startup log. To change one, re-run the installer. The tools server's address is not on this list, but it should also be changed by re-running the installer — see Tools server location.

Not the same as the install-time variables

The OPSIQ_* environment variables in the Install guide are read by the installer from your workstation shell during setup. The runtime settings here live in files on the IBM i. They are different things.

AI server (opsiq-server)

These are set in the AI server's .env.local (above). Restart opsiq-server after changing any of them. A value the AI server cannot accept, such as a CHAT_SUGGESTED_PROMPTS that is not a JSON array, stops it from starting, and its log then reads configuration is invalid, refusing to start followed by the reason.

AI key, model and endpoint

ANTHROPIC_API_KEY — the Anthropic API key that powers the Chat Assistant and investigations. The installer writes the key you gave it (OPSIQ_AI_API_KEY) into .env. To replace it without re-running the installer, for example after the old key was revoked, set it in .env.local and restart the AI server:

ANTHROPIC_API_KEY=your-new-anthropic-api-key

A key in .env.local wins over the one the installer wrote, including after later upgrades, so if you set one here, this is also where you change it next time. To confirm the provider accepts the key, check the AI server's ai-credential health check (see Checking the services' health).

The installer creates .env.local readable only by the profile that owns it. Because the file then holds your API key, keep it that way. If you recreate or copy it, make the service profile (OPSIQ unless you chose another) the owner again before closing it to everyone else — on a managed install a file the AI server cannot read is skipped without an error, and the old key in .env is used instead:

cd <install-root>/apps/opsiq-server
chown <service-profile> .env.local
chmod 600 .env.local

On a direct install you already own the file, so only the chmod is needed. After the restart, the AI server's log should show .env.local overrides .env for: naming ANTHROPIC_API_KEY.

INVESTIGATE_MODEL — the Claude model OpsIQ uses. This single setting controls both the Chat Assistant and investigations. The default is a current Claude Sonnet model, which balances quality and cost. Change it only if you have a specific reason to use a different model:

INVESTIGATE_MODEL=claude-sonnet-4-6

ANTHROPIC_BASE_URL — the address OpsIQ calls for the AI service. It defaults to Anthropic directly. Set it only if your organization routes AI traffic through a gateway or proxy. This is the same value as the installer's --ai-endpoint flag.

Showing executed SQL

EXPOSE_SQL_METADATA — when enabled, the Chat Assistant lets you see the SQL it ran to answer a question (a "view SQL" control on tool results). It is off by default:

EXPOSE_SQL_METADATA=true

Some sites prefer to leave this off so that database query detail is not surfaced in the chat panel. Enable it if your operators find it useful to see the underlying SQL behind an answer.

This option controls what the chat panel shows, not what OpsIQ records. The SQL behind each tool call is always saved with the conversation, so an exported session transcript contains it whether or not this option is enabled. A transcript can only be exported by the user who owns that session.

Tools server location

TOOLS_PROXY_URL — the address of the tools server the AI server queries for system data. The installer sets this automatically (to the local tools server for a standard install, or to the IBM i host for a split install).

The AI server accepts TOOLS_PROXY_URL in .env.local, but do not change it by hand to follow a relocated tools server. Sign-in reaches the tools server through a second setting, AUTH_IBM_OPSIQ_TOOLS_URL, and the AI server trusts the tools server's certificate through NODE_EXTRA_CA_CERTS, which is installer-owned and ignored in .env.local. Changing only TOOLS_PROXY_URL leaves sign-in, or every tool call, pointed at the old server. Instead, re-run the installer for the app role with the new location (--role app with --tools-host, --tools-port and, for a tools server on another host, --tools-ca), which updates all three together. See Installation Options.

TOOLS_API_KEY — the key the AI server presents to the tools server on every request. The tools server refuses any caller without it. The installer owns this value: it must match the tools server's key file (see Tools server below), so it cannot be set in .env.local. If the two ever disagree, sign-in fails; re-run the installer to put them back in step.

Suggested chat prompts

CHAT_SUGGESTED_PROMPTS — the starter prompts the Chat Assistant offers. Give a JSON array of up to six strings, on one line:

CHAT_SUGGESTED_PROMPTS=["What jobs failed overnight?","Summarize system health"]

Leave it unset for the built-in list. A value that is not a JSON array of strings, or that holds more than six, stops the AI server from starting.

Logging

The AI server writes its log to dated files under <install-root>/apps/opsiq-server/logs/ (see Viewing the logs).

Setting	Default	Meaning
LOG_LEVEL	info	The least severe entries written: debug, info, warn or error. An unrecognized value is reported in the log and info is used.
LOG_MAX_FILE_MB	20	Size, in MB, at which the day's log file moves on to the next one.
LOG_MAX_FILES_PER_DAY	5	How many files one day's log may use.
LOG_RETENTION_DAYS	30	How many days of log files are kept before older ones are deleted.

At the defaults, the AI server's log files use at most about 3 GB of disk (30 days × 5 files × 20 MB). Use debug only while investigating a problem, because it makes the log grow much faster.

Web UI (opsiq-web-ui)

The web UI has one setting a customer might change.

Server location

OPSIQ_SERVER_URL — where the web UI sends its requests. The installer sets this automatically to the AI server on the same box. You would only change it to point the web UI at an AI server on a different host or port. Unlike the AI server's settings, this value is not kept in a .env file — it is supplied when the web UI service is launched. The simplest way to change it is to re-run the installer with the new host or ports; contact your Fresche contact if you need to do this by hand.

Tools server (ibm-opsiq-tools)

The tools server's port, TLS certificate, license library and caller key are set at install time. Its own config.yml is the installer's and is replaced on every upgrade. Your settings go in config.local.yml beside it, which the installer creates once, with commented-out examples, and never rewrites:

<install-root>/apps/ibm-opsiq-tools/config.local.yml

The settings you can change there go under a config: heading:

config:
  log_level: debug
  bind_address: "127.0.0.1"

• log_level — the least severe entries the tools server logs: error, warn, info (the default) or debug.
• bind_address — the address the tools server listens on. The installer writes one into config.yml on every run: 127.0.0.1 when everything is on one box, so the tools server is not reachable from the network, and 0.0.0.0 for a split install, where the AI server connects from another machine. A bind_address in config.local.yml wins over it, so set one only if you need a different address; 127.0.0.1 on a split install stops the AI server reaching the tools server.

port and library cannot be changed there. The file also accepts ssl.cert and ssl.key, and applies them as given, without checking them or warning; leave them out, because the tools server's certificate is generated at install and is not meant to be replaced (see Replacing the TLS Certificate). An invalid value is ignored with a warning in the tools log, but a misspelled setting, or one outside the config: heading, is ignored without one, so check the log after an edit to confirm the change took.

Restart opsiq-tools-<instance> after an edit (see Managing the Services). To change the tools server's port, re-run the installer (see Ports); for licensing, see Licensing.

Caller key. The installer generates the key file <install-root>/apps/ibm-opsiq-tools/tools-api.key (readable by the service profile only) and writes the same value into the AI server's TOOLS_API_KEY. An upgrade keeps the existing key. The tools server does not start without a valid key file. Treat the file as a secret, and do not edit or recreate it by hand; re-run the installer instead.

Web UI certificate

The web UI is the exception: install your own CA-signed certificate with --tls-cert / --tls-key, or swap the delivered operator.crt / operator.key by hand and restart the web UI from the ecosystem file. See Replacing the TLS Certificate for the whole procedure — including why a plain pm2 restart does not pick up a certificate change.

Ports

The three ports are interdependent — the AI server must know the tools port, the web UI must know the AI server's port, and the installer's health check probes all three — so they are owned by the installer. PORT in .env.local is ignored, and the AI server reports it as ignored when it starts.

The supported way to change any port is to re-run the installer with --server-port, --tools-port, or --web-port, which updates every service that needs to know — see Installation Options.