Quickstart

Create, access, and terminate your first GPU instance using the FluidStack API

Overview

This FluidStack API tutorial leads you through the following steps:

  1. Create your first GPU instance.
  2. Check the status of your instance.
  3. Access your instance using an SSH client and your SSH key.
  4. Terminate your instance.
Tip
If you’d rather use the FluidStack Dashboard UI to manage instances instead of the API, see: Dashboard - Instances.

Prerequisites

Steps

1

Create a GPU instance

In this step, you will create an instance with the following configuration and operating system template:

GPU TypeGPU CountCPU CountRAM SizeNVME Storage SizeOS Template
RTX_A6000_48GB11659GB425 GBUbuntu 20.04 LTS
Note

If you prefer, you can use a different instance configuration and/or operating system.

Let’s create your first instance! Copy this cURL command:

cURL command
$curl -X POST https://platform.fluidstack.io/instances \
>    -H "api-key: <api-key>" \
>    -H "Content-Type: application/json" \
>    -d '{
>  "gpu_type": "RTX_A6000_48GB",
>  "name": "my-test-instance",
>  "ssh_key": "my_ssh_key"
>}'
Warning
The $ and > characters are not intended to be copied.

Paste the command to a location where you can edit its text in plaintext format, such as a code editor. Replace the text <api_key> with your API key, and my_ssh_key with the name of an SSH key on your account.

If your request succeeds, the endpoint will respond with the created instance’s id, name, gpu_type, and operating_system_label:

Example of a successful response
1{
2  "id": "i-1234567890",
3  "name": "my_test_instance",
4  "gpu_type": "RTX_A6000_48GB",
5  "operating_system_label": "ubuntu_20_04_lts"
6}

Take note of the id of your instance for the next step.

Note

Did you notice that the cURL command you sent did not specify an operating_system_label?

When the instance name is not specified, a randomized string is used. When the operating system is not specified, a default value is used. The only values you’re required to specify when creating an instance are the instance gpu_type, and ssh_key.

2

Check the status of your instance

Request the instance’s status using the List user instances endpoint:

GET
1curl https://platform.fluidstack.io/instances \
2     -H "api-key: <api-key>"

Initially, the instance’s status will be pending. Once the instance is created and available, its status will update to running and FluidStack will assign it an IP address.

Example:

A response that shows a running instance
1[
2  {
3    "id": "i-1234567890",
4    "status": "running",
5    "username": "ubuntu",
6    "ssh_port": "22",
7    "ssh_keys": [
8      "my_ssh_key"
9    ],
10    "ip_address": "192.0.2.0",
11    "name": "my_test_instance",
12    "current_rate": 1,
13    "configuration": {
14      "id": "c-1234567890",
15      "gpu_count": 1,
16      "cpu_count": 16,
17      "nvme_storage_size_gb": 425,
18      "memory_size_gb": 59,
19      "gpu_model": {
20        "name": "RTX_A6000_48GB",
21        "memory_size_gb": 48
22      },
23      "cpu_model": "generic",
24      "estimated_provisioning_time_minutes": 5
25    },
26    "created_at": "2024-01-15T09:30:00Z"
27  }
28]

This endpoint returns a JSON array of all the instances on your account, with each instance represented as an object in the array.

Locate the instance object with the id of your newly created instance. Take note of that instance’s values for username and ip_address for the next step.

3

Access your instance

Once the instance’s status is running, you can connect to it using SSH. Use the private key that corresponds to the public key you used when creating the SSH key for this instance, and the username and ip_address you noted in the previous step.

Connect to your instance with SSH
$ssh -i <path_to_your_private_key> <username>@<ip_address>

Examples:

$ssh -i ~/.ssh/id_rsa ubuntu@192.0.2.0
Note
The first time you connect to your instance, you will see a message that says “The authenticity of host x.x.x.x can’t be established … Are you sure you want to continue connecting”. This is normal for the first connection. Type yes and press Enter.

When you have successfully logged in, notice that your command prompt has changed. All commands that you enter into this command prompt are executed on your instance.

When you’re ready to close your connection and log out from the instance, type exit into your SSH session’s command prompt and press Enter. You should be returned to your local machine’s command prompt.

4

Terminate your instance

To terminate your instance, first close your SSH connection, then call the API using the cURL command below. Replace the text instance_id in the endpoint’s path with the id you received when you created the endpoint, and <api_key> with your API key.

DEL
1curl -X DELETE https://platform.fluidstack.io/instances/{instance_id} \
2     -H "api-key: <api-key>"

Example:

Example request
$  curl -X DELETE https://platform.fluidstack.io/instances/i-1234567890 \
>  -H "api-key: api_key_j123MyFakeAPIKey"

To confirm that your instance was deleted, call the List user instances endpoint again as in Step 2.

Congratulations! You have successfully created an instance, accessed it using SSH, and deleted the instance.

What’s next