# Start with Nodus

---

Install, sign in, run a first job and connect a coding agent.

---

# Build with Nodus

> Run your first job, choose a compute feature, and get from code to results.

Source: https://www.nodus-compute.ai/docs/
Build revision: 53bfc045e800bf7bb44fa18623013c7aa9c9971e

Run your code on cloud CPUs and GPUs. Start with a command, a Python function, or an interactive environment.

> **From code to your first result**
>
> Install the CLI, sign in, and run a job in about five minutes.
>
> [Run your first job →](https://www.nodus-compute.ai/docs/getting-started/)

## What are you building?

Choose a starting point. Each guide covers the essentials and a working example.

* **[Jobs](https://www.nodus-compute.ai/docs/guides/jobs/)** Run a script or batch command to completion.
* **[Workspaces](https://www.nodus-compute.ai/docs/guides/workspaces/)** Develop with SSH, VS Code, or Jupyter.
* **[Functions](https://www.nodus-compute.ai/docs/guides/functions/)** Call Python remotely. Run calls in parallel.
* **[Sandboxes](https://www.nodus-compute.ai/docs/guides/sandboxes/)** Give agent-written code an isolated place to run.
* **[Inference](https://www.nodus-compute.ai/docs/guides/inference/)** Call a hosted model from your application.
* **[Agents](https://www.nodus-compute.ai/docs/guides/agents/)** Run agents with tools and saved progress.

Looking for [training (Beta)](https://www.nodus-compute.ai/docs/guides/training/), [storage](https://www.nodus-compute.ai/docs/guides/volumes/), or [billing](https://www.nodus-compute.ai/docs/guides/billing/)? [Browse all guides →](https://www.nodus-compute.ai/docs/guides/)

## Bring your coding agent

[Connect over MCP](https://www.nodus-compute.ai/docs/for-agents/) to work from your editor, or give your agent the [Markdown task map](https://www.nodus-compute.ai/docs/source/index.md). Read one relevant guide at a time; use the [reference](https://www.nodus-compute.ai/docs/reference/) for exact commands and API fields.


---

# For coding agents

> Connect a coding agent over MCP, and the machine-readable versions of these docs, the API and the setup.

Source: https://www.nodus-compute.ai/docs/for-agents/
Build revision: 53bfc045e800bf7bb44fa18623013c7aa9c9971e

Coding agents use Nodus the way you do: the same account, projects, and spending limits. Connect one over MCP, or point it at the machine-readable outputs below.

## Read in this order

1. Read the [compute decision guide](https://www.nodus-compute.ai/docs/source/guides/choose-compute.md) to choose the feature that fits the request.
2. If this is a first run, read the [quickstart](https://www.nodus-compute.ai/docs/source/getting-started.md).
3. Use the [guide directory](https://www.nodus-compute.ai/docs/source/guides.md) to find the relevant guide, then fetch its Markdown.
4. Look up exact commands in the [CLI reference](https://www.nodus-compute.ai/docs/reference/cli/), signatures in the [Python reference](https://www.nodus-compute.ai/docs/reference/python/), or request fields in [OpenAPI](https://www.nodus-compute.ai/docs/openapi.json).

Fetch individual pages to keep context small. For example, `/docs/guides/jobs/` has its Markdown at [`/docs/source/guides/jobs.md`](https://www.nodus-compute.ai/docs/source/guides/jobs.md). Each docs page has a **View Markdown** link. Use the full corpus only for tasks that need many parts of the product.

## Connect over MCP

Nodus runs one MCP server with generic tools over every resource (`get`, `describe`, `logs`, `estimate`, `apply`, `exec` and more). `apply` returns a dry run and requires `confirmed: true` with its accepted `etag` to create a resource. Other write tools do not use that handshake; obtain authorization for the action and use the client’s approval controls.

|Client type|Configuration|
|-|-|
|Hosted (Claude Code, Codex, Cursor and other HTTP clients)|Add the server URL from [`/mcp-hosted.json`](https://www.nodus-compute.ai/mcp-hosted.json) and sign in with your browser|
|Local stdio clients|Run `nodus mcp`; the configuration is [`/mcp.json`](https://www.nodus-compute.ai/mcp.json)|

Step-by-step setup for each client is at [/connect](https://www.nodus-compute.ai/connect/), and as Markdown at [`/connect.md`](https://www.nodus-compute.ai/connect.md).

## From connection to first result

1. Complete account setup: a new organization needs a verified email and card. Invited members use their organization’s billing.
2. Use `whoami` and a read-only Job listing to verify the intended organization and project. An empty list is normal.
3. Read the [complete small training example](https://www.nodus-compute.ai/docs/getting-started/quickstart/) and the [MCP workflow](https://www.nodus-compute.ai/docs/guides/mcp/#from-a-local-script-to-a-compute-job).
4. Show the image, command, source, output declaration, limits, and estimate. Wait for approval before paid submission.
5. Check terminal status and logs. Retrieve the declared output before reporting success or deleting the Job.

A hosted connection cannot upload files from the user’s laptop. Use an image containing the code or the [CLI source-upload workflow](https://www.nodus-compute.ai/docs/guides/jobs/). A local MCP connection also exposes `upload_source` and `download_output`. Read the actual connected tool schemas before choosing a tool.

## Machine-readable outputs

|Output|What it holds|
|-|-|
|[`/docs/pages.json`](https://www.nodus-compute.ai/docs/pages.json)|Lightweight page manifest: titles, summaries, status and source URLs|
|[`/docs/llms.txt`](https://www.nodus-compute.ai/docs/llms.txt)|An index of these docs for language models|
|[`Start`](https://www.nodus-compute.ai/docs/bundles/start.md), [`compute`](https://www.nodus-compute.ai/docs/bundles/compute.md), [`models`](https://www.nodus-compute.ai/docs/bundles/models.md), [`data`](https://www.nodus-compute.ai/docs/bundles/data.md), [`billing`](https://www.nodus-compute.ai/docs/bundles/billing.md)|Focused bundles with complete pages, examples and source URLs|
|[`/llms-full.txt`](https://www.nodus-compute.ai/llms-full.txt)|Guides and concepts in one Markdown file; use the index for exact references|
|`/docs/source/<path>.md`|Each page’s Markdown, linked from the page with `rel="alternate"`|
|[`/docs/index.json`](https://www.nodus-compute.ai/docs/index.json)|Every page with its headings and text, versioned by build|
|[`/docs/openapi.json`](https://www.nodus-compute.ai/docs/openapi.json)|The HTTP API contract|
|`/skills/<name>/SKILL.md`|Task instructions for agents that support skills|
|[`/install`](https://www.nodus-compute.ai/install), [`/install.ps1`](https://www.nodus-compute.ai/install.ps1)|The CLI installer for macOS, Linux and Windows|

A good first prompt for an agent that can read URLs:

```text
Read https://nodus-compute.ai/connect.md and help me connect Nodus to this agent. Reuse any existing Nodus
connection. Verify setup by listing my jobs. Do not start paid compute.
```

## Use the current contract

Fetch the relevant guide and its linked reference before writing commands. Keep the resource’s API version and Beta status explicit. Use the published OpenAPI schemas for field names and the CLI or SDK reference for the installed interface; do not invent flags from examples for another tool.

Each Markdown page includes its canonical source URL and build revision. Cite the source page when explaining behavior. Read billing and recovery limits before creating work, and verify the resource status, logs and outputs before reporting success. A submitted request is not evidence that the run completed.


---

# Get started

> Install the Nodus CLI, sign in, run a command on a GPU, follow it, get its results and see exactly what it cost.

Source: https://www.nodus-compute.ai/docs/getting-started/
Build revision: 53bfc045e800bf7bb44fa18623013c7aa9c9971e

Run a small GPU check, inspect its status, then move on to a script that produces a downloadable result. You need a terminal, a browser, and an activated Nodus organization.

1. **Install the CLI.**

   **pip**

   Terminal window

   ```sh
   pip install nodus-compute
   ```

   The Python package (Python 3.10 or newer) includes the `nodus` CLI.

   **macOS and Linux**

   Terminal window

   ```sh
   curl -fsSL https://nodus-compute.ai/install | sh
   ```

   **Windows**

   Terminal window

   ```powershell
   irm https://nodus-compute.ai/install.ps1 | iex
   ```

2. **Sign in and finish account setup.**

   Terminal window

   ```sh
   nodus login
   ```

   Creating your first organization requires a verified email and a verified card. Complete onboarding in your browser, then return to the CLI sign-in. Card setup does not collect a payment or enable auto-recharge. Eligible accounts receive a **$30 starter grant**, valid for 30 days; verify your available balance before running work. If you join an existing organization, its administrator manages billing.

   Terminal window

   ```sh
   nodus whoami
   nodus get jobs
   nodus billing
   ```

   These commands check the account, connection, and balance without starting compute. An empty Job list is normal for a new project. On a machine without a browser, use `nodus login --device`.

3. **Review a bounded GPU check.**

   Terminal window

   ```sh
   nodus run --name first-gpu-check --gpu L4 --image nodus/pytorch \
     --no-source --max-cost 1 --timeout 10m --no-warm --dry-run \
     -- python -c "import torch; print(torch.cuda.get_device_name())"
   ```

   Review the returned estimate and any blockers. The $1 limit and 10-minute timeout are example limits, not a quoted price or a promise that capacity will be available. `--no-source` keeps local files on your machine. `--dry-run` does not create the Job.

4. **Run after accepting the estimate.**

   Remove only `--dry-run` from the command above. This submits paid compute. The CLI streams progress and logs; check that the Job succeeds and the logs include the GPU name. If you delegate this step to a coding agent, approve the request before it submits.

   Terminal window

   ```sh
   nodus describe job/first-gpu-check
   nodus logs job/first-gpu-check
   ```

   A created Job is not proof of completed work. If it fails, inspect its status and events before retrying. Use a new name for a new run; avoid resubmitting after an uncertain response without checking the original.

5. **Download a result from your own code.**

   The GPU check prints to its logs. Continue with [Run your own code](https://www.nodus-compute.ai/docs/getting-started/quickstart/) for a complete training script, a declared `metrics.json` output, and its download command.

   Terminal window

   ```sh
   nodus billing
   nodus delete job/first-gpu-check
   ```

   Review usage in Billing. Delete the completed check when you no longer need its status and logs. To stop it while it is running, use `nodus cancel job/first-gpu-check` and verify the final status.

Using a coding agent?

Connect Claude Code, Codex or Cursor to Nodus at [/connect](https://www.nodus-compute.ai/connect/), then ask it to run your command. The agent uses the same account, projects and spending limits as the CLI.

## Next steps

* [Concepts](https://www.nodus-compute.ai/docs/concepts/): resources, projects, and spending controls.
* [Guides](https://www.nodus-compute.ai/docs/guides/): one guide per feature.


---

# Install the CLI

> Install the nodus CLI on macOS, Linux or Windows, verify the download, turn on shell completion and sign in.

Source: https://www.nodus-compute.ai/docs/getting-started/install/
Build revision: 53bfc045e800bf7bb44fa18623013c7aa9c9971e

The `nodus` CLI is one self-contained binary for macOS, Linux and Windows on x86-64 and ARM64. Pick one way to install it.

**pip**

Terminal window

```sh
pip install nodus-compute
```

The Python package (Python 3.10 or newer) includes the CLI, so `nodus` is on your `PATH` wherever the package is installed. Use this if you also want the Python SDK.

**Homebrew**

Terminal window

```sh
brew install --cask nodus-compute/tap/nodus
```

**macOS and Linux**

Terminal window

```sh
curl -fsSL https://nodus-compute.ai/install | sh
```

The script installs to `~/.local/bin` and checks the archive against the release’s `checksums.txt` first. `NODUS_VERSION=1.2.3` pins a release and `NODUS_INSTALL_DIR` picks another directory.

**Windows**

Terminal window

```powershell
irm https://nodus-compute.ai/install.ps1 | iex
```

Check that it works:

Terminal window

```console
$ nodus version
nodus v1.0.0
```

## Sign in

Terminal window

```sh
nodus login
```

Your browser opens to confirm the sign-in. If you belong to several orgs, pick the ones this machine should use: the CLI stores one API key per org in the OS keychain and creates one **context** per org. Switch between them with `nodus config use-context <org>`, or pass `--org <org>` to a single command.

|Where you are|Command|
|-|-|
|A laptop with a browser|`nodus login`|
|An SSH session or a machine without a browser|`nodus login --device`, then approve the code from any device|
|CI, with a key in a secret|`echo "$NODUS_API_KEY" \| nodus login --with-token`, or just set `NODUS_API_KEY`|

`nodus whoami` shows who you are signed in as, your role, the current project and your available credit. `nodus logout` revokes this machine’s key and removes the context.

Environment variables

The CLI reads six variables, all optional: `NODUS_API_KEY`, `NODUS_API_URL`, `NODUS_ORG`, `NODUS_PROJECT`, `NODUS_CONTEXT` and `NODUS_CONFIG`. A variable wins over the config file for that invocation.

## Shell completion

Terminal window

```sh
nodus completion zsh > "${fpath[1]}/_nodus"          # zsh
nodus completion bash > /etc/bash_completion.d/nodus # bash (or ~/.local/share/bash-completion/completions/nodus)
nodus completion fish > ~/.config/fish/completions/nodus.fish
```

Completion covers every command and flag.

## Verify a download

Every release publishes `checksums.txt`, a keyless cosign signature over it, and an SBOM per archive. To verify an archive you downloaded yourself:

Terminal window

```sh
cosign verify-blob checksums.txt \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp '^https://github.com/nodus-compute/nodus-platform/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
shasum -a 256 --ignore-missing -c checksums.txt
```

## Where the CLI keeps things

|Path|What it holds|
|-|-|
|`~/.nodus/config`|Contexts: API server, org and project. It is a kubeconfig, so `KUBECONFIG=~/.nodus/config kubectl get jobs.nodus.dev` works too|
|OS keychain (`~/.nodus/credentials`, mode 0600, where there is none)|One API key per context|
|`~/.nodus/cache/`|The cached list of resource kinds; `nodus api-resources` refreshes it|

If you used Nodus before 1.0, its `~/.nodus/config.toml` is renamed to `config.0x.bak` the first time the new CLI runs; sign in again with `nodus login`. A 0.x `nodus.toml` converts into a manifest you can review and apply:

Terminal window

```sh
nodus convert nodus.toml > job.yaml   # fields that do not carry over are listed on stderr
nodus apply -f job.yaml --dry-run=server -o estimate
```

## Upgrade and uninstall

Upgrade the same way you installed (`pip install -U nodus-compute`, `brew upgrade --cask nodus`, or run the install script again). To uninstall, run `nodus logout`, remove the binary, and delete `~/.nodus`.

## Next steps

* [Quickstart](https://www.nodus-compute.ai/docs/getting-started/quickstart/): run your own code on a GPU and download its results.
* [Nodus for kubectl users](https://www.nodus-compute.ai/docs/getting-started/kubectl-users/): the verbs you already know.
* [CLI reference](https://www.nodus-compute.ai/docs/reference/cli/): every command and flag.

### Creating your first organization

Verify your email and card in the console before creating an organization. Card verification does not collect a payment or turn on auto-recharge. Each card can belong to one account. If you begin with `nodus login`, use the onboarding link, then return to the CLI authorization tab and refresh your organizations. Run the login command again if its code expires. You can accept an invitation to an existing team without adding a personal card.


---

# Run your own code

> Run a training script from your own directory on a GPU with nodus run, follow it, download its output and read what it cost.

Source: https://www.nodus-compute.ai/docs/getting-started/quickstart/
Build revision: 53bfc045e800bf7bb44fa18623013c7aa9c9971e

This page runs a script from your own directory on a GPU, then downloads the file it wrote. It assumes you have [installed the CLI and signed in](https://www.nodus-compute.ai/docs/getting-started/install/). The source and command sequence live in the repository’s `examples/cli/quickstart` example. Creating an organization requires [email and card verification](https://www.nodus-compute.ai/docs/getting-started/install/#creating-your-first-organization).

1. **Put your code in a directory.** Any directory works; this one holds a small PyTorch training loop that saves its final metrics to `/nodus/outputs/metrics.json`.

   train.py

   ```python
   """Fit a small linear model, print progress and save metrics.json as the declared output "metrics"."""

   import json
   import pathlib

   import torch

   device = "cuda" if torch.cuda.is_available() else "cpu"
   print("device:", torch.cuda.get_device_name() if device == "cuda" else "cpu")

   torch.manual_seed(0)
   x = torch.randn(1024, 16, device=device)
   y = x @ torch.randn(16, 1, device=device)
   w = torch.zeros(16, 1, device=device, requires_grad=True)
   opt = torch.optim.SGD([w], lr=0.1)

   for step in range(200):
       loss = ((x @ w - y) ** 2).mean()
       opt.zero_grad()
       loss.backward()
       opt.step()
       if step % 50 == 0:
           print(f"step {step} loss {loss.item():.4f}")

   print(f"final loss {loss.item():.6f}")
   out = pathlib.Path("/nodus/outputs")
   out.mkdir(parents=True, exist_ok=True)
   (out / "metrics.json").write_text(json.dumps({"final_loss": loss.item(), "steps": 200}))
   ```

2. **Review the estimate, then run.** From the directory containing `train.py`:

   Terminal window

   ```sh
   nodus run --name cli-quickstart --gpu L4 --image nodus/pytorch \
     --max-cost 1 --timeout 10m --no-warm --dry-run \
     --output metrics=/nodus/outputs/metrics.json -- python train.py
   ```

   This dry run uploads the directory for inspection but does not create the Job. Inspect the estimate and any blockers. The limits are choices for this example, not a price quote or a guarantee that it will complete. After you accept the estimate, submit the same request without `--dry-run`:

   Terminal window

   ```sh
   nodus run --name cli-quickstart --gpu L4 --image nodus/pytorch \
     --max-cost 1 --timeout 10m --no-warm \
     --output metrics=/nodus/outputs/metrics.json -- python train.py
   ```

   This starts paid compute. The CLI uploads this directory, streams the logs and returns your command’s exit code. Check for a successful final status and training progress in the logs. The script runs 200 steps and writes `metrics.json`; its exact loss and runtime depend on the environment. Files excluded by `.gitignore` or `.nodusignore` stay local. Inspect the directory before uploading it.

3. **Get the output.** The `--output` flag declared `metrics`; copy it back:

   Terminal window

   ```sh
   nodus cp job/cli-quickstart:outputs/metrics metrics.json
   ```

   The file is checked against its SHA-256 digest. Inspect `final_loss` and `steps` in the downloaded JSON. If the Job fails or no output is listed, inspect its status and logs instead of reporting a saved result.

## Leave it running

Press **Ctrl+C** during a run and the CLI asks whether to cancel the Job; answer `n` to detach and leave it running. Or start with `-d` to return as soon as the Job exists. A detached Job keeps running:

Terminal window

```sh
nodus get jobs                        # every Job in the project, with phase and cost so far
nodus get jobs --mine -w              # only yours, updating live
nodus logs -f job/cli-quickstart      # stream the output again
nodus describe job/cli-quickstart     # attempts, placement, cost, conditions and events
nodus cancel job/cli-quickstart       # request cancellation, then verify status
```

## Control the cost

|Flag|Effect|
|-|-|
|`--max-cost 5`|Set a $5 Job spending limit; choose a limit that fits your Job|
|`--timeout 2h`|The Job is stopped after two hours of wall-clock time|
|`--dry-run`|Review the estimate without creating the Job|

`nodus billing` shows your balance and this month’s spend; `nodus billing usage --group-by day` breaks it down.

Exit codes

`nodus run` exits with your command’s own exit code. It exits `125` when Nodus could not run the command (an API error or an invalid request), `124` on `--timeout` and `130` when you interrupt it.

## Clean up

Finished Jobs are kept for 30 days so you can read their logs and outputs, then deleted. To delete one now:

Terminal window

```sh
nodus delete job/cli-quickstart
```

## Next steps

* [Nodus for kubectl users](https://www.nodus-compute.ai/docs/getting-started/kubectl-users/): manifests, `apply`, `get -o`, `wait` and `diff`.
* [CLI reference](https://www.nodus-compute.ai/docs/reference/cli/): every command and flag, with tested examples.