---
title: "Creating and managing instances"
slug: "create-manage-virtual-machines"
source: "https://app.cloudpe.com/help/create-manage-virtual-machines"
updated: "2026-08-27T05:17:14.851Z"
---

# Creating and managing instances

## Overview

CloudPe instances are virtual machines you create from an image and a flavor inside a project and region. From the **Instances** page you can deploy a new instance, watch its status, open its console, resize it, reset its password, attach volumes and networks, tag it, and delete it when you are done. Everything available in the console is also available on the public API.

This article covers the standard create-and-manage flow. GPU-backed instances, console sharing and power-state details are covered in the linked articles at the end.

## Before you start

- Identity verification: your organization must have completed KYC; without it, resource creation is refused with "Complete identity verification to create cloud resources."
- Permissions: you need `vms:read` to see the list, `vms:create` to deploy, `vms:update` for power actions, resize, password reset, tags, interfaces and schedules, and `vms:delete` to remove an instance.
- A project in the target region: the project must already be provisioned in the region you are deploying into; a project belonging to another region cannot host resources there.
- Wallet balance: prepaid organizations must hold enough balance to cover the create-time minimum for the instance, otherwise the request is rejected on the balance check.
- Quota: your organization's vCPU, RAM and storage quota must cover the flavor plus the boot volume and any additional data volumes you ask for.
- Stock: GPU flavors are only deployable while the selected GPU type has free capacity in that region.
- An SSH key or password: you can inject an existing SSH key by name, create one during the deploy flow, or let CloudPe generate an admin password.

## Steps

### 1. Open the instance list

Go to **Instances** under COMPUTE. The list shows every instance in the projects you can see; use **Status** and **Region** to filter, **Export** to download the list, and **Refresh status** on a detail page to re-poll a single instance.

![](/kb/compute/create-manage-virtual-machines-01-list.png)

### 2. Start a deployment

Click **Deploy instance**. The **Deploy an instance** page walks through the configuration in order.

![](/kb/compute/create-manage-virtual-machines-02-create.png)

1. **Region** — pick the region and the project that is provisioned there.
2. **Image** — pick an operating system image or one of your custom images. An uploaded ISO is treated as installer media and is booted alongside a blank target disk.
3. **Size** — pick a flavor. GPU flavors additionally require a GPU type.
4. **Authentication & network** — choose the network and security groups, select an SSH key or use **New key** to create one, and use **Add Volume** to create and attach extra data volumes alongside the boot volume.
5. **Name & quantity** — name the instance and choose how many to create.

Then click **🚀 Deploy now**. The instance is recorded immediately and provisioning continues in the background; the row moves through pending and building states before reaching active.

### 3. Manage the instance

Open an instance from the list to reach its detail page.

![](/kb/compute/create-manage-virtual-machines-03-detail.png)

The page is organised into **Overview**, **Billing**, **Volumes**, **Networking**, **Logs**, **Settings**, **Metrics** and **Alerts** tabs. The action bar gives you:

- **Power** — start, stop, reboot, suspend/resume and shelve/unshelve.
- **Console** — open the VNC console for a running instance.
- **Resize** — opens the **Change VM Flavor** modal to move the instance to another flavor; the instance must be active or stopped, and the resize is confirmed afterwards.
- **Reset Password** — set a new admin/root password on a running instance.
- **More actions** — rebuild from another image, manage tags and expiry, and delete.
- **Generate Install Command** — under **Agent Installation**, produces the command that registers the monitoring agent on the guest.

## API

All calls use the host https://app.cloudpe.com and a bearer token.

List and inspect instances:

```bash
curl https://app.cloudpe.com/api/v1/instances \
  -H "Authorization: Bearer <API_KEY>"

curl https://app.cloudpe.com/api/v1/instances/<instance_id> \
  -H "Authorization: Bearer <API_KEY>"
```

Create an instance:

```bash
curl -X POST https://app.cloudpe.com/api/v1/instances \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "web-1",
    "project_id": "<project_id>",
    "region": "<region_slug>",
    "flavor": "<flavor_slug>",
    "image": "<image_slug>",
    "ssh_key_name": "<key_name>",
    "billing_cycle": "HOURLY",
    "install_agent": false
  }'
```

Other fields accepted by `POST /api/v1/instances` include `flavor_id`, `image_id`, `region_id`, `gpu_id` (required for GPU flavors), `network`, `volume`, `additional_volumes`, `password`, `user_data`, `tags`, `template`, `expires_at`, `commitment_term_months` and `committed_terms_version_accepted`.

Run a lifecycle action:

```bash
curl -X POST https://app.cloudpe.com/api/v1/instances/<instance_id>/actions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"action": "stop"}'
```

`action` accepts `start`, `stop`, `force_stop`, `reboot`, `hard_reboot`, `rebuild`, `suspend`, `resume`, `shelve`, `unshelve`, `resize` and `confirm_resize`. Pass `flavor` for a resize, `image` and optionally `password` for a rebuild, and `security_group_name` for security-group actions.

Rename, re-tag or set expiry:

```bash
curl -X PATCH https://app.cloudpe.com/api/v1/instances/<instance_id> \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name": "web-1-renamed", "remove_expiry": true}'
```

Delete an instance:

```bash
curl -X DELETE https://app.cloudpe.com/api/v1/instances/<instance_id> \
  -H "Authorization: Bearer <API_KEY>"
```

Other endpoints on the same resource:

| Purpose | Method and path |
|---|---|
| Bulk create | `POST /api/v1/instances/bulk` |
| Bulk job status | `GET /api/v1/instances/bulk/{job_id}` |
| Console | `GET /api/v1/instances/{instance_id}/console` |
| Console log | `GET /api/v1/instances/{instance_id}/console/output` |
| Console share create / list / revoke | `POST /api/v1/instances/{instance_id}/console/share`, `GET /api/v1/instances/{instance_id}/console/shares`, `DELETE /api/v1/instances/{instance_id}/console/shares/{share_id}` |
| Change password | `POST /api/v1/instances/{instance_id}/password` |
| Interfaces | `GET`/`POST /api/v1/instances/{instance_id}/interfaces`, `DELETE /api/v1/instances/{instance_id}/interfaces/{port_id}` |
| Port security groups | `POST /api/v1/instances/{instance_id}/interfaces/{port_id}/security-groups`, `DELETE /api/v1/instances/{instance_id}/interfaces/{port_id}/security-groups/{sg_openstack_id}` |
| Instance security groups | `GET /api/v1/instances/{instance_id}/security-groups` |
| Tags | `GET`/`POST /api/v1/instances/{instance_id}/tags`, `DELETE /api/v1/instances/{instance_id}/tags/{tag_key}` |
| Action history | `GET /api/v1/instances/{instance_id}/history` |
| Installer media | `GET /api/v1/instances/{instance_id}/installer-media`, `POST /api/v1/instances/{instance_id}/eject-media` |
| Billing cycle | `GET /api/v1/instances/{instance_id}/billing-cycle/preview`, `POST /api/v1/instances/{instance_id}/billing-cycle` |
| Shelve schedule | `GET`/`POST`/`PUT`/`DELETE /api/v1/instances/{instance_id}/shelve-schedule`, `PATCH /api/v1/instances/{instance_id}/shelve-schedule/toggle` |
| Metrics | `GET /api/v1/vms/{vm_id}/metrics`, `GET /api/v1/vms/{vm_id}/metrics/latest`, `GET /api/v1/vms/{vm_id}/metrics/gpu` |
| Monitoring agent | `GET /api/v1/vms/{vm_id}/agent/status`, `GET /api/v1/vms/{vm_id}/agent/health-metrics`, `POST /api/v1/vms/{vm_id}/agent/register-token`, `DELETE /api/v1/vms/{vm_id}/agent` |

## Limits & billing

- An instance is metered on three independent streams: compute (the flavor), storage (the boot volume plus any attached data volumes), and network (a public IP, when one is assigned).
- Boot and data volumes are billed per GB by storage policy — Eco-NVMe, Standard-NVMe or Pro-NVMe — each with its own IOPS and throughput characteristics. See the **Billing** tab of an instance for its current lines.
- `billing_cycle` at create time and `POST /api/v1/instances/{instance_id}/billing-cycle` afterwards accept `HOURLY`, `DAILY`, `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUAL` and `ANNUAL`. Preview the effect of a change with `GET /api/v1/instances/{instance_id}/billing-cycle/preview` before applying it.
- Resize is available for hourly-billed instances only; an instance on a subscription must be moved to hourly first.
- Deleting an instance closes its compute, storage and network meters and cancels the subscriptions tied to it. Prepaid organizations receive a prorated refund to the wallet; unpaid postpaid invoices for the instance are voided.
- Setting `expires_at` auto-deletes the instance at that UTC time. Remove it with `"remove_expiry": true` on the PATCH call.
- Bulk creation is per project — every instance in one `POST /api/v1/instances/bulk` request must share the same `project_id` — and committed-use purchases must be submitted one at a time.

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `Complete identity verification to create cloud resources.` | KYC is incomplete for the organization. | Finish identity verification, then retry the deployment. |
| `Insufficient wallet balance. Required: ₹{…}, Available: ₹{…}` | Prepaid wallet does not cover the create-time minimum. | Top up the wallet from **Billing** and retry. |
| `Project belongs to a different region; cannot create resources here.` | The selected project is not provisioned in the chosen region. | Pick a project that exists in that region, or create one there. |
| `Flavor {…} not found in this region` | The flavor is not offered in the selected region. | Choose a different **Size** or a different **Region**. |
| `Instance creation service temporarily unavailable.` | The provisioning service could not accept the request. | Retry shortly; if it persists, contact support. |
| `Instance must be stopped to start. Use 'unshelve' for shelved instances or 'resume' for suspended instances.` | The instance is shelved or suspended, not stopped. | Use `unshelve` or `resume` instead of `start`. |
| `Instance must be active or stopped to resize` | The instance is in a transitional or shelved state. | Bring it to active or stopped, then resize. |
| `Resize is available for hourly-billed instances only. This instance has an active subscription — switch its billing cycle to hourly first, or contact support.` | The instance is on a non-hourly subscription. | Change its billing cycle to hourly, then resize. |
| `Instance must be active to change password` | The password reset requires a running guest. | Start the instance and retry **Reset Password**. |
| `Instance must be active for console access` | The console is only served for running instances. | Start the instance, then open **Console**. |
| `Network and VM must be in the same region` | An interface attach referenced a network from another region. | Attach a network from the instance's own region and project. |
| `Instance is already being deleted or has been deleted` | A delete is already in flight. | Wait for the delete to finish; the row disappears from **Instances**. |
| `No installer media is attached to this instance` | An eject was requested on an instance with no ISO media. | No action needed; the instance is already booting from its own disk. |
| `All instances in a bulk request must share the same project_id. Submit one /bulk request per project.` | A bulk payload mixed projects. | Split the payload into one request per project. |

## FAQ

**Can I create many instances at once?**
Yes. Use the quantity field under **Name & quantity** in the console, or `POST /api/v1/instances/bulk` with either an `instances` array or `count` plus a `template` and a `name_prefix` that auto-names them in sequence.

**How do I rebuild an instance onto a different image?**
Stop the instance, then send `{"action": "rebuild", "image": "<image_slug>"}` to `POST /api/v1/instances/{instance_id}/actions`. You can pass a new `password` in the same call.

**Can I shelve instances on a schedule?**
Yes. Create a shelve schedule with `POST /api/v1/instances/{instance_id}/shelve-schedule` using either a preset or a custom cron pair, with your own timezone and notification email. Toggle it on or off with the `toggle` endpoint.

**How do I stop an instance from being deleted automatically?**
Send `{"remove_expiry": true}` to `PATCH /api/v1/instances/{instance_id}`.

**Where do I see CPU, memory and GPU usage?**
Install the monitoring agent via **Generate Install Command** on the instance detail page, then read the **Metrics** tab or the metrics endpoints.

## Related

- [Block storage volumes](/help/block-storage-volumes)
- [VPC networks and subnets](/help/vpc-networks-subnets)
- [Security groups and firewall rules](/help/security-groups-firewall)
- [Floating IP allocation](/help/floating-ips-allocation)
- [Deploying GPU instances](/help/gpu-vm-deployment)
- [SSH key management](/help/ssh-keys-management)
- [Custom images and uploads](/help/custom-images-and-uploads)
- [Instance lifecycle and console](/help/instance-lifecycle-and-console)