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

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

Docker

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

Docker Run

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.

Docker Compose

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

Ansible

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

1. Install the collection

   ansible-galaxy collection install \
       https://setup.costgraph.ai/ansible/costgraph-agent-0.2.0.tar.gz
   
2. 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') }}"
   
3. 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.

Cloud-init

Run the installer from a VM’s first-boot user_data. Each instance installs the agent and registers itself on boot. That 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

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.

GCP

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.

Azure

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 through Homebrew is coming soon. For now, install on a Linux host using one of the preceding methods.

Verify

After it starts, your host appears in the CostGraph 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 detects the host filesystems:

• cgroupfs: it checks /host/sys/fs/cgroup first, then /sys/fs/cgroup.
• procfs: it checks /host/proc first, then /proc.

--api-key · 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.

--metrics-port · number · default: "9101"

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

--state-dir · string · default: "/var/lib/costgraph-agent"

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

--remote-write-max-in-memory-blocks · number · default: "128"

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

--remote-write-max-pending-bytes · number · default: "5368709120"

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

--log-level · string · default: "info"

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

--version · boolean

Prints the agent version and exits.

--flowtrace-include-host-flows · boolean · default: "false"

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

--flowtrace-per-request-collector · boolean · default: "true"

Collect per-request HTTP metrics: request and response sizes, the host each request was sent to, and any X-CostGraph-* request headers. See Request header attribution.

Machine identity

If the agent cannot detect a machine’s cloud, region, or instance type, set them with environment variables. See Machine identity.

Change 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.

Network flow tracing

Flow tracing records which workloads talk to each other and to outside services, so Context can draw those lines and put a cost on them. It’s on by default on hosts that meet the prerequisites.

For each connection, the agent records:

• the source and destination addresses and ports, and the protocol
• the bytes and packets sent and received, and how many connections opened, closed, or failed
• the container on the host that opened or accepted it, or the host process when --flowtrace-include-host-flows is on
• for a public destination, its name, from the DNS lookup or the TLS server name

With request capture on (--flowtrace-per-request-collector), the agent also records, for each HTTP or gRPC request it sends:

• the request and response sizes
• the host it was sent to, from the HTTP Host header or the gRPC :authority
• the values of any X-CostGraph- headers used for request header attribution

CostGraph doesn’t store request or response bodies, or any other header.

CostGraph keeps hourly traffic totals for 90 days and hourly request totals for 30 days. Records of connections and resources that no longer exist are deleted 120 days after they end.

To turn flow tracing off, set ENABLE_NETWORK_TRACE=false for the agent and restart it:

• Script install: add ENABLE_NETWORK_TRACE=false to /etc/default/costgraph-agent (systemd), or export ENABLE_NETWORK_TRACE=false to /etc/conf.d/costgraph-agent (OpenRC).
• Docker: pass -e ENABLE_NETWORK_TRACE=false.

On Kubernetes, set flowtrace.enabled to false in the operator chart. Context still shows your boxes and their cost, without traffic lines.