---
title: "Wake a sandbox"
method: POST
path: "/v1/sandboxes/{id}/wake"
tags: ["Sandboxes"]
---

# Wake a sandbox

`POST /v1/sandboxes/{id}/wake`

## Request

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

Saved project deletion is separate from compute termination. Sleep refuses active commands and retains original limits.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- object

## Response `202`

Success

- 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`: Operation refused with a diagnostic and next action

## Changes

- **2026-10-01** `ba84c74aeec8`: 3 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
  - response property `envelope/outcome/max_cost_usd` deprecated
- **2026-10-01** `544fef290a54`: 2 warning, 1 info
  - 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
  - response property `envelope/outcome/max_cost_usd` reactivated
- **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`: 1 info
  - response property `envelope/outcome/max_cost_usd` deprecated
- **2026-09-27** `90c4cb8514af`: 1 info
  - response property `envelope/outcome/max_cost_usd` reactivated

[Operation history](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/changes/v1/sandboxes/:id/wake/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)