List or watch sandboxes in every project
const url = 'https://example.com/apis/nodus.dev/v1/sandboxes';const options = {method: 'GET'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://example.com/apis/nodus.dev/v1/sandboxesParameters
Section titled “ Parameters ”Query Parameters
Section titled “ Query Parameters ”Responses
Section titled “ Responses ”OK
object
Sandbox is an isolated container for agents and untrusted code on Nodus CPU nodes. You run commands in it, read and write its files, stop it to stop paying for compute and start it again with its /workspace kept. It bills per second while it holds compute, and stops by itself when idle.
object
object
object
object
object
object
object
SandboxSpec is the container to run and its lifecycle.
object
Args are the arguments of Command.
Command is an optional main process. Without it the Sandbox idles and is driven by exec.
SandboxContinuity sets what survives a stop.
object
Mode is Snapshotted (the default: /workspace is saved on stop and restored on start) or Ephemeral (every start begins from the image).
Env sets environment variables (at most 256; the NODUS_ prefix is reserved). A value read from a Secret key uses valueFrom.secretKeyRef.
EnvVar is one environment variable: a literal value or a Secret key.
object
Name matches ^[A-Za-z_][A-Za-z0-9_]*$.
Value is the literal value.
EnvVarSource names where an env value comes from.
object
SecretKeySelector selects one key of a Secret.
object
Key is the key within it.
Name is the Secret.
Image is the container image, such as nodus/agent-tools or ghcr.io/acme/tools:1.2; it is pinned to a digest when the Sandbox is created. The CLI and SDK send nodus/agent-tools when you name none.
SandboxLifecycleSpec sets when a Sandbox stops or is deleted without being asked.
object
IdleTimeout stops (or deletes, with onIdle Delete) the Sandbox after this long with no running command, no file request and no terminal input: 0s never, or 1m–24h (default 5m). A silent open terminal is idle.
MaxLifetime deletes the Sandbox this long after it was created, counting stopped time: 1m–720h (default 24h).
OnIdle is Stop (the default) or Delete.
MaxCostUSD caps what the Sandbox may spend across every start, as a decimal USD string such as “5.00”. It can only be raised.
Network sets egress for the container.
object
Egress is the outbound network policy.
object
Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).
Policy is Deny, AllowList or Open.
Presets add curated host lists such as python-packages or huggingface.
Resources are capacity floors. For GPU work the offering’s host shape applies if larger.
object
CPU is the vCPU floor.
Disk is the ephemeral disk floor.
GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.
object
Count is the GPUs per node: 1, 2, 4 or 8.
Exact pins the exact variant instead of matching the family.
Interconnect is Any or NVLink.
MinMemory is the per-GPU memory floor.
Type lists 1–8 accelerator ids or families from the catalog.
Memory is the host memory floor.
Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.
Secrets mount Secrets as env vars and 0400 files under /run/secrets/
SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.
object
Name is the Secret.
Version pins a version; unset pins the latest at admission.
State is Running (the default) or Stopped. Stopping releases the compute and keeps /workspace.
WorkingDir is the absolute directory commands start in (default /workspace).
SandboxStatus is what Nodus observed about a Sandbox.
object
Activity is Busy while a command runs, else Idle.
SandboxAttempt names one run of a Sandbox’s container.
object
Epoch counts the runs: it grows on every start and every recovery.
Name is the attempt’s id.
Conditions are Scheduled, Funded, Ready and StateSaved.
object
Cost is status.cost on every kind that spends money. It is a display copy of the ledger: amounts are decimal USD strings, and nothing is charged from these fields.
object
CostSegments splits a charge by billing segment.
object
BootUSD is the charge from the start of billing until the program started.
CoveredByNodus lists the segments (Boot, Running, Restore, Teardown) with time Nodus paid for instead of charging it, such as the start and teardown of a run that failed because of Nodus.
RestoreUSD is the charge for bringing a replacement up after capacity was lost.
RunningUSD is the charge while the program ran.
TeardownUSD is the charge from stop until deletion was confirmed, with the billing increment.
Final is true once the final charge has posted.
FundedUntilTime is when the current holds stop paying for the object.
HeldUSD is what is currently held for it.
LimitUSD is the object’s maxCostUSD, if it has one.
RateUSDPerHour is the sum of the hourly rates of its capacity that is still billing.
TotalUSD is what has been charged for this object so far.
ExpirationTime is when maxLifetime deletes the Sandbox.
HandledRequests records the nodus.dev/start-requested-at value last acted on.
object
ImageStatus is the pinned image.
object
Digest is the pinned digest.
Reference is the image as written.
User is the user the image’s config runs its process as (root when it names none). Only an image that runs as root is placed on offerings that start the Nodus node agent inside the image itself.
LastActivityTime is the last command, file request or terminal input seen; idleTimeout counts from it.
Message is a human-readable account of Reason.
Phase is Pending, Starting, Running, Recovering, Stopping, Stopped, Terminating or Failed.
Reason says why the Sandbox Failed, such as StartupFailed or NodeLost.
SecretVersionIDs identify the versions resolved when the Sandbox was created.
object
SecretVersions are the versions resolved when the Sandbox was created, which proves its Secrets exist; each start pins the newest version again.
object
SandboxSnapshot describes the last saved copy of /workspace.
object
Reason is Stop.
Time is when it was saved.
StopReason says why the Sandbox is stopped; empty while it runs.
object
object
Example generated
{ "apiVersion": "example", "items": [ { "apiVersion": "example", "kind": "example", "metadata": { "annotations": { "additionalProperty": "example" }, "creationTimestamp": "example", "deletionGracePeriodSeconds": 1, "deletionTimestamp": "example", "finalizers": [ "example" ], "generateName": "example", "generation": 1, "labels": { "additionalProperty": "example" }, "managedFields": [ { "apiVersion": "example", "fieldsType": "example", "fieldsV1": { "additionalProperty": "example" }, "manager": "example", "operation": "example", "subresource": "example", "time": "example" } ], "name": "example", "namespace": "example", "ownerReferences": [ { "apiVersion": "example", "blockOwnerDeletion": true, "controller": true, "kind": "example", "name": "example", "uid": "example" } ], "resourceVersion": "example", "selfLink": "example", "uid": "example" }, "spec": { "args": [ "example" ], "command": [ "example" ], "continuity": { "mode": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "image": "example", "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "resources": { "cpu": "example", "disk": "example", "gpu": { "count": 1, "exact": true, "interconnect": "example", "minMemory": "example", "type": [ "example" ] }, "memory": "example", "nodes": 1 }, "secrets": [ { "name": "example", "version": 1 } ], "state": "example", "workingDir": "example" }, "status": { "activity": "example", "attempt": { "epoch": 1, "name": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreUSD": "example", "runningUSD": "example", "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "expirationTime": "example", "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "reference": "example", "user": "example" }, "lastActivityTime": "example", "message": "example", "phase": "example", "reason": "example", "secretVersionIDs": { "additionalProperty": "example" }, "secretVersions": { "additionalProperty": 1 }, "snapshot": { "reason": "example", "time": "example" }, "stopReason": "example" } } ], "kind": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "example" } }}default
Section titled “ default ”An error: a metav1.Status whose reason is a registered code.
Status is the error body of every API response: a Kubernetes metav1.Status (so kubectl and client-go understand it) plus three top-level extensions that those clients ignore (ADR-028).
object
object
object
Docs is the URL of the code’s docs page.
Fix says what to do next, for example a CLI command or the field to change.
object
object
RequestID identifies the request in logs and support tickets.
Example generated
{ "apiVersion": "example", "code": 1, "details": { "causes": [ { "field": "example", "message": "example", "reason": "example" } ], "group": "example", "kind": "example", "name": "example", "retryAfterSeconds": 1, "uid": "example" }, "docs": "example", "fix": "example", "kind": "example", "message": "example", "metadata": { "continue": "example", "remainingItemCount": 1, "resourceVersion": "example", "selfLink": "example", "shardInfo": { "selector": "example" } }, "reason": "example", "requestId": "example", "status": "example"}