Setting up agent repositories for dynamic host agents

Dynamic host agents can update themselves from the Instana agent repository, or from a mirror thereof. This documentation covers how to set up a mirror of the Instana agent repository.


  • This topic applies to only dynamic host agents, instead of static host agents. For more information on the difference between static and dynamic agents, refer to the Host agent types documentation.

  • The Instana-provided repositories can not be browsed interactively. The backing repository will redirect any JavaScript-capable browser to the feature-rich UI, which is not accessible from the public internet. If you need to list the repository contents, you can use command-line tools like curl or wget to access the repository contents. An example command to list all available dynamic agent install packages for AIX on Power is as follows:

      curl https://_:<agent-key> | grep aix-ppc

For more information on how to configure dynamic host agent updates, refer to the Updates of dynamic host agents documentation.

Setting up an agent repository mirror

In situations where it is undesirable or impossible to make the agent communicate with the Instana hosted agent repositories, a local mirror can be created instead. Each deployed agent needs to be configured to use the mirror by following the process that is described in the host agent configuration section.

Generic repository information

The Instana host agent pulls feature definitions and updates from any Maven 2 Wagon compatible repository. When you mirror or proxy the repositories that Instana provides, the following general repository configuration applies. Two separate repositories that the agent accesses are provided to pull updates:

The mirror or proxy configuration depends on the vendor and version of your Maven 2 repository.

As an example, the following section describes how to configure Sonatype Nexus to act as an agent repository mirror. Though it's preferred, you are not required to use Nexus for your installation. Any tools that can either proxy the requests to the public download site, or serve the Maven 2 Wagon (located in the system folder of the static agent installation) is capable of acting as a mirror.

Running Nexus

If you do not have Sonatype Nexus running, probably the easiest way to get started is to use it in a docker container (the WebUI appears on http://localhost:8081/, and the default credentials are admin/admin123):

docker run -d -p 8081:8081 --name nexus sonatype/nexus3

nexus setup

If the corresponding machine that runs the Nexus is only allowed to access the Internet by using an HTTP proxy, you can find the form to enter the credentials when you click HTTP.


Configuring Nexus

To proxy data between the Instana Backend and the Instana Agent, two repositories are required:

  1. agent-release
  2. shared

Agent-release repository

Public png

Shared repository

Shared png

Running Artifactory

If you do not have a running Artifactory OSS, an easy way to get started is to use the vendor-provided Docker container. The UI appears on http://localhost:8082/. The default credentials are admin/password. To run this on your system, use the following command:

docker run --name artifactory -d -p 8081:8081 -p 8082:8082

Then, create two remote repositories that are needed:

Name Format URL Username Password
instana-shared Maven2 _ ${INSTANA_AGENT_KEY}
agent-release Maven2 _ ${INSTANA_AGENT_KEY}

Host agent configuration

Note: The configurations that are shown in this setup are necessary only if you are running a mirror of the Instana agent repository.

There are two mutually exclusive ways to configure an Instana host agent to use a mirror of the Instana agent repository:

  1. configuring the mirror, or
  2. changing the repository location

Configuring the mirror

Note: This setup is mutually exclusive with the one shown in the changing the repository location section.

The configuration for the agent repository and how to authenticate with it, is specified in the file <agentfolder>/etc/mvn-settings.xml.

To use your agent repository mirror, uncomment the prepared section in this file:


If you require authentication for that repository, the following settings can be configured in the same file:


Changing the repository location

Note: This setup is mutually exclusive with the one shown in the configuring the mirror section.

Package-based host agent

When you install the host agent by using the One-Liner or a package-based installer, the location from which the host agent downloads updates and sensors is specified in the file <agentfolder>/etc/org.ops4j.pax.url.mvn.cfg.

To use your agent repository mirror, replace the line that contains org.ops4j.pax.url.mvn.repositories with your specific settings. An example configuration for the mentioned Nexus setup on the host on port 8081 would look as follows:


Docker-based host agent

The Docker images for the host agent support setting by using the INSTANA_MVN_REPOSITORY_URL, and INSTANA_MVN_REPOSITORY_FEATURES_PATH environment variables the location from which the host agent downloads updates and sensors.

The following example is equivalent to the example that is displayed in the Package-based Host Agent section: