Workloads API

# Playground

Describe the work and its constraints, not a machine SKU. Watch Nodus match a catalog route, run with checkpoints, and recover from a reclaim. No API key required.

# Install

From the monorepo (published PyPI later). Runtime dependency: httpx.

$ pip install -e sdk/python
# or: pip install nodus-sdk  (when published)

# Authentication

Every request carries Authorization: Bearer <api_key>. Sign in to the console with your email and password, then issue a key under Access. Keys are stored as a SHA-256 hash and shown once at creation, so copy it then. Revocation is checked on every request, so cutting off a leaked key takes effect on the next call, and revoking a key never signs you out of the console.

Nothing here is bound to a host. Set NODUS_BASE_URL or pass nodus.Client(base_url=…); the contract is the same.

# Quick start

Describe the work and constraints. Hardware fit, placement, and recovery stay with Nodus.

# export NODUS_API_KEY=nk_live_…
>>> import nodus
>>>
>>> with nodus.Client() as client:
...     wl = client.run(
...         command=["train"],
...         model="7B fine-tune",
...         peak_memory_gb=24,
...         expected_runtime_hours=1,
...         budget=100,
...     )
...     done = client.wait(wl.id)
...     print(done.status, done.spend_usd)
WorkloadStatus.COMPLETED 0.02

# HTTP surface

The SDK is a thin client over this surface. Everything is tenant-scoped, so another tenant’s workload id reads as absent rather than forbidden. Submission rules are in retries & idempotency.

# CLI

The nodus command ships with the SDK and reads the same environment. Fastest way to submit a one-off brief from a terminal.

$ export NODUS_API_KEY=nk_live_…

# submit and block until the work is done
$ nodus run \
      --model "7B fine-tune" \
      --peak-memory-gb 80 --hours 18 --budget 400 \
      --continuity checkpointed \
      --wait --timeout 72000 \
      -- python train.py --epochs 10

# inspect without blocking
$ nodus list --status active
$ nodus get wl_9f3c1b2a --wait
$ nodus events wl_9f3c1b2a --follow
$ nodus artifacts wl_9f3c1b2a
$ nodus cancel wl_9f3c1b2a

Everything after -- runs inside the workload. --wait exits non-zero on failed or cancelled, so it composes in CI.