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

# Create a cluster

> Create a GPU cluster from the dashboard, your AI agent, the CLI or the API.

Creating a cluster is two steps: find the machines for the size you want, then create the cluster from one of those offers. Offers change as capacity moves, so create soon after you look.

> [!NOTE]
>
> A cluster is all or nothing and is billed from when every machine is up, for every machine, until you terminate it. See [Clusters](https://runcrate.ai/docs/clusters/overview.md#billing).

**Dashboard**

On the **Clusters** page, click **Create cluster**:

1. **Configure**: a **name** (machines are named after it: `train-0`, `train-1`, ...) and an **SSH key** (optional; keyless access from the dashboard and CLI always works), the **GPU**, how many **nodes** (machines; node 0 is the head), the **software** (None, Slurm, Kubernetes or Ray) and a **shared volume** (optional). Then **Find machines**.
2. **Pick machines**: each row is where the machines are, how they are joined, the kind of machine and the GPUs each one has, with the price per hour for the whole cluster and the price per machine under it. Turn on **Include community hosts** to see those too.
3. **Create cluster**. The sheet waits until every machine is reserved, then the cluster opens and shows each node as it joins, then the software installing.

**Request a quote** next to **Create cluster** is for reserved, very large or custom clusters.

**Ask your agent**

Connect the [Runcrate MCP server](https://runcrate.ai/docs/mcp/setup.md) to Claude Code, Codex, Cursor or any MCP client, then ask in plain words:

```text theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
Make me a Slurm cluster of 4 machines with 8 H100s each, show me where and what it costs per hour first.
```

```text theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
Is my cluster train ready yet? Run the NCCL test on it and tell me the bus bandwidth.
```

What the agent does with the first prompt:

1. `cluster_offers` with `gpu_type: "H100"`, `gpus_per_node: 8`, `nodes: 4` and `stack: "slurm"`, and shows you the locations, how the machines are joined, `hourly_rate` for the whole cluster and `hourly_rate_per_node` for each machine.
2. After you pick, `create_cluster` with `name`, the `offer_id`, `node_count: 4` and `stack: "slurm"`. The cluster comes back **provisioning**.
3. `get_cluster` until `status` is `ready`.

For the second prompt it calls `get_cluster`, then `run_cluster_nccl_test`, and reads `last_test` from `get_cluster` until it has passed. `delete_cluster` terminates every machine. See [MCP tools](https://runcrate.ai/docs/mcp/tools.md#clusters).

**See the code**

The CLI:

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
# Where 4 machines of H100s can start now, at every GPU count a machine comes with
runcrate clusters offers --gpu H100 --nodes 4 --stack slurm

# Only machines with 8 GPUs each
runcrate clusters offers --gpu H100:8 --nodes 4 --stack slurm

# Create it from an offer
runcrate clusters create --name train --offer <offer-id> --nodes 4 --stack slurm

# Follow it until it is ready
runcrate clusters get train
```

The API (`https://www.runcrate.ai/api/v1`, with your API key):

```bash theme={"theme":{"light":"github-light","dark":"catppuccin-mocha"}}
curl "https://www.runcrate.ai/api/v1/clusters/offers?gpu_type=H100&gpus_per_node=8&nodes=4&stack=slurm" \
  -H "Authorization: Bearer $RUNCRATE_API_KEY"

curl -X POST https://www.runcrate.ai/api/v1/clusters \
  -H "Authorization: Bearer $RUNCRATE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: train-2026-10-26" \
  -d '{"name": "train", "offer_id": "<offer-id>", "node_count": 4, "stack": "slurm"}'
```

`gpus_per_node` is 1, 2, 4 or 8; leave it out to see every size of machine. Each offer has `hourly_rate` (the whole cluster at `nodes` machines) and `hourly_rate_per_node` (one machine). When an offer lists `allowed_node_counts`, only those sizes can be created from it. With a volume, list offers with `volume=true`: only machines that may hold a volume are shown.

The answer to the create is the cluster, `provisioning`. Poll `GET /clusters/{id}` until `status` is `ready`. Sending the same `Idempotency-Key` again returns the same cluster instead of creating another. See the [API reference](https://runcrate.ai/docs/api-reference).

## When it cannot start

| What you see | What happened | What to do |
| - | - | - |
| `OFFER_GONE` (409) | The offer was taken between looking and creating, or it cannot run the software or volume you asked for. Nothing was created | Pick one of the current offers, listed in `details.offers` |
| `NO_CAPACITY` (503) | Not every machine could be reserved, so none was kept. Nothing was billed | Try another offer, or again after `Retry-After` |
| `insufficient_credits` (402) | Your balance does not cover an hour of the whole cluster (at least \$10) | Add credits |
| `BUDGET_REACHED` (402) | The environment has used its monthly budget | A workspace owner or admin can raise it |
| `rate_limited` (429) | Clusters in the workspace did not finish starting twice in a day, so new ones are paused for a day | Wait until the time in the message, or contact support |
| Status **failed** | A machine did not come up, or the machines could not reach each other, within 25 minutes. Every machine was released and nothing was billed | Read `failure_detail` and the events, then create again from a current offer |
| Status **degraded** | The software failed to install. The machines are up and billed | Read `stack_detail`, then retry the install from the cluster page or `POST /clusters/{id}/retry-install`, or terminate |

## Resize

Where the offer allows it (`resize` on the cluster), add workers to a ready cluster with **Add workers** on its page or with `POST /clusters/{id}/nodes`, and remove one with `DELETE /clusters/{id}/nodes/{rank}`. A new worker joins the private network and the software, and is billed from when it is up; a removed one is drained from the software first. The head (rank 0) stays, and a cluster keeps at least 2 machines.

## Terminate

Terminating stops every machine together and ends billing for the whole cluster. Copy what you need off the machines first: their disks and `/shared` are deleted, and only a volume keeps `/shared/volume`.

* Dashboard: **Terminate all** on the cluster page.
* Agent: `delete_cluster`.
* CLI: `runcrate clusters delete train`.
* API: `DELETE /clusters/{id}`.


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