> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Recover sandbox

> Power-cycle the machine of a sandbox that stopped responding, without touching its disk.



## OpenAPI

````yaml openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/recover
openapi: 3.1.0
info:
  title: Boat Public API v1
  version: 1.0.0
  description: >
    Public JSON API for creating, operating, prompting, observing, and exposing
    sandboxes from backend services, CI jobs, hosted workers, and Boat
    automation products.


    The v1 reference intentionally documents the developer integration surface
    only. Dashboard billing actions are not part of v1.
servers:
  - url: https://boat.dev/api/v1
security:
  - BoatBearerAuth: []
tags:
  - name: Boat
    description: >-
      Unified Boat account, setup, lifecycle, prompting, event history, desktop
      access, and SSH operations.
paths:
  /sandboxes/{sandboxId}/recover:
    post:
      tags:
        - Boat
      summary: Recover a sandbox that stopped responding
      description: >
        Power-cycle the machine of a sandbox that stopped answering. The disk is
        not

        touched. The sandbox usually answers again within 1-2 minutes and then
        saves

        your work by itself; `sandbox.recovered` fires when it does.


        Refused with `409`:

        - `sandbox_is_reachable`: the sandbox answers normally.

        - `too_soon`: a recover started less than 10 minutes ago.

        - `no_machine`: the sandbox has no machine. Resume it instead.

        - `recover_unsupported`: its machine cannot be power-cycled. Wait for it
        to
          answer, or resume it from its last snapshot.
        - `reset_failed`: the power-cycle failed. Reply to the incident email.
      operationId: recover
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      responses:
        '200':
          description: The power-cycle started.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  type:
                    type: string
                    examples:
                      - sandbox.recovering
                  status:
                    type: string
                    enum:
                      - recovering
                  message:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: The sandbox cannot be recovered now. `code` says why (see above).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
              example:
                ok: false
                type: sandbox.error
                status: 409
                code: recover_unsupported
                message: >-
                  This sandbox runs on a machine that cannot be power-cycled.
                  Wait for it to answer again, or resume it from its last
                  snapshot.
                requestId: req_01HX...
                error:
                  code: recover_unsupported
                  message: >-
                    This sandbox runs on a machine that cannot be power-cycled.
                    Wait for it to answer again, or resume it from its last
                    snapshot.
                  status: 409
components:
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      schema:
        type: string
        pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$
      description: Public Sandbox id returned by create/list/get sandbox calls.
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          examples:
            unauthorized:
              value:
                ok: false
                type: sandbox.error
                status: 401
                code: unauthorized
                message: Unauthorized
                error:
                  code: unauthorized
                  message: Unauthorized
                  status: 401
                requestId: req_01HX...
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  schemas:
    ErrorEnvelope:
      type: object
      required:
        - ok
        - type
        - status
        - code
        - message
        - error
        - requestId
      properties:
        ok:
          type: boolean
          examples:
            - false
        type:
          type: string
          examples:
            - sandbox.error
        status:
          type: integer
          examples:
            - 409
        code:
          type: string
          examples:
            - provider_not_configured
        message:
          type: string
          examples:
            - Prompting is locked until Codex is configured on the Agents page.
        requestId:
          type: string
          examples:
            - req_01HX...
        error:
          type: object
          required:
            - code
            - message
            - status
          properties:
            code:
              type: string
            message:
              type: string
            status:
              type: integer
            details:
              type: object
              additionalProperties: true
  securitySchemes:
    BoatBearerAuth:
      type: http
      scheme: bearer
      bearerFormat: sandbox_api_key
      description: >-
        Boat bearer token in the form `boat_...`. Service API keys authenticate
        sandbox operations.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.