Skip to content

Create a Sandbox

POST
/apis/nodus.dev/v1/namespaces/{namespace}/sandboxes
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" } }'
namespace
required
string

The project.

dryRun
string
fieldValidation
string
fieldManager
string
Idempotency-Key
string
If-Match
string
Media type application/json

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
apiVersion
string
kind
string
metadata
object
annotations
object
key
additional properties
string
creationTimestamp
string
deletionGracePeriodSeconds
integer format: int64
deletionTimestamp
string
finalizers
Array<string>
nullable
generateName
string
generation
integer format: int64
labels
object
key
additional properties
string
managedFields
Array<object>
nullable
object
apiVersion
string
fieldsType
string
fieldsV1
object
key
additional properties
manager
string
operation
string
subresource
string
time
string
name
string
namespace
string
ownerReferences
Array<object>
nullable
object
apiVersion
required
string
blockOwnerDeletion
boolean
controller
boolean
kind
required
string
name
required
string
uid
required
string
resourceVersion
string
selfLink
string
uid
string
spec
required

SandboxSpec is the container to run and its lifecycle.

object
args

Args are the arguments of Command.

Array<string>
nullable
command

Command is an optional main process. Without it the Sandbox idles and is driven by exec.

Array<string>
nullable
continuity

SandboxContinuity sets what survives a stop.

object
mode

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.

string
stateDir

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.

string
env

Env sets environment variables (at most 256; the NODUS_ prefix is reserved). A value read from a Secret key uses valueFrom.secretKeyRef.

Array<object>
nullable

EnvVar is one environment variable: a literal value or a Secret key.

object
name
required

Name matches ^[A-Za-z_][A-Za-z0-9_]*$.

string
value

Value is the literal value.

string
valueFrom

EnvVarSource names where an env value comes from.

object
secretKeyRef

SecretKeySelector selects one key of a Secret.

object
key
required

Key is the key within it.

string
name
required

Name is the Secret.

string
fuseMount

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.

boolean
image

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.

string
imagePullSecrets

ImagePullSecrets name Registry Secrets used to pull a private image (at most 4).

Array<string>
nullable
ingress

SandboxIngress declares at most 16 browser-accessible application ports.

object
ports
Array<object>
nullable

SandboxIngressPort is an application port exposed through the isolated preview gateway.

object
port
required

Port is 1024–65535, excluding reserved ports 7777, 18080 and 49983.

integer format: int32
public

Public allows access without Nodus credentials. The default is private.

boolean
wakeOnRequest

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.

boolean
lifecycle

SandboxLifecycleSpec sets when a Sandbox stops or is deleted without being asked.

object
idleTimeout

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.

string
maxLifetime

MaxLifetime deletes the Sandbox this long after it was created, counting stopped time: 1m–720h (default 24h).

string
onIdle

OnIdle is Stop (the default) or Delete.

string
maxCostUSD

MaxCostUSD caps what the Sandbox may spend across every start, as a decimal USD string such as “5.00”. It can only be raised.

string
network

Network sets egress for the container.

object
egress

Egress is the outbound network policy.

object
allow

Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).

Array<string>
nullable
policy

Policy is Deny, AllowList or Open.

string
presets

Presets add curated host lists such as python-packages or huggingface.

Array<string>
nullable
placement

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

Regions are Nodus region classes such as us or ca; empty means any region.

Array<string>
nullable
resources

Resources are capacity floors. For GPU work the offering’s host shape applies if larger.

object
cpu

CPU is the vCPU floor.

string
disk

Disk is the ephemeral disk floor.

string
gpu

GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.

object
count

Count is the GPUs per node: 1, 2, 4 or 8.

integer format: int32
exact

Exact pins the exact variant instead of matching the family.

boolean
interconnect

Interconnect is Any or NVLink.

string
minMemory

MinMemory is the per-GPU memory floor.

string
type

Type lists 1–8 accelerator ids or families from the catalog.

Array<string>
nullable
memory

Memory is the host memory floor.

string
nodes

Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.

integer format: int32
secrets

Secrets mount Secrets as env vars and 0400 files under /run/secrets// (at most 32). Each start pins the newest version of each Secret (or the version a mount names) and keeps it until it stops, so a new value reaches the Sandbox on its next start.

Array<object>
nullable

SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.

object
name
required

Name is the Secret.

string
version

Version pins a version; unset pins the latest at admission.

integer format: int32
source

Source is the code for the container: exactly one of git and blob.

object
blob

Blob is sha256: of an archive uploaded through /blobs/v1.

string
git

GitSource is a repository checkout.

object
path

Path is the checkout path (default workingDir).

string
ref

Ref is a branch, tag or commit.

string
repo
required

Repo is owner/name or an https:// URL.

string
startup

SandboxStartup selects the shared backend resolver. Explicit Sandbox fields always win.

object
defaults

Defaults accepts Interactive: legacy CLI/SDK image and idle behavior at the lowest precedence.

string
inherit

Inherit defaults true for public admission and false for internal callers, including Agents.

boolean
profile

Profile names an organization-owned StartupProfile, applied after organization/project bindings.

string
state

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.

string
virtualization

SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.

object
profile
required

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.

string
workingDir

WorkingDir is the absolute directory commands start in (default /workspace).

string
status

SandboxStatus is what Nodus observed about a Sandbox.

object
activity

Activity is Busy while a command runs, else Idle.

string
attempt

SandboxAttempt names one run of a Sandbox’s container.

object
epoch
required

Epoch counts the runs: it grows on every start and every recovery.

integer format: int64
name
required

Name is the attempt’s id.

string
command

SandboxCommandStatus is the retained successful main-command result, independent of later starts.

object
attempt
required

SandboxAttempt names one run of a Sandbox’s container.

object
epoch
required

Epoch counts the runs: it grows on every start and every recovery.

integer format: int64
name
required

Name is the attempt’s id.

string
exitCode
required

ExitCode is zero for successful completion.

integer format: int32
finishTime
required

FinishTime is when the command completed.

string
conditions

Conditions are Scheduled, Funded and Ready. Explicit local-directory snapshots also report StateSaved.

Array<object>
nullable
object
lastTransitionTime
required
string
message
required
string
observedGeneration
integer format: int64
reason
required
string
status
required
string
type
required
string
cost

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
bySegment

CostSegments splits a charge by billing segment.

object
bootCoveredSeconds

BootCoveredSeconds is the wall-clock time in Boot that Nodus paid for instead, counted like BootSeconds.

integer format: int64
bootSeconds

BootSeconds is the charged wall-clock time spent in Boot, with parallel allocations counted once; omitted when there was none.

integer format: int64
bootUSD

BootUSD is the charge from the start of billing until the program started.

string
coveredByNodus

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.

Array<string>
nullable
restoreCoveredSeconds

RestoreCoveredSeconds is the wall-clock time in Restore that Nodus paid for instead, counted like BootSeconds.

integer format: int64
restoreSeconds

RestoreSeconds is the charged wall-clock time spent in Restore, counted like BootSeconds.

integer format: int64
restoreUSD

RestoreUSD is the charge for bringing a replacement up after capacity was lost.

string
runningCoveredSeconds

RunningCoveredSeconds is the wall-clock time in Running that Nodus paid for instead, counted like BootSeconds.

integer format: int64
runningSeconds

RunningSeconds is the charged wall-clock time spent in Running, counted like BootSeconds.

integer format: int64
runningUSD

RunningUSD is the charge while the program ran.

string
teardownCoveredSeconds

TeardownCoveredSeconds is the wall-clock time in Teardown that Nodus paid for instead, counted like BootSeconds.

integer format: int64
teardownSeconds

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.

integer format: int64
teardownUSD

TeardownUSD is the charge from stop until deletion was confirmed, with the billing increment.

string
final

Final is true once the final charge has posted.

boolean
fundedUntilTime

FundedUntilTime is when the current holds stop paying for the object.

string
heldUSD

HeldUSD is what is currently held for it.

string
limitUSD

LimitUSD is the object’s maxCostUSD, if it has one.

string
rateUSDPerHour

RateUSDPerHour is the sum of the hourly rates of its capacity that is still billing.

string
totalUSD

TotalUSD is what has been charged for this object so far.

string
endpoints

Endpoints are the declared ports on the isolated user-content domain. They contain no credentials.

Array<object>
nullable

SandboxEndpoint is a stable application address; it does not assert application readiness.

object
port
required
integer format: int32
public
boolean
url
required
string
estimate

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

AssemblyBoundUSD is the most a multi-node Job can cost if its members never assemble.

string
blockingReasons

BlockingReasons say why a real create would fail now, with the amounts and a fix.

Array<object>
nullable

BlockingReason says why a create would fail now.

object
budgetName

BudgetName identifies the exact Budget that refused this hold, when applicable.

string
code
required

Code is the error code the create would return, for example InsufficientCredits.

string
fix

Fix says what to do.

string
message

Message states the reason with the amounts involved.

string
concurrentHoldUSD

ConcurrentHoldUSD is the total of the holds for every slot that starts at once.

string
costUSD

USDBand is a median and a 90th-percentile amount in USD.

object
p50

P50 is the median amount.

string
p90

P90 is the 90th-percentile amount.

string
gangHoldUSD

GangHoldUSD is the total of the member holds of a multi-node Job.

string
gapFill

JobGapFillEligibility describes a single Job’s serving-gap prerequisites, not placement or measured benefit.

object
eligible
required

Eligible is whether the organization and compiled shape support requesting serving gaps.

boolean
reason
required

Reason is the current prerequisite result; host availability and execution authority are checked later.

string
requested
required

Requested is whether the Job explicitly prefers interruption.

boolean
holdUSD

HoldUSD is the first hold that must fit your balance, every matching Budget and the object’s own cap.

string
minimumChargeUSD

MinimumChargeUSD is the minimum charge quoted by this estimate.

string
overheadUSD

USDBand is a median and a 90th-percentile amount in USD.

object
p50

P50 is the median amount.

string
p90

P90 is the 90th-percentile amount.

string
placementPreview

PlacementPreview is the customer-safe description of the capacity a create would use.

object
explain

Explain is the scheduler’s explanation, the same shape as Attempt status.placement.explain.

interruptible

Interruptible reports whether the capacity can be reclaimed.

boolean
offering

Offering is the offering id, for example h100-sxm-80g-x8-us.

string
regionClass

RegionClass is the region class of the offering.

string
researchCapacity

ResearchCapacityTerms describes the separate agreement required by research capacity.

object
disclosure
required

Disclosure summarizes collection and capacity conditions before acceptance.

string
policy
required

Policy identifies the immutable addendum version.

string
termsDigest
required

TermsDigest is the SHA256 of the linked addendum’s bytes.

string
termsURL
required

TermsURL links the immutable public addendum.

string
warmReuse

WarmReuse reports whether warm capacity would be reused.

boolean
pricebookVersion

PricebookVersion is the price book the estimate used.

string
rateUSDPerHour

RateUSDPerHour is the hourly rate of the chosen capacity.

string
startup

StartupEstimate is the expected time to start.

object
cold

DurationBand is a median and a 90th-percentile duration, as Go duration strings.

object
p50

P50 is the median duration.

string
p90

P90 is the 90th-percentile duration.

string
warm

DurationBand is a median and a 90th-percentile duration, as Go duration strings.

object
p50

P50 is the median duration.

string
p90

P90 is the 90th-percentile duration.

string
topology

Topology is the resolved multi-node topology of a gang Job.

validUntil

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 %.

string
warnings

Warnings are non-blocking notes, for example ColdStart or InterruptibleSelected.

Array<object>
nullable

EstimateWarning is a non-blocking note on an estimate.

object
code
required

Code is the CamelCase warning code.

string
message

Message explains the warning.

string
expirationTime

ExpirationTime is when maxLifetime deletes the Sandbox.

string
handledRequests

HandledRequests records the nodus.dev/start-requested-at value last acted on.

object
key
additional properties
string
image

ImageStatus is the pinned image.

object
digest

Digest is the pinned digest.

string
process

ImageProcess preserves the image config’s exec-form arguments without shell interpolation.

object
cmd

Cmd is the image’s default command or the arguments appended to Entrypoint.

Array<string>
nullable
entrypoint

Entrypoint is the image’s entrypoint, before Cmd.

Array<string>
nullable
reference

Reference is the image as written.

string
user

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.

string
lastActivityTime

LastActivityTime is the last command, file request or terminal input seen; idleTimeout counts from it.

string
message

Message is a human-readable account of Reason.

string
pauseUntil

PauseUntil is the memory-retention deadline. Expiry stops the Sandbox and discards process memory.

string
phase

Phase is Pending, Starting, Running, Pausing, Paused, Resuming, Recovering, Stopping, Stopped, Terminating or Failed.

string
reason

Reason says why the Sandbox Failed, such as StartupFailed or NodeLost.

string
secretVersionIDs

SecretVersionIDs identify the versions resolved when the Sandbox was created.

object
key
additional properties
string
secretVersions

SecretVersions are the versions resolved when the Sandbox was created, which proves its Secrets exist; each start pins the newest version again.

object
key
additional properties
integer format: int32
snapshot

SandboxSnapshot describes the last saved GPU local-directory copy.

object
reason
required

Reason is Stop.

string
time
required

Time is when it was saved.

string
source

SourceStatus is the resolved code.

object
blob

Blob is the uploaded blob.

string
commit

Commit is the resolved git commit.

string
startupResolution

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
defaults
required

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
args
Array<string>
command
Array<string>
continuity

SandboxContinuity sets what survives a stop.

object
mode

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.

string
stateDir

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.

string
env
Array<object>

EnvVar is one environment variable: a literal value or a Secret key.

object
name
required

Name matches ^[A-Za-z_][A-Za-z0-9_]*$.

string
value

Value is the literal value.

string
valueFrom

EnvVarSource names where an env value comes from.

object
secretKeyRef

SecretKeySelector selects one key of a Secret.

object
key
required

Key is the key within it.

string
name
required

Name is the Secret.

string
fuseMount
boolean
image
string
imagePullSecrets
Array<string>
lifecycle

SandboxLifecycleSpec sets when a Sandbox stops or is deleted without being asked.

object
idleTimeout

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.

string
maxLifetime

MaxLifetime deletes the Sandbox this long after it was created, counting stopped time: 1m–720h (default 24h).

string
onIdle

OnIdle is Stop (the default) or Delete.

string
placement

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

Regions are Nodus region classes such as us or ca; empty means any region.

Array<string>
nullable
resources

Resources are capacity floors. For GPU work the offering’s host shape applies if larger.

object
cpu

CPU is the vCPU floor.

string
disk

Disk is the ephemeral disk floor.

string
gpu

GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.

object
count

Count is the GPUs per node: 1, 2, 4 or 8.

integer format: int32
exact

Exact pins the exact variant instead of matching the family.

boolean
interconnect

Interconnect is Any or NVLink.

string
minMemory

MinMemory is the per-GPU memory floor.

string
type

Type lists 1–8 accelerator ids or families from the catalog.

Array<string>
nullable
memory

Memory is the host memory floor.

string
nodes

Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.

integer format: int32
secrets
Array<object>

SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.

object
name
required

Name is the Secret.

string
version

Version pins a version; unset pins the latest at admission.

integer format: int32
virtualization

SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.

object
profile
required

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.

string
workingDir
string
layers
Array<object>
nullable

SandboxStartupLayer freezes the identity and revision of one resolved profile and optional binding.

object
bindingResourceVersion
string
bindingUID
string
profile
required
string
resourceVersion
required
string
source
required
string
uid
required
string
version
required
string
stopReason

StopReason says why the Sandbox is stopped; empty while it runs.

string
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"
}
}

OK

Media type application/json

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
apiVersion
string
kind
string
metadata
object
annotations
object
key
additional properties
string
creationTimestamp
string
deletionGracePeriodSeconds
integer format: int64
deletionTimestamp
string
finalizers
Array<string>
nullable
generateName
string
generation
integer format: int64
labels
object
key
additional properties
string
managedFields
Array<object>
nullable
object
apiVersion
string
fieldsType
string
fieldsV1
object
key
additional properties
manager
string
operation
string
subresource
string
time
string
name
string
namespace
string
ownerReferences
Array<object>
nullable
object
apiVersion
required
string
blockOwnerDeletion
boolean
controller
boolean
kind
required
string
name
required
string
uid
required
string
resourceVersion
string
selfLink
string
uid
string
spec
required

SandboxSpec is the container to run and its lifecycle.

object
args

Args are the arguments of Command.

Array<string>
nullable
command

Command is an optional main process. Without it the Sandbox idles and is driven by exec.

Array<string>
nullable
continuity

SandboxContinuity sets what survives a stop.

object
mode

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.

string
stateDir

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.

string
env

Env sets environment variables (at most 256; the NODUS_ prefix is reserved). A value read from a Secret key uses valueFrom.secretKeyRef.

Array<object>
nullable

EnvVar is one environment variable: a literal value or a Secret key.

object
name
required

Name matches ^[A-Za-z_][A-Za-z0-9_]*$.

string
value

Value is the literal value.

string
valueFrom

EnvVarSource names where an env value comes from.

object
secretKeyRef

SecretKeySelector selects one key of a Secret.

object
key
required

Key is the key within it.

string
name
required

Name is the Secret.

string
fuseMount

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.

boolean
image
required

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.

string
imagePullSecrets

ImagePullSecrets name Registry Secrets used to pull a private image (at most 4).

Array<string>
nullable
ingress

SandboxIngress declares at most 16 browser-accessible application ports.

object
ports
Array<object>
nullable

SandboxIngressPort is an application port exposed through the isolated preview gateway.

object
port
required

Port is 1024–65535, excluding reserved ports 7777, 18080 and 49983.

integer format: int32
public

Public allows access without Nodus credentials. The default is private.

boolean
wakeOnRequest

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.

boolean
lifecycle

SandboxLifecycleSpec sets when a Sandbox stops or is deleted without being asked.

object
idleTimeout

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.

string
maxLifetime

MaxLifetime deletes the Sandbox this long after it was created, counting stopped time: 1m–720h (default 24h).

string
onIdle

OnIdle is Stop (the default) or Delete.

string
maxCostUSD

MaxCostUSD caps what the Sandbox may spend across every start, as a decimal USD string such as “5.00”. It can only be raised.

string
network

Network sets egress for the container.

object
egress

Egress is the outbound network policy.

object
allow

Allow lists DNS names or *.suffix patterns (AllowList only; at most 128).

Array<string>
nullable
policy

Policy is Deny, AllowList or Open.

string
presets

Presets add curated host lists such as python-packages or huggingface.

Array<string>
nullable
placement

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

Regions are Nodus region classes such as us or ca; empty means any region.

Array<string>
nullable
resources

Resources are capacity floors. For GPU work the offering’s host shape applies if larger.

object
cpu

CPU is the vCPU floor.

string
disk

Disk is the ephemeral disk floor.

string
gpu

GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.

object
count

Count is the GPUs per node: 1, 2, 4 or 8.

integer format: int32
exact

Exact pins the exact variant instead of matching the family.

boolean
interconnect

Interconnect is Any or NVLink.

string
minMemory

MinMemory is the per-GPU memory floor.

string
type

Type lists 1–8 accelerator ids or families from the catalog.

Array<string>
nullable
memory

Memory is the host memory floor.

string
nodes

Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.

integer format: int32
secrets

Secrets mount Secrets as env vars and 0400 files under /run/secrets// (at most 32). Each start pins the newest version of each Secret (or the version a mount names) and keeps it until it stops, so a new value reaches the Sandbox on its next start.

Array<object>
nullable

SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.

object
name
required

Name is the Secret.

string
version

Version pins a version; unset pins the latest at admission.

integer format: int32
source

Source is the code for the container: exactly one of git and blob.

object
blob

Blob is sha256: of an archive uploaded through /blobs/v1.

string
git

GitSource is a repository checkout.

object
path

Path is the checkout path (default workingDir).

string
ref

Ref is a branch, tag or commit.

string
repo
required

Repo is owner/name or an https:// URL.

string
startup

SandboxStartup selects the shared backend resolver. Explicit Sandbox fields always win.

object
defaults

Defaults accepts Interactive: legacy CLI/SDK image and idle behavior at the lowest precedence.

string
inherit

Inherit defaults true for public admission and false for internal callers, including Agents.

boolean
profile

Profile names an organization-owned StartupProfile, applied after organization/project bindings.

string
state

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.

string
virtualization

SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.

object
profile
required

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.

string
workingDir

WorkingDir is the absolute directory commands start in (default /workspace).

string
status

SandboxStatus is what Nodus observed about a Sandbox.

object
activity

Activity is Busy while a command runs, else Idle.

string
attempt

SandboxAttempt names one run of a Sandbox’s container.

object
epoch
required

Epoch counts the runs: it grows on every start and every recovery.

integer format: int64
name
required

Name is the attempt’s id.

string
command

SandboxCommandStatus is the retained successful main-command result, independent of later starts.

object
attempt
required

SandboxAttempt names one run of a Sandbox’s container.

object
epoch
required

Epoch counts the runs: it grows on every start and every recovery.

integer format: int64
name
required

Name is the attempt’s id.

string
exitCode
required

ExitCode is zero for successful completion.

integer format: int32
finishTime
required

FinishTime is when the command completed.

string
conditions

Conditions are Scheduled, Funded and Ready. Explicit local-directory snapshots also report StateSaved.

Array<object>
nullable
object
lastTransitionTime
required
string
message
required
string
observedGeneration
integer format: int64
reason
required
string
status
required
string
type
required
string
cost

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
bySegment

CostSegments splits a charge by billing segment.

object
bootCoveredSeconds

BootCoveredSeconds is the wall-clock time in Boot that Nodus paid for instead, counted like BootSeconds.

integer format: int64
bootSeconds

BootSeconds is the charged wall-clock time spent in Boot, with parallel allocations counted once; omitted when there was none.

integer format: int64
bootUSD

BootUSD is the charge from the start of billing until the program started.

string
coveredByNodus

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.

Array<string>
nullable
restoreCoveredSeconds

RestoreCoveredSeconds is the wall-clock time in Restore that Nodus paid for instead, counted like BootSeconds.

integer format: int64
restoreSeconds

RestoreSeconds is the charged wall-clock time spent in Restore, counted like BootSeconds.

integer format: int64
restoreUSD

RestoreUSD is the charge for bringing a replacement up after capacity was lost.

string
runningCoveredSeconds

RunningCoveredSeconds is the wall-clock time in Running that Nodus paid for instead, counted like BootSeconds.

integer format: int64
runningSeconds

RunningSeconds is the charged wall-clock time spent in Running, counted like BootSeconds.

integer format: int64
runningUSD

RunningUSD is the charge while the program ran.

string
teardownCoveredSeconds

TeardownCoveredSeconds is the wall-clock time in Teardown that Nodus paid for instead, counted like BootSeconds.

integer format: int64
teardownSeconds

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.

integer format: int64
teardownUSD

TeardownUSD is the charge from stop until deletion was confirmed, with the billing increment.

string
final

Final is true once the final charge has posted.

boolean
fundedUntilTime

FundedUntilTime is when the current holds stop paying for the object.

string
heldUSD

HeldUSD is what is currently held for it.

string
limitUSD

LimitUSD is the object’s maxCostUSD, if it has one.

string
rateUSDPerHour

RateUSDPerHour is the sum of the hourly rates of its capacity that is still billing.

string
totalUSD

TotalUSD is what has been charged for this object so far.

string
endpoints

Endpoints are the declared ports on the isolated user-content domain. They contain no credentials.

Array<object>
nullable

SandboxEndpoint is a stable application address; it does not assert application readiness.

object
port
required
integer format: int32
public
boolean
url
required
string
estimate

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

AssemblyBoundUSD is the most a multi-node Job can cost if its members never assemble.

string
blockingReasons

BlockingReasons say why a real create would fail now, with the amounts and a fix.

Array<object>
nullable

BlockingReason says why a create would fail now.

object
budgetName

BudgetName identifies the exact Budget that refused this hold, when applicable.

string
code
required

Code is the error code the create would return, for example InsufficientCredits.

string
fix

Fix says what to do.

string
message

Message states the reason with the amounts involved.

string
concurrentHoldUSD

ConcurrentHoldUSD is the total of the holds for every slot that starts at once.

string
costUSD

USDBand is a median and a 90th-percentile amount in USD.

object
p50

P50 is the median amount.

string
p90

P90 is the 90th-percentile amount.

string
gangHoldUSD

GangHoldUSD is the total of the member holds of a multi-node Job.

string
gapFill

JobGapFillEligibility describes a single Job’s serving-gap prerequisites, not placement or measured benefit.

object
eligible
required

Eligible is whether the organization and compiled shape support requesting serving gaps.

boolean
reason
required

Reason is the current prerequisite result; host availability and execution authority are checked later.

string
requested
required

Requested is whether the Job explicitly prefers interruption.

boolean
holdUSD

HoldUSD is the first hold that must fit your balance, every matching Budget and the object’s own cap.

string
minimumChargeUSD

MinimumChargeUSD is the minimum charge quoted by this estimate.

string
overheadUSD

USDBand is a median and a 90th-percentile amount in USD.

object
p50

P50 is the median amount.

string
p90

P90 is the 90th-percentile amount.

string
placementPreview

PlacementPreview is the customer-safe description of the capacity a create would use.

object
explain

Explain is the scheduler’s explanation, the same shape as Attempt status.placement.explain.

interruptible

Interruptible reports whether the capacity can be reclaimed.

boolean
offering

Offering is the offering id, for example h100-sxm-80g-x8-us.

string
regionClass

RegionClass is the region class of the offering.

string
researchCapacity

ResearchCapacityTerms describes the separate agreement required by research capacity.

object
disclosure
required

Disclosure summarizes collection and capacity conditions before acceptance.

string
policy
required

Policy identifies the immutable addendum version.

string
termsDigest
required

TermsDigest is the SHA256 of the linked addendum’s bytes.

string
termsURL
required

TermsURL links the immutable public addendum.

string
warmReuse

WarmReuse reports whether warm capacity would be reused.

boolean
pricebookVersion

PricebookVersion is the price book the estimate used.

string
rateUSDPerHour

RateUSDPerHour is the hourly rate of the chosen capacity.

string
startup

StartupEstimate is the expected time to start.

object
cold

DurationBand is a median and a 90th-percentile duration, as Go duration strings.

object
p50

P50 is the median duration.

string
p90

P90 is the 90th-percentile duration.

string
warm

DurationBand is a median and a 90th-percentile duration, as Go duration strings.

object
p50

P50 is the median duration.

string
p90

P90 is the 90th-percentile duration.

string
topology

Topology is the resolved multi-node topology of a gang Job.

validUntil

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 %.

string
warnings

Warnings are non-blocking notes, for example ColdStart or InterruptibleSelected.

Array<object>
nullable

EstimateWarning is a non-blocking note on an estimate.

object
code
required

Code is the CamelCase warning code.

string
message

Message explains the warning.

string
expirationTime

ExpirationTime is when maxLifetime deletes the Sandbox.

string
handledRequests

HandledRequests records the nodus.dev/start-requested-at value last acted on.

object
key
additional properties
string
image

ImageStatus is the pinned image.

object
digest

Digest is the pinned digest.

string
process

ImageProcess preserves the image config’s exec-form arguments without shell interpolation.

object
cmd

Cmd is the image’s default command or the arguments appended to Entrypoint.

Array<string>
nullable
entrypoint

Entrypoint is the image’s entrypoint, before Cmd.

Array<string>
nullable
reference

Reference is the image as written.

string
user

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.

string
lastActivityTime

LastActivityTime is the last command, file request or terminal input seen; idleTimeout counts from it.

string
message

Message is a human-readable account of Reason.

string
pauseUntil

PauseUntil is the memory-retention deadline. Expiry stops the Sandbox and discards process memory.

string
phase

Phase is Pending, Starting, Running, Pausing, Paused, Resuming, Recovering, Stopping, Stopped, Terminating or Failed.

string
reason

Reason says why the Sandbox Failed, such as StartupFailed or NodeLost.

string
secretVersionIDs

SecretVersionIDs identify the versions resolved when the Sandbox was created.

object
key
additional properties
string
secretVersions

SecretVersions are the versions resolved when the Sandbox was created, which proves its Secrets exist; each start pins the newest version again.

object
key
additional properties
integer format: int32
snapshot

SandboxSnapshot describes the last saved GPU local-directory copy.

object
reason
required

Reason is Stop.

string
time
required

Time is when it was saved.

string
source

SourceStatus is the resolved code.

object
blob

Blob is the uploaded blob.

string
commit

Commit is the resolved git commit.

string
startupResolution

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
defaults
required

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
args
Array<string>
command
Array<string>
continuity

SandboxContinuity sets what survives a stop.

object
mode

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.

string
stateDir

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.

string
env
Array<object>

EnvVar is one environment variable: a literal value or a Secret key.

object
name
required

Name matches ^[A-Za-z_][A-Za-z0-9_]*$.

string
value

Value is the literal value.

string
valueFrom

EnvVarSource names where an env value comes from.

object
secretKeyRef

SecretKeySelector selects one key of a Secret.

object
key
required

Key is the key within it.

string
name
required

Name is the Secret.

string
fuseMount
boolean
image
string
imagePullSecrets
Array<string>
lifecycle

SandboxLifecycleSpec sets when a Sandbox stops or is deleted without being asked.

object
idleTimeout

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.

string
maxLifetime

MaxLifetime deletes the Sandbox this long after it was created, counting stopped time: 1m–720h (default 24h).

string
onIdle

OnIdle is Stop (the default) or Delete.

string
placement

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

Regions are Nodus region classes such as us or ca; empty means any region.

Array<string>
nullable
resources

Resources are capacity floors. For GPU work the offering’s host shape applies if larger.

object
cpu

CPU is the vCPU floor.

string
disk

Disk is the ephemeral disk floor.

string
gpu

GPURequest asks for accelerators. A family (H100) matches any of its variants and never another family.

object
count

Count is the GPUs per node: 1, 2, 4 or 8.

integer format: int32
exact

Exact pins the exact variant instead of matching the family.

boolean
interconnect

Interconnect is Any or NVLink.

string
minMemory

MinMemory is the per-GPU memory floor.

string
type

Type lists 1–8 accelerator ids or families from the catalog.

Array<string>
nullable
memory

Memory is the host memory floor.

string
nodes

Nodes above 1 is shorthand for spec.distributed.nodes and is stored in that form.

integer format: int32
secrets
Array<object>

SecretMount mounts one Secret, optionally pinned to a version. The bare name is accepted on write.

object
name
required

Name is the Secret.

string
version

Version pins a version; unset pins the latest at admission.

integer format: int32
virtualization

SandboxVirtualization selects a parent capability, not a child VM count or a GPU partition.

object
profile
required

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.

string
workingDir
string
layers
Array<object>
nullable

SandboxStartupLayer freezes the identity and revision of one resolved profile and optional binding.

object
bindingResourceVersion
string
bindingUID
string
profile
required
string
resourceVersion
required
string
source
required
string
uid
required
string
version
required
string
stopReason

StopReason says why the Sandbox is stopped; empty while it runs.

string
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"
}
}

An error: a metav1.Status whose reason is a registered code.

Media type application/json

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
apiVersion
string
code
integer format: int32
details
object
causes
Array<object>
nullable
object
field
string
message
string
reason
string
group
string
kind
string
name
string
retryAfterSeconds
integer format: int32
uid
string
docs

Docs is the URL of the code’s docs page.

string
fix

Fix says what to do next, for example a CLI command or the field to change.

string
kind
string
message
string
metadata
object
continue
string
remainingItemCount
integer format: int64
resourceVersion
string
selfLink
string
shardInfo
object
selector
required
string
reason
string
requestId

RequestID identifies the request in logs and support tickets.

string
status
string
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"
}