Documentation/Python client reference

Python client reference

Client(api_key=None, base_url=None, timeout=30.0, max_retries=2) pools HTTP connections. With no arguments it uses your saved login and the hosted service. Prefer a with block. Otherwise call close(). AsyncClient uses async with or await aclose() and mirrors the methods below.

Optional settings after resource IDs are keyword-only. For download_output, name and destination can also be positional. Status filters accept nodus.WorkloadStatus members, strings, comma-separated strings, or lists. Accepted status strings are accepted, planning, reserving, provisioning, running, recovering, completed, failed, and cancelled. The active preset selects nonterminal states and terminal selects completed, failed, and cancelled. Omit status for no status filter. Unknown statuses raise ValueError. Pagination uses offsets. Concurrent new submissions can shift pages. It is not a consistent historical snapshot.

Sandbox resources

nodus.Sandbox(name=..., image=...) is the direct get-or-create form. Reusing the same name reattaches without an image. It is a context manager that terminates on exit. Call close() to release only the local HTTP client while keeping the remote sandbox alive.

client.sandboxes.create(...) accepts an image, resource requirements, a budget, network policy, lifecycle, reservation, and continuity settings. It returns an accepted Sandbox handle. Read sandbox.state or call sandbox.refresh() before assuming the environment is ready.

client.sandboxes.from_id(ID) reconnects to a sandbox. list() returns one cursor-based page and list_page() also returns next_cursor. Iterating over client.sandboxes follows every page. The asynchronous client provides the same methods and client.sandboxes.iterate().

sandbox.exec(command, ...) accepts shell command text or an argument vector, queues a process, and returns SandboxExec. execution.iter_output() yields ordered SandboxOutputFrame objects with stream, data, and decoded text. execution.write(data, eof=False) sends stdin when it was enabled at execution creation. execution.wait() returns when the process is terminal. Check succeeded and exit_code. Call sandbox.terminate() to stop future execution and request resource cleanup.

Sandbox calls use idempotency keys for create, exec, stdin, and terminate. Supply a stable key when your application retries after an uncertain response. Generated keys protect the SDK transport retries within one method call. If create, exec, or terminate returns an invalid receipt, the SDK raises APIError with the sent key in error.payload["idempotency_key"]. Reuse that key with the original arguments to recover the same operation.

Workload offers refresh, wait, cancel, events, logs, artifacts, outputs, download, routing, and ledger methods without repeating the ID. Reads and waits with refresh() and wait() update it in place. Useful attributes are id, status, succeeded, is_terminal, route, stages, meter, cost_now_usd, links, and raw. Each WorkloadLink has kind and url. Captured wandb links are available before completion. Unknown server enum values remain strings for forward compatibility.

workload.download(destination=None) downloads all published customer outputs, including automatically collected folder archives when no files were declared, and returns a list of local Path objects. The default directory is outputs/WORKLOAD_ID, with each file at STAGE/NAME. await workload.download() is the asynchronous equivalent. Use download_output(name, destination, stage=...) for one specific file.

Method arguments

For all declared files, workload.download() creates directories and refuses to overwrite existing files. Use a new destination directory for another copy.

Models

Event has type and payload, not a message attribute. Output download helpers use the authenticated API endpoint. Treat returned download as server metadata rather than a URL to which you should forward credentials.

Route.sku is a catalog identifier, not a GPU model. When available, route.resources.get("accelerator") reports the device model and route.resources.get("device_memory_gb") reports its memory in GB. Missing metadata does not prove that no GPU was used. The terminal shows Not reported when it cannot identify the compute from the response. List responses may omit the route, so use client.get(ID) or workload.refresh() for current details.

Optional typed request dictionaries

Source, Requirements, Policy, ContinuitySpec, StageInput, and StageSpec are TypedDict helpers exported by nodus. They support autocomplete and static analysis while producing ordinary dictionaries:

import nodus

requirements = nodus.Requirements(compute_class="accelerator", peak_memory_gb=24)
source = nodus.Source(image="pytorch/pytorch:2.8.0-cuda12.8-cudnn9-runtime", command=["python", "-c", "print(1)"])
stage = nodus.StageSpec(id="example", source=source)
# Supply requirements= and stages=[stage] to client.run(..., budget=5).

They do not add runtime validation or defaults. Existing plain dictionaries remain supported. Stage source commands are argv lists, not shell strings.

Personal and team history

Use client.list(scope="mine") for your submissions or scope="team" for the team. Scope also works with list_page() and iter_workloads() and combines with status filters. Personal history requires a member-associated credential. Listed workloads expose owner_user_id, which can be absent for shared keys or older submissions. Scope filters history and does not change team access.