> For the complete documentation index, see [llms.txt](https://docs.acecloud.ai/knowledge-base/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acecloud.ai/knowledge-base/cli/compute/instances.md).

# Instances

Instances are virtual machines running on AceCloud infrastructure. The `ace instance` command provides full lifecycle management: creation, power control, resizing, snapshotting, networking, and more.

**Aliases:** `ace instance`, `ace i`, `ace vm`

***

## Table of Contents

* [List Instances](#list-instances)
* [Get Instance Details](#get-instance-details)
* [Create an Instance](#create-an-instance)
* [Update an Instance](#update-an-instance)
* [Delete Instances](#delete-instances)
* [Power Management](#power-management)
  * [Start](#start)
  * [Stop](#stop)
  * [Reboot](#reboot)
  * [Suspend / Unsuspend](#suspend--unsuspend)
  * [Lock / Unlock](#lock--unlock)
  * [Recovery Mode](#recovery-mode)
  * [Batch Shutoff](#batch-shutoff)
* [Resize](#resize)
  * [Resize an Instance](#resize-an-instance)
  * [Confirm Resize](#confirm-resize)
  * [Revert Resize](#revert-resize)
* [Rebuild](#rebuild)
* [Snapshots and Images](#snapshots-and-images)
  * [Create Snapshot](#create-snapshot)
  * [Save as Image](#save-as-image)
* [Console and Logs](#console-and-logs)
  * [Console URL](#console-url)
  * [Instance Logs](#instance-logs)
  * [Action Logs](#action-logs)
* [Volumes](#volumes)
  * [List Attached Volumes](#list-attached-volumes)
  * [Attach Volume](#attach-volume)
  * [Detach Volume](#detach-volume)
* [Network Interfaces](#network-interfaces)
  * [List Interfaces](#list-interfaces)
  * [Attach Interface](#attach-interface)
  * [Detach Interface](#detach-interface)
* [Security Groups](#security-groups)
* [Summary](#summary)
* [Example Workflow](#example-workflow)

***

## List Instances

List all instances in the current project and region.

```bash
ace instance list
```

**Aliases:** `ls`

**Output columns:** ID, Name, Status, Power State, Flavor, IP Addresses.

**JSON output:**

```bash
ace instance list -o json
```

***

## Get Instance Details

Retrieve a comprehensive overview of a single instance, similar to the web portal detail page.

```bash
ace instance get <instance-id>
```

**Aliases:** `show`, `describe`

The output includes sections for:

* **Overview** — ID, name, status, power state, VM state, lock status
* **Flavor** — ID, name, vCPUs, RAM, disk
* **Image** — ID, name (or "booted from volume")
* **Network** — All attached networks with IP addresses, types, and MAC addresses
* **Security Groups** — Names of all assigned security groups
* **Attached Volumes** — Volume IDs with delete-on-termination status
* **SSH & Config** — Key pair name, config drive, disk config
* **Placement & Timestamps** — Availability zone, created/updated/launched times
* **Metadata** — Key-value metadata pairs
* **Tags** — Instance tags

```bash
# JSON output for scripting
ace instance get <instance-id> -o json
```

***

## Create an Instance

Create a new virtual machine.

```bash
ace instance create \
  --name my-vm \
  --flavor C4i.medium \
  --image Ubuntu-22.04-LTS \
  --network <vpc-id> \
  --security-group <sg-id>
```

### Required Flags

| Flag               | Description                                          |
| ------------------ | ---------------------------------------------------- |
| `--name`           | Instance name (1-255 characters)                     |
| `--flavor`         | Flavor name or UUID (e.g. `C4i.medium`)              |
| `--network`        | VPC/network UUID (repeatable for multiple networks)  |
| `--security-group` | Security group UUID (repeatable for multiple groups) |

You must also supply a boot source: either `--image` or `--snapshot`.

### Optional Flags

| Flag                  | Default                        | Description                                                                  |
| --------------------- | ------------------------------ | ---------------------------------------------------------------------------- |
| `--image`             |                                | Image name or UUID (e.g. `Ubuntu-22.04-LTS`)                                 |
| `--snapshot`          |                                | Volume snapshot name or UUID                                                 |
| `--source-type`       | `image`                        | Boot source type: `image` or `snapshot`. Inferred from the boot flag you use |
| `--description`       |                                | Instance description                                                         |
| `--key`               |                                | SSH key pair name for login                                                  |
| `--count`             | `1`                            | Number of instances to create                                                |
| `--boot-size`         | `20`                           | Boot volume size in GB                                                       |
| `--volume-type`       | `NVMe based High IOPS Storage` | Boot volume storage type                                                     |
| `--billing-type`      | `hourly`                       | Billing type: `hourly` or `monthly`. GPU flavors require `monthly`           |
| `--availability-zone` | `nova`                         | Availability zone                                                            |
| `--script`            |                                | Inline plaintext cloud-init or user-data script                              |
| `--script-file`       |                                | Path to a plaintext cloud-init or user-data script                           |
| `--endpoint-security` | `false`                        | Enable CrowdStrike endpoint security                                         |
| `--config-drive`      | `false`                        | Enable config drive                                                          |

> For spot pricing on the same flavors, use `ace spot` instead — see [Spot Instances](/knowledge-base/cli/compute/spot.md).

### Examples

```bash
# Minimal creation
ace instance create \
  --name web-server \
  --flavor C4i.medium \
  --image Ubuntu-22.04-LTS \
  --network abc12345-1234-1234-1234-123456789abc \
  --security-group def12345-1234-1234-1234-123456789abc

# With SSH key and custom boot volume
ace instance create \
  --name db-server \
  --flavor C4i.large \
  --image Ubuntu-22.04-LTS \
  --network abc12345-1234-1234-1234-123456789abc \
  --security-group def12345-1234-1234-1234-123456789abc \
  --key my-keypair \
  --boot-size 50

# Multiple instances at once
ace instance create \
  --name worker \
  --flavor C4i.medium \
  --image Ubuntu-22.04-LTS \
  --network abc12345-1234-1234-1234-123456789abc \
  --security-group def12345-1234-1234-1234-123456789abc \
  --count 3

# Multiple networks and security groups
ace instance create \
  --name multi-net \
  --flavor C4i.medium \
  --image Ubuntu-22.04-LTS \
  --network <vpc-id-1> \
  --network <vpc-id-2> \
  --security-group <sg-id-1> \
  --security-group <sg-id-2> \
  --key my-key
```

Both `--flavor` and `--image` accept either a human-readable name or a UUID. The CLI automatically resolves names to UUIDs before making the API call.

***

## Update an Instance

Update the name or description of an existing instance.

```bash
ace instance update <instance-id> --name new-name
ace instance update <instance-id> --description "Updated description"
ace instance update <instance-id> --name new-name --description "New desc"
```

| Flag            | Description              |
| --------------- | ------------------------ |
| `--name`        | New instance name        |
| `--description` | New instance description |

At least one of `--name` or `--description` must be provided.

***

## Delete Instances

Delete one or more instances.

```bash
# Delete a single instance
ace instance delete <instance-id>

# Delete multiple instances
ace instance delete <id-1> <id-2> <id-3>
```

**Aliases:** `rm`

***

## Power Management

### Start

Start a stopped (shutoff) instance.

```bash
ace instance start <instance-id>
```

### Stop

Stop (shutoff) a running instance.

```bash
ace instance stop <instance-id>
```

### Reboot

Reboot an instance. By default, performs a soft reboot (graceful OS shutdown). Use `--hard` to force a hard reboot.

```bash
# Soft reboot (default)
ace instance reboot <instance-id>

# Hard reboot
ace instance reboot <instance-id> --hard
```

| Flag     | Default | Description                                    |
| -------- | ------- | ---------------------------------------------- |
| `--hard` | `false` | Perform a hard (forced) reboot instead of soft |

### Suspend / Unsuspend

Suspend an instance to save resources while preserving state, or resume a suspended instance.

```bash
# Suspend
ace instance suspend <instance-id>

# Resume
ace instance unsuspend <instance-id>
```

### Lock / Unlock

Lock an instance to prevent accidental modifications, or unlock it to allow changes.

```bash
# Lock
ace instance lock <instance-id>

# Unlock
ace instance unlock <instance-id>
```

### Recovery Mode

Toggle recovery mode on or off. Exactly one of `--on` or `--off` must be specified.

```bash
# Enable recovery mode
ace instance recovery <instance-id> --on

# Disable recovery mode
ace instance recovery <instance-id> --off
```

| Flag    | Description           |
| ------- | --------------------- |
| `--on`  | Enable recovery mode  |
| `--off` | Disable recovery mode |

Recovery mode may not be available in all regions.

### Batch Shutoff

Shut off or start multiple instances in a single command.

```bash
# Shut off multiple instances (default)
ace instance batch-shutoff <id-1> <id-2> <id-3>
ace instance batch-shutoff <id-1> <id-2> --off

# Start multiple instances
ace instance batch-shutoff <id-1> <id-2> --on
```

| Flag    | Description                                                     |
| ------- | --------------------------------------------------------------- |
| `--on`  | Start (power on) all specified instances                        |
| `--off` | Shut off (power off) all specified instances (default behavior) |

***

## Resize

Resizing changes the flavor (CPU, RAM, disk) of an instance. This is a two-step process: initiate the resize, then confirm or revert it.

### Resize an Instance

Initiate a resize to a new flavor.

```bash
ace instance resize <instance-id> <flavor-name-or-id>
```

Both flavor names and UUIDs are accepted. The CLI resolves names automatically.

```bash
# By name
ace instance resize abc12345-... C4i.large

# By UUID
ace instance resize abc12345-... def67890-...
```

After initiating, the instance enters a `VERIFY_RESIZE` state. You must confirm or revert.

### Confirm Resize

Confirm the resize after verifying the instance works correctly.

```bash
ace instance resize-confirm <instance-id>
```

### Revert Resize

Revert to the previous flavor if something went wrong.

```bash
ace instance resize-revert <instance-id>
```

**Resize workflow:**

1. `ace instance resize <id> <new-flavor>` — initiates the resize
2. Wait for status to become `VERIFY_RESIZE`
3. `ace instance resize-confirm <id>` — makes it permanent
4. Or `ace instance resize-revert <id>` — rolls back to old flavor

***

## Rebuild

Rebuild an instance with a new image. This reinstalls the operating system while keeping the same instance ID, flavor, and network configuration.

```bash
ace instance rebuild <instance-id> --image Ubuntu-24.04-LTS
```

| Flag      | Description                                      |
| --------- | ------------------------------------------------ |
| `--image` | **Required.** Image name or UUID to rebuild with |

Rebuilding an instance destroys all data on the boot disk. Back up important data first.

***

## Snapshots and Images

### Create Snapshot

Create a snapshot of an instance's current state.

```bash
ace instance snapshot <instance-id>
ace instance snapshot <instance-id> --name "before-upgrade"
```

| Flag     | Description            |
| -------- | ---------------------- |
| `--name` | Optional snapshot name |

### Save as Image

Save an instance as a reusable image that can be used to launch new instances.

```bash
ace instance save-image <instance-id>
ace instance save-image <instance-id> --name "my-golden-image"
```

| Flag     | Description         |
| -------- | ------------------- |
| `--name` | Optional image name |

`save-image` may not be available in all regions.

***

## Console and Logs

### Console URL

Get a web console URL for an instance. Open the URL in a browser for VNC-like access.

```bash
ace instance console <instance-id>
```

Outputs the console URL directly (or JSON with `-o json`).

### Instance Logs

View the console/boot logs of an instance.

```bash
ace instance logs <instance-id>
```

### Action Logs

View the history of actions performed on an instance (create, stop, start, resize, etc.).

```bash
ace instance action-logs <instance-id>
```

***

## Volumes

### List Attached Volumes

List all volumes attached to an instance.

```bash
ace instance volumes <instance-id>
```

**Output columns:** ID, Name, Size, Status, Type, Device.

### Attach Volume

Attach an existing volume to an instance.

```bash
ace instance attach-volume <instance-id> --volume <volume-id>
```

| Flag       | Description                         |
| ---------- | ----------------------------------- |
| `--volume` | **Required.** Volume UUID to attach |

### Detach Volume

Detach a volume from an instance.

```bash
ace instance detach-volume <instance-id> --volume <volume-id>
```

| Flag       | Description                         |
| ---------- | ----------------------------------- |
| `--volume` | **Required.** Volume UUID to detach |

***

## Network Interfaces

### List Interfaces

List all network interfaces attached to an instance.

```bash
ace instance interfaces <instance-id>
```

**Output columns:** Port ID, IP Address, Status, Network ID, MAC Address.

### Attach Interface

Attach a new network interface to an instance, either by port or by network.

```bash
# Attach by port ID
ace instance attach-interface <instance-id> --type port --port <port-id>

# Attach by network ID
ace instance attach-interface <instance-id> --type network --network <network-id>
```

| Flag        | Default | Description                           |
| ----------- | ------- | ------------------------------------- |
| `--type`    | `port`  | Interface type: `port` or `network`   |
| `--port`    |         | Port UUID (when type is `port`)       |
| `--network` |         | Network UUID (when type is `network`) |

### Detach Interface

Detach a network interface from an instance by port ID.

```bash
ace instance detach-interface <instance-id> <port-id>
```

***

## Security Groups

List all security groups assigned to an instance.

```bash
ace instance security-groups <instance-id>
```

**Output columns:** ID, Name, Rules count, Description.

***

## Summary

Show a summary of instance counts across the current project.

```bash
ace instance summary
```

**Output:** Total instance count and active instance count.

```
Instances: 5 total, 3 active
```

***

## Example Workflow

A complete workflow for provisioning an instance from scratch:

```bash
# Step 1: Browse available flavors
ace flavor list --cpu

# Step 2: Browse available images
ace image list --os ubuntu

# Step 3: Create an SSH key pair (save the private key!)
ace key-pair create --name deploy-key

# Step 4: Identify your VPC and security group
ace vpc list
ace security-group list

# Step 5: Create the instance
ace instance create \
  --name production-web \
  --flavor C4i.large \
  --image Ubuntu-22.04-LTS \
  --network <vpc-id> \
  --security-group <sg-id> \
  --key deploy-key \
  --boot-size 50

# Step 6: Check the instance status
ace instance list
ace instance get <instance-id>

# Step 7: Get the console URL to verify boot
ace instance console <instance-id>

# Step 8: Attach additional storage
ace volume create --name data-vol --size 100
ace instance attach-volume <instance-id> --volume <volume-id>

# Step 9: Create a snapshot before making changes
ace instance snapshot <instance-id> --name "initial-setup"

# Step 10: When done, stop or delete
ace instance stop <instance-id>
ace instance delete <instance-id>
```

***

## Command Reference

| Command                                     | Description                 |
| ------------------------------------------- | --------------------------- |
| `ace instance list`                         | List all instances          |
| `ace instance get <id>`                     | Get instance details        |
| `ace instance create`                       | Create a new instance       |
| `ace instance update <id>`                  | Update name/description     |
| `ace instance delete <id> [id...]`          | Delete instance(s)          |
| `ace instance start <id>`                   | Start an instance           |
| `ace instance stop <id>`                    | Stop an instance            |
| `ace instance reboot <id>`                  | Reboot an instance          |
| `ace instance suspend <id>`                 | Suspend an instance         |
| `ace instance unsuspend <id>`               | Resume a suspended instance |
| `ace instance lock <id>`                    | Lock an instance            |
| `ace instance unlock <id>`                  | Unlock an instance          |
| `ace instance recovery <id>`                | Toggle recovery mode        |
| `ace instance batch-shutoff <id> [id...]`   | Batch start/stop instances  |
| `ace instance resize <id> <flavor>`         | Resize to new flavor        |
| `ace instance resize-confirm <id>`          | Confirm pending resize      |
| `ace instance resize-revert <id>`           | Revert pending resize       |
| `ace instance rebuild <id>`                 | Rebuild with new image      |
| `ace instance snapshot <id>`                | Create a snapshot           |
| `ace instance save-image <id>`              | Save as reusable image      |
| `ace instance console <id>`                 | Get console URL             |
| `ace instance logs <id>`                    | View instance logs          |
| `ace instance action-logs <id>`             | View action history         |
| `ace instance volumes <id>`                 | List attached volumes       |
| `ace instance attach-volume <id>`           | Attach a volume             |
| `ace instance detach-volume <id>`           | Detach a volume             |
| `ace instance interfaces <id>`              | List network interfaces     |
| `ace instance attach-interface <id>`        | Attach a network interface  |
| `ace instance detach-interface <id> <port>` | Detach a network interface  |
| `ace instance security-groups <id>`         | List security groups        |
| `ace instance summary`                      | Show instance count summary |