Skip to main content
Version: 2026.09

Install the agent on macOS

This page takes a macOS host from nothing to a proven agent: prepare the machine, install the agent, give it credentials, start it, then test it with Open Text. Hosts running Windows or Linux have their own pages.

Before you start, the control plane must be installed, and you need administrator rights on the host and an administrator account in the Istari Digital Platform. You download the agent package from the Customer Portal and create the agent's key in the web app, so have both open. Plan about an hour.

Where a filename contains X.Y.Z, substitute the agent version you downloaded. Angle brackets mark values you supply.

1. Prepare the host​

The agent is distributed for Apple Silicon (arm64) hosts. No further host preparation is required beyond keeping the machine awake: the agent is meant to run continuously so users get 24/7 service, so configure Energy Saver to minimize sleeping and automatic restarts. The agent stays offline after a restart until someone starts it again.

If outbound traffic on this host must pass through a forward proxy, or the firewall blocks direct access to object storage, set the proxy before you start the agent — see Proxy configuration.

One agent can host any number of modules, and modules add requirements of their own. Check each module's Prerequisites before you commit to a host.

2. Install the agent​

Download istari-agent_X.Y.Z_macos-arm64.pkg from the Istari Customer Portal — choose the agent assets under dist, open Asset details, then Download. See Download Istari software from the Customer Portal.

Copy the package onto the host, then double-click it and follow the prompts. To install from the command line:

sudo installer -pkg /PATH/TO/istari-agent_X.Y.Z_macos-arm64.pkg -target /

The install runs as root, whichever way you start it, so it asks for your password and everything it writes under /Applications/istari_agent/ is owned by root.

Where things land​

The agent installs as a version-suffixed application bundle, /Applications/istari_agent/istari_agent_X.Y.Z.app, with the executable at Contents/MacOS/istari_agent_X.Y.Z. The bundle is owned by root and readable and executable by everyone, so the agent can run under a normal account. Runtime files — logs, agent identity, and installed modules — live in ~/Library/Application Support/istari_agent, and belong to whichever account created them.

Upgrades install the new bundle alongside the old one instead of replacing it, so update whatever launches the agent to point at the new version, then delete the bundles you no longer need.

3. Give the agent its credentials​

The process you install in step 2 is not yet known to the platform. You register it from the web app at the same time as you give it a key to sign in with — there is no separate “create agent” form, and you do not pick a name or ID first.

  1. Open Agents in the web app (organization administrators only). Select Generate Key. In the New Access Key dialog, optionally enter a Key name (a label for you, not an identifier), then select Generate. That one action registers a new agent identity on the platform and issues the key the host will use. The agent does not appear under All Agents until this host starts in step 4.

  2. Select Download credentials while the key is on screen. The browser saves agent-credentials-<key id>.json, which holds the private key and is shown only once — losing it means generating another key.

  3. Copy that file onto the host, into a directory the account that will run the agent owns, and close it to everyone else:

    mkdir -p ~/.istari_digital
    mv ~/Downloads/agent-credentials-<key id>.json ~/.istari_digital/
    chmod 600 ~/.istari_digital/agent-credentials-<key id>.json

  4. Copy your platform's API URL from Settings → Developer Settings → Endpoints in the web app.

  5. Create ~/Library/Application Support/istari_digital/istari_digital_config.yaml as that same account, with the URL and the path to the file you just moved:

    default: {}
    agent:
      istari_digital_agent_digital_api_url: "https://api.example.istari.app"
      istari_digital_agent_identity_service_secret_file: "/Users/<you>/.istari_digital/agent-credentials-<key id>.json"
      istari_digital_agent_identity_service_enabled: true
      # Optional. Name shown under All Agents; omit it and the platform assigns one.
      # istari_digital_agent_display_name: "Mac lab 01"

The configuration stores the path to the credentials file rather than its contents, so the agent reads it on every start and fails if the file moves. Both files belong to the account that will run the agent: it derives that directory from its own home, so an agent started by a different account looks somewhere else, finds nothing, writes a placeholder file, and exits a few seconds later — see Which user owns the configuration.

The clientId inside the credentials file is the agent's Client ID, the identity it presents when it authenticates. Which identifier is which separates it from the Agent ID and the other values you will meet, and Agent keys covers rotating a key later or migrating an agent off a deprecated PAT.

4. Start the agent​

Run the executable inside the application bundle:

# Replace X.Y.Z with the installed version — `ls /Applications/istari_agent/` shows it
export AGENT_VERSION=X.Y.Z
"/Applications/istari_agent/istari_agent_${AGENT_VERSION}.app/Contents/MacOS/istari_agent_${AGENT_VERSION}"

Run it as the account that owns the configuration and credentials from step 3, with no sudo. The bundle is root-owned but executable by everyone, and the files the agent writes then belong to that account rather than to root.

The agent may take up to a minute to start, and prints its log output to the terminal you launched it from.

Starting the agent also puts an application icon in the Dock and a menu in the macOS menu bar, because the agent builds a system tray menu unless you tell it not to. To run without any of that — the right choice on a Mac with no one logged in at the screen, or when the icon is simply unwanted — add istari_digital_agent_headless_mode to the agent section of istari_digital_config.yaml before starting:

agent:
  istari_digital_agent_headless_mode: true

To see which versions are installed, and which one is running:

ls -1 /Applications/istari_agent/istari_agent_*.app
pgrep -lf istari_agent

5. Confirm it registered​

On a successful start the log records the name the platform assigned, for example:

INFO - Got display name 'iconic-morgoth-9091' from server

An organization administrator should see that same name under All Agents in the web app. That is how you know the host reached the platform.

To choose the name instead of a platform-assigned one, set istari_digital_agent_display_name under agent: in istari_digital_config.yaml and restart the agent. The log then reports the name you set.

If it does not, read the log at ~/Library/Application Support/istari_agent/istari_agent.log, alongside the agent's identity and module files. An agent started with sudo writes those files as root, so a later run under your own account cannot update them — sudo chown -R "$(id -un)" ~/Library/Application\ Support/istari_agent hands them back. Common failure modes are in Troubleshooting.

6. Test with an open-source module​

Prove this agent can run a job before you add licensed tools. Open Text needs no commercial license and no module YAML keys, and it runs on Windows, Linux, and macOS.

  1. Install and authenticate stari if it is not already on this host.
  2. Deploy Open Text (portal name textract) following the Module deployment instructions.
  3. In the web app, upload a small .txt (or .csv) file.
  4. Run @istari:extract with tool Open Text. Set Operating system to macOS.
  5. When the job completes, open the artifacts (extracted text and metadata report).

If the job stays pending, the agent OS or installed modules do not match the job — see How agents match jobs. Then add Open PDF and Open Spreadsheet the same way if the team needs everyday documents.

Next steps​

If you get stuck, contact support@istaridigital.com.