Documentation/Terminal commands

Terminal commands

These examples require SDK 0.11.0 or later.

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.

Setup

For headless machines and automation, see authentication.

Run

Personal history requires a member-associated login. Shared keys can use team history.

submit also defaults to nodus.toml when no path is given. list --limit N accepts 1 through 100. Set your image, command and advanced options in a workload file.

Monitor and collect results

Interactive waits show lifecycle events, live logs, elapsed time, and reported training progress. Redirected output has no animation. nodus logs retrieves saved log snapshots. Declare files as outputs to download them. logs --tail N selects the last N lines, with 0 meaning all lines. logs --generation N selects an attempt number starting at 1.

Ctrl+C during run, wait, or events --follow requests cancellation. Cleanup happens remotely after acceptance. If the request fails, the CLI reports that cancellation is unconfirmed and prints nodus cancel ID. A second Ctrl+C stops the cancellation attempt. A wait timeout ends observation without cancelling.

If submission ends with an uncertain outcome, the CLI prints a recovery key. Add that idempotency_key to the same workload file before retrying. Keep its other settings unchanged to avoid submitting duplicate work.

GPU workspaces

--budget for run is required. new accepts --size-gb for saved project storage, defaulting to the deployment's capacity, --disk-gb for runtime disk and --ssh-key for a public key. Compute runs until you stop it or your account credit runs out. Mutations accept --idempotency-key for retrying an uncertain response with the same identity.

Agent sandboxes

SDK 0.5.1 accepts active names or exact sandbox IDs for the commands below. Older releases require IDs for sandbox commands.

Managed tools are available only on deployments that advertise the qualified template and admit your account. --project excludes dependencies, caches, credentials and recovery state. Use --template nodus:agent-tools-v1 explicitly when creating a named managed sandbox. Image-less name-only calls reconnect.

GitHub source options are unreleased additions that require an enabled managed deployment. Connect GitHub in the console and grant access to the repository, including private repositories. --github-repo OWNER/REPO adds the GitHub network permission. Use --github-ref REF to select a branch, tag ref or commit. Omitting it uses the repository default branch. --setup runs after checkout. Select one source with --project, --source-asset-id or --github-repo. Repository subdirectory selection is not supported.

Name lookup selects one active exact match in your account. It never creates a replacement. Use an ID for a terminated sandbox or when a name is ambiguous. UUID-shaped sandbox IDs are treated as exact IDs even when absent. If you used an ID-shaped name, use the actual ID returned at creation. An accepted create request does not confirm runtime readiness, and accepting termination does not confirm that remote cleanup has finished.

sandbox new, sandbox exec and sandbox rm accept --idempotency-key. If a mutation has an uncertain outcome, preserve the printed key and retry the unchanged operation. Use the printed sandbox ID when available. For exec, put options before the sandbox reference so they are not interpreted as part of the remote command.

If output observation fails after a command is accepted, the CLI prints its execution ID and a sandbox logs command. Resume observation with that command instead of submitting exec again.

nodus sandbox exec --idempotency-key tool-call-001 research-agent python agent.py

Code and datasets

See code and datasets for imports and attaching assets to work.

Customer-owned compute

Observe is free. Predict activation requires explicit consent to its account monthly charge. See customer-owned pools for activation, renewal, cached reads while paused, and optional reported savings. Enrollment tokens are secrets and must not be written to shared logs.

Advanced diagnostics

Use nodus --debug COMMAND for technical error details. Use command help for JSON output, polling, stage selection, and other diagnostic options. Agents can use the Python client for structured results without parsing terminal output.

Upgrading from 0.1

Replace nodus get ID with nodus status ID, and nodus get ID --wait with nodus wait ID. Submission flags have moved into workload files. Use nodus run to submit and wait, or nodus submit to return immediately. Python client.get() and client.run() keep their existing behavior.

Burst proposals

nodus pools proposals POOL_ID reads retained burst intent. Optional --limit accepts 1 to 100, --cursor follows the returned continuation, and --state filters pending, approved, rejected, expired, no_op, applying, or applied. Use --json for the typed public response.

nodus pools approve POOL_ID PROPOSAL_ID approves the immutable proposed amount. nodus pools reject POOL_ID PROPOSAL_ID rejects pending intent. These commands require a current account admin. Approval does not itself rent capacity and does not change the original expiry. Inspect the amount with proposals first.

Database output load state

nodus workload outputs WORKLOAD_ID lists output names, sizes and database sink load state. Add --json for the API fields. Retry a saved sink output with --reload NAME and add --stage STAGE when output names repeat across stages. Loading happens independently of workload completion.