Custom apps

Reference for how to use custom apps.

This page assumes you have read the Apps Core Concept page.

Custom apps contain executable binaries that have been pushed from a custom model, the versions and instances used to manage these executable binaries, records of runs made, and the results of experiments run on various executable binaries of the app.

Create a custom app

Custom apps can be created in Nextmv Console (Console) or Nextmv CLI. They are created independently from custom models initiated on your local machine via Nextmv CLI. Custom apps are never formally connected to any local directory, however when you run the push command from Nextmv CLI, you must always specify an application ID which is how Nextmv CLI knows which application to publish the executable binary to.

Also, whenever you run create commands with Nextmv CLI, whether it’s creating a new version, instance, experiment, or run, you must always specify an application ID.

In Console, navigate to the main Apps page and then click the Add new app button in the upper right. The fields for a new app are described in the table below.

Field Description
Name & descriptionThese are for your reference only and have no bearing on the application. The name is required, the description is optional.
IDThe ID may only include lowercase letters, numbers, periods, or hyphens and must be between 3 and 30 characters (and cannot start or end with a hyphen or period). The app ID must be unique to the account you are creating it in.

After filling out the fields, click the Create app button to create your new app. You will be redirected back to the main Apps page where you should now see your new custom app. Click on the name of the custom app to view the app’s details and subsections.

For how to create a custom app via Nextmv CLI, see the Nextmv CLI create command reference section.

Publish an executable binary


In its simplest form, you can publish an executable binary to a custom application with the push command. This command creates and packages an executable binary from the custom model you are building locally, and then pushes it to Nextmv Cloud. The push operation will override any prior executable binary in the app it is pushing to if it exists.

This operation will also update the devint to reference this newly pushed executable binary (see Reserved devint instance). The push command is the primary method for publishing a new executable binary to your app.


There is also promote, a helper command that chains together a few commands to assign the app’s current executable binary to a version and then assign that new version to the app’s default instance. (An instance ID can also be specified to attach the version to and that instance will be set as the app’s default instance, replacing the prior default instance if it existed. And if the instance ID does not exist, a new instance will be created.)

Precisely speaking, the promote command will create a new version with the name and ID you pass to the command and assign the app’s current executable binary to this version. Then if you have not specified an instance ID it will assign this newly created version to the app’s default instance. If you did specify an instance ID, then the newly created version will be assigned to this instance, and then this instance will be set as the app’s default instance (replacing the default instance if there was one prior). Lastly, if the instance ID you specified does not exist, a new instance will be created using the specified ID (the name will be auto-generated), the newly created version assigned to the instance, and this newly created instance set as the app’s default instance.

The promote command is provided as a quick way to move a pushed executable binary to an app’s default instance so you can then run it from the API endpoints. However, if you are using Nextmv CLI to run remotely then there is no need to run the promote command because the run command operates off of the reserved devint by default (which always contains the most recently pushed executable binary).

promote equivalent

If you would rather be explicit in how you manage executable binaries, here are the equivalent commands for performing the same action as promote:

nextmv app version create --app-id --name --version-id
nextmv app instance update --app-id --version-id

Run a custom app

You can run a custom app with either the Nextmv CLI using the run command, or with the HTTP API /runs endpoint. Note that if you are submitting and/or retrieving files that are larger than 6 MB then you need to use the large file method for submitting runs and retrieving run results.

Manage a custom app

Instances are provided for managing the different versions of executable binaries in your app. You can create as many instances and versions as you need, there is no limit.

Setting a default instance

When you first create a custom app, there are no executable binaries, version, or instances. However, once you have these entities you may want to set an instance as the default instance.

You can do this in Console by going to the app’s main detail view and clicking Edit App in the upper right. There will be an Instances row with a dropdown of available instances. Select the instance you would like to be the app’s default instance and then click Save. This instance is now your app’s default instance.

In Nextmv CLI, you can set the default instance as well by running the nextmv app update command and passing the app’s ID as well as the ID of the instance you want to set as the default instance.

After setting a default instance, when you submit a run to your app’s /runs API endpoint your app will use this instance to execute the run by default.

Note: remember that when you make a remote run with Nextmv CLI it assumes a developer context and uses the reserved devint as the default instance. Read more in the devint section of Apps core concepts.

Specifying an instance

If you need to specify a certain instance to use for an application run, you can do so by appending the ?instance_id= query parameter to the app’s /runs endpoint:


In Nextmv CLI, to specify a certain instance you can pass the --instance flag with the run command. See the CLI app run command reference.

Page last updated

Go to on-page nav menu