Run your app remotely

Deploy a custom app to Nextmv Cloud in 5 minutes

This tutorial requires access to the Production plan. You can start a free Production trial with your Nextmv Cloud account from the Apps page. Follow the prompts there to start your free trial.

1Create a new application

After going through the Get Started guide, you should have a directory with a local version of your app. In this tutorial we will go through the steps of deploying this app to Nextmv Cloud.

In your terminal, using Nextmv CLI run the following command to create your first app (this can be done from anywhere, you do not have to be in your project’s home directory):

nextmv app create \
  --app-id sudoku \
  --name "Sudoku" \
  --description "My sudoku app"

This creates a new app with an id of sudoku. You can view your newly created app on the Apps page in Nextmv Console.

Alternatively, you can just create the new app from Console by navigating to your Apps page, clicking the New App button and filling out the details there. However, for this tutorial we will be using Nextmv CLI.

Go to step 2

2Push an executable binary to your app

Your new app is just a shell at the moment; it does not contain any executable code. In this step you will build your local model into an executable binary and push it to your new application in Nextmv Cloud.

First, navigate to your local directory that was created in the Get Started guide and then build and push your local model to Nextmv Cloud with the push command:

nextmv app push --app-id sudoku

The push command will build and publish your model as an executable binary to the application you specify. After the push process has completed, run your app remotely with the run command:

nextmv app run \
  --app-id sudoku \
  --input ./input.json \

(Adding the --wait flag will poll the run until the result is available and then display the result.)

After the run has completed you should get back the output of your run. Congratulations! You just made a remote run with your custom model.

When running from Nextmv CLI, an assumption is made to run with the most recently pushed binary and we do some behind the scenes work to make that happen. For this tutorial we are skipping over those details, but they are covered in depth in the Managing Apps how-to guide.

Go to step 3

3Assign your executable to a version

You now have an executable binary of your custom model in Nextmv Cloud. However, if you were to re-run the push command, the prior pushed binary would be overwritten by this new binary. The way to preserve a specific binary is to assign it to a version.

When you create a new version, the version is assigned the most recently pushed executable. You can think of versions as versions of your executable binaries.

In Nextmv CLI, we will use the promote command to create a new application version with the executable we pushed in step 2:

nextmv app promote \
  --app-id sudoku \
  --name "Initial version" \
  --version-id initial-version \
  --instance-id production

The promote command performs a few extra steps to not only assign the executable to a version but also set that version as the default executable for your app’s REST API endpoints using another concept called instances (hence the instance ID specified). For now we will skip this concept, but instances are covered in the Managing Apps how-to guide.

Now, no matter how many times a new binary is pushed to your app, your app’s API endpoints will always use the executable in the version we just specified. (Though note that remote runs made with Nextmv CLI as a developer-first experience use the most recently pushed binary unless you specify the --default flag.)

Go to step 4

4Run the model remotely

You already ran your app remotely in Step 2 with Nextmv CLI. Now run it remotely using your application’s REST API endpoint (make sure to replace the API key placeholder with your actual API key.)

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY" \
  -d "{ \
        \"input\": $(cat ./input.json) \
      }" \

Note that the full API schema for your app can be found in your app’s API Reference page in Console.

The command above executes the run remotely using the version we specified in step 3 as it is the version assigned to the app’s default instance. The run ID that is returned is used to retrieve the run result. Save this unique run ID for the next step.

Go to step 5

5View the results

Retrieve the results of the run created in Step 4 with your application’s run GET endpoint (make sure to fill in the placeholders with your API key and the run ID from step 4):

curl -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NEXTMV_API_KEY" \

The returned result from the API call will contain your solution in the output block of the JSON along with search statistics and the solver options that were used. Also included is a metadata block that contains the run result status and other metadata. You should see the application_instance_id and application_version_id we set with the promote command in step 3 reflected here as well.

  "id": "<YOUR_RUN_ID>",
  "metadata": {
    "status": "succeeded",
    "created_at": "<DATE>",
    "duration": 2178,
    "input_size": 283,
    "output_size": 581,
    "error": "",
    "application_id": "sudoku",
    "application_instance_id": "production",
    "application_version_id": "initial-version"
  "output": {
    "version": {
      "sdk": "<VERSION>"
    "options": {
    "solutions": [
        "store": [
          [ 7, 4, 8, 9, 1, 6, 5, 3, 2 ],
          [ 1, 5, 9, 3, 2, 7, 6, 8, 4 ],
          [ 3, 2, 6, 8, 5, 4, 7, 1, 9 ],
          [ 5, 9, 3, 2, 6, 8, 4, 7, 1 ],
          [ 2, 1, 4, 5, 7, 3, 9, 6, 8 ],
          [ 6, 8, 7, 1, 4, 9, 3, 2, 5 ],
          [ 4, 3, 1, 7, 8, 5, 2, 9, 6 ],
          [ 8, 7, 5, 6, 9, 2, 1, 4, 3 ],
          [ 9, 6, 2, 4, 3, 1, 8, 5, 7 ]
        "statistics": {

You now have successfully deployed a custom model to Nextmv Cloud that could be used in a production environment. Explore the links below to learn more about managing custom applications with Nextmv Cloud.

Explore Apps further