Quick Start Guide

Get started with KloudMate Agent in minutes. This guide will walk you through installation and basic configuration on your preferred platform.

Prerequisites

Before installing KloudMate Agent, ensure you have:

API Key

Obtain your API key from the KloudMate dashboard

Collector Endpoint

Default: https://otel.kloudmate.com:4318

Platform Access

Appropriate permissions for your deployment platform

Network Access

Outbound HTTPS access to the collector endpoint

Choose Your Platform

Select your deployment platform to get started:

Linux
Docker
Kubernetes

Linux Installation

Install KloudMate Agent on Linux using our automated installation script.

Set Environment Variables

Set your API key and collector endpoint:

export KM_API_KEY="<YOUR_API_KEY>"
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"

Run Installation Script

Download and execute the installation script:

bash -c "$(curl -L https://cdn.kloudmate.com/scripts/install_linux.sh)"

The script will:

Detect your Linux distribution (Debian/Ubuntu or RHEL-based)
Install required dependencies (curl, wget, systemctl, jq)
Download the appropriate package (.deb or .rpm)
Install the package and configure the agent
Start the agent as a systemd service

Verify Installation

Check that the agent service is running:

sudo systemctl status kmagent

You should see output indicating the service is “active (running)”.

Manual Installation

If you prefer manual installation:

Download the package from GitHub Releases
Install using your package manager:

sudo dpkg -i kmagent_*.deb

Configure environment variables in /etc/kmagent/agent-config.yaml
Start the service: sudo systemctl start kmagent

Docker Installation

Run KloudMate Agent as a Docker container for host-level metrics and log collection.

Set Environment Variables

Set your API key and collector endpoint:

export KM_API_KEY="<YOUR_API_KEY>"
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"

Run Installation Script

Execute the Docker installation script:

bash -c "$(curl -L https://cdn.kloudmate.com/scripts/install_docker.sh)"

The agent container will be started with:

Host network mode for accurate metrics
Volume mounts for log collection
Privileged mode for host metrics access

Verify Container

Check that the container is running:

docker ps | grep km-agent

View agent logs:

docker logs km-agent

Manual Docker Run

To run the container manually:

docker run -d --name km-agent \
  --network host \
  --privileged \
  -v /var/log:/var/log:ro \
  -v /var/lib/docker/containers:/var/lib/docker/containers:ro \
  -v /sys:/sys:ro \
  -v /proc:/proc:ro \
  -e KM_API_KEY="<YOUR_API_KEY>" \
  -e KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" \
  ghcr.io/kloudmate/km-agent:latest

Kubernetes Installation

Deploy KloudMate Agent on Kubernetes using Helm.

Install CRD

First, install the required Custom Resource Definition:

kubectl apply -f https://raw.githubusercontent.com/kloudmate/km-agent/refs/heads/develop/deployment/helm/km-kube-agent/crds/crd-otel-instrumentation.yaml

Add Helm Repository

Add the KloudMate Helm repository:

helm repo add kloudmate https://kloudmate.github.io/km-agent
helm repo update

Install Agent

Install the agent using Helm:

helm install kloudmate-release kloudmate/km-kube-agent \
  --namespace km-agent \
  --create-namespace \
  --set API_KEY="<YOUR_API_KEY>" \
  --set COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" \
  --set clusterName="<YOUR_CLUSTER_NAME>"

Verify Deployment

Check that the agent pods are running:

kubectl get pods -n km-agent

You should see both DaemonSet and Deployment pods in Running state.

For GKE private clusters, you may need to configure firewall rules to allow webhook traffic. See the Kubernetes installation guide for details.

Enable Additional Features

To enable APM and log collection:

helm install kloudmate-release kloudmate/km-kube-agent \
  --namespace km-agent \
  --create-namespace \
  --set API_KEY="<YOUR_API_KEY>" \
  --set COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318" \
  --set clusterName="<YOUR_CLUSTER_NAME>" \
  --set featuresEnabled.apm=true \
  --set featuresEnabled.logs=true

Configuration

After installation, the agent uses default configuration suitable for most environments. You can customize the configuration using:

Environment Variables

Key environment variables for all platforms:

Variable	Description	Default
`KM_API_KEY`	Authentication key for the collector	Required
`KM_COLLECTOR_ENDPOINT`	OTLP HTTP endpoint URL	`https://otel.kloudmate.com:4318`
`KM_CONFIG_CHECK_INTERVAL`	Remote config update interval (seconds)	`60`
`KM_UPDATE_ENDPOINT`	Remote configuration API endpoint	`https://api.kloudmate.com/agents/config-check`

See the Environment Variables reference for the complete list.

Default Configuration

The agent ships with sensible defaults:

# /etc/kmagent/config.yaml (Linux)
# /usr/local/etc/kmagent/config.yaml (macOS)
receivers:
  otlp:
    protocols:
      http:
        endpoint: 0.0.0.0:4318
  hostmetrics:
    collection_interval: 60s
    scrapers:
      - cpu
      - memory
      - disk
      - filesystem
      - network

processors:
  batch:
    timeout: 10s
    send_batch_size: 1024
  resourcedetection:
    detectors: [system, env]

exporters:
  otlphttp:
    endpoint: ${env:KM_COLLECTOR_ENDPOINT}
    headers:
      authorization: "Bearer ${env:KM_API_KEY}"

service:
  pipelines:
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [resourcedetection, batch]
      exporters: [otlphttp]

For advanced configuration options, see the Configuration Overview.

Verification

After installation, verify that telemetry data is flowing:

Check Agent Status

Verify the agent is running:

sudo systemctl status kmagent

Verify Data Collection

Check that metrics are being collected. For Linux/Docker:

curl http://localhost:13133/

For Kubernetes:

kubectl port-forward -n km-agent svc/km-agent-daemonset 13133:13133
curl http://localhost:13133/

A healthy response indicates the collector is running.

View in Dashboard

Log into your KloudMate dashboard to verify that metrics are appearing for your host/cluster.

Uninstallation

How to uninstall KloudMate Agent

Linux
Docker
Kubernetes

Run the uninstall script:

bash -c "$(curl -L https://cdn.kloudmate.com/scripts/uninstall_linux.sh)"

Or manually:

sudo systemctl stop kmagent
sudo systemctl disable kmagent
sudo apt remove kmagent  # Debian/Ubuntu
sudo yum remove kmagent  # RHEL/CentOS

Stop and remove the container:

docker stop km-agent
docker rm km-agent

Uninstall using Helm:

helm uninstall kloudmate-release -n km-agent
kubectl delete namespace km-agent

Remove the CRD:

kubectl delete -f https://raw.githubusercontent.com/kloudmate/km-agent/refs/heads/develop/deployment/helm/km-kube-agent/crds/crd-otel-instrumentation.yaml

Next Steps

Now that you have KloudMate Agent running, explore these topics:

Platform-Specific Guides

Detailed installation guides for each platform

Remote Configuration

Learn how to manage agent configuration remotely

Auto-Instrumentation

Enable automatic instrumentation for your applications

OpenTelemetry Components

Explore the available receivers, processors, and exporters

Getting Help

If you encounter issues:

Troubleshooting

Common issues and solutions

GitHub Issues

Report bugs or request features

Documentation

Complete KloudMate documentation

Email Support

Contact the KloudMate team

Getting Started

Installation

Configuration

Features

Architecture

Operations

Prerequisites

API Key

Collector Endpoint

Platform Access

Network Access

Choose Your Platform

Linux Installation

Docker Installation

Kubernetes Installation

Configuration

Environment Variables

Default Configuration

Verification

Uninstallation

Next Steps

Platform-Specific Guides

Remote Configuration

Auto-Instrumentation

OpenTelemetry Components

Getting Help

Troubleshooting

GitHub Issues

Documentation

Email Support

Build docs developers (and LLMs) love

Getting Started

Installation

Configuration

Features

Architecture

Operations

​Prerequisites

API Key

Collector Endpoint

Platform Access

Network Access

​Choose Your Platform

​Linux Installation

​Docker Installation

​Kubernetes Installation

​Configuration

​Environment Variables

​Default Configuration

​Verification

​Uninstallation

​Next Steps

Platform-Specific Guides

Remote Configuration

Auto-Instrumentation

OpenTelemetry Components

​Getting Help

Troubleshooting

GitHub Issues

Documentation

Email Support

Build docs developers (and LLMs) love

Prerequisites

Choose Your Platform

Linux Installation

Docker Installation

Kubernetes Installation

Configuration

Environment Variables

Default Configuration

Verification

Uninstallation

Next Steps

Getting Help