Explore Nextmv with a new model and the CLI

In this tutorial you will learn how to use community apps to explore new decision models and the Nextmv Platform, from scratch. Complete this tutorial if you:

• Don't have a pre-existing decision model and you want to explore the Nextmv Platform.
• Are fluent using a language of your preference, such as Python, Java, Go, etc.

Community apps are Nextmv Applications that showcase how to solve different decision problems with various languages and solvers. They are a great way to explore new decision models and the Nextmv Platform. You can think of community apps as examples that serve as strong references when building and customizing your own decision models.

At a high level, this tutorial will go through the following steps:

1. Clone a community app locally.
2. Push the model to Nextmv Cloud.
3. Run the model remotely.
4. Perform scenario testing.

Let’s dive right in 🤿.

1. Create an account

The full suite of benefits starts with a Nextmv Cloud account.

1. Visit the Nextmv Console to sign up for an account at https://cloud.nextmv.io.
2. Verify your account.
   • You’ll receive an email asking to verify your account.
   • Follow the link in that email to sign in.
3. Log in to your account. The Nextmv Console is ready to use!

Once you have logged in to your account, you need to fetch your API key. You can do so from your settings.

When you have your API key, it is convenient to save it as an environment variable so that you can use it for the rest of this tutorial.

export NEXTMV_API_KEY="<YOUR-API-KEY>"

2. Install the Nextmv CLI

Run the following script to install Nextmv CLI:

export NEXTMV_BASE_URL=https://api.cloud.nextmv.io
curl -sS "https://cloud.nextmv.io/install-cli.txt" | bash -

After downloading and installing, the last step is to configure Nextmv CLI with your account:

nextmv configure --api-key $NEXTMV_API_KEY

To check if the installation was successful, run the following command to show the help menu:

nextmv --help

3. Clone a community app

To work with community apps you have two options:

1. Clone the GitHub repository locally.
2. Use the Nextmv CLI to clone a specific community app.

This tutorial will use the second option.

You can list the available community apps with the following command:

$ nextmv community list

╭─────────────────────────────────────────┬────────┬─────────────┬──────────────────────────────────────────────────────────────╮
│ Name                                    │ Type   │ Latest      │ Description                                                  │
├─────────────────────────────────────────┼────────┼─────────────┼──────────────────────────────────────────────────────────────┤
│ go-hello-world                          │ go     │ v20251006.0 │ Get started with Go and Nextmv.                              │
│ go-highs-knapsack                       │ go     │ v20251006.0 │ Use Go and HiGHS - knapsack.                                 │
│ go-highs-orderfulfillment               │ go     │ v20251126.0 │ Use Go and HiGHS - order fulfillment.                        │
│ go-highs-shiftscheduling                │ go     │ v20251006.0 │ Use Go and HiGHS - shift scheduling.                         │
│ go-nextroute                            │ go     │ v20251112.0 │ Use Go and Nextroute - VRP.                                  │
│ java-gurobi-knapsack                    │ java   │ v20251006.0 │ Use Java and Gurobi - knapsack.                              │
│ java-gurobi-multiknapsack-multiexcel    │ java   │ v20251006.0 │ Use Java and Gurobi - multi knapsack via Excel.              │
│ java-hello-world                        │ java   │ v20251006.0 │ Get started with Java and Nextmv.                            │
│ java-hexaly-knapsack                    │ java   │ v20251006.0 │ Use Java and Hexaly - knapsack.                              │
│ java-ortools-knapsack                   │ java   │ v20251006.0 │ Use Java and OR-Tools - knapsack.                            │
│ java-ortools-routing                    │ java   │ v20251006.0 │ Use Java and OR-Tools - VRP.                                 │
│ python-ampl-facilitylocation            │ python │ v20251201.0 │ Use Python and AMPL - facility location.                     │
│ python-ampl-knapsack                    │ python │ v20251201.0 │ Use Python and AMPL - knapsack.                              │
│ python-ampl-priceoptimization           │ python │ v20251201.0 │ Use Python and AMPL - price optimization.                    │
│ python-cuopt-routing                    │ python │ v20251201.0 │ Use Python and cuOpt - VRP.                                  │
│ python-gams-cutstock                    │ python │ v20251201.0 │ Use Python and GAMS - cutstock.                              │
│ python-gamspy-traveling-salesman        │ python │ v20251201.0 │ Use Python and Gamspy - traveling salesman.                  │
│ python-gurobi-knapsack                  │ python │ v20251201.0 │ Use Python and Gurobi - knapsack.                            │
│ python-gurobi-price-optimization        │ python │ v20251201.0 │ Use a Nextmvified Gurobi notebook for price optimization.    │
│ python-hello-world                      │ python │ v20251201.0 │ Get started with Python and Nextmv.                          │
│ python-hexaly-generic                   │ python │ v20251201.0 │ Use Python and Hexaly - hxm models.                          │
│ python-hexaly-knapsack                  │ python │ v20251201.0 │ Use Python and Hexaly - knapsack.                            │
│ python-highs-knapsack                   │ python │ v20251201.0 │ Use Python and HiGHS - knapsack.                             │
│ python-nextmv-gurobipy-knapsack         │ python │ v20251118.0 │ Use the Python Nextmv & gurobipy integration - knapsack.     │
│ python-nextmv-scikit-learn-diabetes     │ python │ v20250507.0 │ Use the Python Nextmv & scikit-learn integration - diabetes. │
│ python-nextroute                        │ python │ v20251201.0 │ Use Python and Nextroute - VRP.                              │
│ python-ortools-costflow                 │ python │ v20251201.0 │ Use Python and OR-Tools - cost flow.                         │
│ python-ortools-demandforecasting        │ python │ v20251201.0 │ Use Python and OR-Tools - demand forecasting.                │
│ python-ortools-knapsack                 │ python │ v20251201.0 │ Use Python and OR-Tools - knapsack.                          │
│ python-ortools-knapsack-multicsv        │ python │ v20251201.0 │ Use Python and OR-Tools - multi CSV knapsack.                │
│ python-ortools-multiknapsack-multiexcel │ python │ v20251201.0 │ Use Python and OR-Tools - multi knapsack via Excel.          │
│ python-ortools-region-allocation        │ python │ v20251201.0 │ Use Python and OR-Tools - region allocation.                 │
│ python-ortools-routing                  │ python │ v20251201.0 │ Use Python and OR-Tools - VRP.                               │
│ python-ortools-shiftassignment          │ python │ v20251201.0 │ Use Python and OR-Tools - shift assignment.                  │
│ python-ortools-shiftplanning            │ python │ v20251201.0 │ Use Python and OR-Tools - shift planning.                    │
│ python-pyomo-knapsack                   │ python │ v20251201.0 │ Use Python and Pyomo - knapsack.                             │
│ python-pyomo-shiftassignment            │ python │ v20251201.0 │ Use Python and Pyomo - shift assignment.                     │
│ python-pyomo-shiftplanning              │ python │ v20251201.0 │ Use Python and Pyomo - shift planning.                       │
│ python-pyoptinterface-knapsack          │ python │ v20251201.0 │ Use Python and PyOptInterface - knapsack.                    │
│ python-pyvroom-routing                  │ python │ v20251201.0 │ Use Python and Pyvroom - VRP.                                │
│ python-scip-knapsack                    │ python │ v20251201.0 │ Use Python and SCIP - knapsack.                              │
│ python-tr-ortools-region-allocation     │ python │ v20251201.0 │ Use tracked runs in Python - region allocation.              │
│ python-vroom-premium-api-routing        │ python │ v20251201.0 │ Use Python and Vroom Premium API - VRP.                      │
│ python-wf-custom-visuals                │ python │ v20251006.0 │ Use workflows in Python - custom visuals.                    │
│ python-wf-ortools-region-allocation     │ python │ v20251201.0 │ Use workflows in Python - region allocation.                 │
│ python-xpress-knapsack                  │ python │ v20251201.0 │ Use Python and Xpress - knapsack.                            │
╰─────────────────────────────────────────┴────────┴─────────────┴──────────────────────────────────────────────────────────────╯

This command is saved as app1.sh in the full tutorial code.

For this tutorial, we will be using the python-highs-knapsack community app, which solves a knapsack problem using the HiGHS solver and Python. To clone this community app, run the following command:

$ nextmv community clone -a python-highs-knapsack

✅ Successfully cloned the "python-highs-knapsack" community app using version "latest" in path: ...

This command is saved as app2.sh in the full tutorial code.

Once the app has been cloned, you should see a structure similar to the following:

python-highs-knapsack
├── app.yaml
├── input.json
├── LICENSE
├── main.ipynb
├── main.py
├── README.md
└── requirements.txt

4. Run the community app locally

You can run the executable code locally to verify that everything is working as expected. Each community app comes with a README.md file that contains detailed instructions on how to run the app locally. Let’s follow those steps to run the app.

1. Make sure you are standing at the root of the cloned community app, where the app.yaml manifest is located.

2. Install the required dependencies:

   • Bash

   pip install -r requirements.txt
   

   Copy

3. Run the app:

   • Bash

   $ python main.py -input input.json -output output.json -duration 30
   Solving knapsack problem:
    - items: 11
    - capacity: 50
   

   Copy

4. Verify that an output.json file has been created with the results of the run.

   • Bash

   $ cat output.json
   
   {
     "options": {
       "input": "input.json",
       "output": "output.json",
       "duration": 30,
       "version": "1.9.0"
     },
     "solution": {
       "items": [
         {
           "id": "cat",
           "value": 100,
           "weight": 20
         },
         {
           "id": "water",
           "value": 40,
           "weight": 2
         },
         {
           "id": "phone",
           "value": 6,
           "weight": 1
         },
         {
           "id": "book",
           "value": 63,
           "weight": 10
         },
         {
           "id": "rx",
           "value": 81,
           "weight": 1
         },
         {
           "id": "coat",
           "value": 44,
           "weight": 9
         },
         {
           "id": "keys",
           "value": 92,
           "weight": 1
         },
         {
           "id": "nuts",
           "value": 18,
           "weight": 4
         }
       ]
     },
     "statistics": {
       "run": {
         "duration": 0.002505064010620117
       },
       "result": {
         "value": 444.0,
         "custom": {
           "status": "HighsStatus.kOk",
           "variables": 11,
           "constraints": 1
         }
       },
       "schema": "v1"
     },
     "assets": []
   }
   

   Copy

5. Subscribe to a Nextmv Plan

Running a custom application remotely in Nextmv Cloud requires a paid plan. However, plans come with a 14-day free trial that can be canceled at any time. You can upgrade your account and subscribe to a plan in Nextmv Console by clicking the Upgrade button in the header, or navigating to the Settings-> Plan section. Upgrading to a plan will allow you to complete the rest of the tutorial.

In the example shown, you will be subscribing to an Innovator plan. A pop-up window will appear, and you will need to fill in your payment details.

Once your account has been upgraded, you will see an active plan in your account.

6. Create your Nextmv Cloud Application

Run the following command:

$ nextmv app create -n test-community-app -a test-community-app

{
  "id": "test-community-app",
  "name": "test-community-app",
  "description": "",
  "type": "custom",
  "default_instance": ""
}

This will create a new application in Nextmv Cloud. Note that the name and app ID can be different, but for simplicity this tutorial uses the same name and app ID. This command is saved as app3.sh in the full tutorial code. You can also create applications directly from Nextmv Console.

You can go to the Apps section in the Nextmv Console where you will see your applications.

7. Push your Nextmv Application

So far, your application has run locally. You are going to push your app to Nextmv Cloud. Once an application has been pushed, you can run it remotely, perform testing, experimentation, and much more. Pushing is the equivalent of deploying an application, this is, taking the executable code and sending it to Nextmv Cloud.

At the root of your local project (where the app.yaml manifest is located), deploy your app (push it) to Nextmv Cloud:

$ nextmv app push -a test-community-app

💽 Starting build for Nextmv application.
🐍 Bundling Python dependencies.
📋 Copied files listed in "app.yaml" manifest.
📦 Packaged application (25.49 MiB, 2120 files).
🌟 Pushing to application: "test-community-app".
💥️ Successfully pushed to application: "test-community-app".
{
  "app_id": "test-community-app",
  "endpoint": "api.cloud.nextmv.io",
  "instance_url": "https://api.cloud.nextmv.io/v1/applications/test-community-app/runs?instance_id=devint"
}

This command is saved as app4.sh in the full tutorial code.

You can go to the Apps section in the Nextmv Console where you will see your application. You can click on it to see more details. Once you are in the overview of the application in the Nextmv Console, it should show the following:

• There is now a pushed executable.
• There is an auto-created latest instance, assigned to the executable.

An instance is like the endpoint of the application.

8. Run the Nextmv Application remotely

To run the Nextmv Application remotely, you have several options. For this tutorial, we will be using the Nextmv Console and CLI.

In the Nextmv Console, in the app overview page:

1. Press the New run button.
2. Drop the data files that you want to use. You will get a preview of the data. You can drop the input.json file that comes with the community app.
3. Optionally, configure your run according to the options that can be passed. In this case, you can configure the duration.
4. Start the run.

You can use the Nextmv Console to browse the information of the run:

• Summary
• Output
• Input
• Metadata
• Logs

Nextmv is built for collaboration, so you can invite team members to your account and share run URLs.

Alternatively, you can run your Nextmv Application using the Nextmv CLI. Here is an example command you can run from the root of the app.

$ nextmv app run -a test-community-app -i input.json

{
  "run_id": "devint-jjk3M1Zvg"
}

This command is saved as app5.sh in the full tutorial code.

9. Perform a scenario test

We are going to take full advantage of the Nextmv Platform by creating a scenario test. Scenario tests are generally used as an exploratory test to understand the impacts to business metrics (or KPIs) on situations such as:

• Updating a model with a new feature, such as an additional constraint.
• Comparing how the same model performs in different conditions, such as low demand vs. high demand.
• Doing a sensitivity analysis to understand how the model behaves when changing a parameter.

Start by creating an input set. As the name suggests, it is a set of inputs, and it serves as a base so that we can perform runs varying one or more configurations (options). To create an input set, you have several options. For this tutorial, we will be using the Nextmv Console and CLI. You may follow these steps for both examples.

1. Navigate to the "Input sets" section.
2. Set a name for your input set.
3. Use the "Instance + date range" creation type given that we already have a few runs on the latest instance.
4. Create the input set.

Another option for creating the input set is using the Nextmv CLI. Here is an example command.

$ nextmv experiment input-set create -a test-community-app -i latest -s input-set-2 -n "Input set 2"

{
  "id": "input-set-2",
  "name": "Input set 2",
  "description": "",
  "app_id": "test-community-app",
  "created_at": "2025-12-02T15:24:35.980849238Z",
  "updated_at": "2025-12-02T15:24:35.980849238Z",
  "input_ids": [
    "latest-BnZOZ1ZDg",
    "latest-5qrIm1ZDg"
  ],
  "inputs": []
}

This command is saved as app6.sh in the full tutorial code.

Once your input set has been created, we are going to create a scenario test. Similarly to runs and input sets, you may use the Console or CLI, amongst other options. We will continue to use the Nextmv Console in this tutorial. You may follow these steps for both examples.

1. Navigate to the Scenario section.
2. Set a name for your scenario test.
3. Select the input set you just created in the previous step.
4. Select the latest instance.
5. Create configuration combinations, which will be factored in to create the scenarios. We are setting duration to be 5, 10, 20 and 30 seconds.
6. Optionally, you may configure repetitions. These are useful when the results are not deterministic.
7. Create the scenario test. Review and confirm the number of scenarios that will be created.

Once all the runs in the scenario test are completed, you can visualize the result of the test. A pivot table is provided to create useful comparisons of your metrics (statistics) across the scenario test runs.

🎉🎉🎉 Congratulations, you have finished this tutorial!

Full tutorial code

You can find the consolidated code examples used in this tutorial in the tutorials GitHub repository. The explore-new-model-cli dir contains all the code that was shown in this tutorial.

Go into the directory for instructions about running the decision model.