Quick start#

NVIDIA cuOpt gRPC remote execution runs LP, MILP, and QP solves on a GPU host while your Python code, C API program, `cuopt_cli`, or a custom client runs elsewhere. When you set CUOPT_REMOTE_HOST and CUOPT_REMOTE_PORT, the bundled Python, C API, and cuopt_cli clients forward solve_lp / solve_mip to cuopt_grpc_server with no code changes. Custom clients call CuOptRemoteService directly (see gRPC API (reference)).

Note

Problem types (gRPC remote): LP, MILP, and QP are supported today. Routing (VRP, TSP, PDP) over this path is not available; For remote routing, use the HTTP/JSON REST self-hosted server. This guide is not the REST server—see Server for HTTP/JSON.

How remote execution works#

GPU host — Run cuopt_grpc_server (bare metal or in the official container) so it listens on a TCP port (default 5001).
Client — Install the NVIDIA cuOpt client libraries on the machine where you invoke the solver. Set CUOPT_REMOTE_HOST to that GPU host’s address and CUOPT_REMOTE_PORT to the listen port.
Solve — Call the same APIs you would for a local solve. The client library opens a gRPC channel, streams the problem, and retrieves the result. Unset the two variables to solve locally again (local mode still needs a GPU on that machine where applicable).

Install NVIDIA cuOpt#

Use the selector below on the GPU server and on clients that need Python, the C API, or cuopt_cli. It is pre-set to C (libcuopt) because that bundle ships cuopt_grpc_server, cuopt_cli, and libraries together; switch to Python if you only need Python packages on a lightweight client.

Verify the server binary after install:

cuopt_grpc_server --help

For the same install selector with Container / registry choices (Docker Hub or NGC), see Installation.

Run the gRPC server (GPU host)#

Bare metal — after activating the same environment you used to install NVIDIA cuOpt:

cuopt_grpc_server --port 5001 --workers 1

Leave the process running. Default port 5001; change --port if needed and expose the same port on the client side.

Docker — requires NVIDIA Container Toolkit (or equivalent) on the host. Pull an image tag from Installation or the Container row in the selector above; substitute <CUOPT_IMAGE> below.

Entrypoint mode (recommended when you are not passing an explicit command):

docker run --gpus all -it --rm -p 5001:5001 \
  -e CUOPT_SERVER_TYPE=grpc \
  <CUOPT_IMAGE>

Or invoke the binary explicitly:

docker run --gpus all -it --rm -p 5001:5001 \
  <CUOPT_IMAGE> \
  cuopt_grpc_server --port 5001 --workers 1

Note

The container image defaults to the Python REST server when CUOPT_SERVER_TYPE is unset and you do not override the command; setting CUOPT_SERVER_TYPE=grpc selects cuopt_grpc_server. Extra environment variables (CUOPT_SERVER_PORT, CUOPT_GPU_COUNT, CUOPT_GRPC_ARGS) and TLS are documented in Advanced configuration.

Point the client at the server#

On the machine where you run Python, the C API, or cuopt_cli (use 127.0.0.1 if the server is on the same host):

export CUOPT_REMOTE_HOST=<gpu-hostname-or-ip>
export CUOPT_REMOTE_PORT=5001

Optional TLS and tuning variables are in Advanced configuration.

Minimal Python example (LP)#

The script is the same for local or remote solves: with the exports above, the client library forwards to cuopt_grpc_server; without them, the solve runs locally (where a GPU is available). Please make sure the server is running before running the client.

remote_lp_demo.py

# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

"""Minimal LP demo for NVIDIA cuOpt gRPC remote execution.

Set CUOPT_REMOTE_HOST and CUOPT_REMOTE_PORT on the client before running to forward
the solve to cuopt_grpc_server; unset them to solve locally (GPU required locally).

The same LP is available as MPS in ``remote_lp_demo.mps`` for ``cuopt_cli``.
"""

import numpy as np
from cuopt import linear_programming

dm = linear_programming.DataModel()
A_values = np.array([3.0, 4.0, 2.7, 10.1], dtype=np.float64)
A_indices = np.array([0, 1, 0, 1], dtype=np.int32)
A_offsets = np.array([0, 2, 4], dtype=np.int32)
dm.set_csr_constraint_matrix(A_values, A_indices, A_offsets)

b = np.array([5.4, 4.9], dtype=np.float64)
dm.set_constraint_bounds(b)

c = np.array([0.2, 0.1], dtype=np.float64)
dm.set_objective_coefficients(c)

dm.set_row_types(np.array(["L", "L"]))

dm.set_variable_lower_bounds(np.array([0.0, 0.0], dtype=np.float64))
dm.set_variable_upper_bounds(np.array([2.0, np.inf], dtype=np.float64))

settings = linear_programming.SolverSettings()
solution = linear_programming.Solve(dm, settings)

print("Termination:", solution.get_termination_reason())
print("Objective:  ", solution.get_primal_objective())
print("Primal x:   ", solution.get_primal_solution())

Run the script from your NVIDIA cuOpt Python environment. From a repository checkout (repo root):

python docs/cuopt/source/cuopt-grpc/examples/remote_lp_demo.py

Or, after downloading the file into your current directory:

python remote_lp_demo.py

You should see an optimal termination. To solve locally, unset the remote variables and rerun with the same path you used above:

unset CUOPT_REMOTE_HOST CUOPT_REMOTE_PORT
python remote_lp_demo.py

Minimal `cuopt_cli` example (LP)#

The same LP is available as MPS. With CUOPT_REMOTE_HOST and CUOPT_REMOTE_PORT set as above, cuopt_cli forwards the solve to the remote server; unset them for a local run (GPU on that machine). Please make sure the server is running before running the client.

remote_lp_demo.mps

NAME   good-1
ROWS
 N  COST
 L  ROW1
 L  ROW2
COLUMNS
   VAR1      COST      -0.2
   VAR1      ROW1      3              ROW2      2.7
   VAR2      COST      0.1
   VAR2      ROW1      4              ROW2      10.1
RHS
   RHS1      ROW1      5.4            ROW2      4.9
ENDATA

From a repository checkout (repo root):

cuopt_cli docs/cuopt/source/cuopt-grpc/examples/remote_lp_demo.mps

Or, after downloading the MPS into your current directory:

cuopt_cli remote_lp_demo.mps

To solve locally with the same file:

unset CUOPT_REMOTE_HOST CUOPT_REMOTE_PORT
cuopt_cli remote_lp_demo.mps

More options (time limits, relaxation): Quickstart Guide and Examples.

C API — With the same environment variables set, call solve_lp / solve_mip as in cuOpt LP/QP/MILP C API Reference.

More patterns (MPS variants, custom gRPC): Examples.

Next steps#

Installation — Top-level install selector (all interfaces), including Container pulls.
Advanced configuration — TLS / mTLS, Docker environment reference, tuning, limitations, troubleshooting.
Examples — Additional client examples and links to LP/MILP sample collections.
gRPC API (reference) and gRPC server behavior — RPC summary and server behavior overview.

See System Requirements for GPU, CUDA, and OS requirements.