Installation Options

The Install guide covers the common case: everything on one box, managed under the OPSIQ profile. This page is a reference for the rest of the installer's options — split installs, development setups, custom ports, and side-by-side instances. Each table is a summary; the notes beneath explain when you would reach for an option.

Command overview

Run the installer from the folder you unzipped it into — see Get the installer. How you refer to the program differs by terminal:

macOS / Linux

./opsiq-install <command> [options]

Windows (PowerShell or Command Prompt)

.\opsiq-install.exe <command> [options]

Windows (Git Bash)

./opsiq-install.exe <command> [options]

The examples on this page use the macOS/Linux form — on Windows, substitute the form for your terminal from the tabs above (.\opsiq-install.exe in PowerShell or Command Prompt, ./opsiq-install.exe in Git Bash).

Command	What it does
install	Install OpsIQ (the default if no command is given).
uninstall	Stop the services and remove the install directory.
status	Show installed versions and the PM2 process list.
help	Show usage.

How options are resolved

Each setting can come from several places. When more than one is given, the installer uses this order of precedence:

1. A command-line flag
2. A value in an --answers file
3. An OPSIQ_* environment variable
4. An interactive prompt

Secrets should always be provided as environment variables, never as flags:

Secret	Environment variable
License key	OPSIQ_LICENSE_KEY
Anthropic API key	OPSIQ_AI_API_KEY
SSH password	OPSIQ_SSH_PASSWORD
Terms acceptance	OPSIQ_ACCEPT_LICENSE

Most other value-taking flags also have an OPSIQ_* environment variable, listed in the Env variable column of the tables below. On/off switches (such as --skip-license or --provision-profile) are flags or answers-file values only.

Connection & host keys

Flag	Env variable	Purpose	Default
--host	OPSIQ_HOST	Hostname or IP of the target.	(required)
--ssh-user	OPSIQ_SSH_USER	SSH login user.	(required)
--ssh-key	OPSIQ_SSH_KEY	Path to a private key for SSH.	your ~/.ssh identity
--ssh-password	OPSIQ_SSH_PASSWORD	SSH password (prefer the environment variable).	prompted
--known-hosts	OPSIQ_KNOWN_HOSTS	Known-hosts file used to verify the target.	~/.ssh/known_hosts
--host-fingerprint	OPSIQ_HOST_FINGERPRINT	Expected SHA256: fingerprint for a first-time connection.	none
--accept-new-host-key	—	Trust an unknown host key without prompting.	false

Signing in. The installer authenticates like the ssh command. If you already have a working SSH key — one at a default ~/.ssh name, or loaded in your SSH agent — it is used automatically and you need none of these flags. Reach for them only in these cases:

• --ssh-key — when your private key is not at one of the default names (~/.ssh/id_ed25519, id_rsa, id_ecdsa). Point this at the key file. If your key is already in a default location or your agent, you do not need this.
• --ssh-password / OPSIQ_SSH_PASSWORD — when you sign in with a password instead of a key. Prefer the environment variable so the password does not appear in your shell history. If you supply neither a key nor a password, the installer prompts for the password on a terminal.

Verifying the host. The first time the installer connects to a given IBM i, it must decide whether to trust that host's key — exactly like the first ssh to a new server. These flags control that decision:

• --known-hosts — the file the installer reads trusted host keys from and records new ones into. It defaults to your normal ~/.ssh/known_hosts, so most people never set it. Point it elsewhere only if you keep a separate trust store for automation.
• --host-fingerprint — the safest way to trust a host you have never connected to. Obtain the box's SHA256: fingerprint from its administrator and pass it here; the installer connects only if the presented key matches, then records it. A mismatch stops the install.
• --accept-new-host-key — trust an unknown host automatically, without a prompt or a fingerprint check. Use this for unattended automation where you accept the small first-connect risk.

If a host's key has changed since a previous connection, the installer always stops — no flag overrides this, because a changed key can indicate a security problem. If the change is expected (for example, the box was rebuilt), clear the old entry with ssh-keygen -R <host> and reconnect.

What to install (roles)

Flag	Purpose	Default
--role all	Tools, AI server, and web UI on one box (loopback). The common case.	all
--role tools	Only the tools server (the IBM i data service).
--role app	Only the AI server and web UI (pointed at a separate tools host).

The environment variable is OPSIQ_ROLE.

Most installs use all. Split the roles when the AI server and web UI should run on a different machine from the IBM i tools server — for example, to keep the AI server off the IBM i. A split install is a --role tools run on the IBM i, followed by a --role app run on the other machine that points back at it with --tools-host (and --tools-ca, below).

The tools server answers only an AI server that presents its caller key. The --role tools run keeps the key it creates on the IBM i and saves a copy on the machine you ran the installer from; the --role app run from the same machine picks that copy up and writes it into the AI server's configuration. So for a split install:

1. Run --role tools against the IBM i.
2. Straight afterwards, run --role app against the other machine, from the same workstation.

Run the two back to back, for an upgrade as well as a first install. Until the --role app run has written the key, the AI server on the other machine may be unable to reach the tools server, and sign-in fails.

If you run the two from different workstations, copy the tools server's key file, <install-root>/apps/ibm-opsiq-tools/tools-api.key on the IBM i, to the second workstation over a secure channel and pass it with --tools-api-key-file (below). Treat that copy as a secret and delete it afterwards.

Installing the app role on Linux or macOS

The tools server needs IBM i, but the --role app half of a split install can go on a Linux or macOS machine. The installer detects the target's operating system when it connects, and on a non-IBM i target it requires:

• --role app — tools and all are refused, because both include the tools server;
• a direct install — set --service-user to the same value as --ssh-user (the managed OPSIQ profile exists only on IBM i);
• an --install-root outside /QOpenSys — for example /opt/opsiq/<instance>.

Point it at the IBM i tools server with --tools-host and --tools-ca as for any split install.

Service identity (managed vs. direct)

Flag	Env variable	Purpose	Default
--service-user	OPSIQ_SERVICE_USER	IBM i profile the services run under.	OPSIQ
--service-jobd	OPSIQ_SERVICE_JOBD	Job description used to submit the services (managed installs).	QGPL/OPSIQJOBD
--provision-profile	—	Create the service profile and job description if they do not exist.	false

• Managed (the default): --service-user differs from --ssh-user, so the services run under a dedicated profile. This requires a security-officer-class SSH user: it needs *ALLOBJ (to hand the install directory to the profile), plus *USE authority to the profile and *JOBCTL (to submit the services as it). Add --provision-profile to have the installer create the OPSIQ profile for you — that step needs security-administration authority (*SECADM). The installer checks all of this before it changes anything. Only the installing user needs *ALLOBJ; the service profile does not, and --provision-profile creates it with no special authorities. Managed is the recommended choice for production.
• Direct: set --service-user to the same value as --ssh-user. The services run under your login, and no special authority is required. This is the right choice for a development box or a quick evaluation.

uninstall and status do not need --service-user. They read the identity the instance runs under off the target — its install manifest, or the install root's owner for an instance installed before that was recorded. Re-installing over an existing instance keeps the identity its manifest records, so an upgrade never converts a direct install into a managed one.

Setting --service-user (or OPSIQ_SERVICE_USER, or serviceUser in an answers file) overrides what they find, so leave it out of an answers file you reuse for teardown. A profile read off the target is never deleted by --delete-profile unless you name it with --service-user.

Ports & networking

Flag	Env variable	Purpose	Default
--server-port	OPSIQ_SERVER_PORT	AI server port.	3939
--tools-port	OPSIQ_TOOLS_PORT	Tools server port.	8445
--web-port	OPSIQ_WEB_PORT	Web UI port.	3000
--tools-host	OPSIQ_TOOLS_HOST	Host the AI server dials for tools (split installs).	127.0.0.1
--tools-ca	OPSIQ_TOOLS_CA	Path to the tools server's public certificate (split).	discovered
--tools-api-key-file	OPSIQ_TOOLS_API_KEY_FILE	Path to a copy of the tools server's key file (split).	discovered
--tls-cert	OPSIQ_TLS_CERT	Your CA-signed certificate for the web UI (full chain).	generated self-signed
--tls-key	OPSIQ_TLS_KEY	That certificate's unencrypted private key.	generated self-signed
--ai-endpoint	OPSIQ_AI_ENDPOINT	Anthropic (or gateway) URL the AI server calls.	https://api.anthropic.com
--recover-ports	—	On a re-install, end a leftover job still holding a port.	true (on)

On a fresh install, if a chosen port is already in use, the installer moves that service to the next free port and reports the change, so you rarely need to set ports by hand. If it finds no free port near the default, it stops with no free port for the <component> component near <port> — pass an explicit port for that component. An upgrade keeps the instance's existing ports instead, unless you pass a new value (the installer warns) — see Upgrading OpsIQ.

When you re-install over an existing instance, the installer stops its services first. If a job left behind by an earlier, crashed run still holds one of the instance's ports after that stop, the installer ends that job (ENDJOB) so the new services can start. It only ends a job that runs under the instance's own service profile. Pass --recover-ports=false to leave such a job alone; the install then fails when that service cannot start on its port.

Set --tools-host and --tools-ca only for a split install, where the AI server must reach the tools server on another machine over verified TLS. Set --tools-api-key-file (or OPSIQ_TOOLS_API_KEY_FILE) only for a split --role app run from a different workstation than the --role tools run, or to give the AI server a new key. Without it, an upgrade keeps the key the AI server already holds from its previous install, and otherwise the installer uses the copy saved by the earlier --role tools run. So if you reinstall the tools server and it creates a new key, pass that saved copy, ~/.opsiq/secrets/<instance>@<tools-host>.tools-api.key, with --tools-api-key-file on the --role app run. <tools-host> is the --host of the --role tools run, in lowercase, and the --role app run finds the copy by its --tools-host, so give both runs the same host name. A file that is missing or does not hold a valid key stops the install before anything changes. A --role all install never needs it: the tools server is on the same box, so the installer reads the key there, even when --tools-host names the box's network address. Set --ai-endpoint only when AI traffic goes through a corporate gateway rather than Anthropic directly.

Your own certificate for the web UI

By default every component gets a self-signed certificate, so browsers warn. Pass --tls-cert and --tls-key (both, or neither) to install your own CA-signed certificate for the browser-facing web UI:

opsiq-install install --host your-ibm-i.example.com --ssh-user youruser \
  --tls-cert ./fullchain.pem --tls-key ./privkey.pem

--tls-cert takes the full chain — the leaf first, then any intermediates — and the key must be unencrypted. Both paths are on the machine you run the installer from. The pair is checked before anything on the target changes, and the install then verifies the web UI is really serving it.

opsiq-server and the tools server keep their generated certificates: they talk to each other over 127.0.0.1, which a CA-signed certificate cannot cover.

To replace the certificate on a system that is already installed, to renew one, or to go back to the generated certificate, see Replacing the TLS Certificate.

Licensing

Flag	Env variable	Purpose	Default
--license	OPSIQ_LICENSE_KEY	OpsIQ license key (prefer the environment variable).	prompted
--license-library	OPSIQ_LICENSE_LIBRARY	IBM i library holding the license data area.	OIQ1, or per-instance
--skip-license	—	Skip the license step (the box already has a valid key).	false

Which library is the default. The default instance (opsiq) uses OIQ1, and so does any install with --skip-license. Any other instance gets its own library, named after the instance: the name is uppercased, characters other than letters and digits are dropped, and it is cut to 10 characters — with an L added in front if it would not start with a letter. For example, instance test-2 uses library TEST2. An upgrade keeps the library the instance was installed with, unless you pass a new value (the installer warns) — see Upgrading OpsIQ.

Use --skip-license when you are reinstalling or upgrading a box that already has a valid license, so the installer leaves the existing key untouched. With it, the library defaults to OIQ1 (unless you name one), and on an install that includes the tools server the installer checks, before changing anything, that the license data area (PW_407) is actually in that library — if it is missing, the install stops and asks you to supply a key with --license or point --license-library at the licensed library. Set --license-library only if you need the license stored in a library other than the default. See Licensing for how keys are obtained and renewed.

Install location & instances

Flag	Env variable	Purpose	Default
--instance	OPSIQ_INSTANCE	Instance name, for running copies side by side.	opsiq
--install-root	OPSIQ_HOME	Directory OpsIQ is installed into.	/QOpenSys/opsiq/<instance>

An instance name may use letters, digits, and hyphens, up to 11 characters. It is folded to lowercase, so PILOT and pilot name the same instance.

The install root defaults to /QOpenSys/opsiq/<instance>, so for the standard instance (opsiq) it is /QOpenSys/opsiq/opsiq. Instances are grouped under the shared /QOpenSys/opsiq/ parent.

To run OpsIQ side by side — for example, a test copy next to a production copy on one box — give each install a distinct --instance name. The instance name scopes the install directory, the license library, and the service names, so the copies do not collide. Ports are not scoped automatically, so give each instance its own --server-port, --tools-port, and --web-port.

Other flags

Flag	Purpose
--accept-license yes	Accept the Terms & Conditions and acknowledge the AI Disclaimer non-interactively. Required for a hands-off install.
--answers <file>	Load answers from a YAML file instead of prompting.
--payload <file>	Use a specific payload tarball instead of the bundled one.
--dry-run	Print every command the installer would run, but change nothing. It does not connect, so the checks on the target are previewed but not enforced.
--keep-backups <n>	How many pre-upgrade snapshots to keep (OPSIQ_KEEP_BACKUPS). Default 3.
--backup=false	Skip the pre-upgrade snapshot. A failed upgrade then cannot be restored to the previous version; the installer only restarts what is on disk.
--rollback=false	Keep the pre-upgrade snapshot, but do not restore it automatically if the upgrade fails — leave it for you to restore by hand.
--version	Print the installer's version and exit.

See Upgrading OpsIQ for how the snapshot and rollback work, and Preview with a dry run for what a dry run does and does not check.

Uninstalling

The uninstall command and its flags (--install-root, --drop-library, --delete-profile, --yes) are documented on the dedicated Uninstalling page.

Verifying a running install

After a successful install, the installer confirms each service is healthy. Later, you can see what is installed and running from your workstation with status. It prints the installed version of each component and the PM2 process list — whether each service is online — but it does not re-run the health checks:

macOS / Linux

./opsiq-install status --host your-ibm-i.example.com --ssh-user YOURPROFILE

Windows (PowerShell or Command Prompt)

.\opsiq-install.exe status --host your-ibm-i.example.com --ssh-user YOURPROFILE

Windows (Git Bash)

./opsiq-install.exe status --host your-ibm-i.example.com --ssh-user YOURPROFILE

On the IBM i itself, pm2 list shows the running services (opsiq-tools-<instance>, opsiq-server-<instance>, opsiq-web-ui-<instance>, and opsiq-logrotate-<instance>, which rotates this instance's PM2 logs and has no port or health check) — point PM2 at the instance's home first, as described in Checking service status.