> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprobe.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Kotlin SDK Setup Guide

> Attach the HyperProbe JVM agent to your Kotlin application without changing application code.

HyperProbe supports Kotlin/JVM applications through the same agent used for [Java](/sdks/java). Attach the agent at startup to capture variables, stack frames, metrics, and logs without adding an initializer or annotations.

***

## Technical prerequisites

* **Runtime:** Kotlin/JVM on Java 17 or later. This guide does not apply to Kotlin/JS or Kotlin/Native.
* **Metadata:** The Git commit SHA used to build your deployed application.
* **Debug information:** Preserve source filenames, line numbers, and local variable metadata in your compiled classes so probes can resolve `.kt` source locations and capture locals.

***

## Installation

Download the agent JAR. Replace `<LATEST_VERSION>` with a version from [Maven Central](https://central.sonatype.com/artifact/co.hyperprobe/hyperprobe-agent/versions):

```bash theme={null}
curl -L -o hyperprobe-agent.jar "https://repo1.maven.org/maven2/co/hyperprobe/hyperprobe-agent/<LATEST_VERSION>/hyperprobe-agent-<LATEST_VERSION>.jar"
```

You do not need a separate Kotlin SDK dependency. Adding the JAR as an application dependency alone does not activate the agent; you must pass `-javaagent` to the application JVM.

***

## Initialization walkthrough

<Steps>
  <Step title="Set environment variables">
    Export these variables before starting your application. Replace the service ID with the UUID from your HyperProbe dashboard:

    ```bash theme={null}
    export GIT_COMMIT=$(git rev-parse HEAD)
    export HYPERPROBE_SERVICE_ID="<service-uuid-from-dashboard>"
    export HYPERPROBE_ENVIRONMENT=production
    export HYPERPROBE_BROKER_URL=https://logger.app.hyperprobe.co
    ```

    Use `git rev-parse HEAD` for local runs. In CI/CD, set `GIT_COMMIT` to the commit used to build the deployed artifact. The agent does not start if it is missing or set to `unknown`.
  </Step>

  <Step title="Attach the agent">
    Choose how you start your application. These examples assume the downloaded JAR is in your project root and the environment variables above are set.

    <Tabs>
      <Tab title="Executable JAR">
        ```bash theme={null}
        java -javaagent:./hyperprobe-agent.jar -jar build/libs/app.jar
        ```

        Replace `build/libs/app.jar` with your executable application JAR.
      </Tab>

      <Tab title="Spring Boot (Gradle)">
        Add the agent to your `bootRun` task:

        ```kotlin build.gradle.kts theme={null}
        tasks.named<org.springframework.boot.gradle.tasks.run.BootRun>("bootRun") {
            jvmArgs("-javaagent:${rootDir}/hyperprobe-agent.jar")
        }
        ```

        ```bash theme={null}
        ./gradlew bootRun
        ```
      </Tab>

      <Tab title="Spring Boot (Maven)">
        ```bash theme={null}
        mvn spring-boot:run \
          -Dspring-boot.run.jvmArguments="-javaagent:$(pwd)/hyperprobe-agent.jar"
        ```
      </Tab>
    </Tabs>

    Keep your existing Kotlin `main` function unchanged. The agent starts before your application.
  </Step>
</Steps>

***

## Docker deployment

Copy the downloaded agent and your built application into the image. Adjust the application JAR path to match your build output:

```dockerfile Dockerfile theme={null}
FROM eclipse-temurin:21-jre
WORKDIR /app

ARG GIT_COMMIT
ENV GIT_COMMIT=${GIT_COMMIT}

COPY hyperprobe-agent.jar /app/hyperprobe-agent.jar
COPY build/libs/app.jar /app/app.jar

ENTRYPOINT ["java", "-javaagent:/app/hyperprobe-agent.jar", "-jar", "/app/app.jar"]
```

Build and run locally with the environment variables from the initialization step:

```bash theme={null}
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -t app:latest .
docker run --rm \
  -e HYPERPROBE_SERVICE_ID \
  -e HYPERPROBE_ENVIRONMENT \
  -e HYPERPROBE_BROKER_URL \
  app:latest
```

***

## Configuration and environment variables

Kotlin uses the same environment variables and defaults as Java. See the [complete environment variable reference](/sdks/java#configuration-and-environment-variables) for performance limits, capture depth, redaction, logging, and trace ID hooks.

To disable the agent at startup, set `HYPERPROBE_DISABLED=YES`.