Create a Sandbox
const url = 'https://example.com/apis/nodus.dev/v1/namespaces/example/sandboxes';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"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","stateDir":"example"},"env":[{"name":"example","value":"example","valueFrom":{"secretKeyRef":{"key":"example","name":"example"}}}],"fuseMount":true,"image":"example","imagePullSecrets":["example"],"ingress":{"ports":[{"port":1,"public":true,"wakeOnRequest":true}]},"lifecycle":{"idleTimeout":"example","maxLifetime":"example","onIdle":"example"},"maxCostUSD":"example","network":{"egress":{"allow":["example"],"policy":"example","presets":["example"]}},"placement":{"regions":["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}],"source":{"blob":"example","git":{"path":"example","ref":"example","repo":"example"}},"startup":{"defaults":"example","inherit":true,"profile":"example"},"state":"example","virtualization":{"profile":"example"},"workingDir":"example"},"status":{"activity":"example","attempt":{"epoch":1,"name":"example"},"command":{"attempt":{"epoch":1,"name":"example"},"exitCode":1,"finishTime":"example"},"conditions":[{"lastTransitionTime":"example","message":"example","observedGeneration":1,"reason":"example","status":"example","type":"example"}],"cost":{"bySegment":{"bootCoveredSeconds":1,"bootSeconds":1,"bootUSD":"example","coveredByNodus":["example"],"restoreCoveredSeconds":1,"restoreSeconds":1,"restoreUSD":"example","runningCoveredSeconds":1,"runningSeconds":1,"runningUSD":"example","teardownCoveredSeconds":1,"teardownSeconds":1,"teardownUSD":"example"},"final":true,"fundedUntilTime":"example","heldUSD":"example","limitUSD":"example","rateUSDPerHour":"example","totalUSD":"example"},"endpoints":[{"port":1,"public":true,"url":"example"}],"estimate":{"assemblyBoundUSD":"example","blockingReasons":[{"budgetName":"example","code":"example","fix":"example","message":"example"}],"concurrentHoldUSD":"example","costUSD":{"p50":"example","p90":"example"},"gangHoldUSD":"example","gapFill":{"eligible":true,"reason":"example","requested":true},"holdUSD":"example","minimumChargeUSD":"example","overheadUSD":{"p50":"example","p90":"example"},"placementPreview":{"explain":"example","interruptible":true,"offering":"example","regionClass":"example","researchCapacity":{"disclosure":"example","policy":"example","termsDigest":"example","termsURL":"example"},"warmReuse":true},"pricebookVersion":"example","rateUSDPerHour":"example","startup":{"cold":{"p50":"example","p90":"example"},"warm":{"p50":"example","p90":"example"}},"topology":"example","validUntil":"example","warnings":[{"code":"example","message":"example"}]},"expirationTime":"example","handledRequests":{"additionalProperty":"example"},"image":{"digest":"example","process":{"cmd":["example"],"entrypoint":["example"]},"reference":"example","user":"example"},"lastActivityTime":"example","message":"example","pauseUntil":"example","phase":"example","reason":"example","secretVersionIDs":{"additionalProperty":"example"},"secretVersions":{"additionalProperty":1},"snapshot":{"reason":"example","time":"example"},"source":{"blob":"example","commit":"example"},"startupResolution":{"defaults":{"args":["example"],"command":["example"],"continuity":{"mode":"example","stateDir":"example"},"env":[{"name":"example","value":"example","valueFrom":{"secretKeyRef":{"key":"example","name":"example"}}}],"fuseMount":true,"image":"example","imagePullSecrets":["example"],"lifecycle":{"idleTimeout":"example","maxLifetime":"example","onIdle":"example"},"placement":{"regions":["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}],"virtualization":{"profile":"example"},"workingDir":"example"},"layers":[{"bindingResourceVersion":"example","bindingUID":"example","profile":"example","resourceVersion":"example","source":"example","uid":"example"}],"version":"example"},"stopReason":"example"}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/apis/nodus.dev/v1/namespaces/example/sandboxes \ --header 'Content-Type: application/json' \ --data '{ "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", "stateDir": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "fuseMount": true, "image": "example", "imagePullSecrets": [ "example" ], "ingress": { "ports": [ { "port": 1, "public": true, "wakeOnRequest": true } ] }, "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "placement": { "regions": [ "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 } ], "source": { "blob": "example", "git": { "path": "example", "ref": "example", "repo": "example" } }, "startup": { "defaults": "example", "inherit": true, "profile": "example" }, "state": "example", "virtualization": { "profile": "example" }, "workingDir": "example" }, "status": { "activity": "example", "attempt": { "epoch": 1, "name": "example" }, "command": { "attempt": { "epoch": 1, "name": "example" }, "exitCode": 1, "finishTime": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootCoveredSeconds": 1, "bootSeconds": 1, "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreCoveredSeconds": 1, "restoreSeconds": 1, "restoreUSD": "example", "runningCoveredSeconds": 1, "runningSeconds": 1, "runningUSD": "example", "teardownCoveredSeconds": 1, "teardownSeconds": 1, "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "endpoints": [ { "port": 1, "public": true, "url": "example" } ], "estimate": { "assemblyBoundUSD": "example", "blockingReasons": [ { "budgetName": "example", "code": "example", "fix": "example", "message": "example" } ], "concurrentHoldUSD": "example", "costUSD": { "p50": "example", "p90": "example" }, "gangHoldUSD": "example", "gapFill": { "eligible": true, "reason": "example", "requested": true }, "holdUSD": "example", "minimumChargeUSD": "example", "overheadUSD": { "p50": "example", "p90": "example" }, "placementPreview": { "explain": "example", "interruptible": true, "offering": "example", "regionClass": "example", "researchCapacity": { "disclosure": "example", "policy": "example", "termsDigest": "example", "termsURL": "example" }, "warmReuse": true }, "pricebookVersion": "example", "rateUSDPerHour": "example", "startup": { "cold": { "p50": "example", "p90": "example" }, "warm": { "p50": "example", "p90": "example" } }, "topology": "example", "validUntil": "example", "warnings": [ { "code": "example", "message": "example" } ] }, "expirationTime": "example", "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "process": { "cmd": [ "example" ], "entrypoint": [ "example" ] }, "reference": "example", "user": "example" }, "lastActivityTime": "example", "message": "example", "pauseUntil": "example", "phase": "example", "reason": "example", "secretVersionIDs": { "additionalProperty": "example" }, "secretVersions": { "additionalProperty": 1 }, "snapshot": { "reason": "example", "time": "example" }, "source": { "blob": "example", "commit": "example" }, "startupResolution": { "defaults": { "args": [ "example" ], "command": [ "example" ], "continuity": { "mode": "example", "stateDir": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "fuseMount": true, "image": "example", "imagePullSecrets": [ "example" ], "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "placement": { "regions": [ "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 } ], "virtualization": { "profile": "example" }, "workingDir": "example" }, "layers": [ { "bindingResourceVersion": "example", "bindingUID": "example", "profile": "example", "resourceVersion": "example", "source": "example", "uid": "example" } ], "version": "example" }, "stopReason": "example" } }'Parameters
Section titled “ Parameters ”Path Parameters
Section titled “ Path Parameters ”The project.
Query Parameters
Section titled “ Query Parameters ”Header Parameters
Section titled “ Header Parameters ”Request Bodyrequired
Section titled “ Request Bodyrequired ”Sandbox is an isolated CPU or GPU container for agents and untrusted code, with command execution and files. Neither mode captures the whole root filesystem or process memory. A Sandbox bills per second while it holds compute and follows its configured idle and lifetime limits.
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 CPU default) or Ephemeral (the GPU default). GPU Snapshotted requires StateDir; An explicit StateDir saves after process exit; CPU without one saves /nodus/state before shutdown. Every start launches a fresh process from the image, without rootfs or GPU-memory recovery.
StateDir opts a Sandbox into saving one local directory on stop and restoring it on start. The path is immutable, starts empty, and must not contain remote filesystem mounts. Requires Snapshotted mode.
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.
FuseMount enables guest FUSE mounts for supported GPU Sandboxes. It requires resources.gpu and fails closed when the selected GPU runtime cannot support the requested mount.
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. An eligible startup profile may supply it; Interactive compatibility mode supplies nodus/agent-tools at the lowest precedence. The raw API otherwise requires an image.
ImagePullSecrets name Registry Secrets used to pull a private image (at most 4).
SandboxIngress declares at most 16 browser-accessible application ports.
object
SandboxIngressPort is an application port exposed through the isolated preview gateway.
object
Port is 1024–65535, excluding reserved ports 7777, 18080 and 49983.
Public allows access without Nodus credentials. The default is private.
WakeOnRequest allows public traffic to wake an idle-stopped Sandbox and incur compute charges. It requires Public. A user-stopped or memory-paused Sandbox always needs an explicit Start.
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.
SandboxPlacement carries the placement fields supported by a Sandbox. It intentionally excludes Job-only profile, pool, community and interruptibility settings, so a Sandbox request cannot silently ignore them.
object
Regions are Nodus region classes such as us or ca; empty means any region.
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.
Source is the code for the container: exactly one of git and blob.
object
Blob is sha256:
GitSource is a repository checkout.
object
Path is the checkout path (default workingDir).
Ref is a branch, tag or commit.
Repo is owner/name or an https:// URL.
SandboxStartup selects the shared backend resolver. Explicit Sandbox fields always win.
object
Defaults accepts Interactive: legacy CLI/SDK image and idle behavior at the lowest precedence.
Inherit defaults true for public admission and false for internal callers, including Agents.
Profile names an organization-owned StartupProfile, applied after organization/project bindings.
State is Running (default), Stopped, or Paused (Beta, compatible exclusive CPU nodes only). Paused retains memory for up to 30 minutes, bills allocated storage, and stops on expiry. Stopped releases compute and saves the declared state according to Continuity.
SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.
object
Profile is gpu-child-v1: one exclusive GPU parent with KVM for customer-managed child VMs (Alpha). Children share the parent’s GPU; this does not promise hardware isolation or saved GPU memory.
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.
SandboxCommandStatus is the retained successful main-command result, independent of later starts.
object
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.
ExitCode is zero for successful completion.
FinishTime is when the command completed.
Conditions are Scheduled, Funded and Ready. Explicit local-directory snapshots also report 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
BootCoveredSeconds is the wall-clock time in Boot that Nodus paid for instead, counted like BootSeconds.
BootSeconds is the charged wall-clock time spent in Boot, with parallel allocations counted once; omitted when there was none.
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.
RestoreCoveredSeconds is the wall-clock time in Restore that Nodus paid for instead, counted like BootSeconds.
RestoreSeconds is the charged wall-clock time spent in Restore, counted like BootSeconds.
RestoreUSD is the charge for bringing a replacement up after capacity was lost.
RunningCoveredSeconds is the wall-clock time in Running that Nodus paid for instead, counted like BootSeconds.
RunningSeconds is the charged wall-clock time spent in Running, counted like BootSeconds.
RunningUSD is the charge while the program ran.
TeardownCoveredSeconds is the wall-clock time in Teardown that Nodus paid for instead, counted like BootSeconds.
TeardownSeconds is the charged wall-clock time from stop until deletion was confirmed, counted like BootSeconds; the billing increment adds to TeardownUSD and not to this.
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.
Endpoints are the declared ports on the isolated user-content domain. They contain no credentials.
SandboxEndpoint is a stable application address; it does not assert application readiness.
object
Estimate is returned in status.estimate by a dry-run (?dryRun=All) and on create for every compute kind (ADR-031). Amounts are decimal USD strings; the ETag of the dry-run response binds a later create to it.
object
AssemblyBoundUSD is the most a multi-node Job can cost if its members never assemble.
BlockingReasons say why a real create would fail now, with the amounts and a fix.
BlockingReason says why a create would fail now.
object
BudgetName identifies the exact Budget that refused this hold, when applicable.
Code is the error code the create would return, for example InsufficientCredits.
Fix says what to do.
Message states the reason with the amounts involved.
ConcurrentHoldUSD is the total of the holds for every slot that starts at once.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
GangHoldUSD is the total of the member holds of a multi-node Job.
JobGapFillEligibility describes a single Job’s serving-gap prerequisites, not placement or measured benefit.
object
Eligible is whether the organization and compiled shape support requesting serving gaps.
Reason is the current prerequisite result; host availability and execution authority are checked later.
Requested is whether the Job explicitly prefers interruption.
HoldUSD is the first hold that must fit your balance, every matching Budget and the object’s own cap.
MinimumChargeUSD is the minimum charge quoted by this estimate.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
PlacementPreview is the customer-safe description of the capacity a create would use.
object
Explain is the scheduler’s explanation, the same shape as Attempt status.placement.explain.
Interruptible reports whether the capacity can be reclaimed.
Offering is the offering id, for example h100-sxm-80g-x8-us.
RegionClass is the region class of the offering.
ResearchCapacityTerms describes the separate agreement required by research capacity.
object
Disclosure summarizes collection and capacity conditions before acceptance.
Policy identifies the immutable addendum version.
TermsDigest is the SHA256 of the linked addendum’s bytes.
TermsURL links the immutable public addendum.
WarmReuse reports whether warm capacity would be reused.
PricebookVersion is the price book the estimate used.
RateUSDPerHour is the hourly rate of the chosen capacity.
StartupEstimate is the expected time to start.
object
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
Topology is the resolved multi-node topology of a gang Job.
ValidUntil is when the prices this estimate used stop being current. A create bound by If-Match is admitted after it too, and never placed above rateUSDPerHour plus 10 %.
Warnings are non-blocking notes, for example ColdStart or InterruptibleSelected.
EstimateWarning is a non-blocking note on an estimate.
object
Code is the CamelCase warning code.
Message explains the warning.
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.
ImageProcess preserves the image config’s exec-form arguments without shell interpolation.
object
Cmd is the image’s default command or the arguments appended to Entrypoint.
Entrypoint is the image’s entrypoint, before Cmd.
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.
PauseUntil is the memory-retention deadline. Expiry stops the Sandbox and discards process memory.
Phase is Pending, Starting, Running, Pausing, Paused, Resuming, 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 GPU local-directory copy.
object
Reason is Stop.
Time is when it was saved.
SourceStatus is the resolved code.
object
Blob is the uploaded blob.
Commit is the resolved git commit.
SandboxStartupResolution is immutable admission provenance. Restarts and repeated create use these defaults rather than current bindings. It contains references only; normal image/secret authorization remains required.
object
SandboxStartupDefaults is the bounded subset of SandboxSpec accepted in a startup profile. Objects merge recursively; lists replace. resources.gpu and virtualization accept null to clear an inherited value; all other fields reject null. Explicit empty lists and false remain present across storage/replay.
object
SandboxContinuity sets what survives a stop.
object
Mode is Snapshotted (the CPU default) or Ephemeral (the GPU default). GPU Snapshotted requires StateDir; An explicit StateDir saves after process exit; CPU without one saves /nodus/state before shutdown. Every start launches a fresh process from the image, without rootfs or GPU-memory recovery.
StateDir opts a Sandbox into saving one local directory on stop and restoring it on start. The path is immutable, starts empty, and must not contain remote filesystem mounts. Requires Snapshotted mode.
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.
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.
SandboxPlacement carries the placement fields supported by a Sandbox. It intentionally excludes Job-only profile, pool, community and interruptibility settings, so a Sandbox request cannot silently ignore them.
object
Regions are Nodus region classes such as us or ca; empty means any region.
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.
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.
SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.
object
Profile is gpu-child-v1: one exclusive GPU parent with KVM for customer-managed child VMs (Alpha). Children share the parent’s GPU; this does not promise hardware isolation or saved GPU memory.
SandboxStartupLayer freezes the identity and revision of one resolved profile and optional binding.
object
StopReason says why the Sandbox is stopped; empty while it runs.
Example generated
{ "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", "stateDir": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "fuseMount": true, "image": "example", "imagePullSecrets": [ "example" ], "ingress": { "ports": [ { "port": 1, "public": true, "wakeOnRequest": true } ] }, "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "placement": { "regions": [ "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 } ], "source": { "blob": "example", "git": { "path": "example", "ref": "example", "repo": "example" } }, "startup": { "defaults": "example", "inherit": true, "profile": "example" }, "state": "example", "virtualization": { "profile": "example" }, "workingDir": "example" }, "status": { "activity": "example", "attempt": { "epoch": 1, "name": "example" }, "command": { "attempt": { "epoch": 1, "name": "example" }, "exitCode": 1, "finishTime": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootCoveredSeconds": 1, "bootSeconds": 1, "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreCoveredSeconds": 1, "restoreSeconds": 1, "restoreUSD": "example", "runningCoveredSeconds": 1, "runningSeconds": 1, "runningUSD": "example", "teardownCoveredSeconds": 1, "teardownSeconds": 1, "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "endpoints": [ { "port": 1, "public": true, "url": "example" } ], "estimate": { "assemblyBoundUSD": "example", "blockingReasons": [ { "budgetName": "example", "code": "example", "fix": "example", "message": "example" } ], "concurrentHoldUSD": "example", "costUSD": { "p50": "example", "p90": "example" }, "gangHoldUSD": "example", "gapFill": { "eligible": true, "reason": "example", "requested": true }, "holdUSD": "example", "minimumChargeUSD": "example", "overheadUSD": { "p50": "example", "p90": "example" }, "placementPreview": { "explain": "example", "interruptible": true, "offering": "example", "regionClass": "example", "researchCapacity": { "disclosure": "example", "policy": "example", "termsDigest": "example", "termsURL": "example" }, "warmReuse": true }, "pricebookVersion": "example", "rateUSDPerHour": "example", "startup": { "cold": { "p50": "example", "p90": "example" }, "warm": { "p50": "example", "p90": "example" } }, "topology": "example", "validUntil": "example", "warnings": [ { "code": "example", "message": "example" } ] }, "expirationTime": "example", "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "process": { "cmd": [ "example" ], "entrypoint": [ "example" ] }, "reference": "example", "user": "example" }, "lastActivityTime": "example", "message": "example", "pauseUntil": "example", "phase": "example", "reason": "example", "secretVersionIDs": { "additionalProperty": "example" }, "secretVersions": { "additionalProperty": 1 }, "snapshot": { "reason": "example", "time": "example" }, "source": { "blob": "example", "commit": "example" }, "startupResolution": { "defaults": { "args": [ "example" ], "command": [ "example" ], "continuity": { "mode": "example", "stateDir": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "fuseMount": true, "image": "example", "imagePullSecrets": [ "example" ], "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "placement": { "regions": [ "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 } ], "virtualization": { "profile": "example" }, "workingDir": "example" }, "layers": [ { "bindingResourceVersion": "example", "bindingUID": "example", "profile": "example", "resourceVersion": "example", "source": "example", "uid": "example" } ], "version": "example" }, "stopReason": "example" }}Responses
Section titled “ Responses ”OK
Sandbox is an isolated CPU or GPU container for agents and untrusted code, with command execution and files. Neither mode captures the whole root filesystem or process memory. A Sandbox bills per second while it holds compute and follows its configured idle and lifetime limits.
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 CPU default) or Ephemeral (the GPU default). GPU Snapshotted requires StateDir; An explicit StateDir saves after process exit; CPU without one saves /nodus/state before shutdown. Every start launches a fresh process from the image, without rootfs or GPU-memory recovery.
StateDir opts a Sandbox into saving one local directory on stop and restoring it on start. The path is immutable, starts empty, and must not contain remote filesystem mounts. Requires Snapshotted mode.
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.
FuseMount enables guest FUSE mounts for supported GPU Sandboxes. It requires resources.gpu and fails closed when the selected GPU runtime cannot support the requested mount.
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. An eligible startup profile may supply it; Interactive compatibility mode supplies nodus/agent-tools at the lowest precedence. The raw API otherwise requires an image.
ImagePullSecrets name Registry Secrets used to pull a private image (at most 4).
SandboxIngress declares at most 16 browser-accessible application ports.
object
SandboxIngressPort is an application port exposed through the isolated preview gateway.
object
Port is 1024–65535, excluding reserved ports 7777, 18080 and 49983.
Public allows access without Nodus credentials. The default is private.
WakeOnRequest allows public traffic to wake an idle-stopped Sandbox and incur compute charges. It requires Public. A user-stopped or memory-paused Sandbox always needs an explicit Start.
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.
SandboxPlacement carries the placement fields supported by a Sandbox. It intentionally excludes Job-only profile, pool, community and interruptibility settings, so a Sandbox request cannot silently ignore them.
object
Regions are Nodus region classes such as us or ca; empty means any region.
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.
Source is the code for the container: exactly one of git and blob.
object
Blob is sha256:
GitSource is a repository checkout.
object
Path is the checkout path (default workingDir).
Ref is a branch, tag or commit.
Repo is owner/name or an https:// URL.
SandboxStartup selects the shared backend resolver. Explicit Sandbox fields always win.
object
Defaults accepts Interactive: legacy CLI/SDK image and idle behavior at the lowest precedence.
Inherit defaults true for public admission and false for internal callers, including Agents.
Profile names an organization-owned StartupProfile, applied after organization/project bindings.
State is Running (default), Stopped, or Paused (Beta, compatible exclusive CPU nodes only). Paused retains memory for up to 30 minutes, bills allocated storage, and stops on expiry. Stopped releases compute and saves the declared state according to Continuity.
SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.
object
Profile is gpu-child-v1: one exclusive GPU parent with KVM for customer-managed child VMs (Alpha). Children share the parent’s GPU; this does not promise hardware isolation or saved GPU memory.
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.
SandboxCommandStatus is the retained successful main-command result, independent of later starts.
object
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.
ExitCode is zero for successful completion.
FinishTime is when the command completed.
Conditions are Scheduled, Funded and Ready. Explicit local-directory snapshots also report 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
BootCoveredSeconds is the wall-clock time in Boot that Nodus paid for instead, counted like BootSeconds.
BootSeconds is the charged wall-clock time spent in Boot, with parallel allocations counted once; omitted when there was none.
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.
RestoreCoveredSeconds is the wall-clock time in Restore that Nodus paid for instead, counted like BootSeconds.
RestoreSeconds is the charged wall-clock time spent in Restore, counted like BootSeconds.
RestoreUSD is the charge for bringing a replacement up after capacity was lost.
RunningCoveredSeconds is the wall-clock time in Running that Nodus paid for instead, counted like BootSeconds.
RunningSeconds is the charged wall-clock time spent in Running, counted like BootSeconds.
RunningUSD is the charge while the program ran.
TeardownCoveredSeconds is the wall-clock time in Teardown that Nodus paid for instead, counted like BootSeconds.
TeardownSeconds is the charged wall-clock time from stop until deletion was confirmed, counted like BootSeconds; the billing increment adds to TeardownUSD and not to this.
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.
Endpoints are the declared ports on the isolated user-content domain. They contain no credentials.
SandboxEndpoint is a stable application address; it does not assert application readiness.
object
Estimate is returned in status.estimate by a dry-run (?dryRun=All) and on create for every compute kind (ADR-031). Amounts are decimal USD strings; the ETag of the dry-run response binds a later create to it.
object
AssemblyBoundUSD is the most a multi-node Job can cost if its members never assemble.
BlockingReasons say why a real create would fail now, with the amounts and a fix.
BlockingReason says why a create would fail now.
object
BudgetName identifies the exact Budget that refused this hold, when applicable.
Code is the error code the create would return, for example InsufficientCredits.
Fix says what to do.
Message states the reason with the amounts involved.
ConcurrentHoldUSD is the total of the holds for every slot that starts at once.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
GangHoldUSD is the total of the member holds of a multi-node Job.
JobGapFillEligibility describes a single Job’s serving-gap prerequisites, not placement or measured benefit.
object
Eligible is whether the organization and compiled shape support requesting serving gaps.
Reason is the current prerequisite result; host availability and execution authority are checked later.
Requested is whether the Job explicitly prefers interruption.
HoldUSD is the first hold that must fit your balance, every matching Budget and the object’s own cap.
MinimumChargeUSD is the minimum charge quoted by this estimate.
USDBand is a median and a 90th-percentile amount in USD.
object
P50 is the median amount.
P90 is the 90th-percentile amount.
PlacementPreview is the customer-safe description of the capacity a create would use.
object
Explain is the scheduler’s explanation, the same shape as Attempt status.placement.explain.
Interruptible reports whether the capacity can be reclaimed.
Offering is the offering id, for example h100-sxm-80g-x8-us.
RegionClass is the region class of the offering.
ResearchCapacityTerms describes the separate agreement required by research capacity.
object
Disclosure summarizes collection and capacity conditions before acceptance.
Policy identifies the immutable addendum version.
TermsDigest is the SHA256 of the linked addendum’s bytes.
TermsURL links the immutable public addendum.
WarmReuse reports whether warm capacity would be reused.
PricebookVersion is the price book the estimate used.
RateUSDPerHour is the hourly rate of the chosen capacity.
StartupEstimate is the expected time to start.
object
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
DurationBand is a median and a 90th-percentile duration, as Go duration strings.
object
P50 is the median duration.
P90 is the 90th-percentile duration.
Topology is the resolved multi-node topology of a gang Job.
ValidUntil is when the prices this estimate used stop being current. A create bound by If-Match is admitted after it too, and never placed above rateUSDPerHour plus 10 %.
Warnings are non-blocking notes, for example ColdStart or InterruptibleSelected.
EstimateWarning is a non-blocking note on an estimate.
object
Code is the CamelCase warning code.
Message explains the warning.
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.
ImageProcess preserves the image config’s exec-form arguments without shell interpolation.
object
Cmd is the image’s default command or the arguments appended to Entrypoint.
Entrypoint is the image’s entrypoint, before Cmd.
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.
PauseUntil is the memory-retention deadline. Expiry stops the Sandbox and discards process memory.
Phase is Pending, Starting, Running, Pausing, Paused, Resuming, 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 GPU local-directory copy.
object
Reason is Stop.
Time is when it was saved.
SourceStatus is the resolved code.
object
Blob is the uploaded blob.
Commit is the resolved git commit.
SandboxStartupResolution is immutable admission provenance. Restarts and repeated create use these defaults rather than current bindings. It contains references only; normal image/secret authorization remains required.
object
SandboxStartupDefaults is the bounded subset of SandboxSpec accepted in a startup profile. Objects merge recursively; lists replace. resources.gpu and virtualization accept null to clear an inherited value; all other fields reject null. Explicit empty lists and false remain present across storage/replay.
object
SandboxContinuity sets what survives a stop.
object
Mode is Snapshotted (the CPU default) or Ephemeral (the GPU default). GPU Snapshotted requires StateDir; An explicit StateDir saves after process exit; CPU without one saves /nodus/state before shutdown. Every start launches a fresh process from the image, without rootfs or GPU-memory recovery.
StateDir opts a Sandbox into saving one local directory on stop and restoring it on start. The path is immutable, starts empty, and must not contain remote filesystem mounts. Requires Snapshotted mode.
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.
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.
SandboxPlacement carries the placement fields supported by a Sandbox. It intentionally excludes Job-only profile, pool, community and interruptibility settings, so a Sandbox request cannot silently ignore them.
object
Regions are Nodus region classes such as us or ca; empty means any region.
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.
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.
SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.
object
Profile is gpu-child-v1: one exclusive GPU parent with KVM for customer-managed child VMs (Alpha). Children share the parent’s GPU; this does not promise hardware isolation or saved GPU memory.
SandboxStartupLayer freezes the identity and revision of one resolved profile and optional binding.
object
StopReason says why the Sandbox is stopped; empty while it runs.
Example generated
{ "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", "stateDir": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "fuseMount": true, "image": "example", "imagePullSecrets": [ "example" ], "ingress": { "ports": [ { "port": 1, "public": true, "wakeOnRequest": true } ] }, "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "maxCostUSD": "example", "network": { "egress": { "allow": [ "example" ], "policy": "example", "presets": [ "example" ] } }, "placement": { "regions": [ "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 } ], "source": { "blob": "example", "git": { "path": "example", "ref": "example", "repo": "example" } }, "startup": { "defaults": "example", "inherit": true, "profile": "example" }, "state": "example", "virtualization": { "profile": "example" }, "workingDir": "example" }, "status": { "activity": "example", "attempt": { "epoch": 1, "name": "example" }, "command": { "attempt": { "epoch": 1, "name": "example" }, "exitCode": 1, "finishTime": "example" }, "conditions": [ { "lastTransitionTime": "example", "message": "example", "observedGeneration": 1, "reason": "example", "status": "example", "type": "example" } ], "cost": { "bySegment": { "bootCoveredSeconds": 1, "bootSeconds": 1, "bootUSD": "example", "coveredByNodus": [ "example" ], "restoreCoveredSeconds": 1, "restoreSeconds": 1, "restoreUSD": "example", "runningCoveredSeconds": 1, "runningSeconds": 1, "runningUSD": "example", "teardownCoveredSeconds": 1, "teardownSeconds": 1, "teardownUSD": "example" }, "final": true, "fundedUntilTime": "example", "heldUSD": "example", "limitUSD": "example", "rateUSDPerHour": "example", "totalUSD": "example" }, "endpoints": [ { "port": 1, "public": true, "url": "example" } ], "estimate": { "assemblyBoundUSD": "example", "blockingReasons": [ { "budgetName": "example", "code": "example", "fix": "example", "message": "example" } ], "concurrentHoldUSD": "example", "costUSD": { "p50": "example", "p90": "example" }, "gangHoldUSD": "example", "gapFill": { "eligible": true, "reason": "example", "requested": true }, "holdUSD": "example", "minimumChargeUSD": "example", "overheadUSD": { "p50": "example", "p90": "example" }, "placementPreview": { "explain": "example", "interruptible": true, "offering": "example", "regionClass": "example", "researchCapacity": { "disclosure": "example", "policy": "example", "termsDigest": "example", "termsURL": "example" }, "warmReuse": true }, "pricebookVersion": "example", "rateUSDPerHour": "example", "startup": { "cold": { "p50": "example", "p90": "example" }, "warm": { "p50": "example", "p90": "example" } }, "topology": "example", "validUntil": "example", "warnings": [ { "code": "example", "message": "example" } ] }, "expirationTime": "example", "handledRequests": { "additionalProperty": "example" }, "image": { "digest": "example", "process": { "cmd": [ "example" ], "entrypoint": [ "example" ] }, "reference": "example", "user": "example" }, "lastActivityTime": "example", "message": "example", "pauseUntil": "example", "phase": "example", "reason": "example", "secretVersionIDs": { "additionalProperty": "example" }, "secretVersions": { "additionalProperty": 1 }, "snapshot": { "reason": "example", "time": "example" }, "source": { "blob": "example", "commit": "example" }, "startupResolution": { "defaults": { "args": [ "example" ], "command": [ "example" ], "continuity": { "mode": "example", "stateDir": "example" }, "env": [ { "name": "example", "value": "example", "valueFrom": { "secretKeyRef": { "key": "example", "name": "example" } } } ], "fuseMount": true, "image": "example", "imagePullSecrets": [ "example" ], "lifecycle": { "idleTimeout": "example", "maxLifetime": "example", "onIdle": "example" }, "placement": { "regions": [ "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 } ], "virtualization": { "profile": "example" }, "workingDir": "example" }, "layers": [ { "bindingResourceVersion": "example", "bindingUID": "example", "profile": "example", "resourceVersion": "example", "source": "example", "uid": "example" } ], "version": "example" }, "stopReason": "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"}