Overview

The CostGraph Agent is a daemon that runs on your virtual machines and continuously reports resource and network usage to CostGraph. It collects:

Host metrics — CPU, memory, disk, and network utilization for the machine.
Container metrics and inventory — when a Docker or containerd runtime is present.

These stream to CostGraph, where they power:

VM inventory and cost — every host and its attached disks, with compute and storage cost attributed per VM, plus live utilization and status.
Rightsizing recommendations — resize suggestions from observed CPU and memory usage, including cheaper instance types across cloud providers.
Idle detection — VMs with consistently low CPU, memory, network, and disk activity are flagged to terminate.
Container and process insight — per-container metrics and the top processes driving usage on each host.
Cost anomalies — unusual spend or utilization changes surfaced automatically.

Prerequisites

A Linux host e.g Debian, Ubuntu, RHEL, Amazon Linux, Alpine etc (amd64 or arm64).
An API key from the CostGraph platform.
For network flow tracing, a root-privileged BTF-enabled kernel and a host-mounted cgroup v2 filesystem.

Installation

Script
Docker
Ansible
Cloud-init

Pipe the installer to sh with your API key on the sh side of the pipe:

curl -sSL https://setup.costgraph.ai/install.sh | COSTGRAPH_API_KEY="bl_..." sh

Or download, inspect, then run:

curl -sSL https://setup.costgraph.ai/install.sh -o install.sh
chmod +x install.sh
COSTGRAPH_API_KEY="bl_..." ./install.sh

The installer detects your init system and registers the agent as a systemd or OpenRC service that starts on boot. It supports Debian, Ubuntu, RHEL, Amazon Linux, and Alpine, and installs the latest stable release by default. Your API key is stored in /etc/default/costgraph-agent (systemd) or /etc/conf.d/costgraph-agent (OpenRC).Pin a specific release with COSTGRAPH_AGENT_VERSION — see the changelog for available versions.Manage the service the usual way:

sudo systemctl status costgraph-agent
sudo journalctl -u costgraph-agent -f

The agent is published as a container image at ghcr.io/baselinehq/costgraph-agent.

Docker Run
Docker Compose

docker run -d --name costgraph-agent \
  --restart unless-stopped \
  --pid host \
  --network host \
  -v /proc:/host/proc:ro \
  -v costgraph-agent-state:/var/lib/costgraph-agent \
  -e COSTGRAPH_API_KEY="bl_..." \
  ghcr.io/baselinehq/costgraph-agent:latest

--pid host and -v /proc:/host/proc:ro give the agent visibility into host processes.
--network host lets it reach the CostGraph backend and exposes its metrics on the host at port 9101.
The named volume persists the durable remote-write queue across restarts.
To collect container inventory, also mount the runtime socket, for example -v /var/run/docker.sock:/var/run/docker.sock:ro.

services:
  costgraph-agent:
    image: ghcr.io/baselinehq/costgraph-agent:latest
    container_name: costgraph-agent
    restart: unless-stopped
    pid: host
    network_mode: host
    environment:
      - COSTGRAPH_API_KEY=bl_...
    volumes:
      - /proc:/host/proc:ro
      - costgraph-agent-state:/var/lib/costgraph-agent
      # Optional: container inventory
      # - /var/run/docker.sock:/var/run/docker.sock:ro

volumes:
  costgraph-agent-state:

docker compose up -d
docker compose logs -f costgraph-agent

Roll the agent out across a fleet with the published Ansible collection.

Install the collection

ansible-galaxy collection install \
    https://downloads.costgraph.com/ansible/costgraph-agent-0.1.0.tar.gz

Create a playbook

---
- name: Install CostGraph agent
  hosts: all
  become: true
  roles:
    - role: costgraph.agent.costgraph_agent
      vars:
        costgraph_api_key: "{{ lookup('env', 'COSTGRAPH_API_KEY') }}"

Run it against your inventory

export COSTGRAPH_API_KEY='bl_...'
ansible-playbook -i inventory.ini install-costgraph-agent.yml

The role installs the binary at /usr/local/bin/costgraph-agent, writes the API key to /etc/default/costgraph-agent, and manages the costgraph-agent systemd service.

Run the installer from a VM’s first-boot user_data. Each instance installs the agent and registers itself on boot — so it works for launch templates, instance templates, and autoscaling groups with no manual step.Use a #cloud-config, which works across most cloud images:

#cloud-config
runcmd:
  - curl -sSL https://setup.costgraph.ai/install.sh -o /tmp/costgraph-install.sh
  - COSTGRAPH_API_KEY="bl_..." sh /tmp/costgraph-install.sh

Or a plain script, for fields that take raw user_data:

#!/bin/sh
curl -sSL https://setup.costgraph.ai/install.sh | COSTGRAPH_API_KEY="bl_..." sh

Where you paste it depends on the provider:

AWS
GCP
Azure

Add it under User data on the instance or launch template (EC2 console -> Advanced details -> User data, or aws ec2 run-instances --user-data file://user-data.sh). Instances launched from that template by an Auto Scaling group install the agent automatically.

Set it as the startup-script metadata key:

gcloud compute instances create my-vm \
  --metadata-from-file startup-script=user-data.sh

Add the same key to an instance template to cover a managed instance group.

Pass the #cloud-config as custom_data on the VM or scale set, for example az vm create --custom-data user-data.yaml.

macOS support via Homebrew is coming soon. For now, install on a Linux host using one of the methods above.

Verify

Once it’s running, your host appears in the CostGraph platform.

CostGraph agent host view in the platform

Configuration

The agent is configured entirely through command-line flags and the COSTGRAPH_API_KEY environment variable.

# API key via flag
costgraph-agent --api-key <your-api-key>

# or via environment variable
export COSTGRAPH_API_KEY=<your-api-key>
costgraph-agent

When you install with the script or Ansible, your API key is written to /etc/default/costgraph-agent and loaded by the service automatically.

The agent automatically detects the host filesystems:

cgroupfs — by checking /host/sys/fs/cgroup first, then /sys/fs/cgroup.
procfs — by checking /host/proc first, then /proc.

string

required

API key used to authenticate with CostGraph. Can also be set with the COSTGRAPH_API_KEY environment variable, which takes precedence over the flag.

number

default:"9101"

Port the agent exposes its own Prometheus metrics on, at /metrics.

string

default:"/var/lib/costgraph-agent"

Directory for durable agent state, including the on-disk remote-write queue.

number

default:"128"

Maximum number of remote-write blocks buffered in memory before they spill to the on-disk queue.

number

default:"5368709120"

Maximum size of the on-disk remote-write queue in bytes (5 GiB) before backpressure is applied.

string

default:"info"

Log verbosity. One of debug, info, warn, or error.

boolean

Prints the agent version and exits.

boolean

default:"false"

Container network flows are collected by default. Host-process network flows are collected only when this is enabled.

Changing flags for the managed service

The install script runs costgraph-agent as a systemd (or OpenRC) service with no extra flags. To change a flag for the managed service on a systemd host, add a drop-in:

sudo systemctl edit costgraph-agent

[Service]
ExecStart=
ExecStart=/usr/local/bin/costgraph-agent --state-dir /opt/var/lib/costgraph-agent

sudo systemctl restart costgraph-agent

The first empty ExecStart= clears the original command so your override fully replaces it.

Get Started

CostGraph Operator

CostGraph Agent

MCP

Integrations

Prerequisites

Installation

Verify

Configuration

Changing flags for the managed service

​Prerequisites

​Installation

​Verify

​Configuration

​Changing flags for the managed service

Prerequisites

Installation

Verify

Configuration

Changing flags for the managed service