> ## 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.

# Create a sandbox

> Creates a sandbox of the size that you send. Send `template` to start the sandbox with the files of a template: its ID, its name, or a share code from another workspace. The sandbox takes a warm slot, or waits a few seconds for a new slot when a host has room, and moves through `creating` and `starting` to `running`. Read the sandbox or its operation to see when it is `running`. If no host has room, the API answers `503` with the code `no_capacity` at once. Send `fromSandbox` to fork a running or stopped sandbox: the fork gets the files and the environment variables of the source, and its own name, hostname, SSH host keys, IPv6 address, and agent key. It does not get the auto-stop time or the URLs of the source. Send `count` to make more than one fork. Needs the `sandboxes:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sandboxes
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:
    post:
      tags:
        - Sandboxes
      summary: Create a sandbox
      description: >-
        Creates a sandbox of the size that you send. Send `template` to start
        the sandbox with the files of a template: its ID, its name, or a share
        code from another workspace. The sandbox takes a warm slot, or waits a
        few seconds for a new slot when a host has room, and moves through
        `creating` and `starting` to `running`. Read the sandbox or its
        operation to see when it is `running`. If no host has room, the API
        answers `503` with the code `no_capacity` at once. Send `fromSandbox` to
        fork a running or stopped sandbox: the fork gets the files and the
        environment variables of the source, and its own name, hostname, SSH
        host keys, IPv6 address, and agent key. It does not get the auto-stop
        time or the URLs of the source. Send `count` to make more than one fork.
        Needs the `sandboxes:write` scope.
      operationId: createSandbox
      parameters:
        - in: header
          name: idempotency-key
          schema:
            description: >-
              A unique value for each new sandbox, such as a UUID. A second
              request with the same key within 24 hours returns the first
              result.
            type: string
            minLength: 1
            maxLength: 255
          description: >-
            A unique value for each new sandbox, such as a UUID. A second
            request with the same key within 24 hours returns the first result.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxBody'
      responses:
        '202':
          description: >-
            The new sandbox, with its create operation. With `count`, the first
            fork, and each fork in `batch`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedSandbox'
        '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 template with this ID or name, the share code
            does not exist or was revoked, or the workspace has no sandbox with
            the ID in `fromSandbox`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Another sandbox in the workspace has this name
            (`sandbox_name_taken`, with the ID of that sandbox in `sandboxId`).
            Or the template is not ready. Or you sent the Idempotency-Key with a
            different request, or a request with this key is in progress. Or the
            source of a fork is starting (`sandbox_starting`), stopping
            (`sandbox_stopping`), not running or stopped, or has no saved files
            (`snapshot_expired`).
          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'
        '503':
          description: >-
            No host has room for the size (`no_capacity`). The body has
            `retryAfterSeconds` and the ID of the failed sandbox. A fork that
            does not fit makes no sandbox, so its body has no sandbox ID. The
            `Retry-After` header has the same value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    CreateSandboxBody:
      type: object
      properties:
        size:
          $ref: '#/components/schemas/SandboxSize'
          description: >-
            The size of the sandbox. Send it for each new sandbox. A fork
            without size has the size of its source.
        fromSandbox:
          description: >-
            The ID of a running or stopped sandbox to fork. The fork gets the
            files and the environment variables of this sandbox, and a new name,
            hostname, SSH host keys, IPv6 address, and agent key.
          example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
          type: string
          minLength: 1
        freshSnapshot:
          description: >-
            Send it only with fromSandbox. When the source runs, true (the
            default) takes a new snapshot of the source first, so that the fork
            has the latest files. false starts the fork from the last snapshot
            of the source. A stopped source has no new files, so this field has
            no effect on it.
          type: boolean
        count:
          description: >-
            Send it only with fromSandbox: the number of forks to make, 1 to
            100. The answer is the first fork, with each fork in batch. If one
            fork cannot start, the API makes no fork. Do not send name with a
            count of more than 1.
          example: 10
          type: integer
          minimum: 1
          maximum: 100
        name:
          type: string
          pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$
          description: >-
            A name that is unique in the workspace: 1 to 63 lowercase letters,
            digits, and hyphens. It cannot start or end with a hyphen.
          example: agent-42
        labels:
          type: object
          propertyNames:
            type: string
            pattern: ^[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,61}[A-Za-z0-9])?$
          additionalProperties:
            type: string
            maxLength: 255
          description: >-
            Up to 50 labels. A key has 1 to 63 letters, digits, and the
            characters . _ / -, and starts and ends with a letter or a digit. A
            value has up to 255 characters.
          example:
            project: web
            agent: reviewer
        env:
          $ref: '#/components/schemas/SandboxEnvironment'
        files:
          maxItems: 20
          type: array
          items:
            $ref: '#/components/schemas/SandboxFile'
          description: >-
            Files to write when the sandbox starts the first time: up to 20,
            with up to 65536 characters of content in total. The owner of a file
            in /home/user is user.
        template:
          description: >-
            The ID or the name of a ready template, or a share code of a
            template of another workspace. The sandbox starts with the files of
            the template.
          example: node-22-base
          type: string
          minLength: 1
        stopAfterSeconds:
          anyOf:
            - type: integer
              minimum: 60
              maximum: 2592000
            - type: 'null'
          description: >-
            The seconds that the sandbox runs after each start before it stops
            on its own: 60 to 2592000 (30 days). The default is 3600 (1 hour).
            Send null to turn off auto-stop. Do not send it with stopAt.
          example: 3600
        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: >-
            The time when the sandbox stops on its own. It must be in the
            future. Send null to turn off auto-stop. Do not send it with
            stopAfterSeconds.
          example: '2026-11-16T12:00:00Z'
        failFast:
          description: >-
            Answer within 1.5 seconds. If the API cannot answer in time, it
            answers 503 no_capacity.
          type: boolean
    CreatedSandbox:
      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))$
        batch:
          description: >-
            Each sandbox of the request, in creation order: the first is this
            sandbox. Only in the answer of a create with count.
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
      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
    SandboxSize:
      type: string
      enum:
        - small
        - medium
        - large
        - xlarge
      description: The vCPU, RAM, and disk of a sandbox.
    SandboxEnvironment:
      type: object
      propertyNames:
        type: string
        pattern: ^[A-Za-z_][A-Za-z0-9_]{0,127}$
      additionalProperties:
        type: string
        maxLength: 4096
      description: >-
        Environment variables for each command, shell, and SSH session of the
        sandbox: up to 100. A name has letters, digits, and _, and does not
        start with a digit. A value has up to 4096 characters. The API does not
        show the values again.
      example:
        NODE_ENV: production
    SandboxFile:
      type: object
      properties:
        path:
          type: string
          minLength: 1
          maxLength: 4096
          pattern: ^\/
          description: The absolute path of the file in the sandbox.
          example: /home/user/.npmrc
        content:
          type: string
        encoding:
          description: The encoding of content. The default is utf8.
          type: string
          enum:
            - utf8
            - base64
        mode:
          description: An octal mode, such as 0644.
          example: '0644'
          type: string
          pattern: ^0[0-7]{3,4}$
      required:
        - path
        - content
    SandboxState:
      type: string
      enum:
        - creating
        - starting
        - running
        - stopping
        - stopped
        - error
        - deleting
        - deleted
        - failed
    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
    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
    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.