---
sidebar_label: Module deployment
title: Module deployment
---

# Module deployment

A **module** is the package that delivers an **integration** (functions users run). Each [Istari Digital Agent](../../icbs-install/04-Agents/01-Overview.md) 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](../../intro/terminology.md#module).

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](../../icbs-install/04-Agents/02-Install-on-Windows.md) |
   | Linux   | [Install the agent on Linux](../../icbs-install/04-Agents/03-Install-on-Linux.md)     |
   | macOS   | [Install the agent on macOS](../../icbs-install/04-Agents/04-Install-on-macOS.md)     |

   See [Agents overview](../../icbs-install/04-Agents/01-Overview.md) if you are still choosing which machine should run the tool.

2. **The module package** for this OS and version from the [Customer Portal](../../icbs-install/02-customer-portal.md). 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](../../icbs-install/05-CLI/01-get-started.md).

## Install the package on the agent {#how-to-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](../../icbs-install/02-customer-portal.md), 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](../../icbs-install/04-Agents/05-Agent-Configuration.md#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

```bash
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:

```bash
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

```bash
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](../../icbs-install/04-Agents/02-Install-on-Windows.md#5-confirm-it-registered), [Linux](../../icbs-install/04-Agents/03-Install-on-Linux.md#5-confirm-it-registered), or [macOS](../../icbs-install/04-Agents/04-Install-on-macOS.md#5-confirm-it-registered) gives its path. Each module the agent picks up is listed with its version:

```text
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 {#configure-the-module}

**Most modules need no configuration.** For [Open Text](../../integrations/05-Productivity/07-open_text/index.mdx), [Open Spreadsheet](../../integrations/05-Productivity/02-open_spreadsheet/index.mdx), [Open PDF](../../integrations/05-Productivity/05-pdf/index.mdx), and other modules that carry their own tooling, skip to [Publish and grant access](#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](../../integrations/03-Systems%20Engineering/03-dassault_cameo/index.mdx) 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](#module-documentation).

1. Open `istari_digital_config.yaml` on the agent host — [Editing the configuration file safely](../../icbs-install/04-Agents/05-Agent-Configuration.md#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](../../icbs-install/04-Agents/03-Install-on-Linux.md#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 {#publishing-the-module-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](../../icbs-install/05-CLI/01-get-started.md) first.

```sh
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`](../../integrations/07-troubleshooting.md#module-version-100-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](mailto:support@istaridigital.com) if you do not have an inlined manifest for a module.

### Grant tool access {#managing-module-function-access}

Administrators grant access in the web app: [Manage Tool Access for a User](../../users/admin-guide/user-management.md#manage-tool-access-for-a-user).

- 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](../../icbs-install/04-Agents/02-Install-on-Windows.md#6-test-with-an-open-source-module), [Linux](../../icbs-install/04-Agents/03-Install-on-Linux.md#6-test-with-an-open-source-module), or [macOS](../../icbs-install/04-Agents/04-Install-on-macOS.md#6-test-with-an-open-source-module) agent guide.

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

- [Ansys HFSS](../../integrations/04-Solvers/05-ansys_hfss/index.mdx)
- [Ansys STK](../../integrations/04-Solvers/08-ansys_stk/index.mdx)
- [Dassault 3DExperience CATIA](../../integrations/02-CAD/01-dassault_3dexperience/index.mdx)
- [Dassault 3DExperience Enovia](../../integrations/03-Systems%20Engineering/05-dassault_3dexperience_enovia/index.mdx)
- [Dassault Cameo](../../integrations/03-Systems%20Engineering/03-dassault_cameo/index.mdx)
- [Dassault Catia v5](../../integrations/02-CAD/02-dassault_catia_v5/index.mdx)
- [Matlab](../../integrations/04-Solvers/01-matlab/index.mdx)
- [Matlab Simulink](../../integrations/04-Solvers/02-simulink/index.mdx)
- [Microsoft Office Excel](../../integrations/05-Productivity/01-microsoft_office_excel/index.mdx)
- [Microsoft Powerpoint](../../integrations/05-Productivity/04-powerpoint/index.mdx)
- [Microsoft Word](../../integrations/05-Productivity/03-word/index.mdx)
- [MSC Nastran Simulation](../../integrations/04-Solvers/03-msc-nastran/index.mdx)
- [Nastran Extraction](../../integrations/04-Solvers/04-nastran-extraction/index.mdx)
- [Open PDF](../../integrations/05-Productivity/05-pdf/index.mdx)
- [Open Spreadsheet](../../integrations/05-Productivity/02-open_spreadsheet/index.mdx)
- [Open Text](../../integrations/05-Productivity/07-open_text/index.mdx)
- [PTC Creo](../../integrations/02-CAD/03-ptc_creo/index.mdx)