Quick Start#

This page walks through a minimal LP against cuopt_grpc_server in two ways:

Remote execution — set CUOPT_REMOTE_HOST and CUOPT_REMOTE_PORT on the client; the same Python, C (cuOptSolve), or cuopt_cli APIs you use locally forward to the GPU server with no code changes.
Python async gRPC client — the same LP, with host and port passed to Client(...) for explicit job control (submit / wait / result / delete).

Start the GPU server, then try remote execution first; the gRPC-client variant follows immediately after that demo. Full client docs: Python Async gRPC Client. Custom clients call CuOptRemoteService directly (see gRPC API (Reference)).

Note

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

How Remote Execution Works#

GPU server — On the machine with the GPU, run cuopt_grpc_server (bare metal or in the cuOpt container) so it listens on a TCP port (default 5001).
Client machine — On the machine where you invoke the solver (which may be the same host), install the NVIDIA cuOpt client libraries. Set CUOPT_REMOTE_HOST to the GPU server’s hostname or IP and CUOPT_REMOTE_PORT to the listen port.
Solve — Call the same APIs you would for a local solve. The integrated client 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 the client machine where applicable).

Install NVIDIA cuOpt#

Use the selector below on the GPU server and on client machines 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 on the GPU server after installing the C/libcuopt bundle (that package ships cuopt_grpc_server). A Python-only client install does not include this binary:

cuopt_grpc_server --help

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

Run the gRPC Server (GPU Server)#

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 to the client.

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.

Minimal Python Example#

On the client machine, point remote execution at the GPU server (use 127.0.0.1 if the server is on the same host):

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

Optional TLS and tuning variables are in Advanced Configuration. The same exports apply to the C API and cuopt_cli.

The script below is the same for local or remote solves: with the exports above, the integrated client 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_maximize(True)

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

Same LP via the Python Async gRPC Client

Remote execution needs no code changes. If you want explicit job control instead, leave CUOPT_REMOTE_* unset and use the Python async gRPC client. Pass the GPU server’s network location in the Client constructor (host and port); it does not read CUOPT_REMOTE_*.

Keep the DataModel setup and SolverSettings from the listing above, and replace everything from the Solve call onward (line 33 in that listing) with:

from cuopt.grpc.linear_programming import Client, JobStatus

# Network location of cuopt_grpc_server (not CUOPT_REMOTE_*).
client = Client("localhost", 5001)
job_id = client.submit(dm, settings)
try:
    status = client.wait(job_id, timeout=120)
    if status != JobStatus.COMPLETED:
        raise RuntimeError(f"unexpected status: {status}")
    # Pass variable names if you want solution.get_vars() keyed by name.
    solution = client.result(job_id, variable_names=["x0", "x1"])
    print("Termination:", solution.get_termination_reason())
    print("Objective:  ", solution.get_primal_objective())
    print("Primal x:   ", solution.get_primal_solution())
finally:
    client.delete(job_id)

A full walkthrough of log and incumbent streaming is in Python Async gRPC Client Examples. Overview and TLS details: Python Async gRPC Client.

Minimal `cuopt_cli` Example (LP)#

The same LP is available as MPS. With CUOPT_REMOTE_HOST and CUOPT_REMOTE_PORT set as in the Python example 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
OBJSENSE
 MAXIMIZE
ROWS
 N  COST
 L  ROW1
 L  ROW2
COLUMNS
    VAR1      COST                 0.2
    VAR1      ROW1                 3.0   ROW2                 2.7
    VAR2      COST                 0.1
    VAR2      ROW1                 4.0   ROW2                10.1
RHS
    RHS1      ROW1                 5.4   ROW2                 4.9
BOUNDS
 LO BND1      VAR1                 0.0
 UP BND1      VAR1                 2.0
 LO BND1      VAR2                 0.0
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 cuOptSolve as in cuOpt Convex Optimization C API Reference.

More patterns: Examples.

Next Steps#

Installation — Top-level install selector (all interfaces), including Container pulls.
Python Async gRPC Client — Python async gRPC client (explicit jobs).
Advanced Configuration — TLS / mTLS, Docker environment reference, tuning, limitations, troubleshooting.
Examples — Additional client examples and links to LP/MIP sample collections.
gRPC API (Reference) and gRPC Server Behavior — RPC summary and server behavior overview.

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