# How Nodus works

> Resources, orgs and projects, how your work is placed and kept alive, and how prepaid billing measures it.

Source: https://nodus-platform-site.pages.dev/docs/concepts/
Build revision: 211ad9f836655b1c3a2668c4693e442471f28614

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](https://nodus-platform-site.pages.dev/docs/reference/pricing/) for every published rate.