Installing the host agent on Mac OS

The Instana agent is a regular Java process at its core. The packages for all our supported operating systems only differ in a few native libraries shipped with it.


A Java Development Kit (JDK) needs to be available for the agent. You can see the list of supported JDKs as follows. There are two options:

  1. The easiest is to place or link that JDK into <instana-agent-install-dir>/jvm (so that <instana-agent-install-dir>/jvm/bin/java exists).

  2. The customizable way is to export an environment variable called JAVA_HOME to point to that JDK (this environment variable can be also set via instana-agent-install-dir>/bin/setenv).

At the moment, the following JVMs are supported for running the agent:

It is important that the JVM is executable for any user on the system. You are recommended to use the latest available patch release of the Java distribution of your choice. The agent requires a JDK thats supports TLSv1.3 (available in all current JDK 8 and JDK 11 builds). Note that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. If you use such a package, you might meet errors like "java.lang.RuntimeException: Could not generate DH key pair."

Download the agent

  1. Sign in to Instana, click More > Agents > Instana agent installation -> Mac OS.

  2. For Mac OS (64bit - Intel and Apple silicon), click Download.

    Your agent key and location are pre-populated, so you just have to extract and start the agent.

    macOS download

  3. Extract the agent archive.

Note: You must use a GNU-tar to extract the archive, since it contains paths longer than 100 characters. Failure to do so will prevent the agent to start with a "SEVERE: Could not launch framework" error.

Run the agent

  1. Open Terminal, and change the directory to to the path where you extracted the agent. Typically it's ~/Downloads/instana-agent.

    cd ~/Downloads/instana-agent
  2. Make sure that the JAVA_HOME environment variable is set according to the prerequisites section. Then, run the following command to start the agent in the background:

  3. Check if the agent is up and running by running the following command in the terminal:

  4. On the first start of the Instana agent on Apple silicon-based machines, you might see a warning from macOS about an unsigned library that is named libsigar-universal64-macosx.dylib, which is required to run the agent.

    macOS dylib warning

    To allow the usage of this architecture-specific library, you need to approve it from System Preferences -> Security & Privacy -> General.

    macOS dylib approve

    Then, restart the agent by running the following command in the terminal, and approve the library on the upcoming pop-up window once again:

    bin/stop & bin/start


  • Instana provides a best-effort compatibility with MacOS for development and testing purposes. You must run the Instana agent as regular user account, instead of the root account. In addition, Instana will monitor only the processes that are run by the same user. Running the agent in a Docker container is not supported. Finally, monitoring Docker containers is not possible due to significant differences in internals of Docker Machine, Docker for Mac, and the regular Linux Docker.

  • On Apple silicon-based machines, the architecture-specific library is not yet signed. Follow step 4 in the run instructions in this topic to approve the libsigar-universal64-macosx.dylib library. For more information, see the official Apple documentation.