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

# Update a sandbox

> Changes the name, the labels, or the state of a sandbox. The request changes only the fields that you send. The labels that you send replace all labels of the sandbox. Send `name: null` to remove the name.

Send `state: stopped` to stop a running sandbox. The sandbox moves to `stopping`: the API runs `~/.vms/pre-stop` (at most 60 seconds), takes a last snapshot, and pauses the sandbox. Then the sandbox is `stopped`, and billing stops. For 10 minutes, the host keeps the memory of the sandbox. A stop while a stop is pending returns the pending operation. If the last snapshot fails 3 times, the operation is `failing`, the sandbox runs again and is not billed, and the stop tries again each 5 minutes. After 3 days, the stop uses the last good snapshot and sends an email to the owners and admins.

Send `state: running` within 10 minutes of a stop to resume the sandbox with its memory and its processes. A resume is a start, so the start limits of the plan apply. A resume while a stop is `failing` cancels the stop.

With `state`, the API answers `202` with the operation of the stop or the resume. Needs the `sandboxes:write` scope.



## OpenAPI

````yaml /api-reference/openapi.json patch /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}:
    patch:
      tags:
        - Sandboxes
      summary: Update a sandbox
      description: >-
        Changes the name, the labels, or the state of a sandbox. The request
        changes only the fields that you send. The labels that you send replace
        all labels of the sandbox. Send `name: null` to remove the name.


        Send `state: stopped` to stop a running sandbox. The sandbox moves to
        `stopping`: the API runs `~/.vms/pre-stop` (at most 60 seconds), takes a
        last snapshot, and pauses the sandbox. Then the sandbox is `stopped`,
        and billing stops. For 10 minutes, the host keeps the memory of the
        sandbox. A stop while a stop is pending returns the pending operation.
        If the last snapshot fails 3 times, the operation is `failing`, the
        sandbox runs again and is not billed, and the stop tries again each 5
        minutes. After 3 days, the stop uses the last good snapshot and sends an
        email to the owners and admins.


        Send `state: running` within 10 minutes of a stop to resume the sandbox
        with its memory and its processes. A resume is a start, so the start
        limits of the plan apply. A resume while a stop is `failing` cancels the
        stop.


        With `state`, the API answers `202` with the operation of the stop or
        the resume. Needs the `sandboxes:write` scope.
      operationId: updateSandbox
      parameters:
        - in: path
          name: id
          schema:
            type: string
            example: sbx_06d8k3m7q2v9x4b1n5c0e8f2ja
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSandboxBody'
      responses:
        '200':
          description: The changed sandbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
        '202':
          description: >-
            The sandbox, with the operation of the stop or the resume in
            `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'
        '402':
          description: >-
            A resume needs a plan (`billing_required`). See the limits of your
            plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            The API key does not have the scope, or the plan does not include
            the size of the sandbox (`size_not_allowed`).
          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'
        '409':
          description: >-
            Another sandbox in the workspace has this name
            (`sandbox_name_taken`). Or a stop of a starting sandbox
            (`sandbox_starting`), a resume of a stopping sandbox
            (`sandbox_stopping`), a resume more than 10 minutes after the stop,
            a resume after `dataExpiresAt` (`snapshot_expired`), or a state
            change of a sandbox in the `error` or `failed` state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            The API key sent more than 1,200 requests in one minute, or a resume
            is above the start limits of the plan (`start_limit`, with
            `retryAfterSeconds`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UpdateSandboxBody:
      type: object
      properties:
        name:
          description: The new name. Send null to remove the name.
          anyOf:
            - 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
            - type: 'null'
        labels:
          description: The new labels. They replace all labels of the sandbox.
          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
          example:
            project: web
            agent: reviewer
        stopAfterSeconds:
          description: >-
            The new seconds that the sandbox runs after each start, counted from
            the current start. If this time is already past, the sandbox stops
            now. Send null to turn off auto-stop. Do not send it with stopAt.
          anyOf:
            - type: integer
              minimum: 60
              maximum: 2592000
            - type: 'null'
          example: 3600
        stopAt:
          description: >-
            The new time when the sandbox stops on its own. It must be in the
            future, and the sandbox must be creating, starting, or running. Send
            null to turn off auto-stop. Do not send it with stopAfterSeconds.
          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'
          example: '2026-11-16T12:00:00Z'
        state:
          $ref: '#/components/schemas/SandboxTargetState'
          description: >-
            Send stopped to stop the sandbox, or running to resume it. The
            response is 202 with the operation of the stop or the resume.
        size:
          $ref: '#/components/schemas/SandboxSize'
          description: >-
            The size after the resume. Send it only with state running, to a
            stopped sandbox.
        pinImage:
          description: >-
            Send true to keep the current base image at each resume. Send false
            to move the sandbox to the latest base image at the next resume
            after the 10-minute hold.
          type: boolean
    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
    SandboxTargetState:
      type: string
      enum:
        - stopped
        - running
      description: stopped stops a running sandbox. running resumes a stopped sandbox.
    SandboxSize:
      type: string
      enum:
        - small
        - medium
        - large
        - xlarge
      description: The vCPU, RAM, and disk of a sandbox.
    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
    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.