---
title: "Create a sandbox"
method: POST
path: "/v1/sandboxes"
tags: ["Sandboxes"]
---

# Create a sandbox

`POST /v1/sandboxes`

## Request

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

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.

## Headers

- `Idempotency-Key` string, required

## Request body

- SandboxCreateRequest: Creates a sandbox, or reconnects to an active name within the authenticated account. New sandboxes require an image. Omitted fields on a reconnect preserve existing configuration.
  - `bootstrap` SandboxBootstrap: Preview repository bootstrap. Requires github.com in the egress allowlist. Checkout is placed in /workspace. The installation credential is never supplied to customer processes.
    - `repo` string, required: Connected GitHub repository as owner/name. Credentials and URLs are not accepted.
    - `ref` string: Optional branch name or refs/tags/name. Defaults to the repository default branch.
    - `setup` string: Shell setup command recorded as a sandbox execution. A managed template requires successful setup before customer commands. Legacy images retain their existing warning behavior.
    - `dotfiles` string: Optional connected GitHub dotfiles repository as owner/name. Its install.sh runs before setup.
  - `continuity` SandboxContinuity
    - `mode` 'snapshotted' | 'ephemeral': Whether Nodus periodically saves filesystem recovery state.
    - `interval_s` integer: Snapshot interval in seconds. Omit for ephemeral sandboxes.
  - `from_snapshot` string: Optional Nodus snapshot identifier used to restore a compatible sandbox.
  - `image` string: Container image reference. Nodus resolves tags to an immutable Linux amd64 digest before placement.
  - `lifecycle` SandboxLifecycle
    - `idle_timeout_s` integer: Idle seconds before the configured action.
    - `max_lifetime_s` integer: Maximum sandbox lifetime in seconds.
    - `on_idle` 'suspend' | 'terminate': Action after the idle timeout.
  - `name` string: Optional stable customer label used when listing sandboxes.
  - `outcome` SandboxOutcome
    - `max_cost_usd` number: Deprecated compatibility field. Customer spending limits are not enforced.
    - `complete_by` string, date-time: Optional RFC3339 deadline for the sandbox.
  - `policy` SandboxPolicy
    - `data_regions` string[]: Allowed placement regions. Empty or omitted imposes no region filter.
    - `network` 'deny' | 'allowlist': Outbound network policy.
    - `egress_allow` string[]: Exact DNS hostnames allowed when network is allowlist.
    - `secret_refs` string[]: Secret names or sec_ IDs pinned at admission and delivered as NODUS_SECRET_<NAME>. Rotation, revocation and recovery preserve the admitted version.
  - `requirements` SandboxRequirements
    - `compute_class` 'vm' | 'accelerator': Infrastructure class. Omission selects vm (CPU) for a new sandbox and preserves the stored class when reconnecting by name. CPU sandboxes require a preview deployment with compatible capacity. Existing GPU sandbox clients explicitly request accelerator.
    - `gpu` string: Optional required GPU model family. Nodus matches compatible infrastructure without exposing supplier SKUs.
    - `vcpus` number: Required virtual CPUs. Zero or omission uses the server default.
    - `peak_memory_gb` number: Required memory in GB. Zero or omission uses the server default.
    - `disk_gb` number: Required disk capacity in GB. Zero or omission uses the server default.
    - `dataset_bytes` integer: Optional input data size used for infrastructure matching.
    - `model` string: Optional workload fit signal.
    - `notes` string: Optional workload fit notes.
  - `reservation` SandboxReservation
    - `wake_slo_ms` integer: Requested wake service level in milliseconds.
    - `max_idle_s` integer: Maximum idle duration retained by the reservation.
    - `min_ready` integer: Minimum ready capacity.
    - `max_concurrent` integer: Maximum concurrent sandboxes for this reservation.
    - `release` 'auto' | 'hold': Whether idle capacity is automatically released.
    - `cron` string: Optional five-field cron expression for planned readiness.
  - `secrets` string[]: 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.
  - `service` SandboxService
    - `command` string[], required
    - `port` integer, required: Guest loopback HTTP port. Port 18080 is reserved.
    - `health_path` string, required: Absolute HTTP health path. Successful 2xx health response is required before serving requests.
  - `stuck_after_s` integer: 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.
  - `workspace` WorkspaceSelection
    - `name` string, required
    - `mount` string: Dedicated top-level directory. System directories cannot be used.
  - `source` object
    - `image` string, required
    - `asset_id` string
    - `cache` boolean: Opt in to verified image layer caching within this team and selected execution region. Retained storage stays attributed to the first materializing sandbox at the configured workspace storage rate. Cache misses use the image registry.
  - `connections` string[]: 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_permissions` string[]
  - `setup` string: Managed template setup command. Customer commands wait for successful setup.

## Response `202`

Accepted

- Sandbox
  - `id` string, required
  - `state` 'creating' | 'ready' | 'running' | 'idle' | 'suspended' | 'resuming' | 'recovering' | 'terminated' | 'failed' | 'freezing' | 'frozen', required
  - `envelope` SandboxEnvelope, required
    - `bootstrap` SandboxBootstrap: Preview repository bootstrap. Requires github.com in the egress allowlist. Checkout is placed in /workspace. The installation credential is never supplied to customer processes.
      - `repo` string, required: Connected GitHub repository as owner/name. Credentials and URLs are not accepted.
      - `ref` string: Optional branch name or refs/tags/name. Defaults to the repository default branch.
      - `setup` string: Shell setup command recorded as a sandbox execution. A managed template requires successful setup before customer commands. Legacy images retain their existing warning behavior.
      - `dotfiles` string: Optional connected GitHub dotfiles repository as owner/name. Its install.sh runs before setup.
    - `continuity` object, required
    - `from_snapshot` string
    - `lifecycle` SandboxLifecycle, required
      - `idle_timeout_s` integer: Idle seconds before the configured action.
      - `max_lifetime_s` integer: Maximum sandbox lifetime in seconds.
      - `on_idle` 'suspend' | 'terminate': Action after the idle timeout.
    - `name` string
    - `outcome` SandboxOutcome, required
      - `max_cost_usd` number: Deprecated compatibility field. Customer spending limits are not enforced.
      - `complete_by` string, date-time: Optional RFC3339 deadline for the sandbox.
    - `policy` SandboxPolicy, required
      - `data_regions` string[]: Allowed placement regions. Empty or omitted imposes no region filter.
      - `network` 'deny' | 'allowlist': Outbound network policy.
      - `egress_allow` string[]: Exact DNS hostnames allowed when network is allowlist.
      - `secret_refs` string[]: Secret names or sec_ IDs pinned at admission and delivered as NODUS_SECRET_<NAME>. Rotation, revocation and recovery preserve the admitted version.
    - `profile` string: Historical profile retained on previously admitted sandboxes. New sandbox requests cannot select a profile.
    - `requirements` object, required
    - `reservation` object, required
    - `secrets` string[]: 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.
    - `service` SandboxService
      - `command` string[], required
      - `port` integer, required: Guest loopback HTTP port. Port 18080 is reserved.
      - `health_path` string, required: Absolute HTTP health path. Successful 2xx health response is required before serving requests.
    - `source` object, required
      - `image` string, required
      - `asset_id` string
      - `cache` boolean: Opt in to verified image layer caching within this team and selected execution region. Retained storage stays attributed to the first materializing sandbox at the configured workspace storage rate. Cache misses use the image registry.
    - `stuck_after_s` integer: Alert after an active command produces no output for this many seconds. Defaults to 1800. Alerts do not stop the command.
    - `workspace` WorkspaceSelection
      - `name` string, required
      - `mount` string: Dedicated top-level directory. System directories cannot be used.
    - `connections` string[]: One live wandb connection name or ID. Admission pins its metadata and credential version. Requires write scope and administrator-enabled live mode.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `last_activity_at` string, date-time, required
  - `terminal_at` string, date-time, nullable
  - `cost_usd` number, 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_usd` number: 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.
  - `network_usage` object: Last reported cumulative proxied HTTP and TLS stream bytes across sandbox generations. A lost host can leave its final unreported bytes unknown. These counters do not determine customer charges.
    - `sent_bytes` integer, required
    - `received_bytes` integer, required
  - `url` string, uri, required: Console URL for this sandbox.
  - `failure` object: Recorded cause and recovery guidance for a failed sandbox. Omitted for other states.
    - `code` string, required
    - `message` string, required
    - `fix` string, required
  - `warnings` string[]: Nonfatal warnings, including bootstrap_failed when the setup command fails.
  - `setup_state` string
  - `setup_failure` string
  - `last_successful_save_at` string, date-time: Last verified nonempty saved project. Absence does not imply saved application progress.
  - `startup` SandboxStartup: Measured startup stages. Missing durations are unobserved. Overlapping durations must not be added into elapsed latency.
    - `stage` string
    - `acquisition_ms` integer
    - `image_preparation_ms` integer
    - `project_download_ms` integer
    - `project_materialization_ms` integer
    - `checkpoint_download_ms` integer
    - `checkpoint_restore_ms` integer
    - `setup_ms` integer
    - `driver_start_ms` integer
    - `image_cache_reads` integer
    - `image_cache_hits` integer
    - `project_prefetched` boolean
    - `checkpoint_prefetched` boolean
    - `warm_claimed` boolean
    - `warm_miss_reason` string
  - `started_at` string, 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.

## Other responses

- `default`: Error. The code, message, and fix fields describe the rejection and its remedy.

## Changes

- **2026-10-01** `ba84c74aeec8`: 4 info
  - request property `outcome/max_cost_usd` deprecated
  - added the optional property `charge_state` to the response with the `202` status
  - added the optional property `final_charge_usd` to the response with the `202` status
  - response property `envelope/outcome/max_cost_usd` deprecated
- **2026-10-01** `544fef290a54`: 3 warning, 2 info
  - the `outcome/max_cost_usd` request property's exclusiveMinimum was set to `0.00`
  - removed the optional property `charge_state` from the response with the `202` status
  - removed the optional property `final_charge_usd` from the response with the `202` status
  - request property `outcome/max_cost_usd` reactivated
  - …1 more
- **2026-09-27** `f73dea7ab0c4`: 2 info
  - added the optional property `charge_state` to the response with the `202` status
  - added the optional property `final_charge_usd` to the response with the `202` status
- **2026-09-27** `dcc58d93c2cb`: 2 info
  - request property `outcome/max_cost_usd` deprecated
  - response property `envelope/outcome/max_cost_usd` deprecated
- **2026-09-27** `90c4cb8514af`: 1 warning, 2 info
  - the `outcome/max_cost_usd` request property's exclusiveMinimum was set to `0.00`
  - request property `outcome/max_cost_usd` reactivated
  - response property `envelope/outcome/max_cost_usd` reactivated

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/sandboxes/post.md)

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)