> For the complete documentation index, see [llms.txt](https://docs.i3d.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.i3d.net/compute/flexvm/getting-started-with-flexvm.md).

# Getting started with FlexVM

## Prerequisites

Before you begin, the i3D team has already set up the following for you:

* **Tenant (K#)**: your unique organization identifier.
  * Each Tenant has its own VLAN and IP prefixes already assigned to it.
* **FlexVM Cloud**: a dedicated resource pool with compute capacity assigned to your Tenant.
  * You can also create and delete Clouds yourself; see [Creating a Cloud and Nodes](/compute/flexvm/creating-a-cloud-and-nodes.md).

## Using FlexVM API

{% hint style="info" %}
API URL prefix is <https://api.i3d.net>
{% endhint %}

### API Token

Generate an API token, the procedure is documented in [API v3 Authentication](https://docs.i3d.net/game-hosting/overview/apiv3-authentication)

* Add IP whitelisting for security (whitelist the IP addresses that will access the API).
* Include your API key in every request using this **HTTP header**:

| HTTP Header Name | HTTP Header Value |
| ---------------- | ----------------- |
| PRIVATE-TOKEN    | YOUR\_API\_KEY    |

### Pagination

Use the **RANGED-DATA** header to control result sets (default: `start=0`, `results=25`). All GET endpoints that return collections support this header.

## Step 1: Create Your First Cloud and Node

A Cloud is your isolated resource pool, and Nodes are the bare-metal servers that provide its capacity. You need at least one Cloud with one Node before you can create VMs — this is where you start.

{% hint style="info" %}
If the i3D.net team has already provisioned a Cloud for you (see [Prerequisites](#prerequisites)), you can skip ahead to [Step 2: Explore Your Environment](#step-2-explore-your-environment).
{% endhint %}

1. Create a Cloud with `POST /v3/flexVM/clouds`, specifying its name, site, and the Bare Metal instance type to use.
2. Add a Node with `POST /v3/flexVM/clouds/{cloudUuid}/nodes`. Nodes are provisioned asynchronously and become available to host VMs once provisioning completes.

For the full request bodies, available instance types, and scaling details, see [Creating a Cloud and Nodes](/compute/flexvm/creating-a-cloud-and-nodes.md).

## Step 2: Explore Your Environment

* List your Clouds:
  * `GET /v3/flexVM/clouds`
  * You should see one Cloud with its UUID, name, and capacity details.
* Get Cloud details:
  * `GET /v3/flexVM/clouds/{cloudUuid}`
  * Returns the details of one specific Cloud.
* List Nodes in your Cloud:
  * `GET /v3/flexVM/clouds/{cloudUuid}/nodes`
  * Nodes represent the underlying compute hosts. This lists the physical server Nodes that are enrolled in the Cloud.
* List available Images:
  * `GET /v3/flexVM/images`
  * Images are templates you can use when creating a VM.
* List available Instance Types:
  * `GET /v3/flexVM/instanceTypes`
  * Instance Types define a VM's size (vCPU, RAM, disk, PCIe device passthrough).

## Step 3: Create Your First VM

Create a VM with the `POST /v3/flexVM/clouds/{cloudUuid}/vms` endpoint. For the full request body and response, see [Creating and Deleting a VM](/compute/flexvm/creating-and-deleting-a-vm.md); for a Terraform example, see [Using Terraform](/compute/flexvm/using-terraform.md).

A newly created VM transitions through `provisioning` → `starting` → `running`. You can monitor its status using the GET VM endpoint described below.

## Step 4: Manage Your VMs

* List VMs in your Cloud:
  * `GET /v3/flexVM/clouds/{cloudUuid}/vms?status=running`
  * Optionally filter by status (e.g., `running`, `stopped`).
  * Returns the creation or deletion timestamp of each VM alongside its IP address and Node.
* Get a specific VM:
  * `GET /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}`
  * Returns the details of the specified VM only.
* Execute a command on a VM:
  * `POST /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}/commands`
  * Supported commands: `start`, `stop`, `reboot`, `reset`. See [Managing VMs](/compute/flexvm/managing-vms.md).
* Delete a VM:
  * `DELETE /v3/flexVM/clouds/{cloudUuid}/vms/{vmUuid}`
  * Immediately wipes the local LVM disk and the passthrough NVMe (if any). See [Creating and Deleting a VM](/compute/flexvm/creating-and-deleting-a-vm.md).

## Step 5: Monitor Monthly Usage

Retrieve usage data across all your Clouds with the `GET /v3/flexVM/reports/monthly` endpoint. For the full request and a breakdown of the reported aggregates, see [Usage and Reporting](/compute/flexvm/usage-and-reporting.md).

## Using FlexVM Terraform Provider

FlexVM can be used through our API or through our Terraform provider. See [Using Terraform](/compute/flexvm/using-terraform.md) for setup and an example.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.i3d.net/compute/flexvm/getting-started-with-flexvm.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.