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

# Delete a sandbox

> Moves the sandbox to `deleting`, then to `deleted`, and removes its data. A second delete while the sandbox is `deleting` returns the same sandbox. Needs the `sandboxes:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json delete /v1/sandboxes/{id}
openapi: 3.1.0
info:
  title: VMS API
  version: 1.0.0
  description: >-
    The public API of a VMS workspace. Each request needs an API key of the
    workspace in the Authorization header.
servers:
  - url: https://vms.dev/api
    description: The VMS API
security:
  - apiKey: []
paths:
  /v1/sandboxes/{id}:
    delete:
      tags:
        - Sandboxes
      summary: Delete a sandbox
      description: >-
        Moves the sandbox to `deleting`, then to `deleted`, and removes its
        data. A second delete while the sandbox is `deleting` returns the same
        sandbox. Needs the `sandboxes:write` scope.
      operationId: deleteSandbox
      parameters:
        - in: path
          name: id
          schema:
            type: string
            example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
          required: true
      responses:
        '202':
          description: The sandbox, with its delete operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '400':
          description: The request is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The API key is missing, not correct, revoked, or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The API key does not have the scope of the endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: The workspace has no sandbox with this ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: The API key sent more than 1,200 requests in one minute.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Sandbox:
      type: object
      properties:
        id:
          type: string
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
        name:
          type:
            - string
            - 'null'
        state:
          $ref: '#/components/schemas/SandboxState'
        size:
          $ref: '#/components/schemas/SandboxSize'
        health:
          anyOf:
            - $ref: '#/components/schemas/SandboxHealth'
            - type: 'null'
          description: Null when the sandbox is not running.
        errorReason:
          anyOf:
            - $ref: '#/components/schemas/SandboxErrorReason'
            - type: 'null'
          description: Why the sandbox is in the error state.
        labels:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            type: string
        ipv6:
          example: 2604:2dc0:100:32d5::1a
          type:
            - string
            - 'null'
        urls:
          type: array
          items:
            $ref: '#/components/schemas/SandboxUrl'
        sshHostKey:
          description: The public SSH host key of the sandbox.
          type:
            - string
            - 'null'
        sshUser:
          type: string
          description: >-
            The user name for ssh.vms.dev: the name and the workspace code, or
            the sandbox ID when the sandbox has no name.
          example: agent-42-k3m7q2v9
        stopAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the sandbox stops on its own. Null when auto-stop is off or the
            sandbox does not run.
        stopAfterSeconds:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
              maximum: 9007199254740991
            - type: 'null'
          description: >-
            The seconds that the sandbox runs after each start before it stops
            on its own. Null when auto-stop is off.
          example: 3600
        dataExpiresAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the saved files are deleted: 30 days after a stop, or at a
            delete. Null while the sandbox runs.
        latestSnapshotAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        snapshotVerifiedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
        lastSnapshotLagSeconds:
          anyOf:
            - type: integer
              minimum: 0
              maximum: 9007199254740991
            - type: 'null'
        snapshotProgress:
          anyOf:
            - type: number
              minimum: 0
              maximum: 1
            - type: 'null'
          description: The part of the current snapshot that is done, 0 to 1.
        hydrated:
          type: boolean
          description: >-
            true when each saved file is on the local disk. After a resume from
            saved files, the sandbox is running before this is true: a file that
            is not local yet downloads when a program opens it.
        hydratedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
          description: >-
            When the last restore put each saved file on the local disk. Null
            when the sandbox did not restore saved files.
        hydration:
          $ref: '#/components/schemas/SandboxHydration'
        lastReboot:
          anyOf:
            - $ref: '#/components/schemas/SandboxLastReboot'
            - type: 'null'
        operation:
          anyOf:
            - $ref: '#/components/schemas/Operation'
            - type: 'null'
          description: The latest operation on the sandbox.
        costMicros:
          description: >-
            The cost of the sandbox in the current month (UTC), in
            micro-dollars: 1,000,000 is $1. Only in a list with include=cost.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        forkedFrom:
          description: >-
            The ID of the sandbox that this sandbox is a fork of. Null when it
            is not a fork.
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
          type:
            - string
            - 'null'
        imageVersion:
          description: >-
            The version of the base image of the sandbox. Null before the first
            start.
          example: ubuntu-26.04-20261116130819
          type:
            - string
            - 'null'
        pinImage:
          type: boolean
          description: >-
            true when a resume keeps the current base image. false when a resume
            after the 10-minute hold moves the sandbox to the latest base image.
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - id
        - name
        - state
        - size
        - health
        - errorReason
        - labels
        - ipv6
        - urls
        - sshHostKey
        - sshUser
        - stopAt
        - stopAfterSeconds
        - dataExpiresAt
        - latestSnapshotAt
        - snapshotVerifiedAt
        - lastSnapshotLagSeconds
        - snapshotProgress
        - hydrated
        - hydratedAt
        - hydration
        - lastReboot
        - operation
        - forkedFrom
        - imageVersion
        - pinImage
        - createdAt
        - updatedAt
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: no_capacity
            message:
              type: string
            requestId:
              type:
                - string
                - 'null'
            retryAfterSeconds:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            sandboxId:
              description: The sandbox that the error is about.
              type: string
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
    SandboxState:
      type: string
      enum:
        - creating
        - starting
        - running
        - stopping
        - stopped
        - error
        - deleting
        - deleted
        - failed
    SandboxSize:
      type: string
      enum:
        - small
        - medium
        - large
        - xlarge
      description: The vCPU, RAM, and disk of a sandbox.
    SandboxHealth:
      type: string
      enum:
        - ok
        - degraded
        - unreachable
    SandboxErrorReason:
      type: string
      enum:
        - host_lost
        - boot_failed
        - restore_failed
    SandboxUrl:
      type: object
      properties:
        id:
          type: string
          example: url_06d8k3m7q2v9x4b1n5c0e8f2jb
        sandboxId:
          type: string
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
        port:
          type: integer
          minimum: 1
          maximum: 65535
          example: 3000
        url:
          type: string
          format: uri
          description: >-
            The HTTPS address of the port. It contains the sandbox name, so it
            changes when you rename the sandbox.
          example: https://agent-42-3000-k3m7q2v9.vmsdev.run
        public:
          type: boolean
          description: True if the URL works without the token.
        token:
          description: >-
            Open the URL one time with ?_token=<token>. The browser then keeps a
            cookie for the URL. It is null for an API key without
            sandboxes:write.
          example: vmsu_Gq3n0Yb1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - id
        - sandboxId
        - port
        - url
        - public
        - token
        - createdAt
        - updatedAt
      additionalProperties: false
    SandboxHydration:
      type: object
      properties:
        phase:
          $ref: '#/components/schemas/HydrationPhase'
        filesDone:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: The files of the home folders that are on the local disk.
        filesTotal:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: The files of the home folders that the restore puts back.
        errorCode:
          anyOf:
            - type: string
              enum:
                - hydration_failed
            - type: 'null'
          description: >-
            hydration_failed when the phase is failed: the download stopped for
            good. Null in each other phase.
      required:
        - phase
        - filesDone
        - filesTotal
        - errorCode
      additionalProperties: false
      description: The progress of the last restore of saved files.
    SandboxLastReboot:
      type: object
      properties:
        reason:
          $ref: '#/components/schemas/RebootReason'
        at:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
      required:
        - reason
        - at
      additionalProperties: false
    Operation:
      type: object
      properties:
        id:
          type: string
          example: op_06d8k3m7q2v9x4b1n5c0e8f2ja
        sandboxId:
          type: string
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
        kind:
          $ref: '#/components/schemas/OperationKind'
        status:
          $ref: '#/components/schemas/OperationStatus'
        error:
          anyOf:
            - $ref: '#/components/schemas/OperationError'
            - type: 'null'
        createdAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        updatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        completedAt:
          anyOf:
            - type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            - type: 'null'
      required:
        - id
        - sandboxId
        - kind
        - status
        - error
        - createdAt
        - updatedAt
        - completedAt
      additionalProperties: false
    HydrationPhase:
      type: string
      enum:
        - folding
        - system
        - docker
        - hydrating
        - hydrated
        - failed
      description: >-
        The step of the restore: folding reads the saved snapshots, system puts
        back the system files, docker puts back the Docker files and starts the
        services, hydrating downloads the files of the home folders, hydrated
        means that each saved file is on the local disk, and failed means that
        the download stopped for good after its tries.
    RebootReason:
      type: string
      enum:
        - crash
        - guest
    OperationKind:
      type: string
      enum:
        - create
        - stop
        - resume
        - delete
        - recover
    OperationStatus:
      type: string
      enum:
        - pending
        - running
        - failing
        - succeeded
        - failed
    OperationError:
      type: object
      properties:
        code:
          type: string
          example: no_capacity
        message:
          type: string
      required:
        - code
        - message
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: An API key that starts with vms_. Make one in Settings > API keys.

````

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