# 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`)              |
| `--image`          | Image name or UUID (e.g. `Ubuntu-22.04-LTS`)         |
| `--network`        | VPC/network UUID (repeatable for multiple networks)  |
| `--security-group` | Security group UUID (repeatable for multiple groups) |

### Optional Flags

| Flag                  | Default                        | Description                                   |
| --------------------- | ------------------------------ | --------------------------------------------- |
| `--description`       |                                | Instance description (max 255 characters)     |
| `--key`               |                                | SSH key pair name for login                   |
| `--count`             | `1`                            | Number of instances to create (1-10)          |
| `--boot-size`         | `20`                           | Boot volume size in GB                        |
| `--volume-type`       | `NVMe based High IOPS Storage` | Boot volume storage type                      |
| `--source-type`       | `image`                        | Boot source: `image`, `snapshot`, or `volume` |
| `--billing-type`      | `hourly`                       | Billing type                                  |
| `--availability-zone` | `nova`                         | Availability zone                             |
| `--config-drive`      | `false`                        | Enable config drive                           |

### 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 |


---

# Agent Instructions: 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:

```
GET https://docs.acecloud.ai/knowledge-base/cli/compute/instances.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.