Agent Configuration

The Istari Agent is configured via the file istari_digital_config.yaml. The Agent expects the file to be located at:

%LOCALAPPDATA%\istari_digital\ on Windows
~/.config/istari_digital/ on RHEL/Ubuntu

warning

For Agents older than v8.3.0, the configuration file is named .istari_config. It should be located at:

%LOCALAPPDATA%\istari_agent\ on Windows
/opt/local/istari_agent/ on RHEL/Ubuntu

Creating the File

Automated

On startup, if no previous configuration is found, the Agent will generate the file and quit silently. At a minimum, Users must replace the placeholder values for the Required Configuration Values.

Manual

On Windows:

Create a plain-text file %LOCALAPPDATA%\istari_digital\istari_digital_config.yaml

On RHEL / Ubuntu

Create a plain-text file ~/.config/istari_digital/istari_digital_config.yaml

File Contents

istari_digital_config.yaml should contain the following:

warning

Important: Starting with the September 2025 release, the Agent configuration format and several keys changed. This page shows the new format. If you are upgrading from 2025-08-01 or earlier, review the legacy example and key mapping in the Revision History.

default:
  istari_digital_agent_registry_api_url: "https://fileservice.istari.com"

agent:
  istari_digital_agent_registry_api_token: "some-agent-token-value"

  ## Commented out variables are optional
  # istari_digital_agent_display_name: "my istari agent"
  # istari_digital_agent_log_level: "info"
  # istari_digital_agent_module_configurations: {}
  # istari_digital_agent_process_timeout: 600
  # istari_digital_agent_poll_interval: 5
  # istari_digital_agent_output_path: "/tmp/output/" # OS-dependent; e.g. "D:\\temp\\output\\" on Windows
  # istari_digital_agent_headless_mode: false
  # istari_digital_agent_status_update_retry_limit: 5
  # istari_digital_agent_download_retry_limit: 5
  # istari_digital_agent_upload_retry_limit: 5
  # istari_digital_agent_upload_pool_size: 4
  # istari_digital_agent_private_key_path: "private_key.pem"

  ## The following were introduced in Agent v6.1.0, are in a beta phase, and are not fully supported yet.
  # istari_digital_agent_module_registry_url: "https://some.registry_url.example.com/"
  # istari_digital_agent_module_registry_auth_token: "some-registry-auth-token"
  # istari_digital_agent_module_registry_repo: "some-istari-module-directory"
  # istari_digital_agent_module_registry_modules_to_update: ["@my_org:my_module"]

  ## Used to configure Sentry logging
  # istari_digital_agent_sentry_dsn: "some-sentry-DSN"
  # istari_digital_agent_sentry_enabled: false
  # istari_digital_agent_sentry_environment: "local"

Headless Host Machines

If the agent is installed on a 'headless' host machine the field istari_digital_agent_headless_mode: true must be added in istari_digital_config.yaml. See below.

Required Configuration Values

The istari_digital_agent_registry_api_url and istari_digital_agent_registry_api_token values MUST be set. All other values are optional, as the agent will fall back to reasonable defaults if they are not set.

`istari_digital_agent_registry_api_url`

This value is the URL of the Istari Platform that the Istari Agent will connect to.

Replace "https://fileservice.istari.com" with the address of the Istari API for the Istari Platform installation.

For example, if the Istari Platform is available at https://istari.example.com, the istari_api_url should be https://fileservice-istari.example.com

`istari_digital_agent_registry_api_token`

This value is the token the Istari Agent uses to authenticate itself to the Istari Platform. Replace "some-agent-token-value" with an Istari Agent API token.

Multi-Tenancy

For organizations using multiple tenants, the agent inherits the tenant of the user who created the Agent API token used in the configuration. See Agent Multi-Tenancy for detailed information on how Agent API tokens work with tenant assignment.

Creating a token

See the How-To section for instructions on creating an Istari Agent API token.

Optional Configuration Values

These values are optional, as the agent will fall back to reasonable defaults if they are not set.

In most circumstances these values do not need to be adjusted.

These values can be set by adding them to the YAML blob in the istari_digital_config.yaml file.

For example, to set the istari_digital_agent_poll_interval to 15 seconds, the file contents from above could be modified as follows:

default:
  istari_digital_agent_registry_api_url: "https://fileservice.istari.com"

agent:
  istari_digital_agent_registry_api_token: "some-agent-token-value"
  istari_digital_agent_poll_interval: 15

Agent Metadata

`istari_digital_agent_display_name`

(Optional) This value governs the human-friendly name displayed for the agent in various parts of the Web frontend.

The default value is a random name auto-assigned by the Registry Service.

Agent Behavior

`istari_digital_agent_log_level`

(Optional) This value governs the verbosity of the logs output by the agent. The values are, from most to least verbose, "debug", "info", "warning", "error", "critical".

The default value is "info".

`istari_digital_agent_module_configurations`

You can define module-specific configuration under the istari_digital_agent_module_configurations collection. Each module is keyed by its full name (e.g., @istari:matlab). You may also specify configuration for specific versions if it is supported by the Module.

Configuration Standardization

Starting with istari-agent 9.8.0 and newer module versions (cameo-module 3.0.0, creo-module 3.0.0, catia-module 2.4.0, 3dexperience-module 1.3.0), configuration variables have been standardized. While old configuration variables remain supported for backward compatibility, we strongly encourage using the new standardized variable names shown in the example below.

Please refer to each Module's documentation to confirm compatibility.

info

Entries in the istari_digital_agent_module_configurations collection should be enclosed in double quotes ""
- This helps to reduce errors translating YAML to JSON

Example:

default:
  istari_digital_agent_registry_api_url: "https://fileservice.istari.com"

agent:
  istari_digital_agent_registry_api_token: "some-agent-token-value"
  istari_digital_agent_module_configurations:
    "@istari:dassault_cameo":
      "2021x-refresh2":
        "dassault_cameo_install_dir": "/path/to/cameo/2021x/installation/dir/"
        "dassault_cameo_license_server_hosts": ["27000@localhost"]
        "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt"
      "2022x-refresh2":
        "dassault_cameo_install_dir": "/path/to/cameo/2022x/installation/dir/"
        "dassault_cameo_license_server_hosts": ["27000@localhost"]
        "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt"
      "2024x-refresh2":
        "dassault_cameo_install_dir": "/path/to/cameo/2024x/installation/dir/"
        "dassault_cameo_license_server_hosts": ["27000@localhost"]
        "dassault_cameo_license_name": "CameoEnterpriseArchitectureEnt"
    "@istari:ptc_creo_parametric":
      "ptc_creo_parametric_executable_path": "/path/to/creo/parametric.exe"
      "ptc_creo_parametric_renderer_executable_path": "/path/to/render/tool"
      "ptc_creo_parametric_converter_executable_path": "/path/to/convert/tool"
    "@istari:dassault_catia_v5":
      "dassault_catia_v5_renderer_executable_path": "/path/to/render/tool"
      "dassault_catia_v5_converter_executable_path": "/path/to/convert/tool"
    "@istari:dassault_3dexperience":
      "dassault_3dexperience_install_dir": "/path/to/3dexperience/installation"
      "dassault_3dexperience_product_attr_name": "PLM_ExternalID"

`istari_digital_agent_process_timeout`

(Optional) This value, in seconds, determines how long the Agent should wait for a module to finish executing a function.

The default value is 600.

`istari_digital_agent_poll_interval`

(Optional) This value governs how often, in seconds, the agent queries the Istari platform for jobs.

The default value is 30.

`istari_digital_agent_output_path`

(Optional) This value governs where the agent writes job output data. This value must be an absolute path. The agent must have permission to write to this folder. The folder must have sufficient storage space for the Istari Agent to write job outputs.

The default value is C:\temp\output\ on Windows and /tmp/output/ on RHEL and Ubuntu.

`istari_digital_agent_headless_mode`

(Optional) This value governs whether the agent attempts to create GUI elements. This value must be set to true if the agent is running on a 'headless' host machine.

The default value is false.

`istari_digital_agent_status_update_retry_limit`

(Optional) This value governs how many attempts the agent makes to update a job's status before marking the job as failed.

The default value is 5.

`istari_digital_agent_download_retry_limit`

(Optional) This value governs how many attempts the agent makes to download a job input before marking the job as failed.

The default value is 5.

`istari_digital_agent_upload_retry_limit`

(Optional) This value governs how many attempts the agent makes to upload a job output before marking the job as failed.

The default value is 5.

`istari_digital_agent_upload_pool_size`

(Optional) How many threads to use to simultaneously upload job outputs. This must be a number between 1 and 15.

The default value is 4.

Auth Integrations

`istari_digital_agent_private_key_path`

(Optional) Path to the private key file for auth token decryption. If not set and the default key file is not present decryption is disabled and the agent cannot process jobs that require auth tokens; agents without this key cannot be used with modules that require an authentication flow.

The default value is the path to a file private_key.pem in the same folder as istari_digital_config.yaml.

Over-the-Air (OTA) Updates for Modules

The Agent uses the following values to handle over-the-air updates of modules.

It reaches out to a specific repository (istari_digital_agent_module_registry_repo) located at a registry (istari_digital_agent_module_registry_url) using a token (istari_digital_agent_module_registry_auth_token) to look for updates to specific modules (istari_digital_agent_module_registry_modules_to_update).

Notes:

All four values must be set to use this feature
Module releases must include linux or windows in the name of the file

Module updates can only be triggered via the System Tray on Windows machines.

System Tray

`istari_digital_agent_module_registry_url`

(Optional) API URL for module releases registry. Istari Agent currently only supports Artifactory.

The default is None.

`istari_digital_agent_module_registry_auth_token`

(Optional) PAT or other auth token for the module releases registry, i.e. Artifactory. Istari Agent currently only supports Artifactory.

The default is None.

`istari_digital_agent_module_registry_repo`

(Optional) Name of the repository hosting module releases in the registry.

The default is None.

`istari_digital_agent_module_registry_modules_to_update`

(Optional) List of modules (full qualified module name, i.e. ["@my_org:my_module"]) to check and update.

The default is None.

Sentry Logging

The follow configuration values are used to capture and log to Sentry.

Note: All three values must be set to use the feature.

`istari_digital_agent_sentry_dsn`

(Optional) DSN for sentry integration.

The default is None.

`istari_digital_agent_sentry_enabled`

(Optional) Flag to enable and disable sentry integration.

The default is false

`istari_digital_agent_sentry_environment`

(Optional) The running environment (production).

The default is local.

Configuration History

2025-09 (September release)

Format: moved from single default: block to two sections: default: (platform URL) and agent: (token and agent options).
Key renames (2025-08-01 legacy → September format):
- Core: istari_api_url → istari_digital_agent_registry_api_url; istari_agent_api_token → istari_digital_agent_registry_api_token.
- Agent options: istari_agent_display_name → istari_digital_agent_display_name; istari_agent_log_level → istari_digital_agent_log_level; istari_agent_output_path → istari_digital_agent_output_path; istari_agent_pull_interval → istari_digital_agent_poll_interval; istari_agent_process_timeout → istari_digital_agent_process_timeout; istari_agent_status_update_retry_limit → istari_digital_agent_status_update_retry_limit; istari_agent_download_retry_limit → istari_digital_agent_download_retry_limit; istari_agent_upload_retry_limit → istari_digital_agent_upload_retry_limit; istari_agent_upload_pool_size → istari_digital_agent_upload_pool_size; istari_agent_headless_mode → istari_digital_agent_headless_mode.
- Module configuration: module_configurations → istari_digital_agent_module_configurations.
- OTA updates: registry_url → istari_digital_agent_module_registry_url; registry_auth_token → istari_digital_agent_module_registry_auth_token; registry_modules_repo → istari_digital_agent_module_registry_repo; registry_modules_to_update → istari_digital_agent_module_registry_modules_to_update.
- Sentry: istari_agent_sentry_dsn → istari_digital_agent_sentry_dsn; istari_agent_sentry_enabled → istari_digital_agent_sentry_enabled; istari_agent_sentry_environment → istari_digital_agent_sentry_environment.
Token creation guidance: consolidated to How-To at /users/how-to/create-agent-token.

Legacy (2025-08-01) format example:

default:
  istari_api_url: <API_URL>
  istari_agent_api_token: <AGENT_PAT>

  # Optional
  # istari_agent_display_name: <AGENT_DISPLAY_NAME>
  # istari_agent_log_level: "info"
  # istari_agent_output_path: "/tmp/output/"
  # istari_agent_pull_interval: 5
  # istari_agent_process_timeout: 600
  # istari_agent_status_update_retry_limit: 5
  # istari_agent_download_retry_limit: 5
  # istari_agent_upload_retry_limit: 5
  # istari_agent_upload_pool_size: 4
  # istari_agent_headless_mode: false

  # Over-the-Air (OTA) updates (beta)
  # registry_url: <REGISTRY_URL>
  # registry_auth_token: <REGISTRY_AUTH_TOKEN>
  # registry_modules_repo: "some-istari-module-directory"
  # registry_modules_to_update: ["@my_org:my_module"]

  # Sentry logging
  # istari_agent_sentry_dsn: "<sentry-dsn>"
  # istari_agent_sentry_enabled: false
  # istari_agent_sentry_environment: "local"

  # Module configuration
  # module_configurations:
  #   "@istari:matlab":
  #     "matlab_home": "/path/to/matlab"

Key rename mapping (2025-08-01 → September 2025):

Legacy key	New key
`istari_api_url`	`istari_digital_agent_registry_api_url`
`istari_agent_api_token`	`istari_digital_agent_registry_api_token`
`istari_agent_display_name`	`istari_digital_agent_display_name`
`istari_agent_log_level`	`istari_digital_agent_log_level`
`istari_agent_output_path`	`istari_digital_agent_output_path`
`istari_agent_pull_interval`	`istari_digital_agent_poll_interval`
`istari_agent_process_timeout`	`istari_digital_agent_process_timeout`
`istari_agent_status_update_retry_limit`	`istari_digital_agent_status_update_retry_limit`
`istari_agent_download_retry_limit`	`istari_digital_agent_download_retry_limit`
`istari_agent_upload_retry_limit`	`istari_digital_agent_upload_retry_limit`
`istari_agent_upload_pool_size`	`istari_digital_agent_upload_pool_size`
`istari_agent_headless_mode`	`istari_digital_agent_headless_mode`
`module_configurations`	`istari_digital_agent_module_configurations`
`registry_url`	`istari_digital_agent_module_registry_url`
`registry_auth_token`	`istari_digital_agent_module_registry_auth_token`
`registry_modules_repo`	`istari_digital_agent_module_registry_repo`
`registry_modules_to_update`	`istari_digital_agent_module_registry_modules_to_update`
`istari_agent_sentry_dsn`	`istari_digital_agent_sentry_dsn`
`istari_agent_sentry_enabled`	`istari_digital_agent_sentry_enabled`
`istari_agent_sentry_environment`	`istari_digital_agent_sentry_environment`

Creating the File​

Automated​

Manual​

File Contents​

Headless Host Machines​

Required Configuration Values​

istari_digital_agent_registry_api_url​

istari_digital_agent_registry_api_token​

Creating a token​

Optional Configuration Values​

Agent Metadata​

istari_digital_agent_display_name​

Agent Behavior​

istari_digital_agent_log_level​

istari_digital_agent_module_configurations​

istari_digital_agent_process_timeout​

istari_digital_agent_poll_interval​

istari_digital_agent_output_path​

istari_digital_agent_headless_mode​

istari_digital_agent_status_update_retry_limit​

istari_digital_agent_download_retry_limit​

istari_digital_agent_upload_retry_limit​

istari_digital_agent_upload_pool_size​

Auth Integrations​

istari_digital_agent_private_key_path​

Over-the-Air (OTA) Updates for Modules​

istari_digital_agent_module_registry_url​

istari_digital_agent_module_registry_auth_token​

istari_digital_agent_module_registry_repo​

istari_digital_agent_module_registry_modules_to_update​

Sentry Logging​

istari_digital_agent_sentry_dsn​

istari_digital_agent_sentry_enabled​

istari_digital_agent_sentry_environment​

Configuration History​

Creating the File

Automated

Manual

File Contents

Headless Host Machines

Required Configuration Values

`istari_digital_agent_registry_api_url`

`istari_digital_agent_registry_api_token`

Creating a token

Optional Configuration Values

Agent Metadata

`istari_digital_agent_display_name`

Agent Behavior

`istari_digital_agent_log_level`

`istari_digital_agent_module_configurations`

`istari_digital_agent_process_timeout`

`istari_digital_agent_poll_interval`

`istari_digital_agent_output_path`

`istari_digital_agent_headless_mode`

`istari_digital_agent_status_update_retry_limit`

`istari_digital_agent_download_retry_limit`

`istari_digital_agent_upload_retry_limit`

`istari_digital_agent_upload_pool_size`

Auth Integrations

`istari_digital_agent_private_key_path`

Over-the-Air (OTA) Updates for Modules

`istari_digital_agent_module_registry_url`

`istari_digital_agent_module_registry_auth_token`

`istari_digital_agent_module_registry_repo`

`istari_digital_agent_module_registry_modules_to_update`

Sentry Logging

`istari_digital_agent_sentry_dsn`

`istari_digital_agent_sentry_enabled`

`istari_digital_agent_sentry_environment`

Configuration History