Module deployment

A module is the package that delivers an integration (functions users run). Each Istari Digital Agent can host any number of modules. A DE tool is the separate vendor or open-source application on the host when the module needs it — installing the module does not install that tool. See Terminology.

Use this page whenever you put a module on an agent: unpack it, confirm the agent loaded it, configure it if needed, publish the manifest, and grant access. During Install, each OS agent guide ends with this procedure for Open Text, so you can test the agent before licensed tools.

What you will do

1. Unpack the package into the agent’s istari_modules folder.
2. Confirm the agent loaded it.
3. Add configuration only if that module’s page requires it.
4. Publish the manifest with the CLI and grant users access.

Repeat the unpack steps for each module on each agent that should run it. Publish and grant access once per module version.

Prerequisites

Complete these before you unpack a package:

1. An agent on this host. A module runs only on an agent that is already installed and online. If this is a new machine, or the tool was just deployed on a host with no agent, install the agent first:

   Host	Guide
   Windows	Install the agent on Windows
   Linux	Install the agent on Linux
   macOS	Install the agent on macOS

   See Agents overview if you are still choosing which machine should run the tool.

2. The module package for this OS and version from the Customer Portal. Confirm the host OS is listed in the module’s Prerequisites (example: Cameo → Windows only; Open Text → Windows, Linux, and macOS).

3. The DE tool on that same host, when the module docs say so.

4. The Istari Digital CLI (stari) on this host. Publishing the module uses stari against the module_manifest.json already on the agent. Install and authenticate stari on the same Linux, Windows, or macOS host before you reach the publish step — Get started with the CLI.

Install the package on the agent

Download the package from the portal, unpack it under istari_modules, and the running agent picks it up.

Download

In the Customer Portal, open dist → modules, find the module, open Asset details, then Download the archive for your OS and version.

Find istari_modules

OS	Typical istari_modules location
Windows	%LOCALAPPDATA%\istari_agent\istari_modules (per-machine install: %ProgramFiles%\IstariDigital\istari_agent\istari_modules)
RHEL / Ubuntu	/opt/local/istari_agent/istari_modules (also check ~/.local/share/istari_agent/ for runtime layout on newer agents)
macOS	~/Library/Application Support/istari_agent/istari_modules (the agent support directory — see The files an agent uses)

Create istari_modules if it does not exist. It belongs to the account that runs the agent, so do this as that account — on RHEL and Ubuntu, where the folder sits inside the root-owned install, sudo instead.

On Windows, a per-machine install puts istari_modules under Program Files, so installing or updating a module there is an administrator action: unpack from an elevated prompt, not as the operating account. The installer creates the folder, so you should not need to. The same applies to updating a module the agent already has — the agent's own module auto-update cannot write to Program Files, and when it finds it cannot, it says so in the log and leaves the installed module alone rather than half-replacing it. The running agent picks a newly unpacked module up on its next poll, as the lifecycle table below says; restart it only when you replaced files of a module it had already loaded.

Unpack

The portal package is an archive: .tar.gz on macOS and Linux, .zip on Windows. Unpack it so istari_modules contains a folder with module_manifest.json inside — not the archive itself.

macOS

MODULES="$HOME/Library/Application Support/istari_agent/istari_modules"
mkdir -p "$MODULES"
mv ~/Downloads/<module>_<version>_macos-arm64.tar.gz "$MODULES/"
tar -xzf "$MODULES/<module>_<version>_macos-arm64.tar.gz" -C "$MODULES"
rm "$MODULES/<module>_<version>_macos-arm64.tar.gz"

Substitute the filename from the portal (for example open_text_1.2.0_macos-arm64.tar.gz). Confirm the extracted folder contains module_manifest.json. Where the module ships a binary, make it executable:

chmod +x "$MODULES/<extracted-folder>/<binary>"

Use the binary name from the manifest if you are unsure.

Windows

1. Copy <module>_<version>_win-amd64.zip onto the host.
2. Extract the ZIP into istari_modules.
3. Confirm there is a module_manifest.json inside the unpacked folder.

Use these steps rather than stari module install on a per-machine install. In this release stari module install and stari module update write only to the per-user folder, %LOCALAPPDATA%\istari_agent\istari_modules, so a module they install on a per-machine host lands where the agent does not look, and the command still reports success. stari module list does not show a per-machine agent's modules either. The 2026.09 release notes carry this as a Known Issue.

Linux

sudo mkdir -p /opt/local/istari_agent/istari_modules
sudo tar -xzf /path/to/<module>_<version>_linux-amd64.tar.gz -C /opt/local/istari_agent/istari_modules

Confirm there is a module_manifest.json inside the unpacked folder, then chmod +x the binary named in the manifest.

Example layout after a successful unpack:

istari_modules/
├── dassault_cameo/
│   ├── module_manifest.json
│   └── …
├── textract/   # Open Text
│   ├── module_manifest.json
│   └── …
└── open_spreadsheet/
    ├── module_manifest.json
    └── …

Confirm the agent loaded the module

Watch the agent log — the install guide for Windows, Linux, or macOS gives its path. Each module the agent picks up is listed with its version:

Loading local modules
Adding module @istari:open_text 1.2.0

A new folder under istari_modules is loaded without a restart. If the version in the log is not the one you just unpacked, you replaced an already loaded module and the agent is still running the previous binary — restart it. On Linux hosts where the agent runs as a service: sudo systemctl restart istari-agent.

If the module is missing from the list:

• the module directory must contain a module_manifest.json and, where the module ships a binary, that the binary is executable;
• the manifest's operating_systems array must include the host OS (for example "Ubuntu 24.04" or "macOS 15") — otherwise the agent skips it.

You do not re-register the agent when you add or update modules.

Module lifecycle on the agent

Change	Restart agent?
Add a new module folder under istari_modules/	No — the running agent auto-reloads new folders
Remove a module folder from istari_modules/	No — the running agent drops it
Replace or update files in an already installed module	Yes — the running process keeps the previous module binary in memory until restart
Edit istari_digital_config.yaml (auth or module keys)	Yes

Configure the module

Most modules need no configuration. For Open Text, Open Spreadsheet, Open PDF, and other modules that carry their own tooling, skip to Publish and grant access.

Modules that drive a licensed desktop tool need site-specific values — where the tool is installed, which license server to use, and so on. Dassault Cameo is the common example; Creo, CATIA, and MATLAB are similar.

Copy the key names from the module's own page (its Installation section). A misspelled key is silently ignored and the module fails at job time. See Module documentation.

1. Open istari_digital_config.yaml on the agent host — Editing the configuration file safely.
2. Add the module's keys under istari_digital_agent_module_configurations, nested inside the existing agent: block.
3. Restart the agent. Configuration is read at startup.

Some modules read credentials or endpoints from environment variables instead. A module runs as a child of the agent, so it inherits the agent's process environment — a .env file next to the module binary is not read. Start the agent from a shell where those variables are set, or, when the agent runs as a service, declare them in the unit with Environment= or EnvironmentFile=. See Run the agent as a service.

Legacy per-module module_config.json files still work for some older modules but are deprecated; prefer the centralized YAML block.

Publish and grant access

Until you publish the manifest and grant access, the agent can load the module locally, but users will not see or run its functions in the web app. Do both once per module version.

Publish the manifest

The module release includes a module_manifest.json. Publish that file to the Module registry so the integration is available on the platform.

Use the Istari Digital CLI on the Linux or Windows agent host, against the manifest as deployed on the agent, so what you publish matches what the agent loads. If stari is not installed yet, complete Get started with the CLI first.

stari module lint /path/to/istari_modules/<module>/module_manifest.json
stari client publish /path/to/istari_modules/<module>/module_manifest.json

The registry refuses to overwrite a version that already exists, so a new build needs a new module_version in the manifest before it can be published — see Module version already exists. Until you publish, the platform still offers the previous version's function list.

The manifest you publish must be an "inlined" manifest that contains the function schemas in the manifest file. Contact support@istaridigital.com if you do not have an inlined manifest for a module.

Grant tool access

Organization administrators grant access in the web app: Manage Tool Access for a User.

• Only organization administrators can grant tool access.
• Access granted for a module applies to later versions of that module; you do not re-add users for each new version.
• The person who publishes a module is on its access list. Everyone else must be added.

In the Tool Access dialog, each tool checkbox has three states:

• Checked — access to the tool, including functions added later.
• Partially checked — only the functions you selected; new functions are not included.
• Unchecked — no access to the tool or its functions.

A fully checked tool (all current functions) is not the same as tool-level access unless the tool checkbox itself is fully checked. Uncheck and re-check the tool if you want future functions included automatically.

To prove a first install with Open Text, finish step 6 of the Windows, Linux, or macOS agent guide.

See each integration for Prerequisites (including OS), Installation, and configuration keys:

• Ansys HFSS
• Ansys STK
• Dassault 3DExperience CATIA
• Dassault 3DExperience Enovia
• Dassault Cameo
• Dassault Catia v5
• Matlab
• Matlab Simulink
• Microsoft Office Excel
• Microsoft Powerpoint
• Microsoft Word
• MSC Nastran Simulation
• Nastran Extraction
• Open PDF
• Open Spreadsheet
• Open Text
• PTC Creo