Index of every page on this site: llms.txt
All skills
nvidia avatar

/cuopt-server-api-python

@6b75e9e
by NVIDIA Corporationnvidia/skills4.1k stars
547
Run it yourself

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

Use this Skill: https://skilld.dev/gh/nvidia/skills/cuopt-server-api-python

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈39 tokens for metadata: the name and description. ≈1.4k when used: this file. ≈6.1k more on demand in 9 files.

Description uses 1.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈155 characters, or 1.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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 type Supported
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).

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

  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 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):

See assets/README.md for overview.

Escalate

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill provides a Python client for the NVIDIA cuOpt optimization server. It is generally safe but includes minor security concerns such as the recommendation of mutable Docker tags and the use of unauthenticated network communication, both of which are documented with appropriate mitigations.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at 6b75e9e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated last month
version
26.12.00
Other metadata
metadata
{
  "author": "NVIDIA cuOpt Team",
  "tags": [
    "cuopt",
    "server",
    "rest-api",
    "python",
    "deployment"
  ]
}

README badge

README badge for nvidia/skills/cuopt-server-api-python