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

# Metadata server

> Read an instance's ID, name, and NCCL topology from inside the instance

Every instance can reach a metadata server at `http://169.254.169.254`. From inside the instance,
you can read its ID and name and a topology file for the NVIDIA Collective Communications Library
(NCCL). The server requires no authentication, and only the instance itself can reach it.

```bash theme={null}
curl http://169.254.169.254/v1/instance/id
```

```text theme={null}
inst_4EzdPrHcTps
```

## Endpoints

All endpoints use `GET` on port 80.

| Path | Response |
| - | - |
| `/v1/instance/id` | The instance ID as plain text |
| `/v1/instance/name` | The instance name as plain text, or `404` if it has no name |
| `/v1/nccl_xml` | An NCCL topology file as XML, or `410` if the instance needs none |

## Read the instance ID and name

`/v1/instance/id` returns the same `inst_...` ID that `sf instances list` and the API show.
`/v1/instance/name` returns the instance's name, or `404 Not Found` with an empty body if the
instance has no name. When you rename a running instance, the endpoint returns the new name.

```bash theme={null}
instance_name=$(curl -sf http://169.254.169.254/v1/instance/name) || instance_name=""
```

## Get the NCCL topology

Instances with GPUs and InfiniBand need an NCCL topology file so NCCL detects the PCIe layout
correctly. `/v1/nccl_xml` returns this file.
Save it and point `NCCL_TOPO_FILE` at it before you start your job.

```bash theme={null}
curl -sf http://169.254.169.254/v1/nccl_xml -o /etc/nccl-topology.xml
export NCCL_TOPO_FILE=/etc/nccl-topology.xml
```

You can also save the file to `/var/run/nvidia-topologyd/virtualTopology.xml`, where NCCL finds it
without `NCCL_TOPO_FILE`.

Unless the instance has both GPUs and InfiniBand, the endpoint returns `410 Gone` with an empty
body. NCCL detects the topology on its own there, so you do not need the file. See
[Multi-node training](https://docs.sfcompute.com/preview/guides/multi-node-training.md) for a full InfiniBand job.