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 8 Development Kit (JDK 8) needs to be available for the agent. 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. We recommend using the latest available patch release of the Java distribution of your choice. Be advised that depending on your OS distribution, the packages provided by the OS distributor might not contain strong encryption support due to export control. Using such a package will result in 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), click Download.

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

  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.


We provide a best effort compatibility with MacOS for development and testing purposes. Please note that you must run the agent as regular user account, not as root, and it will only monitor processes run by the same user. Running the agent in a Docker container is not supported. Finally, monitoring of Docker containers is not possible due to significant differences in internals of Docker Machine and Docker for Mac to the regular Linux Docker.