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

# Machine identity

> Tell the agent which cloud, region, instance type, and pricing a machine has when it cannot detect them

The [agent](/costgraph/agent) detects what a machine is from the cloud's metadata service: provider, region, zone, instance type, and whether it is spot or on-demand. Detection works on AWS, Google Cloud, Azure, DigitalOcean, and Hetzner.

Detection is not possible on on-premises servers, private clouds, other providers, or hosts with blocked metadata access. Those machines show up without a region or instance type and cannot be matched to a public price. Set the values yourself to fix that.

## Variables

A variable you set wins over what the agent detects. Leave a variable unset to keep the detected value.

| Variable | What it sets | Example |
| - | - | - |
| `COSTGRAPH_PROVIDER` | Cloud provider. Lowercased by the agent. | `hetzner` |
| `COSTGRAPH_REGION` | Region. | `us-east-1` |
| `COSTGRAPH_AVAILABILITY_ZONE` | Availability zone. | `us-east-1a` |
| `COSTGRAPH_INSTANCE_TYPE` | Instance type or size. | `m6i.large` |
| `COSTGRAPH_USAGE_TYPE` | `on-demand` (or `ondemand`), or `spot` (or `preemptible`). Any other value is ignored and logged. | `spot` |
| `COSTGRAPH_INSTANCE_ID` | The provider's instance id. Also keeps VMs cloned from one image apart. Setting or changing it starts a new machine record. | `i-0abc123def4567890` |
| `DIGITALOCEAN_TOKEN` | Read-only DigitalOcean API token so the agent can read the droplet size. | `dop_v1_...` |
| `HETZNER_TOKEN` | Read-only Hetzner Cloud API token so the agent can read the server type. | `...` |

<Note>
  To get a public price, values must match the price catalog's naming, for example the AWS region `us-east-1` and instance type `m6i.large`.
</Note>

## Set the variables

<Tabs>
  <Tab title="Install script">
    Export the variables before running the install command. The script writes them to the agent's environment file: `/etc/default/costgraph-agent` on systemd hosts, `/etc/conf.d/costgraph-agent` on OpenRC hosts.

    ```shell theme={null}
    export COSTGRAPH_PROVIDER="hetzner"
    export COSTGRAPH_REGION="fsn1"
    export COSTGRAPH_INSTANCE_TYPE="cx32"
    curl -sSL https://setup.costgraph.ai/install.sh | COSTGRAPH_API_KEY="bl_..." sh
    ```

    Re-running the script keeps any value already recorded in the environment file, so an upgrade does not drop your settings. To change a value, export the new one before running it again. To remove one, delete its line from that file and restart the agent.
  </Tab>

  <Tab title="Docker">
    Pass each variable with `-e`.

    ```shell theme={null}
    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_..." \
      -e COSTGRAPH_PROVIDER="hetzner" \
      -e COSTGRAPH_REGION="fsn1" \
      -e COSTGRAPH_INSTANCE_TYPE="cx32" \
      ghcr.io/baselinehq/costgraph-agent:latest
    ```
  </Tab>

  <Tab title="Ansible">
    Set the role variables, per host or per group.

    | Role variable | Sets |
    | - | - |
    | `costgraph_provider` | `COSTGRAPH_PROVIDER` |
    | `costgraph_region` | `COSTGRAPH_REGION` |
    | `costgraph_availability_zone` | `COSTGRAPH_AVAILABILITY_ZONE` |
    | `costgraph_instance_type` | `COSTGRAPH_INSTANCE_TYPE` |
    | `costgraph_usage_type` | `COSTGRAPH_USAGE_TYPE` |
    | `costgraph_instance_id` | `COSTGRAPH_INSTANCE_ID` |
    | `costgraph_digitalocean_token` | `DIGITALOCEAN_TOKEN` |
    | `costgraph_hetzner_token` | `HETZNER_TOKEN` |
  </Tab>

  <Tab title="Helm">
    Set the identity values for the agent chart.

    ```yaml theme={null}
    costgraph:
      agent:
        identity:
          provider: "hetzner"
          region: "fsn1"
          availabilityZone: ""
          instanceType: "cx32"
          usageType: ""
        providerTokensSecret: "provider-tokens"
    ```

    The values apply to every node the chart runs on, so there is no instance id value. For DigitalOcean or Hetzner tokens, create a Secret with the keys `DIGITALOCEAN_TOKEN` and `HETZNER_TOKEN` and name it in `providerTokensSecret`.
  </Tab>
</Tabs>

## When detection fails at startup

If the agent cannot detect the cloud when it starts, it tries again on its regular metadata interval and updates the machine after detection succeeds. Google Cloud is the exception: restart the agent or set the preceding variables.

## On-premises machines

Machines the agent cannot match to a public price can be given one of your organization's own prices instead. See [Pricing IDs](/costgraph/operator/on-prem-pricing#assign-a-price-to-a-virtual-machine).

## Machines cloned from one image

Machines cloned from one template share a machine id and can merge into one record in CostGraph. Either regenerate the machine id on each clone, or set `COSTGRAPH_INSTANCE_ID` to a unique value per machine.

To regenerate the machine id on a systemd host:

```shell theme={null}
sudo rm /etc/machine-id
sudo systemd-machine-id-setup
```

Also remove `/var/lib/dbus/machine-id` where it exists. The agent reads that file first and falls back to `/etc/machine-id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.