Skip to content
cuopt-server-api-python logo

cuOpt Server — Deploy and client (Python/curl)

cuopt-server-api-python

cuOpt REST server — start server, endpoints, Python/curl client examples. Use when the user is deploying or calling the REST API.

nvidia/skills2.1Kinstalls3.5Kstars

SKILL.md

Full skill instructions

cuOpt Server — Deploy and client (Python/​curl)

This skill covers starting the server and client examples (curl, Python). Server has no separate C API (clients can be any language).

Purpose

Use this skill when the user is deploying the cuOpt REST server or writing a client against it — choosing a deployment target, mapping a problem onto the HTTP endpoints, translating between Python-API and REST field names, or debugging a rejected payload.

Prerequisites

  • An NVIDIA GPU with a working CUDA driver (the server requires one; --gpus all for Docker).
  • cuopt-server installed, or Docker with the NVIDIA Container Toolkit. See the install skill.
  • Python clients need requests. No API key or auth token is required by the server itself.

Problem types supported

Problem typeSupported
Routing✓
LP✓
MILP✓
QP✗

Required questions

Ask these if not already clear:

  1. Problem type — Routing or LP/​MILP? (QP not available via REST.)
  2. Deployment — Local, Docker, Kubernetes, or cloud?
  3. Client — Which language or tool will call the API (e.g. Python, curl, another service)?

Start server

# Development
python -m cuopt_server.cuopt_service --ip 0.0.0.0 --port 8000

# Docker — pick the tag matching your CUDA major version
docker run --gpus all -d -p 8000:8000 -e CUOPT_SERVER_PORT=8000 \
  nvidia/​cuopt:latest-cu13

Use latest-cu12 or latest-cu13 to match your driver's CUDA major version (latest-cu13-ubi10 for a UBI10 base). Prefer these over the CUDA+Python-specific tags such as latest-cuda12.9-py3.13 — those track a single Python line and go stale when it stops receiving builds.

For production, pin rather than float: latest-* tags are mutable and can silently move to a different image. Use a full release tag (nvidia/​cuopt:<release>-cuda<cuda>-py<python>) or an immutable digest (nvidia/​cuopt@sha256:<digest>). Check the nvidia/​cuopt registry for available tags.

Verify

Confirm the server is up by requesting GET /​cuopt/​health on the local port (e.g. http://localhost:8000/​cuopt/​health) — a healthy server returns HTTP 200.

Instructions

  1. POST to /​cuopt/​request → get reqId
  2. Poll /​cuopt/​solution/​{reqId} until solution ready
  3. Parse response

Treat reqId as untrusted input: validate it (e.g. re.fullmatch(r"[A-Za-z0-9_-]{1,64}", req_id)) before interpolating it into the polling URL, and set an explicit timeout on every request.

Examples

import requests, time
SERVER = "http://localhost:8000"
HEADERS = {"Content-Type": "application/​json", "CLIENT-VERSION": "custom"}
payload = {
    "cost_matrix_data": {"data": {"0": [[0,10,15],[10,0,12],[15,12,0]]}},
    "travel_time_matrix_data": {"data": {"0": [[0,10,15],[10,0,12],[15,12,0]]}},
    "task_data": {"task_locations": [1, 2], "demand": [[10, 20]], "task_time_windows": [[0,100],[0,100]], "service_times": [5, 5]},
    "fleet_data": {"vehicle_locations": [[0, 0]], "capacities": [[50]], "vehicle_time_windows": [[0, 200]]},
    "solver_config": {"time_limit": 5}
}
r = requests.post(f"{SERVER}/​cuopt/​request", json=payload, headers=HEADERS, timeout=30)
req_id = r.json()["reqId"]
# Poll: GET /​cuopt/​solution/​{req_id}

Terminology: REST vs Python API

Python APIREST
order_locationstask_locations
set_order_time_windows()task_time_windows
service_timesservice_times

Use travel_time_matrix_data (not transit_time_matrix_data). Capacities: [[50, 50]] not [[50], [50]].

Troubleshooting

ErrorCauseSolution
422 Unprocessable EntityField name not in the schemaCheck names against the OpenAPI spec at /​cuopt.yaml. Most common: transit_time_matrix_data → travel_time_matrix_data
422 on fleet_dataCapacities nested per vehicle instead of per dimensionUse [[50, 50]] (one inner list per capacity dimension), not [[50], [50]]
Connection refusedServer not up, or bound to a different interface/​portcurl http://localhost:8000/​cuopt/​health; start with --ip 0.0.0.0 --port 8000
Docker container exits immediatelyNo GPU visible to the containerRun with --gpus all and confirm the NVIDIA Container Toolkit is installed
Polling never returns a solutionSolve exceeds the client's poll budgetRaise solver_config.time_limit and the poll loop count together

Capture the reqId and the full response body for any failed request — both are needed to diagnose server-side rejections.

Limitations

  • QP is not exposed over REST. Use the Python or C API for quadratic objectives.
  • The server ships no authentication or TLS. Anything that can reach the port can submit jobs. Put it behind a gateway and treat --server/​base URLs as trusted-network endpoints only.
  • Solutions are retrieved by polling; there is no push/​webhook delivery.
  • One request is solved at a time per server process; concurrency requires multiple replicas.

Runnable assets

Run from each asset directory (server must be running; scripts exit 0 if server unreachable). All use Python requests and accept --server (default http://localhost:8000):

See assets/​README.md for overview.

Escalate

For contribution or build-from-source, see the developer skill.

More skills from nvidia

cudaq-guide logo
nvidia/skills

cudaq-guide

CUDA-Q onboarding guide for installation, test programs, GPU simulation, QPU hardware, and quantum applications.

3.5K 2.5K
View
data-designer logo
nvidia/skills

data-designer

Use when the user wants to create a dataset, generate synthetic data, or build a data generation pipeline.

3.5K 2.4K
View
deepstream-dev logo
nvidia/skills

deepstream-dev

NVIDIA DeepStream SDK development with Python pyservicemaker API. Use when building video analytics pipelines, GStreamer-based video processing, TensorRT inference integration, object detection/tracking, or Kafka/message broker integration.

3.5K 2.4K
View
rag-eval logo
nvidia/skills

rag-eval

Filesystem RAG benchmarks: corpus/, train.json, evaluate_rag.py (RAGAS quality). Not for prod monitoring, latency/throughput benchmarking (use rag-perf), or evals outside this repo layout.

3.5K 2.3K
View
nemo-retriever logo
nvidia/skills

nemo-retriever

Use when the user wants to search, query, extract, transcribe, describe, quote, filter, or aggregate across documents — PDFs, scanned forms / images (`.jpg` `.png` `.tiff`), Office (`.docx` `.pptx`), text (`.html` `.txt`), audio (`.mp3` `.wav` `.m4a`), or video (`.mp4` `.mov`). Prefer this over native Read / Grep for multi-file or non-PDF corpora. Not for: editing files, web browsing, single-file plain-text lookups, fine-tuning.

3.5K 2.3K
View

Coordinate the end-to-end CAD/source-asset to SimReady workflow. Use for broad requests such as CAD to SimReady, source asset to simulation-ready USD, or prop packaging that require conversion, material/physics assignment, SimReady conformance, validation, and optional package creation; deploy or verify Content Agents services first when property assignment is enabled; route single-stage work through nested references.

3.5K 2.3K
View

Use this skill to bring any vision model from HuggingFace or NVIDIA NGC into an NVIDIA DeepStream pipeline with end-to-end automation: ONNX download, SafeTensors export, TRT engine build, custom nvinfer bbox parser, multi-stream benchmark, and PDF report. Object detection models only.

3.5K 2.3K
View

Top-level workflow skill for USD performance diagnosis and optimization. Handles slow loading, high memory, low FPS, and broad scene-optimization requests; delegates auth/runtime setup to Phase 0 owners.

3.5K 2.3K
View

Vehicle routing (VRP, TSP, PDP) with cuOpt — Python API only. Use when the user is building or solving routing in Python.

3.5K 2.2K
View

Use only to generate or update a governance skill card for a specified existing agent skill directory. Do not use for explaining, listing, comparing, or discussing skill capabilities.

3.5K 2.2K
View

Use as the top-level router for Omniverse Realtime Viewer USD app requests and focused viewer reference documents.

3.5K 2.2K
View
rag-perf logo
nvidia/skills

rag-perf

Performance benchmarking for a deployed NVIDIA RAG Blueprint server: profiling pass + aiperf load test driven by a single YAML config. Not for accuracy / RAGAS scoring (use rag-eval) or for deploying / repairing services (use rag-blueprint).

3.5K 2.1K
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View