Skip to content

Attaching and running the JVM Agent with your application

The Lightrun agent is at the core of the Lightrun platform. It's the component that enables you to add Lightrun actions at runtime, without redeployments or restarts.

Version Support

The instructions below are geared towards Java developers working with JDK 8+. If you're interested in using Lightrun with Scala or Kotlin, please reach out and let us know!


If you haven't yet done so during the onboarding process, download the Lightrun JVM Agent from the Management Portal.

To download the agent:

  1. Log in to the Management Portal.
  2. Copy the download script from the Install the Agent section:

    Get the Lightrun JVM Agent

  3. Open a terminal and change to the directory where your project folder is located.

  4. Enter the copied script, from step 2. The agent downloads.
    The video, below, shows what the agent download procedure looks like:

    JVM Agent download process

To attach the agent to your application:

On completion of the agent download, from your terminal, enter the following command:
java -agentpath:<path-to-agent>\ -jar <your-jar-file> RestofArgumentsHere
Replace the placeholders in the command as follows:

  • <path-to-agent> - The full path to the agent's folder (~/ will not work)
  • <your-jar-file> - The full path to the application to be run with the agent
  • RestofArgumentsHere - Any relevant configuration options.

See the example in this video:

Running your application with the Lightrun Agent


To cause all launched Java processes automatically to be attached to an agent, you can add the JAVA_OPTS environment variable.
From the server terminal, enter the following command (replace the agentpath value with the path to the Lightrun agent, after it has been downloaded):

export JAVA_OPTS=-agentpath:/path/to/agent/


You can customize the agent configuration at any time. To apply the changes, the application must be restarted. For further details, see here.

Last update: January 18, 2022