> ## 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. # Stop and archive sandbox > Stop active work and archive/snapshot the sandbox for later resume or fork. A stop always saves the sandbox's disk first. If that save is failing, the stop is refused and the sandbox keeps running so your work is not discarded, we retry automatically and email you. You are not billed for time spent in that state. Set `force: true` to stop anyway, accepting the loss of everything written since the last successful snapshot. This is irreversible; only reach for it after a stop has already failed. ## OpenAPI ````yaml openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/stop 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}/stop: post: tags: - Boat summary: Stop and archive sandbox description: > Stop active work and archive/snapshot the sandbox for later resume or fork. A stop always saves the sandbox's disk first. If that save is failing, the stop is refused and the sandbox keeps running so your work is not discarded, we retry automatically and email you. You are not billed for time spent in that state. Set `force: true` to stop anyway, accepting the loss of everything written since the last successful snapshot. This is irreversible; only reach for it after a stop has already failed. operationId: stop parameters: - $ref: '#/components/parameters/SandboxId' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/StopRequest' responses: '202': description: Boat archival started or already in progress. content: application/json: schema: $ref: '#/components/schemas/SandboxActionResponse' examples: archiving: value: ok: true type: sandbox.stopping id: bx_23456789 status: archiving sandbox: id: bx_23456789 name: Sandbox 2026-05-31 12:00 state: archiving desktopAvailable: true snapshotAvailable: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' 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. schemas: StopRequest: type: object description: Options for stopping a sandbox. properties: force: type: boolean default: false description: >- Stop the sandbox even if its disk cannot be snapshotted. Everything written since the last successful snapshot is permanently LOST. Without this, a sandbox whose snapshot pipeline is failing is left running rather than discarding your work, and you are not billed for that time. Only use this after a stop has already been refused. SandboxActionResponse: allOf: - $ref: '#/components/schemas/SuccessBase' - type: object required: - id - status properties: type: type: string examples: - sandbox.stopping id: type: string status: type: string examples: - archiving sandbox: oneOf: - $ref: '#/components/schemas/Sandbox' - type: 'null' SuccessBase: type: object required: - ok - type properties: ok: type: boolean examples: - true type: type: string description: Stable success envelope discriminator added by v1. Sandbox: type: object required: - id - name - state - desktopAvailable - snapshotAvailable properties: id: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ examples: - bx_23456789 name: type: string examples: - Boat 2026-05-31 12:00 state: type: string enum: - init - provisioning - provisioned - cloning - ready - idle - running - archiving - archived - error type: type: string enum: - small - default - large - xlarge description: >- Current machine size: what the sandbox was created with, or the size it was last resumed or forked onto. Legacy bare-metal sandboxes read as `default`. vcpu: type: integer description: vCPUs guaranteed by this sandbox's type. examples: - 4 memoryGB: type: integer description: RAM in GB guaranteed by this sandbox's type. examples: - 8 billingMultiplier: type: number description: >- Rate at which this sandbox consumes machine time. 0.5 for `small`, 1 for `default`, 2 for `large`, and 50/9 for `xlarge`. examples: - 1 url: type: - string - 'null' format: uri description: Machine URL when assigned. ip: type: - string - 'null' description: Machine IPv6 or IPv4 address when assigned. createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time archiveAfter: type: - string - 'null' format: date-time description: Automatic archival time, or null when auto-stop is disabled. desktopAvailable: type: boolean desktopUrl: type: - string - 'null' format: uri description: Secret-bearing desktop stream URL when available. Redact from logs. snapshotAvailable: type: boolean snapshotCompletedAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent successfully completed snapshot, or null. subdomain: type: - string - 'null' description: >- The sandbox's stable three-word subdomain slug (e.g. "frazil-pneuma-rallye"), or null before one is assigned. lastSnapshotAttemptAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent snapshot attempt of any status (queued, in_progress, completed, failed, cancelled), or null. Use with snapshotCompletedAt to detect snapshots that keep failing. lastSnapshotStatus: type: - string - 'null' enum: - queued - in_progress - completed - failed - cancelled - null description: >- Status of the most recent snapshot attempt, or null if none. A value other than completed while snapshotCompletedAt stays stale indicates failing snapshots. setupStatus: type: - string - 'null' enum: - pending - running - done - failed - null description: >- Outcome of the create-time `setupScript`: `pending` (stored, not yet started), `running` (executing on the sandbox in the background), `done` (exit code 0) or `failed` (non-zero exit, or the sandbox lost track of the process). Null when the sandbox was created without a setup script. setupError: type: - string - 'null' description: >- Short failure detail (exit code plus a stderr tail) when `setupStatus` is `failed`; while `pending`, may carry the last start/upload error from a retry in progress. Otherwise null. environment: type: - string - 'null' description: >- Name of the sandbox environment this sandbox is running, or null if it is attached to none (a `noEnv` sandbox, or one whose environment was deleted). A sandbox freezes onto one environment version when it starts and keeps it for life, so this is what the sandbox actually holds, not what the environment says today. examples: - base environmentVersion: type: - integer - 'null' description: >- Version number of `environment` that this sandbox is pinned to. Compare it against the environment's latest version to see whether an upgrade is pending: a sandbox below the latest is still running the older configuration until someone calls `POST /environments/{environmentId}/upgrade`. examples: - 3 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 responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid: value: ok: false type: sandbox.error status: 400 code: invalid_json message: Request body must be valid JSON. error: code: invalid_json message: Request body must be valid JSON. status: 400 requestId: req_01HX... 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' securitySchemes: BoatBearerAuth: type: http scheme: bearer bearerFormat: sandbox_api_key description: >- Boat bearer token in the form `boat_...`. Service API keys authenticate sandbox operations. ````