Python SDK

Launch, use and stop private GPUs from Python. The SDK wraps the ComputeNexa API with Python methods, waits for machines to start, retries when the API is busy, and raises a clear error for every refusal.

1. Install

pip install computenexa

It also installs cnx, a command-line tool for your terminal and CI.

Python 3.9 or newer. PyPI · Source on GitHub (MIT licence).

2. Add your API key

Create a key in the dashboard under API keys: "Launch and stop" to launch, "Look only" for read-only scripts (see Use the API, steps 1 and 2). Keep it in an environment variable, never in your code:

export CNX_API_KEY="cnxk_..."

Or pass it directly: Client(api_key=...). The key acts as the person who created it and spends the team's credits.

3. Quick start

cnx.gpu(...) launches a GPU, waits until it's running, and stops it when the with block ends, even if your code fails. You never leave a GPU running by accident.

from computenexa import Client

cnx = Client()                                    # reads CNX_API_KEY

with cnx.gpu("rtx-4090", app="datascience", hours=2) as machine:
    print(machine.ssh_command)                    # ssh cnx-7f3a9c@ssh.computenexa.com
    ...                                           # your work
# stopped here, even if your code failed; unused minutes refunded

4. Choose a GPU and an app

app= is the same choice as What do you want to do? on the launch page:

On the launch page	In the API (`image_family`)	Pick it to…	AI model	SSH key
Private Chat	`chat`	Chat with open AI models about your documents, in your browser	Optional (recommended one by default)	Not needed
Image Generation (ComfyUI)	`imagegen`	Create images with SDXL or FLUX in ComfyUI, in your browser	Optional (recommended one by default)	Not needed
Model API (vLLM)	`modelapi`	An AI model behind your own API key, for your apps and scripts	Required	Not needed
Voice Agent	`voice`	Speech in, spoken AI reply out: assistants and phone agents	Required (one offered)	Not needed
Notebook (Jupyter)	`datascience`	JupyterLab with PyTorch, pandas and Hugging Face: analysis, training, fine-tuning	None	Recommended
Basic (SSH only)	`basic`	Ubuntu with CUDA and Python for your own code, over SSH or VS Code	None	Required

catalog = cnx.catalog()                           # live prices and stock
for gpu in catalog.available(app="chat"):         # for sale now, cheapest first
    print(gpu.slug, gpu.vram_gb, "GB", gpu.price_per_hour_cents / 100, "$/h")

chat = catalog.apps["chat"]
print(chat.summary)
print(chat.recommended_model(vram_gb=48))         # our model pick for a 48 GB GPU
print(cnx.image_contents("datascience"))          # every package and version installed

For apps that take a model, leave model= out to get the recommended one for the GPU.

5. Keep files between sessions with projects

A project is saved storage: a GPU launched with it starts with the project's files in ~/work and saves ~/work back automatically.

project = cnx.get_or_create_project("titanic-training")

machine = cnx.launch("l40s", app="datascience", hours=4, project=project, label="nightly training")
machine.wait_until_running(on_progress=lambda m: print(m.state, m.startup_progress or ""))
print(machine.ssh_command)
# ... files you write in ~/work are saved back to the project automatically ...
machine.stop()
print("refunded", machine.refunded_cents / 100)

6. Manage machines

cnx.list_instances(active=True)                   # your starting and running machines
cnx.list_instances(everyone=True)                 # the whole team's (owners and admins)
machine = cnx.get_instance("cnx-7f3a9c")
machine.refresh()                                 # its latest state
machine.extend(hours=1)                           # same price it launched with
machine.stop()                                    # stops if running, cancels if still starting

Each machine has id, state (requested, provisioning, running, stopping, terminated, failed), ssh_command, time_left_seconds, cost_so_far_cents, charged_cents, refunded_cents; the full reply is in .raw.

7. Account, credits and SSH keys

me = cnx.account()
print(me.email, me.organization.name, me.organization.role)
print("balance $", me.balance, "· GPUs at a time:", me.max_concurrent_gpus)

for entry in cnx.ledger(limit=20):
    print(entry.created_at, entry.description, entry.amount_cents / 100)

cnx.add_ssh_key("Work laptop", open("/Users/me/.ssh/id_ed25519.pub").read())   # the PUBLIC key only

8. Errors

Every refusal raises a subclass of ComputeNexaError with a stable code, a message you can show and a request_id to quote to support.

Exception	When
`InsufficientCreditsError`	Not enough credits for the launch or extension
`NoCapacityError`	That GPU is fully booked right now: retry later or pick another
`GpuLimitReachedError`	Your team (or you) already run as many GPUs as allowed
`ProjectInUseError`	Another GPU is using the project
`AuthenticationError`	The key is missing, mistyped or revoked
`PermissionDeniedError`	A look-only key tried to launch, or a dashboard-only setting
`NotFoundError`	No such machine or project, or not one you can see
`LaunchFailedError`	The machine couldn't start (refunded in full)
`WaitTimeoutError`	wait_until_running gave up; the machine may still start

from computenexa import NoCapacityError, InsufficientCreditsError

for gpu in ["rtx-4090", "l40s", "a40"]:           # fall back to another GPU when one is booked up
    try:
        machine = cnx.launch(gpu, app="chat", hours=1)
        break
    except NoCapacityError:
        continue
    except InsufficientCreditsError as e:
        print(e.message)                          # "Not enough credits for this duration."
        raise

Reads are retried automatically when the API is busy or has a server error. A launch is never retried after an uncertain failure, so it can't start two GPUs.

Every method, parameter and exception: Python SDK reference.

Configuration

Setting	Default
`Client(api_key=...)` or `CNX_API_KEY`	required
`Client(base_url=...)` or `CNX_API_URL`	`https://api.computenexa.com/v1`
`Client(timeout=...)`	30 seconds per request
`Client(max_retries=...)`	3

Something missing? Every operation is in the API reference; tell us at support@computenexa.com or open an issue on GitHub.