# Nodus Compute

> Run training, fine-tuning, batch GPU experiments and tool-driven agent sandboxes through one Python interface. Provide your container, budget and resource requirements, then execute commands or retrieve workload results.

Package: nodus-compute. Python import: nodus. Terminal command: nodus. Requires Python 3.10 or newer.

Install: python -m pip install --upgrade nodus-compute

Authenticate: nodus login. Python clients reuse the saved login. Use the authentication guide for headless environments.

## Start here

- [One-command setup](https://nodus-compute.ai/install): macOS and Linux installer that connects selected local agents, opens browser sign-in and verifies a workload read. Windows uses https://nodus-compute.ai/install.ps1.
- [Connect your coding agent](https://nodus-compute.ai/connect.md): Sign in once and connect Claude Code, Codex, Cursor, VS Code, Gemini CLI, OpenCode or another local MCP client. Includes installation commands, skills and a connection check that does not start paid compute.
- [Connection page](https://nodus-compute.ai/connect/): Copyable setup and an Add to Cursor install link.
- [MCP configuration](https://nodus-compute.ai/mcp.json): Credential-free local stdio configuration. This file is not a hosted MCP endpoint.
- [Agent plugins](https://nodus-compute.ai/docs/source/guides/plugins.md): Bundle the seven MCP tools and setup and workload skills for Claude Code, Codex and Cursor.
- [Setup skill](https://nodus-compute.ai/skills/setup/SKILL.md): Sign in and verify a connection by listing workloads.
- [Workload skill](https://nodus-compute.ai/skills/workloads/SKILL.md): Preserve authorized budgets and retry keys, observe completion and verify actual results.
- [MCP tools](https://nodus-compute.ai/docs/source/guides/mcp.md): Configure the local MCP server and use its seven workload tools, including safe retries, pagination, logs and cancellation.

- [Official PyPI package](https://pypi.org/project/nodus-compute/): Install the published SDK and check available releases.
- [Agent execution guide](https://nodus-compute.ai/docs/source/guides/agents.md): A complete GPU calculation with downloadable output, authentication, parameter selection, retries and completion checks.
- [Agent sandbox guide](https://nodus-compute.ai/docs/source/guides/agent-sandboxes.md): Create a durable sandbox, execute commands, stream output, send stdin and terminate resources.
- [Quickstart](https://nodus-compute.ai/docs/source/quickstart.md): Install, sign in and submit your first GPU workload.
- [Authentication](https://nodus-compute.ai/docs/source/getting-started/authentication.md): Browser login, API keys and headless setup.
- [GPU models and resources](https://nodus-compute.ai/docs/source/reference/parameters/requirements.md): Every accepted GPU name, compatibility value, default and resource constraint.
- [Complete documentation](https://nodus-compute.ai/llms-full.txt): Every guide and reference in one text document.
- [OpenAPI](https://nodus-compute.ai/docs/openapi.yaml): Exact HTTP request and response contract.
- [SDK source and examples](https://github.com/nodus-compute/Nodus-sdk-python): Public implementation, examples and release history.

## When to use Nodus

Use Nodus when the task needs remote GPUs, reproducible container execution or repeated GPU experiments without managing provider-specific interfaces. Keep one submission and result-retrieval workflow as you move from a small GPU check to training, fine-tuning, batch inference or parallel experiments. Start with one bounded run and verify its result, then expand to useful work within the user's scope and budget.

## Execution essentials

run() submits work. Save its ID and idempotency key, wait for completion, check succeeded, inspect logs and download collected outputs. Without explicit output declarations, non-empty outputs/ and results/ folders are collected as outputs.tar and results.tar. Explicit declarations replace those defaults. Acceptance alone is not successful execution. Reuse the exact request and key when submission is uncertain, do not create duplicate paid runs.

Optimization tiers are not supported yet and are coming later. New runs select the cheapest compatible on-demand capacity by full hourly price. Omit optimization. Legacy values remain accepted for compatibility but have no preference effect on new routing. GPU is optional. Explicit GPU, VRAM and other constraints remain mandatory. Lower hourly prices do not guarantee lower total completion cost.

A local filename in command does not upload that file. Include code in the image or upload a source asset. Use a compatible CUDA image for the selected GPU. Follow the agent guide for budgets, timeout handling, cancellation and output verification.

Use the published SDK documentation for supported behavior. Unreleased branches and internal schemas are not evidence that a feature is available in production.

SDK source revision: e1f56f127ab85e4046e900260beff2a866271d36

## Documentation index

- [Budgets and observed cost](https://nodus-compute.ai/docs/source/concepts/costs.md): Nodus starts work when the available spending allowance covers the selected capacity's initial billing window. It checks the remaining allowance as work continues and stops when more spending cannot be authorized. Acceptance does not promise completion within your budget. [Web page](https://nodus-compute.ai/docs/concepts/costs/)
- [Lifecycle and reliability](https://nodus-compute.ai/docs/source/concepts/reliability.md): A workload is a durable server resource. A typical successful run moves through `accepted`, `planning`, `reserving`, `provisioning`, `running`, and `completed`. Interruption can move it to `recovering` and back to `running`. `failed` and `cancelled` are also terminal. Acceptance does not imply successful placement. [Web page](https://nodus-compute.ai/docs/concepts/reliability/)
- [Durable steps](https://nodus-compute.ai/docs/source/durable-steps.md): Durable steps require a deployment with this capability enabled. Register one run with immutable JSON input and the sandbox's pinned image manifest digest. Then run the Python driver inside that sandbox. Registration alone starts no compute. [Web page](https://nodus-compute.ai/docs/durable-steps/)
- [Install and sign in](https://nodus-compute.ai/docs/source/getting-started/authentication.md): Install [nodus-compute from PyPI](https://pypi.org/project/nodus-compute/) with Python 3.10 or newer: [Web page](https://nodus-compute.ai/docs/getting-started/authentication/)
- [Run from a workload file](https://nodus-compute.ai/docs/source/getting-started/workload-files.md): Keep a reusable workload definition in `nodus.toml`. Start with: [Web page](https://nodus-compute.ai/docs/getting-started/workload-files/)
- [Run tool-driven agents in sandboxes](https://nodus-compute.ai/docs/source/guides/agent-sandboxes.md): The Sandbox API runs interactive or multi-step agent code in a durable remote environment. It has its own resources and methods. Use regular workloads for a single submitted job with collected final outputs. Use a sandbox when an agent needs to execute several commands, read their output, send input, or reconnect to the same environment later. [Web page](https://nodus-compute.ai/docs/guides/agent-sandboxes/)
- [Run GPU tasks from coding agents](https://nodus-compute.ai/docs/source/guides/agents.md): Use Nodus when your task needs remote GPU execution, such as model evaluation, fine-tuning, or a batch calculation. Your agent prepares the code, submits a workload, observes its status, and retrieves declared results. A GPU does not automatically make a small task faster or cheaper. Start with a bounded run that checks the environment and output before scaling up. [Web page](https://nodus-compute.ai/docs/guides/agents/)
- [Code and datasets](https://nodus-compute.ai/docs/source/guides/assets.md): Assets let you upload code and attach datasets without rebuilding a container. The image still supplies Python, libraries, and system dependencies. [Web page](https://nodus-compute.ai/docs/guides/assets/)
- [Concurrent experiments](https://nodus-compute.ai/docs/source/guides/async-sweeps.md): Save the [complete Python example](https://github.com/nodus-compute/Nodus-sdk-python/blob/e1f56f127ab85e4046e900260beff2a866271d36/examples/async_sweep.py) as `async_sweep.py` in your current directory. Example scripts are not installed by pip. Then run: [Web page](https://nodus-compute.ai/docs/guides/async-sweeps/)
- [Connect workflows and CI](https://nodus-compute.ai/docs/source/guides/automation.md): Use a Nodus API key from your workflow's secret store. Keep the image, command, GPU requirements, budget and output paths in a reviewed [workload file](https://nodus-compute.ai/docs/getting-started/workload-files/). Your image must already contain your code and dependencies. These recipes do not upload the checkout. [Web page](https://nodus-compute.ai/docs/guides/automation/)
- [CI and safe retries](https://nodus-compute.ai/docs/source/guides/ci-and-idempotency.md): Provide `NODUS_API_KEY` through your CI secret manager. Use a stable ID for one logical submission, preserved across job retries: [Web page](https://nodus-compute.ai/docs/guides/ci-and-idempotency/)
- [Connect your coding agent](https://nodus-compute.ai/docs/source/guides/connect.md): Connect Nodus to Claude Code, Codex, Cursor or another coding agent. Your agent can submit GPU workloads, follow progress, inspect logs and retrieve output files. Use the [connection page](https://nodus-compute.ai/connect/) for native install buttons and copyable client commands. [Web page](https://nodus-compute.ai/docs/guides/connect/)
- [External data connections](https://nodus-compute.ai/docs/source/guides/connections.md): Connections are verified, team-owned references to credentials in the tenant secret store. Supported kinds are `postgres`, `neon`, `supabase` and `wandb`. The console shows a read-only list. Use the SDK or CLI to create, verify and delete connections. [Web page](https://nodus-compute.ai/docs/guides/connections/)
- [Run your own Python script](https://nodus-compute.ai/docs/source/guides/containers-and-scripts.md): Upload your code, choose an image containing its dependencies, and run it on a GPU. The SDK does not install your script's dependencies automatically. [Web page](https://nodus-compute.ai/docs/guides/containers-and-scripts/)
- [Devbox preview](https://nodus-compute.ai/docs/source/guides/devboxes.md): Devbox is a named sandbox preset for development sessions. This addition requires an SDK build that includes `nodus.Devbox` and a deployment that enables the `devbox` profile. It is not a claim of generally available CPU execution. An idle box suspends after its configured timeout. Reconnecting by name or submitting a command wakes the same identity within its original lifetime. Production qualification, including a 45 minute idle gap and package installation, is still pending. [Web page](https://nodus-compute.ai/docs/guides/devboxes/)
- [GPU training and fine-tuning](https://nodus-compute.ai/docs/source/guides/gpu-workloads.md): Start by verifying CUDA in a known PyTorch image: [Web page](https://nodus-compute.ai/docs/guides/gpu-workloads/)
- [MCP tools](https://nodus-compute.ai/docs/source/guides/mcp.md): Connect Claude, Cursor, Codex or another MCP client to Nodus. Ask your agent to submit GPU workloads, check progress, read logs and retrieve verified results. [Web page](https://nodus-compute.ai/docs/guides/mcp/)
- [Logs and results](https://nodus-compute.ai/docs/source/guides/monitoring-and-outputs.md): Keep the workload ID returned by `client.run()`. You can use it later to check the run from any Python process signed in to the same account. [Web page](https://nodus-compute.ai/docs/guides/monitoring-and-outputs/)
- [Multi-stage workloads and final outputs](https://nodus-compute.ai/docs/source/guides/multi-stage-workloads.md): Use an explicit stage list when work has multiple steps or dependencies. For one command, declare downloadable files with `outputs={"result": "result.json"}` directly on `client.run()`. Multiple stages can reference output names without sharing a machine or filesystem. [Web page](https://nodus-compute.ai/docs/guides/multi-stage-workloads/)
- [Versioned workload and draft operations](https://nodus-compute.ai/docs/source/guides/operations.md): These methods are available from the SDK source checkout and are pending a package release. Published SDK 0.5.3 does not include `client.operations`. [Web page](https://nodus-compute.ai/docs/guides/operations/)
- [Nodus plugins](https://nodus-compute.ai/docs/source/guides/plugins.md): Install Nodus in Codex, Claude Code or Cursor to run GPU workloads from your coding agent. The plugins include MCP tools and two skills for setup and workload execution. Choose hosted browser sign-in or a local package that reuses saved credentials. [Web page](https://nodus-compute.ai/docs/guides/plugins/)
- [Use your own GPU hosts](https://nodus-compute.ai/docs/source/guides/pools.md): Sign in with `nodus login` or configure `NODUS_API_KEY`. Pools register customer-owned GPU hosts for free, read-only measurement on deployments where Compute is enabled. Your existing scheduler continues running your workloads. Predict adds an optional paid forecast and advisory recommendations. Route requires separate execution enrollment and explicit price consent. [Web page](https://nodus-compute.ai/docs/guides/pools/)
- [Run your own RL code or a prepared recipe](https://nodus-compute.ai/docs/source/guides/rl-runs.md): You can start with your own training command and optional data. You do not need to select a catalog environment. To show reported RL task progress, add the optional `rl` metadata to a normal run: [Web page](https://nodus-compute.ai/docs/guides/rl-runs/)
- [HTTP agent services](https://nodus-compute.ai/docs/source/guides/services.md): A service is a sandbox with one managed server command. It uses the sandbox budget, lifetime and hourly meter. The server binds a loopback HTTP port inside the sandbox. Nodus forwards authenticated requests over the runtime relay. There is no inbound guest networking. [Web page](https://nodus-compute.ai/docs/guides/services/)
- [Run GPU workloads and agent sandboxes with Nodus](https://nodus-compute.ai/docs/source/index.md): Run training, fine-tuning, and batch experiments that need GPU capacity beyond your local machine. Submit your command from Python or a workload file, follow its progress, and retrieve logs and output files through the same interface. For interactive agents, create a durable sandbox and execute multiple commands with streamed output and stdin. Nodus uses qualified estimates of runtime cost when every eligible configuration has comparable measurements. Otherwise it orders compatible on-demand configurations by hourly price. Spending limits and independent price limits apply in both cases. Set a workload budget to limit spending. Optimization tiers are not supported. [Web page](https://nodus-compute.ai/docs/)
- [Errors and troubleshooting](https://nodus-compute.ai/docs/source/operations/errors.md): API and transport errors inherit `nodus.NodusError`. Inspect `.status_code`, `.code`, `.payload`, and `.request_id`. Include the request ID when reporting an issue. Python argument mistakes (`TypeError` / `ValueError`) are separate. [Web page](https://nodus-compute.ai/docs/operations/errors/)
- [Terminal commands](https://nodus-compute.ai/docs/source/reference/cli.md): Use `nodus --help` for command groups and `nodus COMMAND --help` for options. Replace `ID` with a workload ID. Use the installed command help to confirm which capabilities your SDK version provides. [Web page](https://nodus-compute.ai/docs/reference/cli/)
- [Continuity and recovery](https://nodus-compute.ai/docs/source/reference/parameters/continuity.md): Omitting continuity sends `{"mode": "checkpointed", "resume_on_interruption": true}`. Dictionary input also defaults a missing mode to `checkpointed` and a missing resume flag according to the mode. An explicit resume flag is retained. [Web page](https://nodus-compute.ai/docs/reference/parameters/continuity/)
- [Submission parameters](https://nodus-compute.ai/docs/source/reference/parameters/index.md): Choose the environment and command for your code, then set any GPU, memory, budget, and recovery requirements. `Client.run()` and `AsyncClient.run()` accept the same named arguments. The table covers every explicit submission argument and links to its accepted values, defaults, and examples. [Web page](https://nodus-compute.ai/docs/reference/parameters/)
- [Budget and deadline](https://nodus-compute.ai/docs/source/reference/parameters/outcome.md): Budget is a hard workload spending limit, not a completion-price promise. Available credits and any configured account spending limit also apply. [Web page](https://nodus-compute.ai/docs/reference/parameters/outcome/)
- [Policy and data regions](https://nodus-compute.ai/docs/source/reference/parameters/policy.md): Restricting regions narrows eligible routes and can make a workload infeasible. The SDK forwards the identifiers without translating them. [Web page](https://nodus-compute.ai/docs/reference/parameters/policy/)
- [Resource requirements](https://nodus-compute.ai/docs/source/reference/parameters/requirements.md): The workload file uses the same argument names. You do not need to predict how long your program will run. Provide memory only when you know the requirement. `model` describes your workload and does not download model weights. [Web page](https://nodus-compute.ai/docs/reference/parameters/requirements/)
- [Container image and command](https://nodus-compute.ai/docs/source/reference/parameters/source.md): To attach your code, upload it with `client.assets.upload()` and pass the returned asset ID as `source_asset_id`. Nodus extracts that code into the workload working directory. See [run your own Python script](https://nodus-compute.ai/docs/guides/containers-and-scripts/) for a complete upload-and-run example. [Web page](https://nodus-compute.ai/docs/reference/parameters/source/)
- [Stage parameters](https://nodus-compute.ai/docs/source/reference/parameters/stages.md): A stage-specific nonempty `continuity.mode` does not receive the SDK top-level resume default: provide `resume_on_interruption` explicitly. Setting only that flag without a mode does not override inherited mode and resume behavior. [Web page](https://nodus-compute.ai/docs/reference/parameters/stages/)
- [Python client reference](https://nodus-compute.ai/docs/source/reference/python/client.md): 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. [Web page](https://nodus-compute.ai/docs/reference/python/client/)
- [Tenant secrets](https://nodus-compute.ai/docs/source/reference/python/secrets.md): Pass `secrets=["API_KEY"]` to `client.sandboxes.create()` to bind those names at boot. Commands receive each value as an environment variable and as a file named for the secret under `NODUS_SECRETS_DIR`. Names must be environment variable names outside the reserved `NODUS_` prefix. A sandbox can select at most 32 names, and each value can contain up to 4096 UTF-8 bytes without NUL characters. [Web page](https://nodus-compute.ai/docs/reference/python/secrets/)
- [Per-unit measurements](https://nodus-compute.ai/docs/source/unit-metrics.md): Print one complete JSON line when your command finishes a logical unit of work: [Web page](https://nodus-compute.ai/docs/unit-metrics/)
- [Named workspaces](https://nodus-compute.ai/docs/source/workspaces.md): Create a workspace and attach it to a sandbox to preserve selected files between sandbox identities. [Web page](https://nodus-compute.ai/docs/workspaces/)
- [Quickstart](https://nodus-compute.ai/docs/source/quickstart.md): Get [nodus-compute on PyPI](https://pypi.org/project/nodus-compute/). Requires Python 3.10 or newer. Upgrading an existing installation? Use `pip install --upgrade nodus-compute`. These docs cover SDK 0.5.3. [Web page](https://nodus-compute.ai/docs/quickstart/)