Skip to main content
The KloudMate Agent project provides two command-line tools for deploying and managing OpenTelemetry collectors across different environments.

​
Available CLI Tools

kmagent

General-purpose agent for VMs, bare metal, and Docker environments

kubeagent

Kubernetes-native agent with ConfigMap-based configuration

​
Key Differences

Featurekmagentkubeagent
EnvironmentVMs, bare metal, DockerKubernetes only
ConfigurationFile-based (YAML) + CLI flagsEnvironment variables + ConfigMap
Service ManagementSystem service supportRuns as pod/daemonset
Remote ConfigPolling-based updatesConfigMap watch
Docker ModeOptional specialized modeN/A

​
Common Configuration

Both agents share common configuration options:

​
Authentication

​
KM_API_KEY
string
required
API key for authenticating with KloudMate services. Used to identify your agent and authorize configuration updates.

​
Collector Endpoint

​
KM_COLLECTOR_ENDPOINT
string
default:"https://otel.kloudmate.com:4318"
OpenTelemetry exporter endpoint where telemetry data is sent. Supports HTTP/HTTPS protocols.

​
Configuration Updates

​
KM_CONFIG_CHECK_INTERVAL
integer
default:"60"
Interval in seconds between checks for remote configuration updates. Set to 0 to disable automatic updates.

​
Installation Paths

Default configuration file locations vary by operating system: 
/etc/kmagent/config.yaml
The configuration directory is automatically created if it doesn’t exist, with 0755 permissions on Unix systems.

​
Configuration File Format

Both agents use YAML configuration files. The CLI flags can also be specified in the agent configuration file:
agent-config.yaml
config: /path/to/otel-config.yaml
collector-endpoint: https://otel.kloudmate.com:4318
api-key: your-api-key-here
config-check-interval: 60
update-endpoint: https://api.kloudmate.com/agents/config-check
Never commit API keys to version control. Use environment variables or secure secret management for production deployments.

​
Environment Variables

All CLI flags can be set via environment variables with the KM_ prefix: 
export KM_API_KEY="your-api-key"
export KM_COLLECTOR_ENDPOINT="https://otel.kloudmate.com:4318"
export KM_CONFIG_CHECK_INTERVAL="60"

​
Configuration Priority

Configuration values are loaded in the following priority order (highest to lowest):
1

CLI Flags

Command-line arguments take precedence over all other sources
2

Environment Variables

Environment variables with KM_ prefix override file values
3

Configuration File

YAML file specified via --agent-config or default path
4

Default Values

Built-in defaults are used if no other source provides a value

​
Version Information

Both agents support the --version flag to display version information: 
kmagent --version
kmagent version 0.1.0
The version is also injected into telemetry data via the KM_AGENT_VERSION environment variable for tracking and debugging.

​
Logging

The agents use structured JSON logging with automatic log rotation:
  • Format: JSON with ISO8601 timestamps
  • Rotation: 10MB max file size
  • Retention: 7 days, 1 backup file
  • Compression: Old logs are automatically compressed
  • Output: Both file and console (console shows debug level)

​
Next Steps

kmagent Reference

Complete command reference for the general-purpose agent

kubeagent Reference

Kubernetes-specific agent documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us