OpsIQ

Installation ​

This guide walks you through a typical install of OpsIQ: a single IBM i server running everything, with the OpsIQ services managed under a dedicated user profile. For advanced options, such as custom ports, partial installs, a custom license library, etc, see Installation Options.

Before you start ​

The installer runs from your local workstation (Windows, macOS, or Linux). It connects to the IBM i over SSH, handling file uploads and issuing installation commands remotely.

Have these ready:

  • A supported IBM i — OpsIQ requires IBM i 7.4 or later, plus a few open-source components on the box. See Prerequisites on the IBM i.
  • An SSH login to the IBM i — for the default managed install, this login must be a powerful profile (security-officer-class): it needs authority to hand the services off to the OpsIQ profile. See How the installer signs in over SSH.
  • Your OpsIQ license key — a 43-character key from your Fresche contact. See Licensing.
  • An Anthropic API key — this is what powers the AI. See Configuration.

Prerequisites on the IBM i ​

OpsIQ runs on IBM i 7.4 or later. Earlier releases (7.3 and below) are not supported.

The IBM i also needs a few components installed:

  • Node.js 22 (the nodejs22 package), version 22.15 or later
  • PM2 (the process manager that keeps the services running), installed with that Node.js 22's npm, as below — the installer looks for it in /QOpenSys/pkgs/lib/nodejs22/bin
  • openssl

Before modifying your system, the installer checks that Node.js is 22.15 or later and that PM2 and openssl respond, and reports anything missing. It does not check the IBM i release, so confirm you are on 7.4 or later yourself. If you need to install them, run this once on the IBM i in a PASE shell (open one by connecting over SSH, or from a 5250 session with CALL QP2TERM):

bash
PATH=/QOpenSys/pkgs/lib/nodejs22/bin:/QOpenSys/pkgs/bin:$PATH; export PATH
yum install nodejs22 openssl && npm i -g pm2

The first line is needed because the open-source programs (yum, and pm2 once installed) live under /QOpenSys/pkgs, which is not on the default PASE PATH — without it, yum reports not found. It uses the two-step VAR=…; export VAR form because the PASE default shell (bsh) rejects a combined export VAR=…, and does so fatally: it abandons the whole block, not just that line.

Where commands run

Throughout the documentation, commands fall into a few places:

  • Your workstation — the opsiq-install commands and the environment-variable commands below. Run these in your normal terminal (PowerShell, Command Prompt, Terminal, or a shell).
  • A PASE shell on the IBM i — commands such as yum, pm2, and npm. Open a PASE shell over SSH, or with CALL QP2TERM from a 5250 session.
  • An IBM i command line (5250) — CL commands such as SBMJOB (used on the Managing the Services page).

Each command block notes which one it belongs to. Where a command differs by terminal, every version is shown on a labelled tab — pick yours.

How the installer signs in over SSH ​

The installer authenticates to the IBM i the same way the ssh command does:

  • If you already have an SSH key set up for the box — a key in your default ~/.ssh directory, or one loaded into your SSH agent — the installer uses it automatically. There is nothing to supply; leave the password unset.
  • If you do not have a key, the installer signs in with a password. Provide it through the OPSIQ_SSH_PASSWORD environment variable, or let the installer prompt you for it. The prompt is hidden and does not echo as you type.
  • If your key is in a non-standard location (not one of the default ~/.ssh/id_ed25519, id_rsa, or id_ecdsa names), point the installer at it with --ssh-key — see Installation Options.

The security-officer requirement comes from the managed install, not from SSH itself. If you cannot use such a profile, a direct install runs the services under your own login and needs no special authority. See Managed vs. direct install for the trade-off, and Service identity for how to select it.

What gets installed ​

OpsIQ has three parts, and the default install puts all of them on one box:

  • The tools server — the service that manages the tools OpsIQ uses to look at your system.
  • The AI server — the service that talks to the AI model and coordinates investigations.
  • The web UI — the browser interface your operators sign in to.

Those three services do not run under your login. On the default managed install they run under a dedicated OPSIQ user profile, and the installer hands ownership of the install directory to it — so OpsIQ has its own identity on the box, with only the authority it needs. That profile must already exist, or you can have the installer create it by adding --provision-profile (a step that needs security-administration authority). To run the services under your own profile instead, see Managed vs. direct install.

Install steps ​

Four steps, all run from your workstation: get the installer, store your secrets in environment variables, preview the install with a dry run, then run it for real.

Step 1 — Get the installer ​

The installer is a single self-contained program — there is nothing to install before it, and no Node.js needed on your workstation. Your Fresche contact provides the download for your platform:

Your workstationDownloadThe program inside
Windowsopsiq-installer-windows-x64.zipopsiq-install.exe
macOSopsiq-installer-macos-arm64.zipopsiq-install
Linuxopsiq-installer-linux-x64.zipopsiq-install

The macOS build is for Apple Silicon. There is no Intel-Mac build — on an Intel Mac, run the installer from a Linux or Windows workstation, or ask your Fresche contact.

Unzip it, then open your terminal in that folder — every opsiq-install command on this page runs from there.

macOS — clear the download flag before you run it the first time

macOS quarantines anything downloaded in a browser and will silently move this tool to the Trash the first time you run it. In the unzipped folder, clear the flag once, before the first run below:

bash
xattr -c opsiq-install        # or, for the whole folder: xattr -dr com.apple.quarantine .

This is expected for an internal tool and is safe. (The older right-click → Open trick is unreliable on recent macOS — use the command above.)

On Windows, if SmartScreen warns you, choose More info → Run anyway.

Check that the program runs by asking it for its help text — the simplest command there is, and the one that proves your prefix is right:

bash
./opsiq-install --help
powershell
.\opsiq-install.exe --help
bash
./opsiq-install.exe --help

The ./ or .\ prefix is required — and depends on your terminal

The installer is not added to your system PATH, so you have to say whichopsiq-install you mean: the prefix means "the one in this folder". Neither PowerShell nor a Unix shell (macOS, Linux, Git Bash, WSL) searches the current folder on its own, so without the prefix they report the program as not found even though it is sitting right there. Command Prompt is the exception — it does search the current folder — so there a bare name works, and not found means you are in the wrong folder.

Which prefix works depends on the terminal, not just the OS — the two Windows forms are not interchangeable:

  • Git Bash / MSYS2 treats \ as an escape character, so .\opsiq-install.exe fails there with a confusing .opsiq-install.exe: command not found (the backslash is silently swallowed). Use ./opsiq-install.exe.
  • Command Prompt is the mirror image: it rejects a leading ./ with '.' is not recognized. Use .\opsiq-install.exe.
  • PowerShell accepts either; the tabs use .\opsiq-install.exe.
  • WSL is Linux — install the Linux download there and use ./opsiq-install. Do not use the Windows .exe in WSL.

Every command block on this page has a tab for each of these (in WSL, use the macOS/Linux tab), so pick your tab and copy it as-is.

Step 2 — Store your secrets in environment variables ​

The installer can be run interactively and will prompt you for necessary parameters before proceeding; however, to ensure sensitive values are kept from the command line and shell history, it is recommended that you store the secrets in environment variables by setting them in your workstation shell first — the same machine you run the installer from, not the IBM i:

Set them the way your workstation shell expects — pick the tab for your terminal:

bash
export OPSIQ_LICENSE_KEY='your-43-character-license-key'
export OPSIQ_AI_API_KEY='your-anthropic-api-key'
export OPSIQ_SSH_PASSWORD='your-ibm-i-password'    # skip if you use an SSH key
powershell
$env:OPSIQ_LICENSE_KEY = 'your-43-character-license-key'
$env:OPSIQ_AI_API_KEY = 'your-anthropic-api-key'
$env:OPSIQ_SSH_PASSWORD = 'your-ibm-i-password'    # skip if you use an SSH key
bat
REM The quotes wrap the whole NAME=VALUE pair — cmd strips them, so they do not
REM land in the value. Omit them and a password containing & will break the line.
set "OPSIQ_LICENSE_KEY=your-43-character-license-key"
set "OPSIQ_AI_API_KEY=your-anthropic-api-key"
set "OPSIQ_SSH_PASSWORD=your-ibm-i-password"

Use single quotes — a password with $ or a backtick gets mangled

The quoting above is deliberate. In double quotes, macOS/Linux/Git Bash and PowerShell both expand $… and backticks inside the value, so a password like pa$sword is silently stored as pa and the install then fails with a wrong password or a rejected key. Single quotes take the value literally in all three. In Command Prompt, wrap the whole NAME=VALUE pair as shown — quoting only the value (set VAR="value") makes the quotes part of the value.

The installer reads these from your workstation shell during setup. They are not set on the IBM i, and they are not OpsIQ's runtime configuration (which the installer writes to a file on the box — see Configuration Options). They last only for the current shell session. To clear them sooner, close the terminal — or clear them explicitly, using the form your terminal expects:

bash
unset OPSIQ_LICENSE_KEY OPSIQ_AI_API_KEY OPSIQ_SSH_PASSWORD
powershell
# -ErrorAction lets this succeed quietly if you never set the SSH password.
Remove-Item Env:OPSIQ_LICENSE_KEY, Env:OPSIQ_AI_API_KEY, Env:OPSIQ_SSH_PASSWORD -ErrorAction SilentlyContinue
bat
REM An empty value is how cmd clears a variable.
set OPSIQ_LICENSE_KEY=
set OPSIQ_AI_API_KEY=
set OPSIQ_SSH_PASSWORD=

Step 3 — Preview with a dry run ​

Start with --dry-run. It prints every command the installer would run and changes nothing. It does not connect to the IBM i, so none of the checks on the target (prerequisites, authority, free ports, health) run — a clean dry run does not guarantee the real install will pass.

Run this from the folder you unzipped the installer into. Two things differ by terminal — how you refer to the program (./opsiq-install vs .\opsiq-install.exe) and the character that continues a command across lines (\ on macOS/Linux, a backtick on PowerShell, ^ on Command Prompt) — so pick your tab and copy the whole block:

bash
./opsiq-install install \
  --host your-ibm-i.example.com \
  --ssh-user YOURPROFILE \
  --accept-license yes \
  --dry-run
powershell
.\opsiq-install.exe install `
  --host your-ibm-i.example.com `
  --ssh-user YOURPROFILE `
  --accept-license yes `
  --dry-run
bat
.\opsiq-install.exe install ^
  --host your-ibm-i.example.com ^
  --ssh-user YOURPROFILE ^
  --accept-license yes ^
  --dry-run
bash
./opsiq-install.exe install \
  --host your-ibm-i.example.com \
  --ssh-user YOURPROFILE \
  --accept-license yes \
  --dry-run

--accept-license yes confirms that you accept the Fresche Terms & Conditions and acknowledge the AI Disclaimer. An install needs that acceptance: without the flag, an interactive run asks you to type yes, and an unattended (non-interactive) run stops. A dry run installs nothing, so it does not ask.

OpsIQ uses AI to help diagnose IBM i system events, so some system data is sent to Anthropic (Claude), a third-party AI provider, for analysis. Review both documents before you install:

WARNING

Pass --accept-license yes only once you have reviewed both documents. Without the flag, the installer shows the full notice and waits for you to type yes, so you can read it there instead.

Step 4 — Run the real install ​

When the dry run looks right, run the same command without --dry-run:

bash
./opsiq-install install \
  --host your-ibm-i.example.com \
  --ssh-user YOURPROFILE \
  --accept-license yes
powershell
.\opsiq-install.exe install `
  --host your-ibm-i.example.com `
  --ssh-user YOURPROFILE `
  --accept-license yes
bat
.\opsiq-install.exe install ^
  --host your-ibm-i.example.com ^
  --ssh-user YOURPROFILE ^
  --accept-license yes
bash
./opsiq-install.exe install \
  --host your-ibm-i.example.com \
  --ssh-user YOURPROFILE \
  --accept-license yes

The installer will check the box, upload OpsIQ, install the license, start the services, and run health checks. It prints its progress as it goes.

What to expect during the install ​

If you supply everything up front (as above), the run is hands-off. If you leave something out, the installer prompts for it interactively. On a normal run you may see, in this order:

  1. The Terms & AI Disclaimer notice. Unless you passed --accept-license yes, the installer shows the notice — that OpsIQ sends some system data to Anthropic (Claude) for analysis, plus links to the Terms & Conditions and the AI Disclaimer — then asks Do you accept the Terms & Conditions and AI Disclaimer? (yes/no):. Anything other than yes stops the install, and nothing is created on the target.
  2. A few setup questions, only for values you did not provide — which components to install (press Enter to accept all), the install directory (press Enter to accept the default), and, if you gave no license key, whether to install a new key or reuse the one already on the box. Answering reuse is the same as passing --skip-license.
  3. A "Before you begin" list of what you will need to have ready for the components you chose — SSH access, and the Anthropic API key and license key where they apply.
  4. The remaining questions, again only for values you did not provide: the IBM i host, the SSH user, then the Anthropic API key and the OpsIQ license key. The keys do not echo as you type; the installer then prints a masked copy (the first and last few characters) so you can check it went in right.
  5. The SSH password, if you did not supply one or an SSH key. The prompt is hidden; press Enter without typing to sign in with your SSH key or agent instead.
  6. A host-key confirmation the first time you connect to a given IBM i. As the ssh command does, the installer shows the host's fingerprint and asks you to confirm before trusting it. For unattended runs, see the host-key options in Installation Options.

Verify the install worked ​

When everything passes, the installer prints:

text
✓ Install complete — all checks passed.

…followed by the web UI address, which looks like:

text
https://your-ibm-i.example.com:3000/login

Open that address in a browser. If you reach the OpsIQ login page, the install succeeded. Continue to the First login walkthrough.

If the installer stops with ✗ Install failed at: <step>, it will name the step that failed and show the last lines of that service's log. See Installation & setup issues.

Upgrading OpsIQ ​

To move an existing instance to a newer build, run the same install command again with the newer installer. The installer recognizes the existing instance and performs an in-place upgrade rather than a fresh install:

  • it keeps the instance's current ports, license library, and service profile, so you do not need to pass them again (if you do pass a different value, the new one wins and the installer prints a warning saying what it changed);
  • it keeps the instance's role — an upgrade with a different --role is refused;
  • it stops the running services and takes a snapshot of the install directory first (kept alongside it as <install-root>.backup.<timestamp>);
  • it installs the new build and restarts the services;
  • if any step of the upgrade fails — including the final health check — it automatically rolls back to the snapshot and restarts the previous version, so a bad upgrade does not leave you with a down system.

Your chat history, license, and sign-in secrets are preserved across an upgrade, so users stay signed in. Your Anthropic API key is not carried over: an upgrade that includes the AI server needs it again, so set OPSIQ_AI_API_KEY as in Step 2 (or answer the prompt). If you set ANTHROPIC_API_KEY in .env.local, though, that key still wins over the one you give the installer, so change it there instead (see AI key, model and endpoint). The installer rewrites the AI server's .env file on every upgrade, but never touches your own settings files — .env.local for the AI server and config.local.yml for the tools server — so put any changes there (see Configuration Options). The installer keeps the most recent snapshots — 3 by default, set with --keep-backups <n> — and prunes older ones. To skip the pre-upgrade snapshot entirely, pass --backup=false; a failed upgrade then cannot be restored to the previous version, and the installer only restarts what is on disk. To keep the snapshot but not auto-restore on a failed upgrade, pass --rollback=false. Snapshots are not removed when you uninstall, so bound them with --keep-backups if disk is tight.

Reuse the license

On an upgrade the existing license is left in place — you can add --skip-license so the installer does not ask for a key. To change ports at the same time, pass explicit --server-port / --tools-port / --web-port. To change which components are installed (the role), uninstall first, then do a fresh install.

Default ports ​

The default install uses these ports on the IBM i. On a fresh install, if any are already in use, the installer automatically picks the next free one and tells you. An upgrade keeps the ports the instance already uses.

ServiceDefault port
Web UI3000
AI server3939
Tools8445

To choose ports yourself, see Installation Options.

Keeping OpsIQ running ​

The services run under PM2. After a full system restart (IPL) they do not come back automatically yet, so someone needs to start them again. See After a system restart for the procedure, and plan for it when you schedule IPLs.