# 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://nodus-platform-site.pages.dev/docs/ Build revision: 211ad9f836655b1c3a2668c4693e442471f28614 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://nodus-platform-site.pages.dev/docs/getting-started/) ## What are you building? Choose a starting point. Each guide covers the essentials and a working example. * **[Jobs](https://nodus-platform-site.pages.dev/docs/guides/jobs/)** Run a script or batch command to completion. * **[Workspaces](https://nodus-platform-site.pages.dev/docs/guides/workspaces/)** Develop with SSH, VS Code, or Jupyter. * **[Functions](https://nodus-platform-site.pages.dev/docs/guides/functions/)** Call Python remotely. Run calls in parallel. * **[Sandboxes](https://nodus-platform-site.pages.dev/docs/guides/sandboxes/)** Give agent-written code an isolated place to run. * **[Inference](https://nodus-platform-site.pages.dev/docs/guides/inference/)** Call a hosted model from your application. * **[Agents](https://nodus-platform-site.pages.dev/docs/guides/agents/)** Run agents with tools and saved progress. Looking for [training (Beta)](https://nodus-platform-site.pages.dev/docs/guides/training/), [storage](https://nodus-platform-site.pages.dev/docs/guides/volumes/), or [billing](https://nodus-platform-site.pages.dev/docs/guides/billing/)? [Browse all guides →](https://nodus-platform-site.pages.dev/docs/guides/) ## Bring your coding agent [Connect over MCP](https://nodus-platform-site.pages.dev/docs/for-agents/) to work from your editor, or give your agent the [Markdown task map](https://nodus-platform-site.pages.dev/docs/source/index.md). Read one relevant guide at a time; use the [reference](https://nodus-platform-site.pages.dev/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://nodus-platform-site.pages.dev/docs/for-agents/ Build revision: 211ad9f836655b1c3a2668c4693e442471f28614 Coding agents use Nodus the way you do: the same account, projects, budgets and confirmations. Connect one over MCP, or point it at the machine-readable outputs below. ## Read in this order 1. Read the [compute decision guide](https://nodus-platform-site.pages.dev/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://nodus-platform-site.pages.dev/docs/source/getting-started.md). 3. Use the [guide directory](https://nodus-platform-site.pages.dev/docs/source/guides.md) to find the relevant guide, then fetch its Markdown. 4. Look up exact commands in the [CLI reference](https://nodus-platform-site.pages.dev/docs/reference/cli/), signatures in the [Python reference](https://nodus-platform-site.pages.dev/docs/reference/python/), or request fields in [OpenAPI](https://nodus-platform-site.pages.dev/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://nodus-platform-site.pages.dev/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). Writes return a dry run first and run only once confirmed. |Client type|Configuration| |-|-| |Hosted (Claude Code, Codex, Cursor and other HTTP clients)|Add the server URL from [`/mcp-hosted.json`](https://nodus-platform-site.pages.dev/mcp-hosted.json) and sign in with your browser| |Local stdio clients|Run `nodus mcp`; the configuration is [`/mcp.json`](https://nodus-platform-site.pages.dev/mcp.json)| Step-by-step setup for each client is at [/connect](https://nodus-platform-site.pages.dev/connect/), and as Markdown at [`/connect.md`](https://nodus-platform-site.pages.dev/connect.md). ## Machine-readable outputs |Output|What it holds| |-|-| |[`/docs/pages.json`](https://nodus-platform-site.pages.dev/docs/pages.json)|Lightweight page manifest: titles, summaries, status and source URLs| |[`/docs/llms.txt`](https://nodus-platform-site.pages.dev/docs/llms.txt)|An index of these docs for language models| |[`Start`](https://nodus-platform-site.pages.dev/docs/bundles/start.md), [`compute`](https://nodus-platform-site.pages.dev/docs/bundles/compute.md), [`models`](https://nodus-platform-site.pages.dev/docs/bundles/models.md), [`data`](https://nodus-platform-site.pages.dev/docs/bundles/data.md), [`billing`](https://nodus-platform-site.pages.dev/docs/bundles/billing.md)|Focused bundles with complete pages, examples and source URLs| |[`/llms-full.txt`](https://nodus-platform-site.pages.dev/llms-full.txt)|Guides and concepts in one Markdown file; use the index for exact references| |`/docs/source/.md`|Each page’s Markdown, linked from the page with `rel="alternate"`| |[`/docs/index.json`](https://nodus-platform-site.pages.dev/docs/index.json)|Every page with its headings and text, versioned by build| |[`/docs/openapi.json`](https://nodus-platform-site.pages.dev/docs/openapi.json)|The HTTP API contract| |`/skills//SKILL.md`|Task instructions for agents that support skills| |[`/install`](https://nodus-platform-site.pages.dev/install), [`/install.ps1`](https://nodus-platform-site.pages.dev/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://nodus-platform-site.pages.dev/docs/getting-started/ Build revision: 211ad9f836655b1c3a2668c4693e442471f28614 This page takes you from nothing to a finished GPU job and its bill. You need a terminal and a browser. New accounts start with a **$30 starter grant**, so the first runs need no card. 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.** Terminal window ```sh nodus login ``` Your browser opens to confirm the sign-in. A new account gets an org with a `default` project, an API key for this machine, and the $30 starter grant, which expires 30 days after it is granted. On a machine without a browser, run `nodus login --device` and approve the code from any other device. 3. **Run a command on a GPU.** Terminal window ```console $ nodus run --gpu L4 --image nodus/pytorch -- python -c "import torch; print(torch.cuda.get_device_name())" job/run-4kq7z created · est. $0.01–0.03 · starts in ~2–4 min (cold) · Ctrl+C to cancel, -d to detach ✓ Scheduled l4-24g-x1-us · $0.52/h (rate frozen) ✓ Provisioning 1m48s ✓ Pulling image 22s ▶ Running NVIDIA L4 ✓ Succeeded in 2m31s · $0.02 · kept warm 60 s · nodus describe job/run-4kq7z ``` `nodus run` uploads the current directory, prints the estimate before anything is charged, streams the logs and exits with your command’s exit code. The rate is fixed when the machine is chosen and holds for the whole run. Add `-d` to return right away and let the job run on its own. 4. **Follow it.** Every run is a Job you can come back to. Terminal window ```sh nodus get jobs -w # live list of your jobs nodus logs -f job/run-4kq7z # stream the logs again nodus describe job/run-4kq7z # status, events and the cost so far ``` 5. **Get the results.** Declare an output path when you run, then copy it back. Downloads are checked against their SHA-256 digest. Terminal window ```sh nodus run --gpu L4 --image nodus/pytorch --output model=/outputs/model -- python train.py nodus cp job/:outputs/model ./model ``` 6. **See what it cost.** Terminal window ```console $ nodus billing $ nodus get usage --field-selector object.name=run-4kq7z --group-by segment SEGMENT AMOUNT Boot $0.018778 Running $0.003033 Teardown $0.002889 ``` You pay for the machine from the moment it is created until it is deleted: starting up (`Boot`), your command (`Running`) and shutting down (`Teardown`), all at the rate frozen at launch. Credit is prepaid: a hold is reserved before a machine starts, and only what was used is charged. Using a coding agent? Connect Claude Code, Codex or Cursor to Nodus at [/connect](https://nodus-platform-site.pages.dev/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://nodus-platform-site.pages.dev/docs/concepts/): resources, projects, and how billing is measured. * [Pricing reference](https://nodus-platform-site.pages.dev/docs/reference/pricing/): list prices for every GPU, CPU shape, storage and egress. * [Guides](https://nodus-platform-site.pages.dev/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://nodus-platform-site.pages.dev/docs/getting-started/install/ Build revision: 211ad9f836655b1c3a2668c4693e442471f28614 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 `, or pass `--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 \ --signature checksums.txt.sig --certificate checksums.txt.pem \ --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://nodus-platform-site.pages.dev/docs/getting-started/quickstart/): run your own code on a GPU and download its results. * [Nodus for kubectl users](https://nodus-platform-site.pages.dev/docs/getting-started/kubectl-users/): the verbs you already know. * [CLI reference](https://nodus-platform-site.pages.dev/docs/reference/cli/): every command and flag. --- # 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://nodus-platform-site.pages.dev/docs/getting-started/quickstart/ Build revision: 211ad9f836655b1c3a2668c4693e442471f28614 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://nodus-platform-site.pages.dev/docs/getting-started/install/). Every command here runs in CI as the `cli/quickstart` example. 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. **Run it.** From that directory: Terminal window ```sh nodus run --name cli-quickstart --gpu L4 --image nodus/pytorch \ --output metrics=/nodus/outputs/metrics.json -- python train.py ``` Terminal window ```console job/cli-quickstart created · est. $0.01–0.03 · starts in ~2–4 min (cold) · hold $0.50 · Ctrl+C to cancel, -d to detach ✓ Scheduled l4-24g-x1-us · $0.52/h (rate frozen) ✓ Provisioning 1m48s ▶ Running device: NVIDIA L4 step 0 loss 15.8732 ... final loss 0.000001 ✓ Succeeded in 2m31s · $0.02 (boot $0.01 · running $0.01) · kept warm 60 s · nodus describe job/cli-quickstart ``` Before anything is charged you see the estimate and a hold: the most this run can cost before you are asked. `nodus run` then uploads the directory (files listed in `.gitignore` or `.nodusignore` stay local), prints each phase, streams your program’s output on stdout and ends with the cost line. The CLI exits with your command’s exit code, so it works in scripts and CI. 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 and only written when it matches. ## 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 # stop it; you pay only for what ran ``` ## Control the cost |Flag|Effect| |-|-| |`--max-cost 5`|The Job stops gracefully before it spends more than $5| |`--timeout 2h`|The Job is stopped after two hours of wall-clock time| |`--dry-run`|Print the estimate and exit without creating anything| `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://nodus-platform-site.pages.dev/docs/getting-started/kubectl-users/): manifests, `apply`, `get -o`, `wait` and `diff`. * [CLI reference](https://nodus-platform-site.pages.dev/docs/reference/cli/): every command and flag, with tested examples.