.(cpus|disk|memory)`.
+
+To modify one of this properties, first stop the instance and then issue the [`set`](/reference/command-line-interface/set) command. For example:
+
+```plain
+multipass stop handsome-ling
+multipass set local.handsome-ling.cpus=4
+multipass set local.handsome-ling.disk=60G
+multipass set local.handsome-ling.memory=7G
+```
+
+[note type="information"]
+The disk size can only be increased.
+```
+
+```{caution}
+When increasing the disk size of an instance, the partition may not expand automatically to use the new available space. This usually happens if the partition was already full when trying to increase the disk size.
+
+In such cases, you need to expand the partition manually. To do so, `shell` into the instance and run the following command:
+
+```plain
+sudo parted /dev/sda resizepart 1 100%
+```
+
+The system will guide you through the configuration steps:
+
+
+Warning: Not all of the space available to /dev/sda appears to be used,
+you can fix the GPT to use all of the space (an extra 4194304 blocks)
+or continue with the current setting.
+Fix/Ignore? fix
+Partition number? 1
+Warning: Partition /dev/sda1 is being used.
+Are you sure you want to continue? Yes/No? yes
+
+
+When done, run `sudo resize2fs /dev/sda1`.
+```
+
+You can view these properties using the `get` command, without the need to stop instances. For example, `multipass get local.handsome-ling.cpus` returns the configured number of CPUs, which in our example is "4".
+
+[note type="information"]
+You can only update the properties of `Stopped`, non-deleted instances. If you try to update an instance that is in `Running`, `Suspended`, or `Deleted` status you'll incur an error.
+
+On the other hand, it's always possible to fetch properties for all instances. Use `multipass get --keys` to obtain their settings keys.
+```
+
+[note type="information"]
+Modifying instance settings is not supported when using the Hyperkit driver, which has been deprecated in favor of QEMU. The QEMU and VirtualBox drivers on Intel-based macOS hosts do support instance modification.
+```
+
+## Set the status of an instance to primary
+
+> See also: [client.primary-name](/reference/settings/client-primary-name)
+
+This section demonstrates how to set the status of an instance to primary. This is convenient because it makes this instance the default argument for several commands, such as `shell` , `start` , `stop` , `restart` and `suspend`, and also automatically mounts your $HOME directory into the instance.
+
+To grant a regular instance the primary status, assign its name to the `client.primary-name`:
+
+```plain
+multipass set client.primary-name=
+```
+
+This setting allows transferring primary status among instances. The primary instance's name can be configured independently of whether instances with the old and new names exist. If they do, they lose and gain primary status accordingly.
+
+This provides a means of (de)selecting an existing instance as primary.
+
+### Example
+
+Assign the primary status to an instance called "first":
+
+```
+multipass set client.primary-name=first
+```
+
+This instance is picked up automatically by `multipass start`. When you run this command, the primary instance also automatically mounts the user's home directory into a directory called `Home`:
+
+```
+...
+Launched: first
+Mounted '/home/ubuntu' into 'first:Home'
+```
+
+Run `multipass stop` to stop the primary instance, and then launch another instance named "second":
+
+```
+multipass launch --name second
+```
+
+Now, change the primary instance to the existing "second" instance:
+
+```
+multipass set client.primary-name=second
+```
+
+From now on, the "second" instance will be used as the *primary* instance, so for example it will be used by default when you run the command `multipass suspend`.
+
+When listing instances, the primary one is displayed first. For example, if you run `multipass list` now, you'll see:
+
+```
+Name State IPv4 Image
+second Suspended -- Ubuntu 18.04 LTS
+first Stopped -- Ubuntu 18.04 LTS
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/manage-instances/remove-an-instance.md b/docs/how-to-guides/manage-instances/remove-an-instance.md
new file mode 100644
index 0000000000..330882fc64
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/remove-an-instance.md
@@ -0,0 +1,66 @@
+# Remove an instance
+> See also: [Instance](/explanation/instance)
+
+This guide demonstrates how to remove an instance, either temporarily or permanently.
+
+## Move an instance to the recycle bin
+
+> See also: [`delete`](/reference/command-line-interface/launch), [`recover`](/reference/command-line-interface/recover)
+
+To mark an instance as deleted, run:
+
+```plain
+multipass delete keen-yak
+```
+
+Now, if you run `multipass list` to list the instances, you will see that it is actually just marked for deletion (or to put it in other words, moved to the recycle bin):
+
+```plain
+Name State IPv4 Release
+keen-yak DELETED -- Not Available
+```
+
+You can move all instances to the recycle bin at once using the `--all` option:
+
+```plain
+multipass delete --all
+```
+
+Instances that have been marked as deleted can later be recovered; for example:
+
+```plain
+multipass recover keen-yak
+```
+
+If you try `multipass list` again, you'll see that the instance is no longer marked for deletion:
+
+```plain
+Name State IPv4 Release
+keen-yak STOPPED -- Ubuntu 18.04 LTS
+```
+
+## Remove an instance permanently
+
+> See also: [`delete`](/reference/command-line-interface/launch), [`purge`](/reference/command-line-interface/purge)
+
+If you want to get rid of all instances in `Deleted` status for good, you can purge them:
+
+```plain
+multipass delete keen-yak
+multipass purge
+```
+
+```{caution}
+The `purge` command does not take an argument. It will permanently remove all instances marked as `Deleted`.
+```
+
+You can also use the `--purge` option to permanently delete an instance in a single command; for example:
+
+```plain
+multipass delete --purge keen-yak
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md b/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md
new file mode 100644
index 0000000000..25d95d349c
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/run-a-docker-container-in-multipass.md
@@ -0,0 +1,143 @@
+# Run a Docker container in Multipass
+
+
+
+
+## Overview
+
+Multipass has a Docker blueprint that gives its users access to out-of-the-box Docker on any platform. This new blueprint makes it easy to develop and test Docker containers locally on macOS, Windows, or Linux.
+
+In this tutorial, you will see how to get started with the Docker blueprint by creating a blog in a Docker container in Multipass.
+
+### What you’ll learn
+
+- How to use Docker on macOS or Windows with Multipass
+
+- How to alias the `docker` command to your host command line
+
+- How to use [Portainer](https://www.portainer.io/) to launch a Docker container in [Multipass](http://multipass.run)
+
+### What you’ll need
+
+- Any computer with an internet connection
+
+## Install Multipass
+
+Duration: 3 minutes
+
+Let's start by installing Multipass on your machine, following the steps in [How to install Multipass](/how-to-guides/install-multipass).
+
+
+
+## Launch a Docker VM
+
+Duration: 1 minute
+
+Now that Multipass is installed, you can create a VM running Docker very simply. Open up a terminal and type
+
+```plain
+multipass launch docker
+```
+
+This command will create a virtual machine running the latest version of Ubuntu, with Docker and Portainer installed. You can now use Docker already! Try the command below to see for yourself!
+
+```plain
+multipass exec docker docker`
+```
+
+
+
+## Alias of the Docker commands
+
+Duration: 1 minute
+
+The Docker blueprint creates automatically two aliases, that is, two commands which can be run from the host to use commands in the instance as if they were in the host. In particular, the host `docker` command executes `docker` in the instance, and the host `docker-compose` command executes `docker-compose` in the instance.
+
+In order for these to work, you just need to add them to the path so that you can use them directly from your command line. If this was not done before, launching the Docker blueprint will return instructions showing how to add the aliases to your path. Simply copy and paste the command shown. It will likely be of this form:
+
+```plain
+PATH="$PATH:/home//snap/multipass/common/bin"
+```
+
+
+
+Run the command:
+
+```plain
+multipass launch docker
+```
+
+Sample output:
+
+```plain
+You'll need to add this to your shell configuration (.bashrc, .zshrc or so) for
+aliases to work without prefixing with `multipass`:
+
+PATH="$PATH:/home/nhart/snap/multipass/common/bin"
+```
+
+You can now use `docker` straight from the command line. To try it out, run
+
+```plain
+docker run hello-world
+```
+
+## Using Portainer
+
+Duration: 5 minutes
+
+Let's now go one step further, with Portainer. The Docker blueprint comes with Portainer installed, which gives an easy-to-use graphical interface for managing your Docker containers. To access Portainer, you will first need its IP address. The following command will show the IP addresses associated with the Ddocker VM you created in the previous steps:
+
+```plain
+multipass list
+```
+
+
+
+There should be two IP addresses listed, one for the Docker instance, the other for Portainer. The Portainer IP should start with a 10.
+
+In a web browser, enter the Portainer IP address from the previous step followed by the Portainer port, 9000, like this: “:9000”. Set up a username and password at the prompt, then select the option for managing a *local* Docker environment and click *connect*.
+
+
+
+Click on the newly created “Local” environment to manage the Docker instance on your local VM.
+
+
+
+## Launching a container
+
+Duration: 5 minutes
+
+For this tutorial, you will be creating a blog using the Ghost template in Portainer. Portainer has many other app templates if you are looking for more ideas. If you want more selection, you can launch containers from the Docker hub from Portainer or from the command line.
+
+Inside Portainer, click on **App Templates** in the left toolbar, and scroll down to the **Ghost** template.
+
+
+
+Now, you can configure and deploy the template. Enter a name and click deploy. The **bridge** network is the default and correct option.
+
+
+
+On the **Containers** page, you should now see two containers running. One containing Ghost, and the other containing Portainer itself.
+
+
+
+You can now access your Ghost blog by going to the published port indicated in the Containers page, i.e., **\:\**.
+
+
+
+There it is, your blog running within a Docker container inside Multipass!
+
+For next steps, try out Portainer’s other App Templates (Step 5), or check out [Docker Hub](https://hub.docker.com/search?type=image) for more containers to try. If you want to try out container orchestration, [Microk8s](https://microk8s.io/) or Multipass’ [Minikube](https://minikube.sigs.k8s.io/docs/) blueprint are great places to start.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/manage-instances/share-data-with-an-instance.md b/docs/how-to-guides/manage-instances/share-data-with-an-instance.md
new file mode 100644
index 0000000000..42906c6297
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/share-data-with-an-instance.md
@@ -0,0 +1,111 @@
+# Share data with an instance
+> See also: [Instance](/explanation/instance), [Mount](/explanation/mount), [ID mapping](/explanation/id-mapping), [`launch`](/reference/command-line-interface/launch), [`mount`](/reference/command-line-interface/mount), [`umount`](/reference/command-line-interface/umount), [`transfer`](/reference/command-line-interface/transfer)
+
+This guide explains how to share data between your host and an instance. There are two ways to accomplish this:
+* the `mount` command, that maps a local folder to a new or existing folder in the instance's filesystem
+* the `transfer` command, that copies files to and from an instance
+
+## Using `mount`
+
+You can use the [`multipass mount`](/reference/command-line-interface/mount) command to share data between your host and an instance, by making specific folders in your host's filesystem available in your instance's filesystem, with read and write permissions. Mounted paths are persistent, meaning that they will remain available until they are explicitly unmounted.
+
+The basic syntax of the `mount` command is:
+
+```plain
+multipass mount
+```
+
+For example, to map your local home directory on a Linux system (identified as $HOME) into the `keen-yak` instance, run this command:
+
+```plain
+multipass mount $HOME keen-yak
+```
+
+You can check the result running `multipass info keen-yak`:
+
+```plain
+…
+Mounts: /home/michal => /home/michal
+```
+
+From this point the local home directory `/home/michal` will be available inside the instance.
+
+If you want to mount a local directory to a different path in your instance, you can specify the target path as follows:
+
+```plain
+multipass mount $HOME keen-yak:/some/path
+```
+
+```{caution}
+If the `/some/path` directory already exists in the instance's filesystem, its contents will be temporarily hidden ("overlaid") by the mounted directory, but not overwritten. The original folder remains intact and will be revealed if you unmount.
+
+For this reason, it is not possible to mount an external folder path over the instance's $HOME directory, because it also contains the SSH keys required to access the instance: by hiding them, you would no longer be able to shell into the instance.
+```
+
+You can also define mounts when you create an instance, using the [`multipass launch`](/reference/command-line-interface/launch) command with the `--mount` option:
+
+```plain
+multipass launch --mount /local/path:/instance/path
+```
+
+### Unmounting shared directories
+
+To unmount previously mounted paths, use the [`multipass umount`](/reference/command-line-interface/umount) command.
+
+You can specify the folder path to unmount:
+
+```plain
+multipass umount keen-yak:/home/michal
+```
+
+or, if you don't specify any paths, unmount all shared folders at once:
+
+```plain
+multipass umount keen-yak
+```
+
+## Using `transfer`
+
+You can also use the [`multipass transfer`](/reference/command-line-interface/transfer) command to copy files from your local filesystem to the instance's filesystem, and vice versa.
+
+To indicate that a file is inside an instance, prefix its path with `:`.
+
+For example, to copy the `crontab` and `fstab` files from the `/etc` directory on the `keen-yak` instance to the `/home/michal` folder in the host's filesystem:
+
+```plain
+multipass transfer keen-yak:/etc/crontab keen-yak:/etc/fstab /home/michal
+```
+
+The files will be copied with the correct user mapping, as you'll see running the `ls -l /home/michal` command:
+
+```plain
+…
+-rw-r--r-- 1 michal michal 722 Oct 18 12:13 /home/michal/crontab
+-rw-r--r-- 1 michal michal 82 Oct 18 12:13 /home/michal/fstab
+…
+```
+
+The other way around, if you want to copy these files from your local filesystem into the instance, run the command:
+
+```plain
+multipass transfer /etc/crontab /etc/fstab keen-yak:/home/michal
+```
+
+In this case, the output of the `ls -l /home/michal` command on the instance will be:
+```plain
+…
+-rw-rw-r-- 1 ubuntu ubuntu 722 Oct 18 12:14 crontab
+-rw-rw-r-- 1 ubuntu ubuntu 82 Oct 18 12:14 fstab
+…
+```
+
+See also [ID mapping](/explanation/id-mapping) for more information on how the mount command maps user and group IDs between the host and the instance.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+---
+
+**Contributors:** @saviq, @nhart, @andreitoterman, @ricab, @gzanchi
+
diff --git a/docs/how-to-guides/manage-instances/use-a-blueprint.md b/docs/how-to-guides/manage-instances/use-a-blueprint.md
new file mode 100644
index 0000000000..4828236991
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/use-a-blueprint.md
@@ -0,0 +1,35 @@
+# Use a blueprint
+> See also: [Blueprint](/explanation/blueprint)
+
+Blueprints provide a shortcut to initialising Multipass instances for a variety of applications.
+
+To see what blueprints are available, run
+
+```plain
+multipass find --only-blueprints
+```
+
+> See more: [`multipass find`](/reference/command-line-interface/find)
+
+To use a blueprint run:
+
+```plain
+multipass launch
+```
+
+Launching a blueprint can take the same arguments as launching any other type of instance. If no further arguments are specified, the instance will launch with the defaults defined in the blueprint. Here’s an example of creating an instance from the Docker blueprint with a few more parameters specified:
+
+```plain
+multipass launch docker --name docker-dev --cpus 4 --memory 8G --disk 50G --bridged
+```
+
+This command will create an instance based on the Docker blueprint, with 4 CPU cores, 8GB of RAM, 50 GB of disk space, and connect that instance to the (predefined) bridged network.
+
+Blueprints also provide a way of exchanging files between the host and the instance. For this, a folder named `multipass/` is created in the user's home directory on the host and mounted in `` in the user's home directory on the instance.
+
+> See more: [`multipass launch`](/reference/command-line-interface/launch)
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/manage-instances/use-an-instance.md b/docs/how-to-guides/manage-instances/use-an-instance.md
new file mode 100644
index 0000000000..0a85a2cd02
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/use-an-instance.md
@@ -0,0 +1,157 @@
+# Use an instance
+> See also: [Instance](/explanation/instance)
+
+This document demonstrates various ways to use an instance.
+
+## Open a shell prompt inside an instance
+
+> See also: [`shell`](/reference/command-line-interface/shell)
+
+To open a shell prompt on an existing instance (e.g. `loving-duck`), run the command `multipass shell loving-duck`. The output will be similar to the following:
+
+```plain
+Welcome to Ubuntu 20.04.4 LTS (GNU/Linux 5.4.0-109-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com
+ * Management: https://landscape.canonical.com
+ * Support: https://ubuntu.com/advantage
+
+ System information as of Tue May 31 14:26:40 -03 2022
+
+ System load: 0.0 Processes: 113
+ Usage of /: 28.8% of 4.67GB Users logged in: 0
+ Memory usage: 21% IPv4 address for ens3: 10.49.93.241
+ Swap usage: 0%
+
+
+1 update can be applied immediately.
+To see these additional updates run: apt list --upgradable
+
+
+The list of available updates is more than a week old.
+To check for new updates run: sudo apt update
+
+To run a command as administrator (user "root"), use "sudo ".
+See "man sudo_root" for details.
+
+ubuntu@loving-duck:~$
+```
+
+If the instance `loving-duck` is `Stopped` or `Suspended`, it will be started automatically.
+
+If no argument is given to the `shell` command, Multipass will open a shell prompt on the primary instance (and also create it, if it doesn't exist).
+
+As shown in the example above, an Ubuntu prompt is displayed as a result of the `shell` command, where you can run commands inside the instance.
+
+To end the session, use `logout`, `exit`, or the `Ctrl-D` shortcut.
+
+[note type="information"]
+This is also available on the GUI.
+```
+
+## Run a command inside an instance
+
+> See also: [`exec`](/reference/command-line-interface/exec)
+
+To run a single command inside an instance, you don't need to open a shell. The command can be directly called from the host using `multipass exec`. For example, the command `multipass exec loving-duck -- pwd` returns:
+
+```plain
+/home/ubuntu
+```
+
+In the example, `/home/ubuntu` is the output of invoking the `pwd` command on the `loving-duck` instance.
+
+## Start an instance
+
+> See also: [`start`](/reference/command-line-interface/start)
+
+An existing instance that is in `Stopped` or `Suspended` status can be started with the `multipass start` command; for example:
+
+```plain
+multipass start loving-duck
+```
+
+You can start multiple instances at once, specifying the instance names in the command line:
+
+```plain
+multipass start loving-duck devoted-lionfish sensible-shark
+```
+
+To start all existing instances at once, use the `--all` option:
+
+```plain
+multipass start --all
+```
+
+If no options are specified, the `multipass start` command starts the primary instance, creating it if needed.
+
+[note type="information"]
+This is also available on the GUI.
+```
+
+## Suspend an instance
+
+> See also: [`suspend`](/reference/command-line-interface/suspend)
+
+An instance can be suspended with the command:
+
+```plain
+multipass suspend loving-duck
+```
+
+You can suspend multiple instances at once, specifying the instance names in the command line:
+
+```plain
+multipass suspend loving-duck devoted-lionfish sensible-shark
+```
+
+To suspend all running instances at once, use the `--all` option:
+
+```plain
+multipass suspend --all
+```
+
+If no options are specified, the `multipass suspend` command suspends the primary instance, if it exists and is running.
+
+## Stop an instance
+
+> See also: [`stop`](/reference/command-line-interface/stop)
+
+A running, not suspended instance is stopped with the command:
+
+```plain
+multipass stop loving-duck
+```
+
+You can stop multiple instances at once, specifying the instance names in the command line:
+
+```plain
+multipass stop loving-duck devoted-lionfish sensible-shark
+```
+
+To stop all running instances at once, use the `--all` option:
+
+```plain
+$ multipass stop --all
+```
+
+If no options are specified, the `multipass stop` command stops the primary instance, if it exists and is running.
+
+### Stop an instance forcefully
+
+If the `multipass stop` command doesn’t work, you can use the `--force` argument to force the instance to shut down immediately. This is particularly useful when the virtual machine is in a non-responsive, unknown or suspended state.
+
+```plain
+multipass stop --force
+```
+
+```{caution} The `stop --force` command is analogous to unplugging the power cord from a physical machine – it immediately halts all computing activities. This may be necessary under certain circumstances but can potentially lead to data loss or corruption. ```
+
+[note=information] This command is also available on the Multipass GUI. ```
+
+
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/manage-instances/use-instance-command-aliases.md b/docs/how-to-guides/manage-instances/use-instance-command-aliases.md
new file mode 100644
index 0000000000..dd98548c64
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/use-instance-command-aliases.md
@@ -0,0 +1,227 @@
+# Use instance command aliases
+> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases), [Instance](/explanation/instance).
+
+This guide demonstrates how to create, list, run and remove aliases for commands running inside an instance.
+
+## Create an alias
+
+> See also: [`alias`](/reference/command-line-interface/alias)
+
+To create an alias that runs a command on a given instance, use the command [`multipass alias`](/reference/command-line-interface/alias). The code below uses this command to create an alias `lscc` that will run the command `ls` inside an instance `crazy-cat`:
+
+```plain
+multipass alias crazy-cat:ls lscc
+```
+
+After running this command, the alias `lscc` is defined as running the command `ls` on the instance `crazy-cat`. If the alias name `lscc` is omitted, the alias name defaults to the name of the command to run (`ls` in this case).
+
+### Working directory mapping
+
+By default, if the host folder on which you are running an alias is mounted on the instance, the working directory on the instance is changed to the mounted directory. To avoid this behaviour, use the option `--no-map-working-directory` when defining the alias; for example:
+
+```plain
+multipass alias crazy-cat:pwd pwdcc --no-map-working-directory
+```
+
+### Alias contexts
+
+> See also: [`prefer`](/reference/command-line-interface/prefer)
+
+Contexts are sets of aliases. While one can safely work with one context, named `default`, contexts can be useful in some scenarios; for example, to define aliases with the same name in different instances.
+
+You can switch to using another context with `multipass prefer secondary`. Then, defining an alias in the new context is done in the usual way. The name of the alias can coincide with an already defined one. For example, `multipass alias cozy-canary:ls lscc`.
+
+## List the existing aliases
+
+> See also: [`aliases`](/reference/command-line-interface/aliases)
+
+To see the list of aliases defined so far, use the `multipass aliases` command.
+
+The output will be similar to the following:
+
+```plain
+Alias Instance Command Context Working directory
+lscc crazy-cat ls default map
+pwdcc crazy-cat pwd default default
+lscc cozy-canary ls secondary* map
+```
+
+The current context is marked with an asterisk.
+
+The column `Working directory` tells us on which directory of the host the alias will be run. The value `default` means that the alias will be run in the instance default working directory (normally, `/home/ubuntu`). The value `map` means that, in case the host directory from which the user calls the alias is mounted on the instance, the alias will be run on the mounted directory on the instance. The value will be `default` only if the `--no-map-working-directory` argument is present at alias creation.
+
+## Run an alias
+
+There are two ways to run an alias:
+* `multipass `
+* ``
+
+### `multipass `
+
+The first way of running an alias is invoking it with `multipass `, for example:
+
+```plain
+multipass lscc
+```
+
+This command opens a shell into the instance `cozy-canary`, runs `ls` and returns to the host command line, as if it was an `exec` command. Since we have defined two aliases with the same name, `lscc`, the one in the current context will be run.
+
+If you want to run an alias outside the current context, you can use a fully-qualified alias name:
+
+```plain
+multipass default.lscc
+```
+
+Arguments are also supported, provided you separate any options with `--`:
+
+```plain
+multipass lscc -- -l
+```
+
+or:
+
+```plain
+multipass default.lscc -- -l
+```
+
+### ``
+
+The second way of running an alias is a two-step process:
+
+1. Add the Multipass alias script folder to the system path.
+2. Run the alias.
+
+#### Add the Multipass alias script folder to the system path
+
+The instructions to add the Multipass alias script folder to the system path are displayed the first time you create an alias, and vary for each platform. For instance, when you run the command:
+
+```plain
+multipass alias crazy-cat:ls lscc
+```
+
+the following output is displayed:
+
+```plain
+You'll need to add this to your shell configuration (.bashrc, .zshrc or so) for
+aliases to work without prefixing with `multipass`:
+
+PATH="$PATH:/home/user/snap/multipass/common/bin"
+```
+
+[tabs]
+
+[tab version="Linux"]
+
+On Linux, you'll have to edit the shell configuration file. In most Linux distributions, the shell used by default is `bash`. You can configure this option by editing the file `.bashrc` in the user's home directory using a text editor; for example:
+
+```plain
+nano ~/.bashrc
+```
+
+You can modify the path by appending a line to the `.bashrc` file, such as:
+
+```plain
+export PATH="$PATH:/home/user/snap/multipass/common/bin"
+```
+
+[note type="information"]
+Remember to replace the correct folder, as indicated in the output of the Multipass command above, and to restart the shell when done.
+
+If your shell is `zsh` and not `bash`, the file to modify is `.zshrc` instead of `.bashrc`. The procedure is the same.
+```
+
+[/tab]
+
+[tab version="macOS"]
+
+On macOS, you'll have to edit the shell configuration file. The shell used by default is `zsh`. You can configure this option by editing the file `.zshrc` in the user's home directory using a text editor.
+
+You can modify the path by appending a line to the `.zshrc` file, such as:
+
+
+```plain
+export PATH="$PATH:/Users//Library/Application Support/multipass/bin"
+```
+
+[note type="information"]
+Remember to replace the correct folder, as indicated in the output of the Multipass command above, and to restart the shell when done.
+```
+
+[/tab]
+
+[tab version="Windows"]
+
+On Windows, to make the change permanent, use PowerShell to store the old system path, add the alias folder to it, and store the new path:
+
+```powershell
+$old_path = (Get-ItemProperty -Path 'Registry::HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment' -Name PATH).path
+$new_path = “$old_path;C:\Users\\AppData\Local\Multipass\bin”
+Set-ItemProperty -Path 'Registry::HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Session Manager\Environment' -Name PATH -Value $new_path
+```
+
+Don't forget to restart your terminal. The folder is now permanently added to your path, and Multipass can now run aliases just invoking their name.
+
+[/tab]
+
+[/tabs]
+
+#### Run the alias
+
+Once you've added the alias folder to the system path, you can run it directly from the command line, without the need to also mention `multipass`; for example:
+
+```plain
+lscc
+```
+
+or:
+
+```plain
+default.lscc
+```
+
+Since the path has been added to the system path, this command is equivalent to `multipass lscc`. Arguments are also supported, without the need for `--`:
+
+```plain
+lscc -l
+```
+
+## Remove an alias
+
+> See also: [`unalias`](/reference/command-line-interface/unalias)
+
+Finally, to remove the alias `lscc`, run the following command:
+
+```plain
+multipass unalias lscc
+```
+
+or:
+
+```plain
+multipass unalias default.lscc
+```
+
+The `unalias` command accepts many arguments, specifying more than one alias to remove. For example, you can remove both aliases `lscc` and `pwdcc` at once:
+
+```plain
+multipass unalias lscc pwdcc
+```
+
+You can also use the `--all` option to remove all the defined aliases in the current context at once:
+
+```plain
+multipass unalias --all
+```
+
+[note type="information]
+Aliases are also removed when the instance for which they were defined is deleted and purged. This means that `multipass delete crazy-cat --purge` will also remove the aliases `lscc` and `pwdcc`.
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+---
+
+**Contributors:** @luisp , @saviq , @tmihoc , @andreitoterman , @itecompro , @ricab , @gzanchi , @sharder996
+
diff --git a/docs/how-to-guides/manage-instances/use-the-docker-blueprint.md b/docs/how-to-guides/manage-instances/use-the-docker-blueprint.md
new file mode 100644
index 0000000000..5745160bfa
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/use-the-docker-blueprint.md
@@ -0,0 +1,27 @@
+# Use the Docker blueprint
+The Docker blueprint gives Multipass users an easy way to create Ubuntu instances with Docker installed. It is based on the latest LTS release of Ubuntu, and includes docker engine and [Portainer](https://www.portainer.io/). The Docker blueprint automatically aliases the `docker` and `docker-compose` commands to your host, and creates a workspace that is shared between the host and the instance.
+
+To use the Docker blueprint, run `multipass launch docker`, which will launch an instance with default parameters.
+
+Next, follow the instructions in the output to add the aliased command to your path, it should look something like this:
+
+```plain
+You'll need to add this to your shell configuration (.bashrc, .zshrc or so) for
+
+aliases to work without prefixing with `multipass`:
+
+PATH="$PATH:/home/user/snap/multipass/common/bin"
+```
+
+[note type=tip]
+Running `which docker` from your host command line should confirm that you are running Docker inside Multipass.
+```
+
+To access Portainer, run `multipass ls` and copy the IP address of the multipass instance (the first in the list), then enter it into your browser followed by a colon and Portainer’s port number, 9000 (something like this: 10.21.145.191:9000). This gives you Portainer's web interface for visually managing your containers.
+
+You can mount files into this instance as with any Multipass instance, but the default shared workspace is an easy way to edit your `dockerfiles` and `docker-compose.yaml` files from your host. With working directory mapping, you can run the `docker-compose` command from your host inside the shared directory, and have it run within that same directory in your Multipass instance.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/manage-instances/use-the-primary-instance.md b/docs/how-to-guides/manage-instances/use-the-primary-instance.md
new file mode 100644
index 0000000000..3144736184
--- /dev/null
+++ b/docs/how-to-guides/manage-instances/use-the-primary-instance.md
@@ -0,0 +1,83 @@
+# Use the primary instance
+> See also: [Instance](/explanation/instance), [client.primary-name](/reference/settings/client-primary-name), [`shell`](/reference/command-line-interface/shell), [`mount`](/reference/command-line-interface/mount)
+
+Multipass offers a quick way to access an Ubuntu instance via a simple `multipass shell` command. This is achieved via the so-called [primary instance](/t/28469#primary-instance) that is also automatically created (if it doesn't exist) when the user runs the [`multipass start`](/reference/command-line-interface/start) or [`multipass shell`](/reference/command-line-interface/shell) commands without any arguments.
+
+When automatically created, the primary instance gets the same properties as if [`launch`](/reference/command-line-interface/launch) was used with no arguments, except for the name (`primary` by default). In particular, this means that the instance will use the latest Ubuntu LTS image and will have the default CPU, disk and memory configuration.
+
+You can also launch the primary instance with additional parameters, as you would do for any other instance. This provides one way to fine-tune its properties (e.g. `multipass launch --name primary --cpus 4 lts`). Alternatively, you can set another instance as primary, as explained in [Changing the primary instance](#changing-the-primary-instance) below.
+
+There can be only one primary instance at any moment. If it exists, it is always listed first in the output of `list` and `info`.
+
+## Steering the primary instance
+
+The primary instance can also be controlled from the [tray icon](/t/28484#tray-icon) menu.
+
+In the command line, it is used as the default when no instance name is specified in the `shell`, `start`, `stop`, `restart` and `suspend` commands. When issuing one of these commands with no positional arguments, the primary instance is targeted. Its name can still be given explicitly wherever an instance name is expected (e.g. `multipass start primary`).
+
+## Automatic home mount
+
+When launching the primary instance, whether implicitly or explicitly, Multipass automatically mounts the user's home inside it, in the folder `Home`. As with any other mount, you can unmount it with `multipass umount`. For instance, `multipass umount primary` will unmount all mounts made by Multipass inside `primary`, including the auto-mounted `Home`.
+
+[note type=information]
+On Windows mounts are disabled by default for security reasons. See [`multipass set`](/reference/command-line-interface/set) and [local.privileged-mounts](/reference/settings/local-privileged-mounts) for information on how to enable them if needed.
+```
+
+## Changing the primary instance
+
+The primary instance is identified as such by its name. The name that designates an instance as the primary one is determined by a configuration setting with the key `client.primary-name`. In other words, while `primary` is the default name of the primary instance, you can change it with `multipass set client.primary-name=`.
+
+This setting allows transferring primary status among instances. You can configure the primary name independently of whether instances with the old and new names exist. If they do, they lose and gain primary status accordingly.
+
+This provides a means of (de)selecting an existing instance as primary. For example, after `multipass set client.primary-name=first`, the primary instance would be called `first`. A subsequent `multipass start` would start `first` if it existed, and launch it otherwise.
+
+## Example
+
+Here is a long-form example of how Multipass handles the primary instance.
+
+Set the name of the primary instance and start it:
+
+```plain
+multipass set client.primary-name=first
+multipass start
+```
+
+Sample output:
+
+```plain
+Launched: first
+Mounted '/home/ubuntu' into 'first:Home'
+```
+
+Now, stop the primary and launch another instance:
+
+```plain
+multipass stop
+multipass launch eoan
+```
+
+Sample output:
+
+```plain
+Launched: calm-chimaera
+```
+
+Change the `client.primary-name` setting to the newly launched instance, and review the list of existing instances:
+
+```plain
+multipass set client.primary-name=calm-chimaera
+multipass list
+```
+
+Sample output:
+
+```plain
+Name State IPv4 Image
+calm-chimaera Running 10.122.139.63 Ubuntu 19.04 LTS
+first Stopped -- Ubuntu 18.04 LTS
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/troubleshoot/access-logs.md b/docs/how-to-guides/troubleshoot/access-logs.md
new file mode 100644
index 0000000000..0603cf89d9
--- /dev/null
+++ b/docs/how-to-guides/troubleshoot/access-logs.md
@@ -0,0 +1,47 @@
+# Access logs
+Logs are our first go-to when something goes wrong. Multipass is comprised of a daemon process (service) and the [CLI](/reference/command-line-interface/command-line-interface) and [GUI](/reference/gui-client) clients, each of them reporting on their own health.
+
+The `multipass` command accepts the `--verbose` option (`-v` for short), which can be repeated to go from the default (*error*) level through *warning*, *info*, *debug* up to *trace*.
+
+We use the underlying platform's logging facilities to ensure you get the familiar behaviour wherever you are.
+
+[tabs]
+
+[tab version="Linux"]
+
+On Linux, [`systemd-journald`](https://www.freedesktop.org/software/systemd/man/systemd-journald.service.html) is used, integrating with the de-facto standard for this on modern Linux systems.
+
+To access the daemon (and its child processes') logs:
+
+```console
+journalctl --unit 'snap.multipass*'
+```
+
+The Multipass GUI produces its own logs, that can be found under `~/snap/multipass/current/data/multipass_gui/multipass_gui.log`
+
+[/tab]
+
+[tab version="macOS"]
+
+On macOS, log files are stored in `/Library/Logs/Multipass`, where `multipassd.log` has the daemon messages. You will need `sudo` to access it.
+
+The Multipass GUI produces its own logs, that can be found under `~/Library/Application\ Support/com.canonical.multipassGui/multipass_gui.log`
+
+[/tab]
+
+[tab version="Windows"]
+
+On Windows, the Event system is used and Event Viewer lets you access them. Our logs are currently under "Windows Logs/Application", where you can filter by "Multipass" Event source. You can then export the selected events to a file.
+
+Logs from the installation and uninstall process can be found under `%APPDATA%\Local\Temp`. Sort the contents of the directory by "Date Modified" to bring the newest files to the top. The name of the file containing the logs follows the pattern `MSI[0-9a-z].LOG`.
+
+The Multipass GUI produces its own logs, that can be found under `%APPDATA%\com.canonical\Multipass GUI\multipass_gui.log`
+
+[/tab]
+
+[/tabs]
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/how-to-guides/troubleshoot/index.md b/docs/how-to-guides/troubleshoot/index.md
new file mode 100644
index 0000000000..fdf20326ac
--- /dev/null
+++ b/docs/how-to-guides/troubleshoot/index.md
@@ -0,0 +1,21 @@
+# Troubleshoot
+The following guides provide step-by-step instructions on how to troubleshoot issues with your Multipass installation, beginning by inspecting the logs.
+
+- [Access logs](/how-to-guides/troubleshoot/access-logs)
+- [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder)
+- [Troubleshoot launch/start issues](/how-to-guides/troubleshoot/troubleshoot-launch-start-issues)
+- [Troubleshoot networking](/how-to-guides/troubleshoot/troubleshoot-networking)
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+
+```{toctree}
+:hidden:
+:titlesonly:
+:maxdepth: 2
+:glob:
+
+*
+*/index
diff --git a/docs/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md b/docs/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md
new file mode 100644
index 0000000000..cec29270c2
--- /dev/null
+++ b/docs/how-to-guides/troubleshoot/mount-an-encrypted-home-folder.md
@@ -0,0 +1,26 @@
+# Mount an encrypted home folder
+
+
+
+> See also: [`mount`](/reference/command-line-interface/mount), [Instance](/explanation/instance)
+
+When you create the [primary instance](/t/28469#primary-instance-1) using `multipass start` or `multipass shell` without additional arguments, Multipass automatically mounts your home directory into it.
+
+On Linux, if your local home folder is encrypted using ` fscrypt`, [snap confinement](https://snapcraft.io/docs/snap-confinement) prevents you from accessing its contents from a Multipass mount due the peculiar directory structure (`/home/.ecryptfs//.Private/`). This also applies to the primary instance, where the home folder is mounted automatically.
+
+A workaround is mounting the entire `/home` folder into the instance, using the command:
+
+```plain
+multipass mount /home primary
+```
+
+By doing so, the home folder's contents will be mounted correctly.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+---
+
+**Contributors:** @ricab, @gzanchi
+
diff --git a/docs/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md b/docs/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md
new file mode 100644
index 0000000000..78a7f02e9f
--- /dev/null
+++ b/docs/how-to-guides/troubleshoot/troubleshoot-launch-start-issues.md
@@ -0,0 +1,289 @@
+# Troubleshoot launch/start issues
+
+
+This topic addresses common issues when launching or starting instances, such as *timeouts or "unknown state" errors*.
+
+These problems can occur for a few different reasons. Since Multipass relies on instances having an IP address on the default interface to establish an SSH connection, they are often (but not always) linked to IP assignment or connectivity issues.
+
+The possible reasons that can lead the `launch` or `start` commands to fail are:
+
+1. When you launch a new instance, it fails to load the required image due to stale network cache.
+2. The VM didn't manage to boot properly and didn't get to the point where it requests an IP address.
+3. The VM requested an IP address, but didn't obtain one.
+4. The VM obtained an IP address, but:
+ 1. Multipass can't find it.
+ 2. Multipass finds an IP that doesn't match the one that was assigned to the instance.
+5. SSH doesn't function properly in the VM, or Multipass is blocked from accessing it.
+6. When you launch a new instance, it times out waiting for initialization to complete.
+
+## Diagnose your issue
+
+Follow these steps to diagnose your issue and identify the most likely scenario:
+
+1. If the `multipass launch` command fails with the message "Downloaded image hash does not match", see: [Stale network cache](#stale-network-cache-6).
+
+1. [Windows, Hyper-V driver] Inspect the file `C:\WINDOWS\System32\drivers\etc\hosts.ics` and see if there is more than one entry with your instance name in it. If that's the case, see: [Stale internet connection sharing lease](#stale-internet-connection-sharing-lease).
+
+1. [Linux/macOS, QEMU driver] Inspect the Multipass logs and look for a message mentioning `NIC_RX_FILTER_CHANGED`. This message indicates that the network interface has been initialised.
+ * If you don't find it, it means that the VM didn't manage to bring up the interface; see: [VM boot failure](#vm-boot-failure-3).
+ * If the message is present, proceed to check DHCP traffic in the next step.
+
+1. [Linux/macOS, QEMU driver] Check DHCP traffic from your host to the instance, to find out if there are requests and replies. Adapt and run the following command *right after starting/launching* the instance:
+
+ ```
+ sudo tcpdump -i udp port 67 and port 68
+ ```
+
+ You will need to replace `` with `mpqemubr0` on Linux and with `bridge100` on macOS.
+
+ ```{note}Note that, on macOS, `bridge100` is a virtual network interface that only appears when at least a VM is running.```
+
+ * If you see `NIC_RX_FILTER_CHANGED`, you should also see DHCP requests. If you don't, see [VM boot failure](#vm-boot-failure-3) and please [let us know](https://github.com/canonical/multipass/issues/new/choose).
+ * If you see a DHCP request, but no reply, it means that the VM is still waiting for an IP address to be assigned; see: [No IP assigned](#no-ip-assigned-4).
+ * If you see DHCP requests and replies, continue to the next step.
+
+1. Look for messages regarding SSH in Multipass's logs. The instance may have obtained an IP and/or be properly connected, but still refuse Multipass when it tries to SSH into it.
+
+1. Look for the message in the CLI or GUI spinner. Once it reads "Waiting for initialization to complete", Multipass willl have succeeded SSH-ing into the instance but remain waiting for cloud-init to finish.
+
+## Troubleshooting steps
+
+### VM boot failure
+
+To find out if something is failing during boot, you'd need to attach to the VM's console/serial and observe the output and try to find out where the VM is getting stuck. Here is how you can do that, depending on the driver:
+
+- [Linux/macOS, QEMU driver] Relaunch QEMU manually:
+ 1. Look for the `qemu-system-*` command line corresponding to the failing VM in Multipass logs
+ 2. copy it to an editor and modify it
+ 1. remove `-serial chardev:char0 -nographic`
+ 2. escape any spaces in paths (e.g. `Application Support` should become `Application\ Support`)
+ 3. Run the edited line in a terminal, with `sudo`. Here is an example:
+ ```
+ /Library/Application\ Support/com.canonical.multipass/bin/qemu-system-aarch64 -machine virt,gic-version=3 -accel hvf -drive file=/Library/Application\ Support/com.canonical.multipass/bin/../Resources/qemu/edk2-aarch64-code.fd,if=pflash,format=raw,readonly=on -cpu host -nic vmnet-shared,model=virtio-net-pci,mac=52:54:00:e2:30:dd -device virtio-scsi-pci,id=scsi0 -drive file=/var/root/Library/Application\ Support/multipassd/qemu/vault/instances/superior-chihuahua/ubuntu-22.04-server-cloudimg-arm64.img,if=none,format=qcow2,discard=unmap,id=hda -device scsi-hd,drive=hda,bus=scsi0.0 -smp 2 -m 4096M -qmp stdio -cdrom /var/root/Library/Application\ Support/multipassd/qemu/vault/instances/superior-chihuahua/cloud-init-config.iso
+ ```
+ This will open a QEMU window where you can see the boot output. You may need to select the correct display output (Serial or VGA) from the QEMU menu.
+
+- [macOS/Windows, VirtualBox driver] Observe the output in the VirtualBox GUI:
+ 1. Run the VirtualBox GUI as admin/root:
+ - [macOS] `sudo VirtualBox`
+ - [Windows] [Run with `psexec.exe`](...):
+ 2. Start or launch the instance with `multipass start|launch`
+ 3. Select and attach to the VM in the VirtualBox GUI and observe the boot output. If it eventually arrives at a login screen, it means that the instance should've started correctly.
+
+- [Windows, Hyper-V driver]
+ 1. Open the Hyper-V Manager GUI (look for it in your Start menu)
+ 2. Start or launch the instance with `multipass start|launch`
+ 2. Select the VM in Hyper-V manager and click "Connect" on the Actions pane, at the right-hand side. Observe the boot output.
+
+#### VM image corruption
+
+Boot failures are often caused by VM image corruption, which can happen when the VM is killed without a proper shutdown.
+
+Here are some options to attempt recovery:
+
+- If you took a [snapshot](/explanation/snapshot) before incurring this issue, you could try to restore it. However, snapshots are typically stored layers against an original image file, so they may not be enough.
+- **Run [`fsck`](https://manpages.ubuntu.com/manpages/oracular/en/man8/fsck.8.html) in the Serial Console:**
+
+ The `fsck` tool (short for "file system consistency check") is used to scan the file system for errors and attempt repairs.
+
+ **To use it, access the VM’s console as described above and follow these steps:**
+
+ 1. **Access the VM's Console**
+
+ - Use the method appropriate for your driver to access the VM's console, as described in the [VM Boot Failure](#vm-boot-failure) section.
+
+ 2. **Interrupt the Boot Process**
+
+ - As the VM starts booting, interrupt the boot process to access the GRUB menu:
+ - Press the `Esc` key repeatedly during the VM's startup until the GRUB menu appears.
+ - On some systems, you might need to hold down the `Shift` key instead.
+ - The key needs to be pressed at just the right time, after UEFI loading (to avoid getting into the UEFI screen), but before Ubuntu starts booting (to trigger GRUB)
+
+ 3. **Enter Recovery Mode**
+
+ - In the GRUB menu:
+ - Use the arrow keys to select **Advanced options for Ubuntu** (or your distribution's equivalent) and press `Enter`.
+ - Select a kernel version with `(recovery mode)` appended and press `Enter`.
+
+ 4. **Run `fsck` from Recovery Menu**
+
+ - Once in the recovery menu:
+ - Use the arrow keys to highlight **`fsck`** and press `Enter`.
+ - You will be prompted to remount the filesystem in read/write mode. Select **Yes**.
+ - The system will run `fsck` and attempt to repair any detected issues.
+
+ 5. **Alternatively, Drop to a Root Shell**
+
+ - If you prefer to run `fsck` manually:
+ - From the recovery menu, select **`root`** to drop to a root shell prompt.
+ - At the prompt, run the following commands:
+
+ ```bash
+ mount -o remount,ro /
+ fsck -f /
+ ```
+
+ - After `fsck` completes, remount the filesystem in read/write mode:
+
+ ```bash
+ mount -o remount,rw /
+ ```
+
+ - Type `exit` to return to the recovery menu.
+
+ 6. **Resume Normal Boot**
+
+ - In the recovery menu, select **`resume`** to continue with the normal boot process.
+ - The system should now boot normally if `fsck` was able to repair the filesystem.
+
+- [Linux/macOS] Alternatively, run `fsck` over a [mounted image](#reading-data-from-a-qcow2-image-12) on the host.
+- Run `qemu-img check -r` on the image.
+ * `qemu-img`, shipped with Multipass, can also be used to check and repair disk images.
+ * See below how to [locate it](#locating-multipass-binaries-draft).
+ * See [here](#locating-multipass-images-draft) on how to locate images.
+ * For example:
+ ```
+ /Library/Application\ Support/com.canonical.multipass/bin/qemu-img check -r /var/root/Library/Application\ Support/multipassd/qemu/vault/instances//![]()
+ ```
+- If none of the above works, you can still try to [mount the image manually]() to recover data.
+
+### No IP assigned
+
+Sometimes VMs request an IP address, but don't obtain one. That can happen because of interference from other software, VPNs, network misconfiguration and, firewall settings.
+
+#### [macOS, QEMU driver] Firewall blocks `bootp`
+
+The macOS firewall is known to cause `vmnet` to malfunction, because it blocks Apple's own `bootp` from giving out IPs. The effect of this problem on Multipass is tracked in [this issue](https://github.com/canonical/multipass/issues/2387), which we internally call the *dreaded firewall issue*.
+
+You may be able to work around it by disabling the firewall entirely, or executing
+
+```
+/usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd
+/usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd
+```
+
+We are aware that this requires administrative privileges, which managed Macs won't have. We unfortunately don't have a better fix for those cases. We continue hoping that Apple will eventually fix the problem which, to the best of our knowledge, affects all products using `vmnet`. Chances of that happening will probably increase if enough people [report it to them](https://developer.apple.com/bug-reporting/).
+
+> See also: [How to troubleshoot networking](/how-to-guides/troubleshoot/troubleshoot-networking).
+>
+#### [macOS, QEMU driver] `bootp` not coming up
+
+The DHCP server should be launched automatically when there is a request, but you can also launch it manually if needed. To do so, run:
+
+```
+sudo launchctl start com.apple.bootpd
+```
+
+If that doesn't work for you, try :
+
+```
+sudo launchctl load -w /System/Library/LaunchDaemons/bootps.plist
+```
+
+### [Windows, with Hyper-V] Stale internet connection sharing lease
+
+Another possible reason for instance timeouts is a problem with the `Internet Connection Sharing` hosts file. This file sometimes gets corrupted, with jumbled or incomplete text. Other times, it contains duplicate or stale IP addresses.
+
+Using Administrator privileges, edit the file `C:\WINDOWS\System32\drivers\etc\hosts.ics` and look for any corruption or entries that have your instance name in it. If there is more than one entry, remove any of them except for the first one listed. Save the file and try again. If that does not work, stop any running instances, delete the file, and reboot.
+
+### SSH issues **(DRAFT)**
+
+If SSH doesn't function properly in the VM, or Multipass is blocked from accessing it, your instance may need to be reconfigured or repaired.
+
+* If the default user is not `ubuntu`, Multipass cannot connect. If you used a custom cloud-init config file, make sure that the default user is `ubuntu`.
+
+* if SSH keys are missing or incorrect, you will have to add your public SSH key from `~/.ssh/id_rsa.pub` on the host to `~/.ssh/authorized_keys` in the instance. To do so you may need to gain access to the instance through a method besides SSH.
+
+To gain access to an instance without SSH you can try the following methods.
+
+* [Mount the instance's image file](#reading-data-from-a-qcow2-image-13) on your host and make necessary changes through the filesystem.
+
+* Run the instance VM directly. This will require a username and password to log in. The username is the default user, `ubuntu`, and the password is what was set in cloud-init if you used a custom cloud-init config. If you do not have a password you can modify the instance's `cloud-init-config.iso` file to change it. One way to do so is as follows.
+ 1. Back up your existing `cloud-init-config.iso`.
+ 2. Make a new instance by running `multipass launch --cloud-init config.yaml`, the contents `config.yaml` are shown below.
+ 3. Replace your existing `cloud-init-config.iso` with the newly generated `cloud-init-config.iso`.
+ 4. Restart the VM and use the password `ubuntu`. The instance's password will remain `ubuntu` unless it is changed again
+ 5. Make necessary changes.
+
+```
+#cloud-config
+password: ubuntu
+chpasswd: { expire: false }
+```
+
+### Cloud-init tarries during an instance launch **(DRAFT)**
+
+- When launching a new instance, once Multipass obtains an SSH session to the instance, it will wait for cloud-init to complete. During this phase, the CLI/GUI spinner reads "Waiting for initialization to complete".
+
+- At this point, the initialization continues in the background, even if you interrupt the launch command or if it times out.
+
+- So if you wait for a little while longer, your instance may eventually finish setting up. When it does, it will have this file: `/var/lib/cloud/instance/boot-finished`.
+ * Consider passing a longer timeout to the `launch` command. For example, `multipass launch --timeout 1000` sets the launch timeout to 1000 seconds.
+
+* You can use `multipass shell` to get a shell in the instance when Multipass is waiting for cloud-init to finish. To diagnose problems, inspect cloud-init's logs in `/var/log/cloud-init*log`.
+
+### [Windows, VirtualBox driver] Running VirtualBox with the system account
+
+To run the VirtualBox GUI with the system account, you will need a Windows tool called PsExec:
+
+1. Install [PsExec](https://docs.microsoft.com/en-us/sysinternals/downloads/psexec)
+1. Add it to your `PATH`
+1. Run PowerShell as Administrator
+1. Execute `psexec.exe -s -i "C:\Program Files\Oracle\VirtualBox\VirtualBox.exe"` (adapt the path to the VirtualBox executable as needed)
+
+When successful, you should see Multipass's instances in VirtualBox
+
+### Stale network cache
+
+This can be caused by a known Qt bug (see issue [#1714](https://github.com/canonical/multipass/issues/1714) on our GitHub).
+
+A workaround to resolve this issue is to run the command `multipass find --force-update`, which forces downloading the image information from the network. As a result, if the download is successful, the `network-cache` will be overwritten.
+
+Alternatively, try deleting the `network-cache` folder and restart the Multipass service:
+
+* (on Linux)
+ ```
+ sudo snap stop multipass
+ sudo rm -rf /var/snap/multipass/common/cache/multipassd/network-cache/
+ sudo snap start multipass
+ ```
+* (on macOS)
+ ```
+ sudo launchctl unload /Library/LaunchDaemons/com.canonical.multipassd.plist
+ sudo rm -rf /System/Volumes/Data/private/var/root/Library/Caches/multipassd/network-cache
+ sudo launchctl load /Library/LaunchDaemons/com.canonical.multipassd.plist
+ ```
+* (on Windows)
+ Remove `C:\ProgramData\Multipass\cache\network-cache` and restart the Multipass service.
+
+### Reading data from a QCOW2 image
+
+The images that Multipass uses with the QEMU driver follow a standard format — QCOW2 — which other tools can read.
+
+One example is [`qemu-nbd`](https://manpages.ubuntu.com/manpages/oracular/en/man8/qemu-nbd.8.html), which allows mounting the image. This tool is not shipped with Multipass, so you would need to install it manually.
+
+Once you have it, you can search the web for recipes to "mount a QCOW2 image". For example, here is a [a recipe](https://askubuntu.com/a/4404).
+
+### Locating Multipass Binaries **(DRAFT)**
+You may need to locate where Multipass is installed. There are several ways to do so, depending on your platform:
+* (on Linux)
+ * Run the command `which multipass` or `whereis multipass`.
+ * By default, Multipass is installed in the `/snap/bin` folder.
+
+* (on Windows)
+ * Run the command `where.exe multipass`.
+ * Right-click a shortcut to Multipass in your files or Start menu and select "Open file location".
+ * By default, Multipass is installed in the `C:\Program Files\Multipass\bin` folder.
+
+* (on MacOS)
+ * Run the command `readlink -f $(which multipass)`
+ * By default, Multipass is installed in the `/Library/Application\ Support/com.canonical.multipass/bin/` folder.
+
+### Locating Multipass Images **(DRAFT)**
+You may need to locate where Multipass is storing instances. The location changes depending on your platform:
+* (Linux) `/root/.local/share/multipassd/vault/instances/`
+
+* (Windows) `C:\ProgramData\Multipass\data\vault\instances\\![]()
`
+
+* (MacOS) `/var/root/Library/Application\ Support/multipassd/qemu/vault/instances//![]()
`
+
diff --git a/docs/how-to-guides/troubleshoot/troubleshoot-networking.md b/docs/how-to-guides/troubleshoot/troubleshoot-networking.md
new file mode 100644
index 0000000000..9d7f490b14
--- /dev/null
+++ b/docs/how-to-guides/troubleshoot/troubleshoot-networking.md
@@ -0,0 +1,322 @@
+# Troubleshoot networking
+
+
+This document demonstrates how to troubleshoot various known Multipass networking issues on macOS and Windows.
+
+## Troubleshoot networking on macOS
+
+### Architecture
+
+On macOS, the QEMU driver employs the Hypervisor.framework. This framework manages the networking stack for the instances.
+
+On creation of an instance, the Hypervisor framework on the host uses macOS’ **Internet Sharing** mechanism to:
+
+1. Create a virtual switch and connect each instance to it (subnet 192.168.64.*).
+2. Provide DHCP and DNS resolution on this switch at 192.168.64.1 (via bootpd & mDNSResponder services running on the host). This is configured by an auto-generated file (`/etc/bootpd.plist`), but editing this is pointless as MacOS regenerates it as it desires.
+
+Note that, according to **System Preferences > Sharing**, the **Internet Sharing** service can appear disabled. This is fine---in the background, it will still be enabled to support instances.
+
+### Tools known to interfere with Multipass
+
+* VPN software can be aggressive at managing routes and may route 192.168.64 subnet through the VPN interface, instead of keeping it locally available.
+ * Possible culprits: OpenVPN, F5, Dell SonicWall, Cisco AnyConnect, Citrix/Netscaler Gateway, Jupiter Junos Pulse / Pulse Secure
+ * Tunnelblick doesn’t cause problems
+* Cisco Umbrella Roaming Client it binds to localhost:53 which clashes with Internet Sharing, breaking instance’s DNS (ref: [Umbrella Roaming Client OS X and Internet Sharing](https://support.umbrella.com/hc/en-us/articles/230561007-Umbrella-Roaming-Client-OS-X-and-Internet-Sharing))
+* dnscrypt-proxy/dnscrypt-wrapper/cloudflared-proxy \
+Default configuration binds to localhost port 53, clashing with Internet Sharing.
+* another dnsmasq process bound to localhost port 53
+* custom DHCP server bound to port 67? ("sudo lsof -iUDP:67 -n -P" should show launchd & bootpd only)
+* MacOS update can make changes to the firewall and leave instances in unknown state (see [below](heading--issues-caused-by-macos-update)).
+
+### Problem class
+
+* `multipass launch` fails
+ * go to ["Generic networking" section](#generic-networking-problems)
+* `multipass shell ` fails
+ * go to ["Network routing" section](#network-routing-problems)
+* `multipass shell ` works but the instance cannot connect to the internet
+ * go to ["DNS" section](#dns-problems)
+* extra IPs not reachable between instances
+ * go to ["ARP" section](#arp-problems)
+
+#### Generic networking problems
+
+`Unable to determine IP address` usually implies some networking configuration is incompatible, or there is interference from a Firewall or VPN.
+
+
+
+##### Troubleshooting
+
+1. Firewall
+ 1. Is Firewall enabled?
+ 1. If so it must not "Block all incoming connections"
+ * Blocking all incoming connections prevents a DHCP server from running locally, to give an IP to the instance.
+ * It’s OK to block incoming connections to "multipassd" however.
+1. VPN
+1. Little Snitch - defaults are good, it should permit mDNSResponder and bootpd access to BPF
+If you're having trouble downloading images and/or see `Unknown error`s when trying to `multipass launch -vvv`, Little Snitch may be interfering with `multipassd`'s network access (ref. [#1169](https://github.com/CanonicalLtd/multipass/issues/1169))
+1. Internet Sharing - doesn’t usually clash
+1. Is the bootpd DHCP server alive? (`sudo lsof -iUDP:67 -n -P` should mention `bootpd`)
+ - It should be launched automatically when there is a request, but you can also launch it manually if needed.
+ - Start it by running `sudo launchctl start com.apple.bootpd`. If that doesn't work for you, try `sudo launchctl load -w /System/Library/LaunchDaemons/bootps.plist`.
+
+#### Network routing problems
+
+You could try:
+
+```plain
+sudo route -nv add -net 192.168.64.0/24 -interface bridge100
+```
+
+If you get a "File exists" error, maybe delete and retry?
+
+```plain
+sudo route -nv delete -net 192.168.64.0/24
+sudo route -nv add -net 192.168.64.0/24 -interface bridge100
+```
+
+Maybe `-static` route helps?
+
+If using Cisco AnyConnect, try using OpenConnect (`brew install openconnect`) instead as it messes with routes less (but your company sysadmin/policy may not permit/authorize this).
+
+* It monitors the routing table so may prevent any customisation. Here is [a very hacky workaround](https://unix.stackexchange.com/questions/106304/route-add-no-longer-works-when-i-connected-to-vpn-via-cisco-anyconnect-client/501094#501094).
+
+Does your VPN software provide a "split connection" option, where VPN sysadmin can designate a range of IP addresses to **not** be routed through the VPN?
+* Cisco does
+* Pulse Secure / Jupiter Junos Pulse do
+
+#### Potential workaround for VPN conflicts
+
+This was reported on GitHub (issue [#495](https://github.com/CanonicalLtd/multipass/issues/495#issuecomment-448461250)).
+
+After the `nat …` line (if there is one, otherwise at the end) in `/etc/pf.conf`, add this line:
+
+```plain
+nat on utun1 from bridge100:network to any -> (utun1)
+```
+
+and reload PF with the command:
+
+```plain
+sudo pfctl -f /etc/pf.conf
+```
+
+#### Configure Multipass to use a different subnet
+
+Edit `/Library/Preferences/SystemConfiguration/com.apple.vmnet.plist` to change the "Shared_Net_Address" value to something other than `192.168.64.1 -`.
+* it works if you edit the plist file and stay inside 192.168 range, as Multipass hardcoded for this
+
+```{note}
+If you change the subnet and launch an instance, it will get an IP from that new subnet. But if you try changing it back, the change is reverted on next instance start. It appears that the DHCP server reads the last IP in `/var/db/dhcpd_leases`, decides the subnet from that, and updates Shared_Net_Address to match. So, the only way to really revert this change is to edit or delete `/var/db/dhcpd_leases`.
+```
+
+#### DNS problems
+
+Can you ping IP addresses?
+
+```plain
+ping 1.1.1.1
+```
+
+If not, the output will be similar to the following:
+
+```plain
+PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.
+^C
+--- 1.1.1.1 ping statistics ---
+3 packets transmitted, 0 received, 100% packet loss, time 2030ms
+```
+
+Note that macOS’s firewall can block the ICMP packets that `ping` uses, which will interfere with this test. Make sure you disable **Stealth Mode** in **System Preferences > Security & Privacy > Firewall** just for this test.
+
+
+
+If you try again, it should work:
+
+```plain
+ping 1.1.1.1
+```
+
+The output will be similar to the following:
+
+```plain
+PING 1.1.1.1 (1.1.1.1) 56(84) bytes of data.
+64 bytes from 1.1.1.1: icmp_seq=1 ttl=53 time=7.02 ms
+64 bytes from 1.1.1.1: icmp_seq=2 ttl=53 time=5.91 ms
+64 bytes from 1.1.1.1: icmp_seq=3 ttl=53 time=5.12 ms
+^C
+--- 1.1.1.1 ping statistics ---
+3 packets transmitted, 3 received, 0% packet loss, time 2143ms
+rtt min/avg/max/mdev = 5.124/6.020/7.022/0.781 ms
+```
+
+This means the instance can indeed connect to the internet, but DNS resolution is broken. You can test DNS resolution using the `dig` tool:
+
+```plain
+dig @192.168.64.1 google.ie
+```
+
+If broken, the output will be similar to:
+
+```plain
+; <<>> DiG 9.10.3-P4-Ubuntu <<>> google.ie
+;; global options: +cmd
+;; connection timed out; no servers could be reached
+```
+
+On the other hand, if it works correctly the output will be similar to:
+
+```plain
+; <<>> DiG 9.10.3-P4-Ubuntu <<>> google.ie
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 48163
+;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
+
+;; OPT PSEUDOSECTION:
+; EDNS: version: 0, flags:; udp: 4096
+;; QUESTION SECTION:
+;google.ie. IN A
+
+;; ANSWER SECTION:
+google.ie. 15 IN A 74.125.193.94
+
+;; Query time: 0 msec
+;; SERVER: 192.168.64.1#53(192.168.64.1)
+;; WHEN: Thu Aug 01 15:17:04 IST 2019
+;; MSG SIZE rcvd: 54
+```
+
+To test further, try supplying an explicit DNS server:
+
+```plain
+dig @1.1.1.1 google.ie
+```
+
+If it works correctly, the output will be similar to:
+
+```plain
+; <<>> DiG 9.10.3-P4-Ubuntu <<>> @1.1.1.1 google.ie
+; (1 server found)
+;; global options: +cmd
+;; Got answer:
+;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 11472
+;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1
+
+;; OPT PSEUDOSECTION:
+; EDNS: version: 0, flags:; udp: 1452
+;; QUESTION SECTION:
+;google.ie. IN A
+
+;; ANSWER SECTION:
+google.ie. 39 IN A 74.125.193.94
+
+;; Query time: 6 msec
+;; SERVER: 1.1.1.1#53(1.1.1.1)
+;; WHEN: Thu Aug 01 15:16:27 IST 2019
+;; MSG SIZE rcvd: 54
+```
+
+This implies the problem is with the macOS **Internet Sharing** feature---for some reason, its built-in DNS server is broken.
+
+The built-in DNS server should be "mDNSResponder", which binds to localhost on port 53.
+
+If using Little Snitch or another per-process firewall, ensure mDNSResponder can establish outgoing connections. MacOS’ built-in firewall should not interfere with it.
+
+Check what is bound to that port on the host with:
+
+```plain
+sudo lsof -iTCP:53 -iUDP:53 -n -P
+```
+
+The sample output below shows the correct state while a instance is running:
+
+```plain
+sudo lsof -iTCP:53 -iUDP:53 -n -P
+COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
+mDNSRespo 191 _mdnsresponder 17u IPv4 0xa89d451b9ea11d87 0t0 UDP *:53
+mDNSRespo 191 _mdnsresponder 25u IPv6 0xa89d451b9ea1203f 0t0 UDP *:53
+mDNSRespo 191 _mdnsresponder 50u IPv4 0xa89d451b9ea8b8cf 0t0 TCP *:53 (LISTEN)
+mDNSRespo 191 _mdnsresponder 55u IPv6 0xa89d451b9e2e200f 0t0 TCP *:53 (LISTEN)
+```
+
+If no instance is running (and **Internet Sharing** is disabled in **System Preferences**), the command should return nothing.
+
+Any other command appearing in that output means a process is conflicting with **Internet Sharing** and thus will break DNS in the instance.
+
+##### Possible workarounds
+
+1. Configure DNS inside the instance to use an external working DNS server. Can do so by appending this line to /etc/resolv.conf manually:
+
+ ```
+ nameserver 1.1.1.1
+ ```
+
+ "1.1.1.1" is a free DNS service provided by CloudFlare, but you can use your own.
+2. Use a [custom cloud-init to set /etc/resolv.conf](https://cloudinit.readthedocs.io/en/latest/topics/examples.html?highlight=dns#configure-an-instances-resolv-conf) for you on first boot.
+
+#### ARP problems
+
+The macOS bridge by Multipass filters packets so that only the IP address originally assigned to the VM is allowed through. If you add an additional address (e.g. an IP alias) to the VM, the ARP broadcast will get through but the ARP response will be filtered out.
+
+This means that applications that rely on additional IP addresses, such as [metallb](https://metallb.universe.tf/) under [microk8s](https://microk8s.io/), will not work.
+
+#### Issues caused by MacOS update
+
+When upgrading MacOS to 12.4 (this might happen however also when upgrading to other vesions), MacOS makes changes to the firewall. If the instances are not stopped before the update, it is possible the connection to the instances are blocked by the MacOS firewall. We cannot know what is exactly the change introduced to the firewall, it seems the Apple's `bootpd` stops replying DHCP requests.
+
+There are some procedures that can help to overcome this issue (see [issue #2387](https://github.com/canonical/multipass/issues/2387) on the Multipass GitHub repo for a discussion on this and some alternative solutions). First, you can try to:
+
+* Reboot the computer.
+* Disable and then reenable Internet sharing and/or the firewall.
+* Configure the driver (QEMU) and Multipass in the firewall to allow incoming connections.
+
+## Troubleshoot networking on Windows
+
+### Architecture
+
+Multipass uses the native "Hyper-V" hypervisor on Windows, along with the "Default Switch" created for it. That, in turn, uses the "Internet Sharing" functionality, providing DHCP (IP addresses) and DNS (domain name resolution) to the instances.
+
+### Known issues
+
+#### Default switch going awry
+
+Unfortunately the default switch is known to be quirky and Windows updates often put it in a weird state. This may result in new instances failing to launch and existing ones timing out to start.
+
+The broken state also persists over reboots. The one approach that has helped is removing the network sharing from the default switch:
+
+```powershell
+Get-HNSNetwork | ? Name -Like "Default Switch" | Remove-HNSNetwork
+```
+
+and then rebooting the system:
+
+```powershell
+Restart-Computer
+```
+
+Hyper-V will recreate it on next boot.
+
+#### Stale Internet connection sharing lease
+
+
+
+Another reason for instance timeouts may be that a "stale" IP address for a particular instance name is stored in the `Internet Connection Sharing` hosts file.
+
+Using Administrator privileges, edit the file `C:\WINDOWS\System32\drivers\etc\hosts.ics` and look for any entries that have your instance name in it. If there is more than 1 entry, remove any of them except for the first listed. Save the file and try again.
+
+#### Anti-virus / security software blocking instances
+
+Anti-virus and network security software are not necessarily virtualization-aware. If you’re having issues with connectivity, temporarily disabling this software to test can result in a positive outcome. Examples of this software are Symantec, ESET, Kaspersky and Malware Bytes.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+---
+
+**Contributors:** @saviq , @townsend , @sowasred2012 , @ya-bo-ng , @candlerb , @sergiusens , @nhart , @andreitoterman , @tmihoc , @luisp , @ricab , @gzanchi , @naynayu , @QuantumLibet
+
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 0000000000..4ef6476c12
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,60 @@
+
+
+
+# Multipass documentation
+
+Multipass is a tool to generate cloud-style Ubuntu VMs quickly on Linux, macOS and Windows. It provides a simple but powerful CLI that enables you to quickly access an Ubuntu command line or create your own local mini-cloud.
+
+Local development and testing can be challenging, but Multipass simplifies these processes by automating setup and teardown. Multipass has a growing library of images that you can use to launch purpose-built VMs or custom VMs you’ve configured yourself through its powerful `cloud-init` interface.
+
+Developers can use Multipass to prototype cloud deployments and to create fresh, customized Linux dev environments on any machine. Multipass is the quickest way for Mac and Windows users to get an Ubuntu command line on their systems. You can also use it as a sandbox to try new things without affecting your host machine or requiring a dual boot.
+
+---
+
+## In this documentation
+
+| | |
+|------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
+| [Tutorial](/tutorial/tutorial) Get started - a hands-on introduction to Multipass for new users | [How-to guides](/how-to-guides/how-to-guides) Step-by-step guides covering key operations and common tasks |
+| [Explanation](/explanation/explanation) Concepts - discussion and clarification of key topics | [Reference](/reference/reference) Technical information - specifications, APIs, architecture |
+
+---
+
+## Project and community
+
+We value your input and contributions! Here are some ways you can join our community or get help with your Multipass questions:
+
+* Read our [Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+* Read our quick guide: [Contribute to Multipass docs](/contribute-to-multipass-docs)
+* Join the [Discourse forum](https://discourse.ubuntu.com/c/multipass/21)
+* Report an issue or contribute to the code on [GitHub](https://github.com/canonical/multipass/issues)
+
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+---
+
+**Contributors:** @nhart, @saviq, @townsend, @andreitoterman, @tmihoc, @luisp, @ricab, @sharder996, @georgeliaojia, @gzanchi
+
+
+```{toctree}
+:hidden:
+:titlesonly:
+:maxdepth: 2
+:glob:
+
+Home
+tutorial
+/how*/index
+/reference*/index
+/explanation*/index
+contribute-to-multipass-docs
diff --git a/docs/log.txt b/docs/log.txt
new file mode 100644
index 0000000000..0699e6c86c
--- /dev/null
+++ b/docs/log.txt
@@ -0,0 +1,22 @@
+. .sphinx/venv/bin/activate; .sphinx/venv/bin/sphinx-autobuild -b dirhtml "src" "_build" -c . -d .sphinx/.doctrees -j auto
+Running Sphinx v7.4.7
+loading translations [en]... done
+matplotlib is not installed, social cards will not be generated
+loading pickled environment... done
+myst v4.0.0: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'substitution', 'linkify', 'deflist'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
+building [mo]: targets for 0 po files that are out of date
+writing output...
+building [dirhtml]: targets for 0 source files that are out of date
+updating environment: 0 added, 0 changed, 0 removed
+reading sources...
+getting Git timestamps for source files...
+getting Git timestamps for dependencies...
+looking for now-outdated files... none found
+no targets are out of date.
+build succeeded.
+
+The HTML pages are in _build.
+[32m[sphinx-autobuild] [36mStarting initial build[0m
+[32m[sphinx-autobuild] [34m> python -m sphinx build -b dirhtml src _build -c . -d .sphinx/.doctrees -j auto[0m
+[32m[sphinx-autobuild] [36mServing on http://127.0.0.1:8000[0m
+[32m[sphinx-autobuild] [36mWaiting to detect changes...[0m
diff --git a/docs/reference/command-line-interface/alias.md b/docs/reference/command-line-interface/alias.md
new file mode 100644
index 0000000000..d6b568bdf1
--- /dev/null
+++ b/docs/reference/command-line-interface/alias.md
@@ -0,0 +1,43 @@
+# alias
+> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases).
+
+The `alias` command makes Multipass create a persistent alias to run commands on a given instance. Its syntax is the following:
+
+```plain
+multipass alias instance:command [name]
+```
+
+If `name` is omitted, the alias name defaults to `command`.
+
+After running this command, a new alias is defined as running the `command` on the given instance.
+
+By default, if the host folder where the alias is being executed is mounted on the instance, the instance's working directory is changed to the mounted directory. This behaviour can be avoided by defining the alias with the option `--no-map-working-directory`.
+
+---
+
+The full `multipass help alias` output explains the available options:
+
+```plain
+Usage: multipass alias [options] []
+Create an alias to be executed on a given instance.
+
+Options:
+ -h, --help Displays help on commandline options
+ -v, --verbose Increase logging verbosity. Repeat the 'v' in
+ the short option for more detail. Maximum
+ verbosity is obtained with 4 (or more) v's,
+ i.e. -vvvv.
+ -n, --no-map-working-directory Do not automatically map the host execution
+ path to a mounted path
+
+Arguments:
+ definition Alias definition in the form
+ :
+ name Name given to the alias being defined,
+ defaults to
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/command-line-interface/aliases.md b/docs/reference/command-line-interface/aliases.md
new file mode 100644
index 0000000000..9597b8d0c6
--- /dev/null
+++ b/docs/reference/command-line-interface/aliases.md
@@ -0,0 +1,49 @@
+# aliases
+> See also: [Alias](/explanation/alias), [How to use command aliases](/how-to-guides/manage-instances/use-instance-command-aliases)
+
+The `aliases` command shows the aliases defined for all the instances.
+
+```plain
+multipass aliases
+```
+
+The output will be similar to the following:
+
+```plain
+Alias Instance Command Working directory
+lsrm rewarded-merlin ls default
+topfp flying-pig top map
+```
+
+The `Working directory` column tells us the directory of the host where the alias will be run. The value `default` means that the alias will be run in the instance's default working directory (normally, `/home/ubuntu`). The value `map` means that, if the host directory from which the user calls the alias is mounted on the instance, the alias will be run on the mounted directory on the instance.
+
+[note type="information"]
+The value will be `default` only if the alias was created with the `--no-map-working-directory` option.
+```
+
+The command can be used in conjunction with the `--format` or `-f` options to specify the desired output format: `csv`, `json`, `table` or `yaml`.
+
+---
+
+The full `multipass help aliases` output explains the available options:
+
+```plain
+Usage: multipass aliases [options]
+List available aliases
+
+Options:
+ -h, --help Displays help on commandline options
+ -v, --verbose Increase logging verbosity. Repeat the 'v' in the short
+ option for more detail. Maximum verbosity is obtained with
+ 4 (or more) v's, i.e. -vvvv.
+ --format Output list in the requested format. Valid formats are:
+ table (default), json, csv and yaml. The output working
+ directory states whether the alias runs in the instance's
+ default directory or the alias running directory should try
+ to be mapped to a mounted one.
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/command-line-interface/authenticate.md b/docs/reference/command-line-interface/authenticate.md
new file mode 100644
index 0000000000..53b4f12ec3
--- /dev/null
+++ b/docs/reference/command-line-interface/authenticate.md
@@ -0,0 +1,38 @@
+# authenticate
+> See also: [Authentication](/explanation/authentication), [How to authenticate clients with the Multipass service](/how-to-guides/customise-multipass/authenticate-clients-with-the-multipass-service), [`local.passhprase`](/reference/settings/local-passphrase)
+
+The `authenticate` command is used to authenticate a client with the Multipass service. Once authenticated, the client can issue commands such as `list`, `launch`, etc.
+
+To help reduce the amount of typing for `authenticate`, one can also use `multipass auth` as an alias:
+
+```plain
+multipass auth foo
+```
+
+If no passphrase is specified in the `multipass authenticate` command line, you will be prompted to enter it.
+
+---
+
+The full `multipass help authenticate` output explains the available options:
+
+```plain
+Usage: multipass authenticate [options] []
+Authenticate with the Multipass service.
+A system administrator should provide you with a passphrase
+to allow use of the Multipass service.
+
+Options:
+ -h, --help Displays help on commandline options
+ -v, --verbose Increase logging verbosity. Repeat the 'v' in the short option
+ for more detail. Maximum verbosity is obtained with 4 (or more)
+ v's, i.e. -vvvv.
+
+Arguments:
+ passphrase Passphrase to register with the Multipass service. If omitted,
+ a prompt will be displayed for entering the passphrase.
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/command-line-interface/clone.md b/docs/reference/command-line-interface/clone.md
new file mode 100644
index 0000000000..1a2ac5bfe8
--- /dev/null
+++ b/docs/reference/command-line-interface/clone.md
@@ -0,0 +1,51 @@
+# clone
+The `multipass clone` command creates a clone of an instance. A cloned instance is a standalone instance that is a replica of the original instance in terms of its configuration, installed software, and data at the time of cloning. Cloning an instance can be useful for backup or testing purposes, or to create identical VMs from a working template.
+
+```{caution}
+The `clone` command is available since Multipass version 1.15.0.
+```
+
+Currently, only instances that are in the `Stopped` state can be cloned.
+
+You can run the `clone` command on a source instance without any additional options. For example, `multipass clone natty-nilgai` will produce the following output:
+
+```plain
+…
+Cloned from natty-nilgai to natty-nilgai-clone1.
+```
+
+By default, the `multipass clone` command automatically generates a name for the cloned instance using the format *-cloneN*, where *N* represents the number of instances cloned from that specific source instance, starting at 1. In the example, the name of the source VM is "natty-nilgai" and the automatically generated name for its clone is "natty-nilgai-clone1".
+
+Alternatively, you can specify a custom name for the cloned instance using `--name` option, following the [standard instance name format](/reference/instance-name-format). For example:
+
+```
+multipass clone natty-nilgai --name custom-clone
+```
+
+---
+
+The full `multipass help clone` output explains the available options:
+
+```plain
+Usage: multipass clone [options]
+Create an independent copy of an existing (stopped) instance.
+
+Options:
+ -h, --help Displays help on commandline options
+ -v, --verbose Increase logging verbosity. Repeat the 'v' in
+ the short option for more detail. Maximum
+ verbosity is obtained with 4 (or more) v's,
+ i.e. -vvvv.
+ -n, --name An optional custom name for the cloned
+ instance. The name must follow the usual
+ validity rules (see "help launch"). Default:
+ "-cloneN", where N is the Nth
+ cloned instance.
+
+Arguments:
+ source_name The name of the source instance to be cloned
+```
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/command-line-interface/delete.md b/docs/reference/command-line-interface/delete.md
new file mode 100644
index 0000000000..b378c0c852
--- /dev/null
+++ b/docs/reference/command-line-interface/delete.md
@@ -0,0 +1,49 @@
+# delete
+> See also: [`recover`](/reference/command-line-interface/recover), [`purge`](/reference/command-line-interface/purge)
+
+The `multipass delete` command deletes the instances or snapshots that are specified as arguments.
+
+You can provide multiple arguments in the same delete command, including both instances and snapshots; for example:
+
+```plain
+multipass delete --purge legal-takin calm-squirrel.snapshot2
+```
+
+Deleted instances are marked as such and removed from use, but you can still recover them using the `multipass recover` command, unless you used the `-p`/`--purge` option to delete them permanently.
+
+To completely destroy instances and release the disk space they take up, use the `--purge` option or the [`multipass purge`](/reference/command-line-interface/purge) command.
+
+```{caution}
+When you delete a [snapshot](/explanation/snapshot), or when you delete an instance using the [GUI client](/reference/gui-client), Multipass removes them permanently (even if you didn't use the `--purge` option) and they cannot be recovered.
+
+```
+
+The `--all` option will delete all instances and their snapshots. Take care if using this option.
+
+---
+
+The output of `multipass help delete` explains the available options:
+
+```plain
+Usage: multipass delete [options] [.snapshot] [[.snapshot] ...]
+Delete instances and snapshots. Instances can be purged immediately or later on,
+with the "purge" command. Until they are purged, instances can be recovered
+with the "recover" command. Snapshots cannot be recovered after deletion and must be purged at once.
+
+Options:
+ -h, --help Displays help on commandline options
+ -v, --verbose Increase logging verbosity. Repeat the 'v' in the short option
+ for more detail. Maximum verbosity is obtained with 4 (or more)
+ v's, i.e. -vvvv.
+ --all Delete all instances and snapshots
+ -p, --purge Permanently delete specified instances and snapshots
+ immediately
+
+Arguments:
+ name Names of instances and snapshots to delete
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/command-line-interface/exec.md b/docs/reference/command-line-interface/exec.md
new file mode 100644
index 0000000000..8b0d6603c9
--- /dev/null
+++ b/docs/reference/command-line-interface/exec.md
@@ -0,0 +1,75 @@
+# exec
+> See also: [Multipass `exec` and shells](/explanation/multipass-exec-and-shells), [How to use instance command aliases](/how-to-guides/manage-instances/use-instance-command-aliases)
+
+The `exec` command runs the given commands inside the instance. The first argument is the instance to run the commands on, `--` optionally separates the `multipass` options from the rest - the command to run itself:
+
+```plain
+multipass exec primary -- uname -r
+```
+
+Sample output:
+
+```plain
+4.15.0-48-generic
+```
+
+You can pipe standard input and output to/from the command; for example:
+
+```plain
+multipass exec primary -- lsb_release -a | grep ^Codename:
+```
+
+Sample output:
+
+```plain
+No LSB modules are available.
+Codename: bionic
+```
+
+The `--` separator is required if you want to pass options to the command being run. Options to the `exec` command itself must be specified before `--`.
+
+You can specify on which instance directory the command must be run in three different ways.
+
+The first one is `--working-directory `, which tells Multipass that the command must be run in the folder ``. For example:
+
+```plain
+multipass exec arriving-pipefish --working-directory /home -- ls -a
+```
+
+The `ls -la` command shows the contents of the `/home` directory, because it was run from there:
+
+```plain
+. .. ubuntu
+```
+
+The second option to specify the working directory is to look through the mounted folders first. In case we are running the alias on the host from a directory which is mounted on the instance, the command will be run on the instance from there. If the working directory is not mounted on the instance, the command will be run on the default directory on the instance. This is the default behaviour and no parameter must be specified for this mapping to happen.
+
+The third option is to directly run the command in the default directory in the instance (usually, it is `/home/ubuntu`. The parameter to force this behaviour is `--no-map-working-directory`.
+
+---
+
+The full `multipass help exec` output explains the available options:
+
+```plain
+Usage: multipass exec [options] [--]
+Run a command on an instance
+
+Options:
+ -h, --help Displays help on commandline options
+ -v, --verbose Increase logging verbosity. Repeat the 'v' in
+ the short option for more detail. Maximum
+ verbosity is obtained with 4 (or more) v's,
+ i.e. -vvvv.
+ -d, --working-directory Change to before execution
+ -n, --no-map-working-directory Do not map the host execution path to a
+ mounted path
+
+Arguments:
+ name Name of instance to execute the command on
+ command Command to execute on the instance
+```
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/command-line-interface/find.md b/docs/reference/command-line-interface/find.md
new file mode 100644
index 0000000000..13bcace8e4
--- /dev/null
+++ b/docs/reference/command-line-interface/find.md
@@ -0,0 +1,7 @@
+# find
+
+
+These instance states reflect the various stages an instance can be in while using Multipass. Instances in different states can accept different commands. See [Multipass CLI commands](/t/multipass-cli-commands/29329) for more information on which commands can be used and when.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/logging-levels.md b/docs/reference/logging-levels.md
new file mode 100644
index 0000000000..dee394983c
--- /dev/null
+++ b/docs/reference/logging-levels.md
@@ -0,0 +1,29 @@
+# Logging levels
+> See also: [Configure Multipass’s default logging level](/how-to-guides/customise-multipass/configure-multipasss-default-logging-level)
+
+In Multipass, a hierarchy of logging levels is used is used to convey severity and improve visibility of important events. Multipass uses the following levels ranked from most severe to least severe for its background daemon and child processes.
+
+## Error
+
+Indicates a failure that prevents the intended operation from being accomplished in its entirety. If there is a corresponding CLI command, it should exit with an error code.
+
+## Warning
+
+Indicates an event or fact that might not correspond to the user's intentions/desires/beliefs, or a problem that is light enough that it does not prevent main goals from being accomplished. If there is a corresponding CLI command, it should exit with a success code.
+
+## Info
+
+Indicates information that may be useful for the user to know, learn, etc.
+
+## Debug
+
+Indicates information that is useful for developers and troubleshooting.
+
+## Trace
+
+Indicates information that may be helpful for debugging, but which would clutter logs unreasonably if enabled by default.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/client-apps-windows-terminal-profiles.md b/docs/reference/settings/client-apps-windows-terminal-profiles.md
new file mode 100644
index 0000000000..49e0f9c74a
--- /dev/null
+++ b/docs/reference/settings/client-apps-windows-terminal-profiles.md
@@ -0,0 +1,31 @@
+# client.apps.windows-terminal.profiles
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [How to integrate with Windows Terminal](/how-to-guides/customise-multipass/how-to-integrate-with-windows-terminal)
+
+## Key
+
+`client.apps.windows-terminal.profiles`
+
+## Description
+
+Which profiles should be enabled in Windows Terminal.
+
+
+## Possible values
+
+The following values are supported:
+
+ - `primary` to enable a profile for the [primary instance](/t/28469#primary-instance). Note that this value is independent of what primary name is configured.
+ - `none` to disable any profiles.
+
+## Examples
+
+- `multipass set client.apps.windows-terminal.profiles=none`
+
+## Default value
+
+`primary` (a profile for `primary` is added when Windows Terminal is found)
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/client-gui-autostart.md b/docs/reference/settings/client-gui-autostart.md
new file mode 100644
index 0000000000..c5823d6015
--- /dev/null
+++ b/docs/reference/settings/client-gui-autostart.md
@@ -0,0 +1,32 @@
+# client.gui.autostart
+```{caution}
+This setting has been removed from the CLI starting from Multipass version 1.14.
+It is now only available in the [GUI client](/reference/gui-client).
+```
+
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [GUI client](/reference/gui-client)
+
+## Key
+
+`client.gui.autostart`
+
+## Description
+
+Whether or not the Multipass GUI should start automatically on startup.
+
+## Possible values
+
+Any case variations of `on`|`off`, `yes`|`no`, `1`|`0` or `true`|`false`.
+
+## Examples
+
+`multipass set client.gui.autostart=true`
+
+## Default value
+
+`true` (on Linux and macOS it only takes effect after the client (CLI or GUI) is run for the first time)
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/client-gui-hotkey.md b/docs/reference/settings/client-gui-hotkey.md
new file mode 100644
index 0000000000..fd06ffe76a
--- /dev/null
+++ b/docs/reference/settings/client-gui-hotkey.md
@@ -0,0 +1,48 @@
+# client.gui.hotkey
+```{caution}
+This setting has been removed from the CLI starting from Multipass version 1.14.
+It is now only available in the [GUI client](/reference/gui-client).
+```
+
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [GUI client](/reference/gui-client)
+
+## Key
+
+`client.gui.hotkey`
+
+## Description
+
+A keyboard shortcut for the GUI to open a shell into the [primary instance](/t/28469#primary-instance).
+
+## Possible values
+
+A single case-insensitive sequence of keys, containing:
+
+ * zero or more modifiers (such as `Ctrl`, `Alt`, `Cmd`, `Command`, `Opt`, etc.)
+ * one non-modifier key (such as `u`, `4`, `.`, `Space`, `Tab`, `Pause`, `F3`). When key names have multiple words, quote and use spaces (for example: `"Print Screen"`).
+ * (on macOS) alternatively, UTF-8 characters for Mac keys (such as ⌘, ⌥, ⇧, ⌃)
+ * a plus (`+`) sign separating each alphabetic word (but not key symbols) from the next
+ * the empty string (`""`) to disable the hotkey
+
+```{caution}
+**Caveats:**
+- There are some limitations on what keys and combinations are supported, depending on multiple factors such as keyboard, mapping, and OS (e.g. `AltGr`, numpad, or media keys may or may not work; `shift+enter` is rejected).
+- Some combinations may be grabbed by the OS before they reach multipass (e.g. `meta+a` may open the Applications, `ctrl+alt+f3` may move ttys).
+```
+
+## Examples
+
+ * `multipass set client.gui.hotkey="Ctrl+Print Screen"`.
+ * `multipass set client.gui.hotkey="⌃⇧Y"`.
+ * `multipass set client.gui.hotkey=option+space`.
+ * `multipass set client.gui.hotkey=""`
+
+## Default value
+
+* `Ctrl+Alt+U` on Linux and Windows
+* `⌥⌘U` on macOS
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/client-primary-name.md b/docs/reference/settings/client-primary-name.md
new file mode 100644
index 0000000000..f65635a991
--- /dev/null
+++ b/docs/reference/settings/client-primary-name.md
@@ -0,0 +1,30 @@
+# client.primary-name
+> See also: [Instance](/explanation/instance), [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch)
+
+## Key
+
+`client.primary-name`
+
+## Description
+
+The name of the instance that is launched/recognized as primary.
+
+> See also: [Primary instance](/t/28469#primary-instance)
+
+## Possible values
+
+Any valid instance name or the empty string (`""`) to disable primary.
+
+## Examples
+
+- `multipass set client.primary-name=asdf`
+- `multipass set client.primary-name=`
+
+## Default value
+
+`primary`
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/index.md b/docs/reference/settings/index.md
new file mode 100644
index 0000000000..27d1973d9e
--- /dev/null
+++ b/docs/reference/settings/index.md
@@ -0,0 +1,64 @@
+# Settings
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [GUI client](/reference/gui-client)
+
+Multipass can be configured with a number of **settings** that are read and written by the [`get`](/reference/command-line-interface/get) and [`set`](/reference/command-line-interface/set) CLI commands, respectively. Some settings are also available in the [GUI client](/reference/gui-client).
+
+Settings are organized in a tree structure, where each individual setting is identified by a unique **key** and takes on a single **value** at any given time.
+
+## Settings keys
+
+A **settings key** is a string in the form of a dot-separated path through the settings tree (such as `client.primary-name`). It specifies a path along the settings tree, from the root to a leaf. Thus, individual settings correspond to the leaves of the settings tree.
+
+Conceptually, branches of the tree can be singled out with wildcards, to refer to multiple settings at once. For instance, `local..*` designates the settings that affect a specific instance. Wildcards can also be used to select separate branches. For example `local.*.cpus` refers to the number of CPUs of Multipass instances.
+
+## Settings values
+
+A **settings value** is a string whose syntax (possible values/representations) and semantics (their interpretation) is determined by the setting in question.
+
+Values often express common concepts (such as `true`, `false`, `42`, etc.) and are interpreted internally using the corresponding data types (such as boolean, integer, etc.). They can also be more complex (such as a key combination), but they are always specified and displayed through a string representation (for example: `Ctrl+Alt+U`).
+
+## Available settings
+
+At any given time, the available settings depend on the state of the system. Some settings are only available on some platforms, while daemon settings can only be accessed when the Multipass daemon itself can be reached.
+
+Some instance properties are also exposed as settings.
+> See also: [Set the CPU, RAM or disk of an instance](/t/28603#set-the-cpu-ram-or-disk-of-an-instance).
+
+The command `multipass get --keys` shows what settings are available at any given time.
+
+As of now, this is the total set of settings available:
+
+- [`client.apps.windows-terminal.profiles`](/reference/settings/client-apps-windows-terminal-profiles)
+- [`client.primary-name`](/reference/settings/client-primary-name)
+- [`local..bridged`](/reference/settings/local-instance-name-bridged)
+- [`local..cpus`](/reference/settings/local-instance-name-cpus)
+- [`local..disk`](/reference/settings/local-instance-name-disk)
+- [`local..memory`](/reference/settings/local-instance-name-memory)
+- [`local...name`](/reference/settings/local-instance-name-snapshot-name-name)
+- [`local...comment`](/reference/settings/local-instance-name-snapshot-name-comment)
+- [`local.bridged-network`](/reference/settings/local-bridged-network)
+- [`local.driver`](/reference/settings/local-driver)
+- [`local.passphrase`](/reference/settings/local-passphrase)
+- [`local.privileged-mounts`](/reference/settings/local-privileged-mounts)
+
+```{caution}
+Starting from Multipass version 1.14, the following settings have been removed from the CLI and are only available in the [GUI client](/reference/gui-client):
+- [`client.gui.autostart`](/reference/settings/client-gui-autostart)
+- [`client.gui.hotkey`](/reference/settings/client-gui-hotkey)
+```
+
+
+
+---
+
+ *Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+
+```{toctree}
+:hidden:
+:titlesonly:
+:maxdepth: 2
+:glob:
+
+*
+*/index
diff --git a/docs/reference/settings/local-bridged-network.md b/docs/reference/settings/local-bridged-network.md
new file mode 100644
index 0000000000..74fad70db2
--- /dev/null
+++ b/docs/reference/settings/local-bridged-network.md
@@ -0,0 +1,29 @@
+# local.bridged-network
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch), [`networks`](/reference/command-line-interface/networks), [Create an instance with multiple network interfaces](/t/27188#create-an-instance-with-multiple-network-interfaces), [Add a network to an existing instance](/how-to-guides/manage-instances/add-a-network-to-an-existing-instance), [`local..bridged`](/reference/settings/local-instance-name-bridged)
+
+## Key
+
+`local.bridged-network`
+
+## Description
+
+The name of the interface to connect the instance to when the shortcut `launch --bridged` is issued.
+
+## Possible values
+
+Any name from [`multipass networks`](/reference/command-line-interface/networks).
+
+Validation is deferred to [`multipass launch`](/reference/command-line-interface/launch).
+
+## Examples
+
+`multipass set local.bridged-network=en0`
+
+## Default value
+
+`` (`""`).
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-driver.md b/docs/reference/settings/local-driver.md
new file mode 100644
index 0000000000..d3f87cf340
--- /dev/null
+++ b/docs/reference/settings/local-driver.md
@@ -0,0 +1,28 @@
+# local.driver
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [Driver](/explanation/driver), [How to use libvirt in Multipass](/)
+
+## Key
+
+`local.driver`
+
+## Description
+
+A string identifying the hypervisor back-end in use.
+
+## Possible values
+
+ - `qemu`, [`libvirt`](/) and `lxd` on Linux
+ - `hyperv` and `virtualbox` on Windows
+ - `qemu` and `virtualbox` on macOS 10.15+
+ - *(deprecated)* `hyperkit` on Intel macOS 10.15+
+
+## Default values
+
+ - `qemu` on macOS and amd64 Linux
+ - `lxd` on non-amd64 Linux
+ - `hyperv` on Windows
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-instance-name-bridged.md b/docs/reference/settings/local-instance-name-bridged.md
new file mode 100644
index 0000000000..2dd48872ea
--- /dev/null
+++ b/docs/reference/settings/local-instance-name-bridged.md
@@ -0,0 +1,45 @@
+# local.\.bridged
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`local.bridged-network`](/reference/settings/local-bridged-network), [How to add networks to existing instances](/how-to-guides/manage-instances/add-a-network-to-an-existing-instance)
+
+## Key
+
+`local..bridged`
+
+where `` is the name of a Multipass instance.
+
+## Description
+
+Whether or not the virtual machine is connected to the preferred bridge that is currently defined by `local..bridged`.
+
+Setting this to `true` will cause the instance to be bridged to that host network interface.
+
+Removing a bridged network from an instance is currently not supported.
+
+## Possible values
+
+This setting can have a boolean value (`true` or `false`). However, at this time, it can only be manually set to `true`, but not to `false`.
+
+The value of this setting depends on the value of [`local.bridged-network`](/reference/settings/local-bridged-network); that is, it varies dynamically according to the configured preferred network and the networks that have been added to the instance so far.
+
+## Examples
+
+`multipass set local.ultimate-grosbeak.bridged=true`
+
+If the instance `ultimate-grosbeak` was launched with the command `multipass launch --network eth0`, the result of `multipass get local.ultimate-grosbeak.bridged` will be `true` for as long as the value of `local.bridged-network` is `eth0`.
+
+If you run the command `multipass set local.bridged-network=eth1`, the result of `multipass get local.ultimate-grosbeak.bridged` will become `false`. At that point, you could run the command `multipass set local.ultimate-grosbeak.bridged=true` to bridge `ultimate-grosbeak` with `eth1`.
+
+### Bridged connection to a physical network interface
+
+On some platforms/backends, Multipass cannot connect instances directly to physical network interface controllers (NICs). In this case, Multipass offers to create a bridge/switch on the host connecting to that NIC. The instance is then connected to the bridge/switch, achieving the same effect as if it had been connected to the physical NIC directly. An instance that is indirectly connected with a physical NIC in this fashion is also considered to be bridged with that NIC by Multipass.
+
+For example, if the preferred network is `eth1` and the instance `ultimate-grosbeak` is connected with a bridge `br-eth1` that is linked with `eth1`, then `multipass get local.ultimate-grosbeak.bridged` will return `true`.
+
+## Default value
+
+`true` if the instance is bridged with the preferred network, `false` otherwise.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-instance-name-cpus.md b/docs/reference/settings/local-instance-name-cpus.md
new file mode 100644
index 0000000000..39c705ce3e
--- /dev/null
+++ b/docs/reference/settings/local-instance-name-cpus.md
@@ -0,0 +1,29 @@
+# local.\.cpus
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch).
+
+## Key
+
+`local..cpus`
+
+where `` is the name of a Multipass instance.
+
+## Description
+
+The number of CPUs to simulate on the virtual machine. This establishes a limit on how many host threads the instance can simultaneously use, at most.
+
+## Possible values
+
+A positive integer number. Multipass does not impose an upper limit on the possible values, but the underlying backend may do so.
+
+## Examples
+
+`multipass set local.handsome-ling.cpus=4`
+
+## Default value
+
+The number of CPUs that the instance was launched with.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-instance-name-disk.md b/docs/reference/settings/local-instance-name-disk.md
new file mode 100644
index 0000000000..af17f4fabe
--- /dev/null
+++ b/docs/reference/settings/local-instance-name-disk.md
@@ -0,0 +1,42 @@
+# local.\.disk
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch)
+
+## Key
+
+`local..disk`
+
+where `` is the name of a Multipass instance.
+
+## Description
+
+The size of the instance's disk.
+
+```{caution}
+The disk size can only be increased.
+Decreasing the disk size is not permitted since it could cause data loss and the VM might break.
+```
+
+## Allowed values
+
+A size no smaller than the current disk size. This size can be specified with a positive integer or decimal number, optionally followed by a unit. Any case variations of the following suffixes are accepted as units:
+ - B, to designate one byte.
+ - KiB, KB, or K, to designate 1024 bytes.
+ - MiB, MB, or M, to designate 1024 x 1024 = 1048576 bytes
+ - GiB, GB, or G, to designate 1024 x 1024 x 1024 = 1073741824 bytes
+
+[note type="information"]
+Decimal bytes (e.g. 1.1B) are refused, unless specified with larger units (>= KiB), in which case the amount is floored (e.g. 1.2KiB is interpreted as 1228B, even though 1.2 x 1024 = 1228.8).
+```
+
+## Examples
+
+`multipass set local.handsome-ling.disk=7.5G`
+
+## Default value
+
+The size of the disk that the instance was launched with.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-instance-name-memory.md b/docs/reference/settings/local-instance-name-memory.md
new file mode 100644
index 0000000000..951acffcc2
--- /dev/null
+++ b/docs/reference/settings/local-instance-name-memory.md
@@ -0,0 +1,45 @@
+# local.\.memory
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`launch`](/reference/command-line-interface/launch)
+
+## Key
+
+`local..memory`
+
+where `` is the name of a Multipass instance.
+
+## Description
+
+The amount of RAM that is allocated to the instance.
+
+[note type="information"]
+Hypervisors may impose additional rounding on the total memory that is given to the instance. Furthermore, the value that is set here does not correspond exactly to the memory size that is available in userspace inside the instance (e.g. reported by `free -b`), because the guest kernel claims some for its own. Total memory can be inspected inside the instance with `lshw` (e.g. `sudo lshw -json -class memory`).
+```
+
+[note type="information"]
+Memory on the host is only allocated as the instance uses it, not right away. Once used, it is not released until the instance is shutdown or restarted.
+```
+
+## Allowed values
+
+A positive memory size, specified with a positive integer or decimal number, optionally followed by a unit. Any case variations of the following suffixes are accepted as units:
+ - B, to designate one byte
+ - KiB, KB, or K, to designate 1024 bytes
+ - MiB, MB, or M, to designate 1024 x 1024 = 1048576 bytes
+ - GiB, GB, or G, to designate 1024 x 1024 x 1024 = 1073741824 bytes
+
+[note type="information"]
+Decimal bytes (e.g. 1.1B) are refused, unless specified with larger units (>= KiB), in which case the amount is floored (e.g. 1.2KiB is interpreted as 1228B, even though 1.2 x 1024 = 1228.8).
+```
+
+## Examples
+
+`multipass set local.handsome-ling.memory=4G`
+
+## Default value
+
+The amount of memory that the instance was launched with.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-instance-name-snapshot-name-comment.md b/docs/reference/settings/local-instance-name-snapshot-name-comment.md
new file mode 100644
index 0000000000..38cdbb09aa
--- /dev/null
+++ b/docs/reference/settings/local-instance-name-snapshot-name-comment.md
@@ -0,0 +1,29 @@
+# local.\.\.comment
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`snapshot`](/reference/command-line-interface/snapshot)
+
+## Key
+
+`local...comment`
+
+Where `` is the name of a Multipass instance and `` is the current name of one of its snapshots.
+
+## Description
+
+An optional free piece of text that is associated with the snapshot. This can be used to describe the snapshot, recognize its role, or any other purpose.
+
+## Possible values
+
+Any string that your terminal can encode.
+
+## Examples
+
+`multipass set local.relative-lion.snaphot2.comment="Got it! 😏"`
+
+## Default value
+
+The comment that was assigned to the snapshot when it was taken.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-instance-name-snapshot-name-name.md b/docs/reference/settings/local-instance-name-snapshot-name-name.md
new file mode 100644
index 0000000000..5be0f2ebc2
--- /dev/null
+++ b/docs/reference/settings/local-instance-name-snapshot-name-name.md
@@ -0,0 +1,29 @@
+# local.\.\.name
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`snapshot`](/reference/command-line-interface/snapshot), [Instance](/explanation/instance)
+
+## Key
+
+`local...name`
+
+where `` is the name of a Multipass instance and `` is the current name of one of its snapshots.
+
+## Description
+
+The name that identifies the snapshot in the context of its instance. Snapshot names cannot be repeated.
+
+## Possible values
+
+Any name that follows the same rules as [instance names](/t/28469#heading--Instance-name-format) and is not currently in use by another instance.
+
+## Examples
+
+`multipass set local.relative-lion.snaphot2.name=primed`
+
+## Default value
+
+The name that was assigned to the snapshot when it was taken.
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-passphrase.md b/docs/reference/settings/local-passphrase.md
new file mode 100644
index 0000000000..943f89438a
--- /dev/null
+++ b/docs/reference/settings/local-passphrase.md
@@ -0,0 +1,31 @@
+# local.passphrase
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`authenticate`](/reference/command-line-interface/authenticate)
+
+## Key
+
+`local.passphrase`
+
+## Description
+
+Passphrase used by clients requesting access to the Multipass service via the [`multipass authenticate`](/reference/command-line-interface/authenticate) command.
+
+The passphrase can be given directly in the command line; if omitted, the user will be prompted to enter it.
+
+
+
+## Possible values
+
+Any string
+
+## Examples
+
+`multipass set local.passphrase`
+
+## Default value
+
+Not set (expressed as `false` by `multipass get`)
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reference/settings/local-privileged-mounts.md b/docs/reference/settings/local-privileged-mounts.md
new file mode 100644
index 0000000000..1161ffd40f
--- /dev/null
+++ b/docs/reference/settings/local-privileged-mounts.md
@@ -0,0 +1,28 @@
+# local.privileged-mounts
+> See also: [`get`](/reference/command-line-interface/get), [`set`](/reference/command-line-interface/set), [`mount`](/reference/command-line-interface/mount), [Mount](/explanation/mount)
+
+## Key
+
+`local.privileged-mounts`
+
+## Description
+
+Controls whether [`multipass mount`](/reference/command-line-interface/mount) is allowed.
+
+## Possible values
+
+Any case variations of `on`|`off`, `yes`|`no`, `1`|`0` or `true`|`false`.
+
+## Examples
+
+`multipass set local.privileged-mounts=Yes`
+
+## Default value
+
+ - `true` on Linux and macOS
+ - `false` on Windows
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
diff --git a/docs/reuse/links.txt b/docs/reuse/links.txt
new file mode 100644
index 0000000000..6b68da8429
--- /dev/null
+++ b/docs/reuse/links.txt
@@ -0,0 +1,36 @@
+.. _reStructuredText style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/
+.. _MyST style guide: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide-myst/
+.. _Read the Docs at Canonical: https://library.canonical.com/documentation/read-the-docs-at-canonical
+.. _How to publish documentation on Read the Docs: https://library.canonical.com/documentation/publish-on-read-the-docs
+.. _Example product documentation: https://canonical-example-product-documentation.readthedocs-hosted.com/
+.. wokeignore:rule=master
+.. _`Sphinx configuration`: https://www.sphinx-doc.org/en/master/usage/configuration.html
+.. wokeignore:rule=master
+.. _`Sphinx extensions`: https://www.sphinx-doc.org/en/master/usage/extensions/index.html
+.. wokeignore:rule=master
+.. _`file-wide metadata`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/field-lists.html
+.. _`Furo documentation`: https://pradyunsg.me/furo/quickstart/
+.. _`Hiding Contents sidebar`: https://pradyunsg.me/furo/customisation/toc/
+.. _`Sphinx`: https://www.sphinx-doc.org/
+.. _woke documentation: https://docs.getwoke.tech/ignore
+.. _Canonical Sphinx: https://github.com/canonical/canonical-sphinx
+.. _change log: https://github.com/canonical/sphinx-docs-starter-pack/wiki/Change-log
+.. _Open Graph: https://ogp.me/
+.. _manual import: https://readthedocs.com/dashboard/import/manual/
+.. _How to manually configure a Git repository integration: https://docs.readthedocs.io/en/stable/guides/setup/git-repo-manual.html
+.. _reStructuredText: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
+.. _Markdown: https://commonmark.org/
+.. _MyST: https://myst-parser.readthedocs.io/
+.. _Diátaxis: https://diataxis.fr/
+.. _Pa11y: https://pa11y.org/
+.. _Pa11y readme: https://github.com/pa11y/pa11y#command-line-configuration
+.. _woke: https://github.com/get-woke/woke
+.. _woke User Guide: https://docs.getwoke.tech/usage/#file-globs
+.. _More useful markup: https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#more-useful-markup
+.. _Vale: https://vale.sh/
+.. _Vale rules: https://github.com/canonical/praecepta
+.. _Web Content Accessibility Guidelines (WCAG) 2.2: https://www.w3.org/TR/WCAG22/
+.. _Level AA conformance: https://www.w3.org/WAI/WCAG2AA-Conformance
+
+.. SHORTCUTS
+.. |RST| replace:: :abbr:`reST (reStructuredText)`
diff --git a/docs/tutorial.md b/docs/tutorial.md
new file mode 100644
index 0000000000..b4f3af2916
--- /dev/null
+++ b/docs/tutorial.md
@@ -0,0 +1,689 @@
+# Tutorial
+
+
+Multipass is a flexible and powerful tool that can be used for many purposes. In its simplest form, you can use it to quickly create and destroy Ubuntu VMs (instances) on any host machine. But you can also use Multipass to build a local mini-cloud on your laptop, to test and develop multi-instance or container-based cloud applications.
+
+This tutorial will help you understand how Multipass works, and the skills you need to use its main features.
+
+## Install Multipass
+
+Multipass is available for Linux, macOS and Windows. To install it on the OS of your choice, please follow the instructions provided in [How to install Multipass](/how-to-guides/install-multipass).
+
+[note type="information"]
+Select the tab corresponding to your operating system (e.g. Linux) to display the relevant content in each section. Your decision will stick until you select another OS from the drop-down menu.
+```
+
+## Create and use a basic instance
+
+[tabs]
+
+[tab version="Linux"]
+
+Start Multipass from the application launcher. In Ubuntu, press the super key and type "Multipass", or find Multipass in the Applications panel on the lower left of the desktop.
+
+
+
+After launching the application, you should see the Multipass tray icon on the upper right section of the screen.
+
+
+
+Click on the Multipass icon and select **Open Shell**.
+
+
+
+Clicking this button does many things in the background:
+* It creates a new virtual machine (instance) named `primary`, with 1GB of RAM, 5GB of disk, and 1 CPU. See also: [Primary instance](/t/28469#primary-instance).
+* It installs the most recent Ubuntu LTS release on that instance.
+* It mounts your `$HOME` directory in the instance.
+* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`.
+
+
+
+```{caution}
+If your local home folder is encrypted using ` fscrypt` and you are having trouble accessing its contents when it is automatically mounted inside your primary instance, see: [Mount an encrypted home folder](/how-to-guides/troubleshoot/mount-an-encrypted-home-folder).
+```
+
+You can see elements of this in the printout below:
+
+```plain
+Launched: primary
+Mounted '/home/' into 'primary:Home'
+Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com
+ * Management: https://landscape.canonical.com
+ * Support: https://ubuntu.com/advantage
+
+ System information as of Thu Jan 26 08:06:22 PST 2023
+
+ System load: 0.0 Processes: 95
+ Usage of /: 30.2% of 4.67GB Users logged in: 0
+ Memory usage: 21% IPv4 address for ens3: 10.110.66.242
+ Swap usage: 0%
+
+ * Strictly confined Kubernetes makes edge and IoT secure. Learn how MicroK8s
+ just raised the bar for easy, resilient and secure K8s cluster deployment.
+
+ https://ubuntu.com/engage/secure-kubernetes-at-the-edge
+
+0 updates can be applied immediately.
+
+
+The list of available updates is more than a week old.
+To check for new updates run: sudo apt update
+
+ubuntu@primary:~$
+```
+
+Let's test it. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory:
+
+
+
+As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance:
+
+```plain
+cd ./Home/Multipass_Files/
+cat README.md
+```
+
+Sample output:
+
+```plain
+## Shared Folder
+
+This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM!
+```
+
+[/tab]
+
+[tab version="macOS"]
+
+Start Multipass from the application launcher. In macOS, open the application launcher, type "Multipass", and launch the application.
+
+****
+
+After launching the application, you should see the Multipass tray icon in the upper right section of the screen.
+
+****
+
+Click on the Multipass icon and select **Open Shell**.
+
+****
+
+Clicking this button does many things in the background:
+
+* It creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU.
+* It installs the most recent Ubuntu LTS release on that instance. Last, it mounts your `$HOME` directory in the instance.
+* It opens a shell to the instance, announced by the command prompt `ubuntu@primary`.
+
+You can see elements of this in the printout below:
+
+```plain
+Launched: primary
+Mounted '/home/' into 'primary:Home'
+Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com
+ * Management: https://landscape.canonical.com
+ * Support: https://ubuntu.com/advantage
+
+ System information as of Thu Jan 26 21:15:05 UTC 2023
+
+ System load: 0.72314453125 Processes: 105
+ Usage of /: 29.8% of 4.67GB Users logged in: 0
+ Memory usage: 20% IPv4 address for ens3: 192.168.64.5
+ Swap usage: 0%
+
+
+0 updates can be applied immediately.
+
+
+The list of available updates is more than a week old.
+To check for new updates run: sudo apt update
+
+ubuntu@primary:~$
+```
+
+Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Use this to share data with your instance. More concretely, create a new folder called `Multipass_Files` in your `$HOME` directory.
+
+****
+
+As you can see, a `README.md` file has been added to the shared folder. Check for the folder and read the file from your new instance:
+
+```plain
+ubuntu@primary:~$ cd ./Home/Multipass_Files/
+ubuntu@primary:~/Home/Multipass_Files$ cat README.md
+## Shared Folder
+
+This folder could be a great place to keep files that need to be accessed by both your host machine and Ubuntu VM!
+
+ubuntu@primary:~/Home/Multipass_Files$
+```
+
+[/tab]
+
+[tab version="Windows"]
+
+Start Multipass from the application launcher. Press the Windows key and type "Multipass", then launch the application.
+
+****
+
+After launching the application, you should see the Multipass tray icon in the lower right section of the screen (you may need to click on the small arrow located there).
+
+****
+
+Click on the Multipass icon and select **Open Shell**.
+
+****
+
+Clicking this button does many things in the background. First, it creates a new virtual machine (instance) named "primary", with 1GB of RAM, 5GB of disk, and 1 CPU. Second, it installs the most recent Ubuntu LTS release on that instance. Third, it mounts your `$HOME` directory in the instance. Last, it opens a shell to the instance, announced by the command prompt `ubuntu@primary`.
+
+You can see elements of this in the printout below:
+
+```plain
+Launched: primary
+Mounted '/home/' into 'primary:Home'
+Welcome to Ubuntu 22.04.1 LTS (GNU/Linux 5.15.0-57-generic x86_64)
+
+ * Documentation: https://help.ubuntu.com
+ * Management: https://landscape.canonical.com
+ * Support: https://ubuntu.com/advantage
+
+ System information as of Thu Jan 26 08:06:22 PST 2023
+
+ System load: 0.0 Processes: 95
+ Usage of /: 30.2% of 4.67GB Users logged in: 0
+ Memory usage: 21% IPv4 address for ens3: 10.110.66.242
+ Swap usage: 0%
+
+ * Strictly confined Kubernetes makes edge and IoT secure. Learn how MicroK8s
+ just raised the bar for easy, resilient and secure K8s cluster deployment.
+
+ https://ubuntu.com/engage/secure-kubernetes-at-the-edge
+
+0 updates can be applied immediately.
+
+
+The list of available updates is more than a week old.
+To check for new updates run: sudo apt update
+
+ubuntu@primary:~$
+```
+
+Let’s test it out. As you've just learnt, the previous step automatically mounted your `$HOME` directory in the instance. Try out a few Linux commands to see what you’re working with.
+
+```plain
+ubuntu@primary:~$ free
+ total used free shared buff/cache available
+Mem: 925804 203872 362484 916 359448 582120
+Swap: 0 0 0
+ubuntu@primary:~$ df
+Filesystem 1K-blocks Used Available Use% Mounted on
+tmpfs 92584 912 91672 1% /run
+/dev/sda1 4893836 1477300 3400152 31% /
+tmpfs 462900 0 462900 0% /dev/shm
+tmpfs 5120 0 5120 0% /run/lock
+/dev/sda15 106858 5329 101529 5% /boot/efi
+tmpfs 92580 4 92576 1% /run/user/1000
+:C:/Users/Scott 1048576000 0 1048576000 0% /home/ubuntu/Home
+```
+
+[/tab]
+
+[/tabs]
+
+Congratulations, you've got your first instance!
+
+This instance is great for when you just need a quick Ubuntu VM, but let's say you want a more customised instance, how can you do that? Multipass has you covered there too.
+
+[details = "Optional Exercises"]
+Exercise 1:
+When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first).
+
+Exercise 2:
+In Multipass, an instance with the name "primary" is privileged. That is, it serves as the default argument of `multipass shell` among other capabilities. In different terminal instances, check `multipass shell primary` and `multipass shell`. Both commands should give the same result.
+[/details]
+
+## Create a customised instance
+
+Multipass has a great feature to help you get started with creating customised instances. Open a terminal and run the `multipass find` command. The result shows a list of all images you can currently launch through Multipass.
+
+```plain
+$ multipass find
+Image Aliases Version Description
+snapcraft:core18 18.04 20201111 Snapcraft builder for Core 18
+snapcraft:core20 20.04 20210921 Snapcraft builder for Core 20
+snapcraft:core22 22.04 20220426 Snapcraft builder for Core 22
+snapcraft:devel 20230126 Snapcraft builder for the devel series
+core core16 20200818 Ubuntu Core 16
+core18 20211124 Ubuntu Core 18
+core20 20230119 Ubuntu Core 20
+core22 20230119 Ubuntu Core 22
+18.04 bionic 20230112 Ubuntu 18.04 LTS
+20.04 focal 20230117 Ubuntu 20.04 LTS
+22.04 jammy,lts 20230107 Ubuntu 22.04 LTS
+22.10 kinetic 20230112 Ubuntu 22.10
+daily:23.04 devel,lunar 20230125 Ubuntu 23.04
+appliance:adguard-home 20200812 Ubuntu AdGuard Home Appliance
+appliance:mosquitto 20200812 Ubuntu Mosquitto Appliance
+appliance:nextcloud 20200812 Ubuntu Nextcloud Appliance
+appliance:openhab 20200812 Ubuntu openHAB Home Appliance
+appliance:plexmediaserver 20200812 Ubuntu Plex Media Server Appliance
+anbox-cloud-appliance latest Anbox Cloud Appliance
+charm-dev latest A development and testing environment for charmers
+docker 0.4 A Docker environment with Portainer and related tools
+jellyfin latest Jellyfin is a Free Software Media System that puts you in control of managing and streaming your media.
+minikube latest minikube is local Kubernetes
+```
+
+Launch an instance running Ubuntu 22.10 ("Kinetic Kudu") by typing the `multipass launch kinetic` command.
+
+[tabs]
+
+[tab version="Linux"]
+
+Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "coherent-trumpetfish".
+
+```plain
+$ multipass launch kinetic
+Launched: coherent-trumpetfish
+```
+
+You can check some basic info about your new instance by running the following command:
+
+`multipass exec coherent-trumpetfish -- lsb_release -a`
+
+This tells multipass to run the command `lsb_release -a` on the "coherent-trumpetfish" instance.
+
+```plain
+$ multipass exec coherent-trumpetfish -- lsb_release -a
+No LSB modules are available.
+Distributor ID: Ubuntu
+Description: Ubuntu 22.10
+Release: 22.10
+Codename: kinetic
+```
+
+Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "coherent-trumpetfish" instance by running the following command:
+
+`multipass delete coherent-trumpetfish`
+
+You can now launch the type of instance you need by running this command:
+
+`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2`
+
+[/tab]
+
+[tab version="macOS"]
+
+Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "breezy-liger".
+
+```plain
+$ multipass launch kinetic
+Launched: breezy-liger
+```
+
+You can check some basic info about your new instance by running the following command:
+
+`multipass exec breezy-liger -- lsb_release -a`
+
+This tells Multipass to run the command `lsb_release -a` on the “breezy-liger” instance.
+
+```plain
+$ multipass exec breezy-liger -- lsb_release -a
+No LSB modules are available.
+Distributor ID: Ubuntu
+Description: Ubuntu 22.10
+Release: 22.10
+Codename: kinetic
+```
+
+Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "breezy-liger" instance by running the following command:
+
+`multipass delete breezy-liger`
+
+You can now launch the type of instance you need by running this command:
+
+`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2`
+
+[/tab]
+
+[tab version="Windows"]
+
+Now, you have an instance running and it has been named randomly by Multipass. In this case, it has been named "decorous-skate".
+
+```plain
+C:\WINDOWS\system32> multipass launch kinetic
+Launched: decorous-skate
+```
+
+You can check some basic info about your new instance by running the following command:
+
+`multipass exec decorous-skate -- lsb_release -a`
+
+This tells Multipass to run the command `lsb_release -a` on the “decorous-skate” instance.
+
+```plain
+C:\WINDOWS\system32> multipass exec decorous-skate -- lsb_release -a
+No LSB modules are available.
+Distributor ID: Ubuntu
+Description: Ubuntu 22.10
+Release: 22.10
+Codename: kinetic
+```
+
+Perhaps after using this instance for a while, you decide that what you really need is the latest LTS version of Ubuntu, with a more informative name and a little more memory and disk. You can delete the "decorous-skate" instance by running the following command:
+
+`multipass delete decorous-skate`
+
+You can now launch the type of instance you need by running this command:
+
+`multipass launch lts --name ltsInstance --memory 2G --disk 10G --cpus 2`
+
+[/tab]
+
+[/tabs]
+
+## Manage instances
+
+You can confirm that the new instance has the specs you need by running `multipass info ltsInstance`.
+
+[tabs]
+
+[tab version="Linux"]
+
+```plain
+$ multipass info ltsInstance
+Name: ltsInstance
+State: Running
+IPv4: 10.110.66.139
+Release: Ubuntu 22.04.1 LTS
+Image hash: 3100a27357a0 (Ubuntu 22.04 LTS)
+CPU(s): 2
+Load: 1.11 0.36 0.12
+Disk usage: 1.4GiB out of 9.5GiB
+Memory usage: 170.4MiB out of 1.9GiB
+Mounts: --
+```
+
+You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have.
+
+```plain
+$ multipass list
+Name State IPv4 Image
+primary Running 10.110.66.242 Ubuntu 22.04 LTS
+coherent-trumpetfish Deleted -- Not Available
+ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS
+```
+
+The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "coherent-trumpetfish" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover coherent-trumpetfish`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted.
+
+```plain
+$ multipass list
+Name State IPv4 Image
+primary Running 10.110.66.242 Ubuntu 22.04 LTS
+ltsInstance Running 10.110.66.139 Ubuntu 22.04 LTS
+```
+
+
+[/tab]
+
+[tab version="macOS"]
+
+```plain
+$ multipass info ltsInstance
+Name: ltsInstance
+State: Running
+IPv4: 192.168.64.3
+Release: Ubuntu 22.04.1 LTS
+Image hash: 3100a27357a0 (Ubuntu 22.04 LTS)
+CPU(s): 2
+Load: 1.55 0.44 0.15
+Disk usage: 1.4GiB out of 9.5GiB
+Memory usage: 155.5MiB out of 1.9GiB
+Mounts: --
+```
+
+You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have.
+
+```plain
+$ multipass list
+Name State IPv4 Image
+primary Running 192.168.64.5 Ubuntu 22.04 LTS
+breezy-liger Deleted -- Not Available
+ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS
+```
+
+The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "breezy-liger" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover breezy-liger`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted.
+
+```plain
+$ multipass list
+Name State IPv4 Image
+primary Running 192.168.64.5 Ubuntu 22.04 LTS
+ltsInstance Running 192.168.64.3 Ubuntu 22.04 LTS
+```
+
+[/tab]
+
+[tab version="Windows"]
+
+```plain
+C:\WINDOWS\system32> multipass info ltsInstance
+Name: ltsInstance
+State: Running
+IPv4: 172.22.115.152
+Release: Ubuntu 22.04.1 LTS
+Image hash: 3100a27357a0 (Ubuntu 22.04 LTS)
+CPU(s): 2
+Load: 1.11 0.36 0.12
+Disk usage: 1.4GiB out of 9.5GiB
+Memory usage: 170.4MiB out of 1.9GiB
+Mounts: --
+```
+
+You've created and deleted quite a few instances. It is time to run `multipass list` to see the instances you currently have.
+
+```plain
+C:\WINDOWS\system32> multipass list
+Name State IPv4 Image
+primary Running 10.110.66.242 Ubuntu 22.04 LTS
+decorous-skate Deleted -- Not Available
+ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS
+```
+
+The result shows that you have two instances running, the "primary" instance and the LTS machine with customised specs. The "decorous-skate" instance is still listed, but its state is "Deleted". You can recover this instance by running `multipass recover decorous-skate`. But for now, delete the instance permanently by running `multipass purge`. Then run `multipass list` again to confirm that the instance has been permanently deleted.
+
+```plain
+C:\WINDOWS\system32> multipass list
+Name State IPv4 Image
+primary Running 10.110.66.242 Ubuntu 22.04 LTS
+ltsInstance Running 172.22.115.152 Ubuntu 22.04 LTS
+```
+
+[/tab]
+
+[/tabs]
+
+You've now seen a few ways to create, customise, and delete an instance. It is time to put those instances to work!
+
+## Put your instances to use
+
+Let's see some practical examples of what you can do with your Multipass instances:
+
+* [Run a simple web server](#run-a-simple-web-server)
+* [Launch from a Blueprint to run Docker containers](#launch-from-a-blueprint-to-run-docker-containers)
+
+### Run a simple web server
+
+One way to put a Multipass instance to use is by running a local web server in it.
+
+Return to your customised LTS instance. Take note of its IP address, which was revealed when you ran `multipass list`. Then run `multipass shell ltsInstance` to open a shell in the instance.
+
+From the shell, you can run:
+
+```
+sudo apt update
+
+sudo apt install apache2
+```
+
+Open a browser and type in the IP address of your instance into the address bar. You should now see the default Apache homepage.
+
+[tabs]
+
+[tab version="Linux"]
+
+[/tab]
+
+[tab version="macOS"]
+
+[/tab]
+
+[tab version="Windows"]
+
+[/tab]
+
+[/tabs]
+
+Just like that, you've got a web server running in a Multipass instance!
+
+You can use this web server locally for any kind of local development or testing. However, if you want to access this web server from the internet (for instance, a different computer), you need an instance that is exposed to the external network.
+
+### Launch from a Blueprint to run Docker containers
+
+Some environments require a lot of configuration and setup. Multipass Blueprints are instances with a deep level of customization. For example, the Docker Blueprint is a pre-configured Docker environment with a Portainer container already running.
+
+You can launch an instance using the Docker Blueprint by running `multipass launch docker --name docker-dev`.
+
+Once that's done, run `multipass info docker-dev` to note down the IP of the new instance.
+
+[tabs]
+
+[tab version="Linux"]
+
+```plain
+$ multipass launch docker --name docker-dev
+Launched: docker-dev
+$ multipass info docker-dev
+Name: docker-dev
+State: Running
+IPv4: 10.115.5.235
+ 172.17.0.1
+Release: Ubuntu 22.04.1 LTS
+Image hash: 3100a27357a0 (Ubuntu 22.04 LTS)
+CPU(s): 2
+Load: 1.50 2.21 1.36
+Disk usage: 2.6GiB out of 38.6GiB
+Memory usage: 259.7MiB out of 3.8GiB
+Mounts: --
+```
+
+Copy the IP address starting with "10" and paste it into your browser, then add a colon and the portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password.
+
+
+
+From there, select **Local** to manage a local Docker environment.
+
+
+
+Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **app templates**, then select **NGINX**.
+
+
+
+From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers.
+
+
+
+[/tab]
+
+[tab version="macOS"]
+
+```plain
+$ multipass launch docker --name docker-dev
+Launched: docker-dev
+$ multipass info docker-dev
+Name: docker-dev
+State: Running
+IPv4: 10.115.5.235
+ 172.17.0.1
+Release: Ubuntu 22.04.1 LTS
+Image hash: 3100a27357a0 (Ubuntu 22.04 LTS)
+CPU(s): 2
+Load: 1.40 0.64 0.25
+Disk usage: 2.5GiB out of 38.6GiB
+Memory usage: 236.4MiB out of 3.8GiB
+Mounts: --
+```
+
+Copy the IP address starting with "10" and paste it into your browser, then add a colon and the portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password.
+
+
+
+From there, select **Local** to manage a local Docker environment.
+
+
+
+Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **app templates**, then select **NGINX**.
+
+
+
+From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers.
+
+
+
+[/tab]
+
+[tab version="Windows"]
+
+```plain
+C:\WINDOWS\system32> multipass launch docker --name docker-dev
+Launched: docker-dev
+C:\WINDOWS\system32> multipass info docker-dev
+Name: docker-dev
+State: Running
+IPv4: 10.115.5.235
+ 172.17.0.1
+Release: Ubuntu 22.04.1 LTS
+Image hash: 3100a27357a0 (Ubuntu 22.04 LTS)
+CPU(s): 2
+Load: 0.04 0.17 0.09
+Disk usage: 2.5GiB out of 38.6GiB
+Memory usage: 283.3MiB out of 3.8GiB
+Mounts: --
+```
+
+Copy the IP address starting with "10" and paste it into your browser, then add a colon and the portainer default port, 9000. It should look like this: 10.115.5.235:9000. This will take you to the Portainer login page where you can set a username and password.
+
+
+
+From there, select **Local** to manage a local Docker environment.
+
+
+
+Inside the newly selected local Docker environment, locate the sidebar menu on the page and click on **app templates**, then select **NGINX**.
+
+
+
+From the Portainer dashboard, you can see the ports available on nginx. To verify that you have nginx running in a Docker container inside Multipass, open a new web page and paste the IP address of your instance followed by one of the port numbers.
+
+
+
+[/tab]
+
+[/tabs]
+
+## Next steps
+
+Congratulations! You can now use Multipass proficiently.
+
+There's more to learn about Multipass and its capabilities. Check out our [How-to guides](/how-to-guides/how-to-guides) for ideas and help with your project. In our [Explanation](/explanation/explanation) and [Reference](/reference/reference) pages you can find definitions of key concepts, a complete CLI command reference, settings options and more.
+
+Join the discussion on the [Multipass forum](https://discourse.ubuntu.com/c/multipass/) and let us know what you are doing with your instances!
+
+---
+
+*Errors or typos? Topics missing? Hard to read? Let us know or open an issue on GitHub.*
+
+---
+
+**Contributors:** @nhart, @saviq, @townsend, @andreitoterman, @tmihoc, @luisp, @ricab, @sharder996, @georgeliaojia, @mscho7969, @itecompro, @mr-cal, @sally-makin, @gzanchi, @bagustris , @pitifulpete
+
{{ project }} ++ +
+
+
+
+