Skip to main content
POST
/
sandboxes
/
{sandbox_id}
/
restore
Restore Sandbox
curl --request POST \
  --url https://api.declaw.ai/sandboxes/{sandbox_id}/restore \
  --header 'X-API-Key: <api-key>'
Performs a cross-worker sandbox restore. Resolves the snapshot to restore from (either an explicitly named snapshot_id or the best available), picks an eligible orchestrator node — always excluding the originating node — forwards the restore to that orchestrator, and updates sandbox-manager state with the new node assignment. Unlike resume, restore works on sandboxes in any state as long as at least one snapshot exists, and always lands the sandbox on a fresh worker.

​
Path Parameters

​
sandbox_id
string
required
The sandbox identifier. Format: sbx-<8 chars>.

​
Query Parameters

​
snapshot_id
string
Optional specific snapshot to restore from. If omitted, the best available snapshot is selected (preference: pause → periodic → manual).

​
Response

Returns the orchestrator’s restore response (passed through), including the new guest_ip and envd_port for the restored VM.

​
Example

curl -X POST "https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/restore?snapshot_id=snap-xyz" \
  -H "X-API-Key: YOUR_API_KEY"

​
Error Responses

StatusCause
401Missing or invalid API key
404Sandbox not found, or no snapshot available
502Orchestrator unreachable or restore failed
503No eligible orchestrator node available