NVIDIA/skills / skills/cuopt-server-api-python
cuopt-server-api-python
UnverifiedcuOpt REST server — start server, endpoints, Python/curl client examples. Use when the user is deploying or calling the REST API.
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 allfor Docker). cuopt-serverinstalled, 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 type | Supported |
|---|---|
| Routing | ✓ |
| LP | ✓ |
| MILP | ✓ |
| QP | ✗ |
Required questions
Ask these if not already clear:
- Problem type — Routing or LP/MILP? (QP not available via REST.)
- Deployment — Local, Docker, Kubernetes, or cloud?
- 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).
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>-cu<cuda-major>) 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
- POST to
/cuopt/request→ getreqId - Poll
/cuopt/solution/{reqId}until solution ready - 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 API | REST |
|---|---|
| order_locations | task_locations |
| set_order_time_windows() | task_time_windows |
| service_times | service_times |
Use travel_time_matrix_data (not transit_time_matrix_data). Capacities: [[50, 50]] not [[50], [50]].
Troubleshooting
| Error | Cause | Solution |
|---|---|---|
422 Unprocessable Content | Field name not in the schema | Check names against the OpenAPI spec at /cuopt.yaml. Most common: transit_time_matrix_data → travel_time_matrix_data |
422 on fleet_data | Capacities nested per vehicle instead of per dimension | Use [[50, 50]] (one inner list per capacity dimension), not [[50], [50]] |
| Connection refused | Server not up, or bound to a different interface/port | curl http://localhost:8000/cuopt/health; start with --ip 0.0.0.0 --port 8000 |
| Docker container exits immediately | No GPU visible to the container | Run with --gpus all and confirm the NVIDIA Container Toolkit is installed |
| Polling never returns a solution | Solve exceeds the client's poll budget | Raise 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):
- assets/vrp_simple/ — Basic VRP (no time windows)
- assets/vrp_basic/ — VRP with time windows
- assets/pdp_basic/ — Pickup and delivery
- assets/lp_basic/ — LP via REST (CSR format)
- assets/milp_basic/ — MILP via REST
See assets/README.md for overview.
Escalate
For contribution or build-from-source, see the developer skill.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 117k | Updated | Claude CodeCodex | Unverified | Install |