How to create an instance

To launch an application or an image, Anbox Cloud creates an instance for it. To create and launch an instance, you can use the Anbox Cloud dashboard or the CLI.

Depending on what you need, you can use the either of the following commands to create an instance for a registered application or an image.

  • amc launch creates and starts the instance.

  • amc init only creates the instance.

By default, the instance will run headless.

The following examples demonstrate different ways of launching instances using amc launch, but you can use amc init in the same way.

Launch application instances

Before launching an instance for an application, get the ID of the application that for which you want to launch an instance. To do this, run:

amc application ls

This command lists the available applications along their IDs and their published status.

+----------------------+----------------+---------------+--------+-----------+--------+---------------------+
|          ID          |      NAME      | INSTANCE TYPE | ADDONS | PUBLISHED | STATUS |    LAST UPDATED     |
+----------------------+----------------+---------------+--------+-----------+--------+---------------------+
| bdp7kmahmss3p9i8huu0 |      candy     | a4.3          | ssh    | false     | ready  | 2018-08-14 08:44:41 |
+----------------------+----------------+---------------+--------+-----------+--------+---------------------+

To launch an instance for a published application, run:

amc launch <application_id>

Tip

  • To know about published applications, see Publish application versions.

  • The --vm flag is not required when you specify an application id. The application has the information about whether a container or a virtual machine is to be created.

The amc launch command fails if you provide the ID of an application that is not yet published. However, if you have a specific version of an application that has been published, you can specify it to launch the instance successfully:

amc launch --application-version=0 bcmap7u5nof07arqa2ag

Launch a raw instance

You can launch a raw instance from an image. To do so, get the ID of the image by running:

Tip

If you don’t know what a raw instance is, see Application vs. raw instances.

amc image ls

This command lists the available images along with their IDs and status:

+----------------------+---------+--------+----------+----------------------+
|          ID          |  NAME   | STATUS | VERSIONS |       USED BY        |
+----------------------+---------+--------+----------+----------------------+
| bh01n90j1qm6416q0ul0 | default | active | 1        |                      |
+----------------------+---------+--------+----------+----------------------+

Launch a raw instance by providing the image ID in the following command:

amc launch --raw <image_id>

See Provided Anbox Cloud images for a list of images that are available in Anbox Cloud.

Launch an instance with streaming enabled

since 1.22.0

If you want to stream the visual output from an instance, specify it at the time of instance creation. Otherwise, the instance cannot be streamed. In previous versions of Anbox Cloud, it was only possible to create an instance that has streaming enabled via the Stream Gateway API. The same can now be achieved through the AMS API or the amc CLI.

To enable streaming for a new instance, simply run:

amc launch --enable-streaming ...

AMS will automatically create a streaming session for the instance. You can find the id of the session as a tag on the instance in the format session=<id>.

If you want to to further customise the streaming configuration such as display settings or frame rate, use the corresponding arguments: --display-size, --display-density and --fps. For example, to create an instance with a 1080p resolution, a frame rate of 60 and a DPI of 120, run:

amc launch --enable-streaming --display-size=1920x1080 --display-density=120 --fps=60 ...

Launch an instance with a specific name

since 1.22.0

To allow identifying and referencing instances easier you can give them a name at creation time. Names must be unique and can be used with all CLI commands.

To create an instance with a name, run:

amc launch --name=foo ...

This will create an instance with the name “foo” which can then be used in other CLI commands. For example, when opening a shell for interacting with the instance, the following command can be used:

amc shell foo

Launch an instance on a specific node

By default, every instance is scheduled by AMS onto a LXD node. Alternatively, you can launch an instance directly on a specific node:

amc launch --node=lxd0 <application_id>

Note

AMS will still verify that the selected node has enough resources to host the instance. If not, the instance will fail to launch.

Launch an instance with a different Anbox platform

By default, instances start with the webrtc platform if --enable-graphics is specified. Otherwise, they start with the null platform. To select a different platform, specify it with the -p flag. The platform cannot be changed at runtime and must be selected when the instance is created. For example, you can launch an instance with the webrtc platform with the following command:

amc launch -p webrtc <application_id>

If you have built your own platform named foo and you built it via an addon into the instance images, you can launch an instance with the platform the same way:

amc launch -p foo <application_id>

For more information, see Supported platforms and Supported platforms.

Launch an instance with development mode enabled

You can launch instances with additional development features turned on. This development mode must be enabled when an instance is launched, and it cannot be turned off afterwards. You should never enable development mode for instances used in a production environment.

To launch an instance with development mode enabled, add the --devmode flag to the launch command:

amc launch --devmode <application_id>