<a id="instances-manage"></a>

# How to manage instances

When listing the existing instances, you can see their type, status, and location (if applicable).
You can filter the instances and display only the ones that you are interested in.

CLI

Enter the following command to list all instances:

```none
lxc list
```

You can filter the instances that are displayed, for example, by type, status or the cluster member where the instance is located:

```none
lxc list type=container
lxc list status=running
lxc list location=server1
```

You can also filter by name.
To list several instances, use a regular expression for the name.
For example:

```none
lxc list ubuntu.*
```

Enter [`lxc list --help`](https://canonical.com/lxd/docs/default/reference/manpages/lxc/list/index.html.md#lxc-list-md) to see all filter options.

API

Query the `/1.0/instances` endpoint to list all instances.
You can use [Recursion](https://canonical.com/lxd/docs/default/rest-api/index.html.md#rest-api-recursion) to display more information about the instances:

```none
lxc query --request GET /1.0/instances?recursion=2
```

You can [filter](https://canonical.com/lxd/docs/default/rest-api/index.html.md#rest-api-filtering) the instances that are displayed, by name, type, status or the cluster member where the instance is located:

```none
lxc query --request GET /1.0/instances?filter=name+eq+ubuntu
lxc query --request GET /1.0/instances?filter=type+eq+container
lxc query --request GET /1.0/instances?filter=status+eq+running
lxc query --request GET /1.0/instances?filter=location+eq+server1
```

To list several instances, use a regular expression for the name.
For example:

```none
lxc query --request GET /1.0/instances?filter=name+eq+ubuntu.*
```

See [`GET /1.0/instances`](/lxd/stable-5.21/api/#/instances/instances_get) for more information.

UI

Go to Instances to see a list of all instances.

You can filter the instances that are displayed by status, instance type, or the profile they use by selecting the corresponding filter.

In addition, you can search for instances by entering a search text.
The text you enter is matched against the name, the description, and the name of the base image.

## Show information about an instance

CLI

Enter the following command to show detailed information about an instance:

```none
lxc info <instance_name>
```

Add `--show-log` to the command to show the latest log lines for the instance:

```none
lxc info <instance_name> --show-log
```

API

Query the following endpoint to show detailed information about an instance:

```none
lxc query --request GET /1.0/instances/<instance_name>
```

See [`GET /1.0/instances/{name}`](/lxd/stable-5.21/api/#/instances/instance_get) for more information.

UI

Clicking an instance line in the overview will show a summary of the instance information right next to the instance list.

Click the instance name to go to the instance detail page, which contains detailed information about the instance.

<a id="instances-manage-start"></a>

## Start an instance

CLI

Enter the following command to start an instance:

```none
lxc start <instance_name>
```

You will get an error if the instance does not exist or if it is running already.

To immediately attach to the console when starting, pass the `--console` flag.
For example:

```none
lxc start <instance_name> --console
```

See [How to access the console](https://canonical.com/lxd/docs/default/howto/instances_console/index.html.md#instances-console) for more information.

API

To start an instance, send a PUT request to change the instance state:

```none
lxc query --request PUT /1.0/instances/<instance_name>/state --data '{"action": "start"}'
```

<!-- Include start monitor status -->

The return value of this query contains an operation ID, which you can use to query the status of the operation:

```none
lxc query --request GET /1.0/operations/<operation_ID>
```

Use the following query to monitor the state of the instance:

```none
lxc query --request GET /1.0/instances/<instance_name>/state
```

See [`GET /1.0/instances/{name}/state`](/lxd/stable-5.21/api/#/instances/instance_state_get) and [`PUT /1.0/instances/{name}/state`](/lxd/stable-5.21/api/#/instances/instance_state_put)for more information.

<!-- Include end monitor status -->

UI

To start an instance, go to the instance list or the respective instance and click the Start button (▷).

You can also start several instances at the same time by selecting them in the instance list and clicking the Start button at the top.

On the instance detail page, select the Console tab to see the boot log with information about the instance starting up.
Once it is running, you can select the Terminal tab to access the instance.

### Prevent accidental start of instances

To protect a specific instance from being started, set [`security.protection.start`](https://canonical.com/lxd/docs/default/reference/instance_options/index.html.md#instance-security:security.protection.start) to `true` for the instance.
See [How to configure instances](https://canonical.com/lxd/docs/default/howto/instances_configure/index.html.md#instances-configure) for instructions.

<a id="instances-manage-stop"></a>

## Stop an instance

CLI

Enter the following command to stop an instance:

```none
lxc stop <instance_name>
```

You will get an error if the instance does not exist or if it is not running.

API

To stop an instance, send a PUT request to change the instance state:

```none
lxc query --request PUT /1.0/instances/<instance_name>/state --data '{"action": "stop"}'
```

<!-- Include content from above -->

The return value of this query contains an operation ID, which you can use to query the status of the operation:

```none
lxc query --request GET /1.0/operations/<operation_ID>
```

Use the following query to monitor the state of the instance:

```none
lxc query --request GET /1.0/instances/<instance_name>/state
```

See [`GET /1.0/instances/{name}/state`](/lxd/stable-5.21/api/#/instances/instance_state_get) and [`PUT /1.0/instances/{name}/state`](/lxd/stable-5.21/api/#/instances/instance_state_put)for more information.

UI

To stop an instance, go to the instance list or the respective instance and click the Stop button (□).
You are then prompted to confirm.

<!-- Include start skip confirmation -->

#### TIP
To skip the confirmation prompt, hold the `Shift` key while clicking.

<!-- Include end skip confirmation -->

You can choose to force-stop the instance.
If stopping the instance takes a long time or the instance is not responding to the stop request, click the spinning stop button to go back to the confirmation prompt, where you can select to force-stop the instance.

You can also stop several instances at the same time by selecting them in the instance list and clicking the Stop button at the top.

<a id="instances-manage-delete"></a>

## Delete an instance

If you don’t need an instance anymore, you can remove it.
The instance must be stopped before you can delete it.

CLI

Enter the following command to delete an instance:

```none
lxc delete <instance_name>
```

API

To delete an instance, send a DELETE request to the instance:

```none
lxc query --request DELETE /1.0/instances/<instance_name>
```

See [`DELETE /1.0/instances/{name}`](/lxd/stable-5.21/api/#/instances/instance_delete) for more information.

UI

To delete an instance, go to its instance detail page and click Delete instance.
You are then prompted to confirm.

<!-- Include content from above -->

#### TIP
To skip the confirmation prompt, hold the `Shift` key while clicking.

You can also delete several instances at the same time by selecting them in the instance list and clicking the Delete button at the top.

#### CAUTION
This command permanently deletes the instance and all its snapshots.

### Prevent accidental deletion of instances

There are different ways to prevent accidental deletion of instances:

- To protect a specific instance from being deleted, set [`security.protection.delete`](https://canonical.com/lxd/docs/default/reference/instance_options/index.html.md#instance-security:security.protection.delete) to `true` for the instance.
  See [How to configure instances](https://canonical.com/lxd/docs/default/howto/instances_configure/index.html.md#instances-configure) for instructions.
- In the CLI client, you can create an alias to be prompted for approval every time you use the [`lxc delete`](https://canonical.com/lxd/docs/default/reference/manpages/lxc/delete/index.html.md#lxc-delete-md) command:
  ```none
   lxc alias add delete "delete -i"
  ```

<a id="instances-manage-rebuild"></a>

## Rebuild an instance

If you want to wipe and re-initialize the root disk of your instance but keep the instance configuration, you can rebuild the instance.

Rebuilding is only possible for instances that do not have any snapshots.

Stop your instance before rebuilding it.

CLI

Enter the following command to rebuild the instance with a different image:

```none
lxc rebuild <image_name> <instance_name>
```

Enter the following command to rebuild the instance with an empty root disk:

```none
lxc rebuild <instance_name> --empty
```

For more information about the `rebuild` command, see [`lxc rebuild --help`](https://canonical.com/lxd/docs/default/reference/manpages/lxc/rebuild/index.html.md#lxc-rebuild-md).

API

To rebuild the instance with a different image, send a POST request to the instance’s `rebuild` endpoint.
For example:

```none
lxc query --request POST /1.0/instances/<instance_name>/rebuild --data '{
  "source": {
    "alias": "<image_alias>",
    "protocol": "simplestreams",
    "server": "<server_URL>"
  }
}'
```

To rebuild the instance with an empty root disk, specify the source type as `none`:

```none
lxc query --request POST /1.0/instances/<instance_name>/rebuild --data '{
  "source": {
    "type": "none"
  }
}'
```

See [`POST /1.0/instances/{name}/rebuild`](/lxd/stable-5.21/api/#/instances/instance_rebuild_post) for more information.

UI

Rebuilding an instance is not yet supported in the UI.