How Nodus works

This page is the map. Each section links to the concept page that goes deeper.

Everything is a resource

You describe work as a resource: a small declarative object with a kind, a metadata.name and a spec, the same shape Kubernetes uses. You create it with the CLI, the Python SDK, the console or the HTTP API, and Nodus reports progress in its status. The same object reads the same everywhere, so nodus get, kubectl get and the console show one truth.

You want to	Kind	Everyday command
Run a command to completion	Job (and Pipeline, Sweep to chain or fan out Jobs)	nodus run, nodus apply -f job.yaml
Keep an isolated container for untrusted code	Sandbox	nodus create sandbox, nodus exec -it
Call Python remotely and fan out	App, Function, FunctionCall	nodus deploy app.py
Run a durable agent	Agent, AgentRun, AgentGroup	nodus create agentrun
Serve or call a model	Model, InferenceEndpoint	nodus get models -n nodus
Train or evaluate with a recipe	TrainingJob, TrainingRuntime, Environment	nodus create trainingjob
Develop on a remote machine	Workspace	nodus ssh workspace/<name>
Store data, images and secrets	Volume, Image, Secret, Connection	nodus volume put
Bring your own machines	Pool, Node, EnrollmentToken, CloudAccount	nodus create pool

TrainingJob and TrainingRuntime are Beta. Every other kind above is generally available. Run nodus api-resources for the full list and nodus explain <kind>.spec for any field.

Orgs and projects

An org is your billing and access boundary: members, API keys, credit and budgets belong to it. Inside an org, projects group resources (every org starts with default). Pass -p <project> to the CLI, or set NODUS_PROJECT for a whole shell. Names are unique within a project, and labels such as team=nlp let you select resources and break down cost across projects.

How your work runs

You state requirements (an accelerator and count, memory, a region class, a deadline or a cost ceiling) and Nodus chooses an offering that satisfies them, such as h100-sxm-80g-x8-us. You see offerings and Nodus ids, never the machines behind them. Each placement of your container on a machine is an Attempt. When capacity is reclaimed, Nodus starts a new Attempt and restores the files your program saved to its checkpoint directory (NODUS_CHECKPOINT_DIR). Your program reloads its own model, optimizer and progress from those files; Nodus restores files, not process memory.

How billing works

Nodus sells prepaid credit, and four rules decide every charge:

1. A hold comes first. Before any paid machine starts, a hold reserves enough credit on your org, and on every budget that applies, to cover the expected run. A launch that cannot be funded is refused with the amounts and a fix, and a running Job stops gracefully, inside its reserved amount, when money runs out.

2. The rate is frozen at launch. nodus run and the console show the estimate before launch; the rate chosen when the machine is acquired is the rate for the whole run, and it is never above the published list price.

3. You pay what the provider bills for your machine, and nothing Nodus caused. Rented capacity bills from the moment the machine is created until its deletion is confirmed, at provider cost ÷ 0.875 (Nodus keeps 12.5 % of what you pay). Capacity Nodus chose and discarded, orphaned machines and Nodus failures are never charged.

4. Usage is itemized by segment. Every compute usage line names the part of the machine’s billed time it covers:

   Segment	Covers
   Boot	From the machine’s creation to your command starting: start-up, readiness and image pull
   Running	Your command, until it stops
   Restore	A replacement machine’s start-up when your work resumes from a checkpoint
   Teardown	From stop to confirmed deletion, plus the provider’s rounding increment

   nodus get usage --group-by segment and the console’s Cost tab show the breakdown for any object.

Nodus-operated capacity (Sandbox nodes, warm pools, CPU nodes) bills from the pricebook’s published per-vCPU, per-GiB and per-disk rates instead. Storage above 10 GB per org and egress above 10 GiB per org per day are metered; logs are free.

The starter grant

The first org a verified user creates receives $30 of credit that expires 30 days after it is granted. Grant credit is spent before purchased credit, soonest-expiring first. Until your first purchase, the org has starter limits (one Nodus node, three live Sandboxes, Sandbox lifetimes up to two hours), which lift when you buy credit.

See the pricing reference for every published rate.