NOnodus-compute
Sandboxes

Create a sandbox

Changed on

Creates a durable execution environment after Nodus matches infrastructure and authorizes customer-funded usage. 202 means accepted and can precede readiness. Payment and credits are checked before billable placement.

post/v1/sandboxes

Request

  • Base URL
    / (relative, and the document was published on a file host, not at the API’s origin)
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring required

Stable key for this logical operation. Reuse the same key and body after an uncertain response.

Request body

from_snapshotstring

Optional Nodus snapshot identifier used to restore a compatible sandbox.

imagestring

Container image reference. Nodus resolves tags to an immutable Linux amd64 digest before placement.

namestring

Optional stable customer label used when listing sandboxes.

secretsstring[]

Tenant secret names bound to current versions at boot. The NODUS_ prefix is reserved. Values are available to commands as environment variables and files in NODUS_SECRETS_DIR.

stuck_after_sinteger

Alert after an active command produces no output for this many seconds. Defaults to 1800. Alerts do not stop the command.

wake'auto' | 'instant' | 'fast' | 'cheap'

Startup preference expressed as an outcome. Nodus still chooses the infrastructure.

connectionsstring[]

One live wandb connection name or ID. Admission pins its metadata and credential version. Requires write scope and administrator-enabled live mode.

template'nodus:agent-tools-v1'

Qualified managed environment. Availability is returned by sandbox templates. Omit for name-only reconnect or a custom image.

network_permissionsstring[]
setupstring

Managed template setup command. Customer commands wait for successful setup.

Response

Accepted

idstring required
state'creating' | 'ready' | 'running' | 'idle' | 'suspended' | 'resuming' | 'recovering' | 'terminated' | 'failed' | 'freezing' | 'frozen' required
created_atstring date-time required
updated_atstring date-time required
last_activity_atstring date-time required
terminal_atstring date-time nullable
cost_usdnumber required

Customer cost recorded for this sandbox.

charge_state'estimated' | 'final'

Present for metered sandboxes. A terminal sandbox remains estimated while required cost records are unavailable. Show Finalizing cost until final. Historical contracts omit this field.

final_charge_usdnumber

Immutable aggregate lifetime compute charge once charge_state is final. This amount is independent of current-month readings and excludes ongoing retained-file usage. Retaining files can continue to incur separate usage charges after compute is final. Omitted while the compute cost is finalizing.

urlstring uri required

Console URL for this sandbox.

warningsstring[]

Nonfatal warnings, including bootstrap_failed when the setup command fails.

setup_statestring
setup_failurestring
last_successful_save_atstring date-time

Last verified nonempty saved project. Absence does not imply saved application progress.

started_atstring date-time

First observed tool readiness for the current direct workspace compute session. Absent while starting and on legacy sessions without this timestamp. This is separate from creation time and changes with a replacement session.

Changes

  • ba84c74aeec8Revision changes
    • info

      request property / deprecated

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      response property envelope/outcome/max_cost_usd deprecated

  • 544fef290a54Revision changes
    • warning

      the / request property's exclusiveMinimum was set to 0.00

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      request property / reactivated

    • info

      response property envelope/outcome/max_cost_usd reactivated