Create Your First VM

_{Updated May 8, 2026} This guide walks you through creating a virtual machine, connecting via SSH, and managing its lifecycle.

Prerequisites

A Raff account with billing set up
An API key (Dashboard → API Keys → Create API Key)
A project ID (Dashboard → Projects)
An SSH key pair (optional but recommended)

Step 1: Authenticate

Set your API key and project ID as environment variables for convenience:

export RAFF_API_KEY="YOUR_API_KEY"
export RAFF_PROJECT_ID="YOUR_PROJECT_ID"

Verify your access:

curl -H "X-API-Key: $RAFF_API_KEY" \
  https://api.rafftechnologies.com/api/v1/vms

Step 2: Create a VM

Create an Ubuntu VM with 2 vCPUs, 4 GB RAM:

curl -X POST https://api.rafftechnologies.com/api/v1/vms \
  -H "X-API-Key: $RAFF_API_KEY" \
  -H "X-Project-ID: $RAFF_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-ubuntu-server",
    "template_id": "<template-uuid>",
    "pricing_id": 3,
    "region": "us-east",
    "ssh_keys": ["ssh-ed25519 AAAA... user@laptop"],
    "backup_type": "weekly",
    "backup_time": "8am",
    "backup_date": "Saturday"
  }'

Replace <template-uuid> with your OS template ID — get one from List Templates (no auth required; filter with ?category=os).The pricing_id selects a plan that determines vCPU, RAM, storage, and bandwidth — list plans with List VM Pricing.

The response includes your new VM details:

{
  "success": true,
  "data": {
    "id": "69590a15-9f68-4b6f-8232-b07781218852",
    "name": "my-ubuntu-server",
    "status": "provisioning",
    "cpu": 2,
    "ram": 4,
    "storage": 80,
    "pricing_id": 3,
    "price_per_hour": "0.027764",
    "billing_type": "payg",
    "public_ipv4_address": "15.204.178.3",
    "region": "us-east"
  }
}

Step 3: Wait for VM to Become Active

Poll the VM status until it becomes active:

curl -H "X-API-Key: $RAFF_API_KEY" \
  https://api.rafftechnologies.com/api/v1/vms/69590a15-9f68-4b6f-8232-b07781218852

The VM transitions through these states in order:

Status	Description
`initiating`	Queued, initial setup before provisioning
`provisioning`	VM being created in the hypervisor
`booting`	VM starting up
`active`	Running and reachable

Step 4: Connect via SSH

Once the VM is active, connect using the public IPv4 address:

ssh root@15.204.178.3

If you provided a password instead of SSH keys during creation:

ssh root@15.204.178.3
# Enter the password you set

Step 5: Manage Your VM

Stop the VM

curl -X POST -H "X-API-Key: $RAFF_API_KEY" -H "X-Project-ID: $RAFF_PROJECT_ID" \
  https://api.rafftechnologies.com/api/v1/vms/69590a15-9f68-4b6f-8232-b07781218852/stop

Stopped VMs retain their resources and IP address. You are still billed for reserved resources.

Resize the VM

Resize requires the VM to be stopped first. Pass a new pricing_id — the plan determines the new vCPU, RAM, storage, and bandwidth. Get plan IDs from List VM Pricing.

curl -X POST https://api.rafftechnologies.com/api/v1/vms/69590a15-9f68-4b6f-8232-b07781218852/resize \
  -H "X-API-Key: $RAFF_API_KEY" \
  -H "X-Project-ID: $RAFF_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"pricing_id": 5}'

Start the VM

curl -X POST -H "X-API-Key: $RAFF_API_KEY" -H "X-Project-ID: $RAFF_PROJECT_ID" \
  https://api.rafftechnologies.com/api/v1/vms/69590a15-9f68-4b6f-8232-b07781218852/start

Delete the VM

curl -X DELETE -H "X-API-Key: $RAFF_API_KEY" -H "X-Project-ID: $RAFF_PROJECT_ID" \
  https://api.rafftechnologies.com/api/v1/vms/69590a15-9f68-4b6f-8232-b07781218852

Deleting a VM is permanent. All data on the VM will be lost. Make sure to back up any important data first.

VPC Networking

By default every VM gets a VPC. You can opt out, or share a VPC across multiple VMs.

Auto-created VPC (default)

If you don’t pass any VPC fields, a VPC named vpc-{vm-name} is created automatically and the VM is attached to it. No extra setup required.

Shared VPC

To place multiple VMs on the same private network, create a VPC first, then pass its vpc_id to every VM that should join:

# Second VM joins the same VPC
curl -X POST https://api.rafftechnologies.com/api/v1/vms \
  -H "X-API-Key: $RAFF_API_KEY" \
  -H "X-Project-ID: $RAFF_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-second-vm",
    "template_id": "<template-uuid>",
    "pricing_id": 1,
    "region": "us-east",
    "vpc_id": "<vpc-uuid-from-first-vm>"
  }'

Inline VPC creation

Create the VPC and the first VM in a single call by passing vpc_name and vpc_cidr instead of an existing vpc_id:

curl -X POST https://api.rafftechnologies.com/api/v1/vms \
  -H "X-API-Key: $RAFF_API_KEY" \
  -H "X-Project-ID: $RAFF_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-vm",
    "template_id": "<template-uuid>",
    "pricing_id": 1,
    "region": "us-east",
    "vpc_name": "production-vpc",
    "vpc_cidr": "10.0.1.0/24"
  }'

Skip the VPC

For a single-VM setup that only needs its public IP, pass skip_vpc: true to opt out of the auto-created VPC entirely. Cannot be combined with skip_public_ip: true — a VM must have at least one network.

curl -X POST https://api.rafftechnologies.com/api/v1/vms \
  -H "X-API-Key: $RAFF_API_KEY" \
  -H "X-Project-ID: $RAFF_PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "public-only-vm",
    "template_id": "<template-uuid>",
    "pricing_id": 1,
    "region": "us-east",
    "skip_vpc": true
  }'

Getting Started

Guides

REST API

CLI

Terraform

Create Your First VM

Prerequisites

Step 1: Authenticate

Step 2: Create a VM

Step 3: Wait for VM to Become Active

Step 4: Connect via SSH

Step 5: Manage Your VM

Stop the VM

Resize the VM

Start the VM

Delete the VM

VPC Networking

Auto-created VPC (default)

Shared VPC

Inline VPC creation

Skip the VPC

​Prerequisites

​Step 1: Authenticate

​Step 2: Create a VM

​Step 3: Wait for VM to Become Active

​Step 4: Connect via SSH

​Step 5: Manage Your VM

​Stop the VM

​Resize the VM

​Start the VM

​Delete the VM

​VPC Networking

​Auto-created VPC (default)

​Shared VPC

​Inline VPC creation

​Skip the VPC

Prerequisites

Step 1: Authenticate

Step 2: Create a VM

Step 3: Wait for VM to Become Active

Step 4: Connect via SSH

Step 5: Manage Your VM

Stop the VM

Resize the VM

Start the VM

Delete the VM

VPC Networking

Auto-created VPC (default)

Shared VPC

Inline VPC creation

Skip the VPC