Skip to content

Manage Cloud application instances

Info

Learn the concepts and fundamentals of instances in the Explanation page.

An application instance is a representation of a version and optional configuration (including options/parameters). Instances are the mechanism by which a run is made.

This how-to guide explains how to interact with instances using methods on the Application class. These methods return an Instance object. Go the reference section to see all the available parameters for each method.

Create an instance

Use the Application.new_instance method to create a new instance.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instance = app.new_instance(version_id="v0.0.1")

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "instance-gu67ntli",
  "application_id": "drifting-heron",
  "version_id": "v0.0.1",
  "name": "instance-gu67ntli",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-28T18:56:47.900471Z",
  "updated_at": "2026-07-28T18:56:47.900471Z"
}

The call above will create a random ID, and use the same identifier for the instance's name. The name of the instance is used as a human-readable label. You can use the id and/or name keyword arguments to specify a custom ID and name for the instance. For example:

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instance = app.new_instance(
    version_id="v0.0.1",
    id="production",
    name="The main production instance",
)

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "production",
  "application_id": "drifting-heron",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-28T18:56:54.037778Z",
  "updated_at": "2026-07-28T18:56:54.037778Z"
}

In automated workflows, you don't have to check if an instance exists before creating it. Use the exist_ok keyword argument to avoid an error if the instance already exists:

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instance = app.new_instance(
    version_id="v0.0.1",
    id="production",
    exist_ok=True,
)

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "production",
  "application_id": "drifting-heron",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-28T18:56:54.037778Z",
  "updated_at": "2026-07-28T18:56:54.037778Z"
}

You can configure the instance at the time of creation. Use the configuration keyword argument, passing an InstanceConfiguration object, to set attributes such as:

  • execution_class: the execution class to use for runs created on this instance.
  • queuing: a RunQueuing object used to configure queuing for runs created on this instance. Set disabled=True to disable queuing, and use the priority attribute to set the queuing priority.
  • options: the default options to use for runs created on this instance, as a dictionary of key-value pairs.

Go the reference section to see all the available attributes for configuring an instance. Consider the following example where an instance is created with customized configuration:

import os

import nextmv
from nextmv import cloud
from nextmv import RunQueuing

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instance = app.new_instance(
    version_id="v0.0.1",
    id="staging",
    configuration=cloud.InstanceConfiguration(
        execution_class="6c9500mb870s",
        options={"details": "false"},
        queuing=RunQueuing(priority=2, disabled=True),
    ),
)

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "staging",
  "application_id": "drifting-heron",
  "version_id": "v0.0.1",
  "name": "staging",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "options": {
      "details": "false"
    },
    "queuing": {
      "priority": 2,
      "disabled": true
    }
  },
  "locked": false,
  "created_at": "2026-07-28T18:57:34.417383Z",
  "updated_at": "2026-07-28T18:57:34.417383Z"
}

Get an instance

Use the Application.instance method to get an existing instance by its ID.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instance = app.instance(instance_id="production")

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "production",
  "application_id": "drifting-heron",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "queuing": {
      "priority": 6,
      "disabled": false
    }
  },
  "locked": false,
  "created_at": "2026-07-28T18:56:54.037778Z",
  "updated_at": "2026-07-28T18:56:54.037778Z"
}

You can list all instances in the application using the Application.list_instances method. The same information is displayed as for the individual instances, but as a list of objects.

import json
import os

from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instances = app.list_instances()

print(json.dumps([instance.to_dict() for instance in instances], indent=2))

uv run main.py

[
  {
    "id": "latest",
    "application_id": "drifting-heron",
    "version_id": "",
    "name": "Latest",
    "description": "Auto-created instance to manage the latest pushed executable binary.",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "queuing": {
        "priority": 6,
        "disabled": false
      }
    },
    "locked": false,
    "created_at": "2026-07-28T18:56:39.388355Z",
    "updated_at": "2026-07-28T18:56:39.388355Z"
  },
  ...
  {
    "id": "production",
    "application_id": "drifting-heron",
    "version_id": "v0.0.1",
    "name": "The main production instance",
    "description": "",
    "configuration": {
      "execution_class": "6c9500mb870s",
      "queuing": {
        "priority": 6,
        "disabled": false
      }
    },
    "locked": false,
    "created_at": "2026-07-28T18:56:54.037778Z",
    "updated_at": "2026-07-28T18:56:54.037778Z"
  }
]

The latest instance is the default instance of an application and is automatically created when an application is created. The latest instance always point to the latest pushed executable. You cannot delete the latest instance.

For automated workflows, you can check if an instance exists with the Application.instance_exists method. The method returns True if the instance exists, and False if it does not.

import os

import nextmv
from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
exists = app.instance_exists(instance_id="production")

nextmv.write({"exists": exists})

uv run main.py

{
  "exists": true
}

Update an instance

You can update attributes of an instance and its configuration with the Application.update_instance method, such as its:

Go the reference section to see all the available parameters for updating an instance. The parameters are similar to the ones available in the Application.new_instance method.

To lock and unlock an instance, use the locked keyword argument, passing True or False, respectively. You can only update the locked status of an instance when you update it, not when you create it.

You cannot update the instance ID. For the latest instance, you cannot update the version ID, as it is always associated to the latest pushed executable.

import os

import nextmv
from nextmv import cloud
from nextmv import RunQueuing

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
instance = app.update_instance(
    id="production",
    configuration=cloud.InstanceConfiguration(
        options={"details": "true"},
        queuing=RunQueuing(priority=9),
    ),
    locked=True,
)

nextmv.write(instance.to_dict())

uv run main.py

{
  "id": "production",
  "application_id": "drifting-heron",
  "version_id": "v0.0.1",
  "name": "The main production instance",
  "description": "",
  "configuration": {
    "execution_class": "6c9500mb870s",
    "options": {
      "details": "true"
    },
    "queuing": {
      "priority": 9,
      "disabled": false
    }
  },
  "locked": true,
  "created_at": "2026-07-28T18:56:54.037778Z",
  "updated_at": "2026-07-28T18:58:04.139398Z"
}

Delete an instance

Warning

Deleting an instance is irreversible. All the instance's data will be permanently deleted.

Info

  • You cannot delete the latest instance.
  • You cannot delete locked instances. You must unlock the instance before deleting it.

Delete an instance using the Application.delete_instance method.

import os

from nextmv import cloud

client = cloud.Client(api_key=os.getenv("NEXTMV_API_KEY"))
app = cloud.Application.get(client=client, id="drifting-heron")
app.delete_instance(instance_id="staging")

uv run main.py