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

# Start Workspace

> Boot a provisioned or stopped workspace.

If a stopped workspace is below its template/catalog resource floor, Rigbox raises the stored RAM, vCPU, and disk values before booting. If the account cannot fit the raised resources, the start request fails before the VM is started.


## OpenAPI

````yaml POST /api/v1/workspaces/{id}/start
openapi: 3.1.0
info:
  title: Rigbox Public API
  description: >-
    Gateway-owned public API for Rigbox. The gateway composes its local
    lifecycle API with service-owned exported specs.
  contact:
    name: Rigbox
    url: https://rigbox.dev
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.rigbox.dev
    description: Production gateway
security: []
tags:
  - name: Workspaces
  - name: CLI
  - name: Observability
  - name: Auth
  - name: API Keys
  - name: Access Control
  - name: Apps
  - name: App Catalog
  - name: Logs
  - name: AI
  - name: Tools
  - name: Snapshots
  - name: SSH Keys
  - name: Templates
  - name: Setup Scripts
  - name: Service Specs
  - name: Deploy
  - name: Community
  - name: User Settings
  - name: Roadmap
  - name: System
paths:
  /api/v1/workspaces/{id}/start:
    post:
      tags:
        - Workspaces
      summary: Start a workspace.
      description: Boot the workspace VM and wait until it reports running.
      operationId: start_vm
      parameters:
        - name: id
          in: path
          description: Workspace ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Workspace start queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWorkspaceResponse'
      security:
        - bearer: []
components:
  schemas:
    GetWorkspaceResponse:
      type: object
      required:
        - vm
      properties:
        failure:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/WorkspaceFailure'
              description: >-
                Structured failure info when `vm.status == Failed`. `None`
                otherwise.

                Computed from the workspace's `failure_code`, `failure_reason`,
                and

                `creation_attempts` fields plus the retryable allowlist policy.
        vm:
          $ref: '#/components/schemas/Vm'
    WorkspaceFailure:
      type: object
      description: >-
        Structured failure surface returned by the workspace API when a
        workspace

        is in `Failed` status. Phase 4 Task 4.3 wires this into the response.
      required:
        - code
        - message
        - retryable
        - occurred_at
        - attempts
      properties:
        attempts:
          type: integer
          format: int32
        code:
          type: string
        message:
          type: string
        occurred_at:
          type: string
          format: date-time
        retryable:
          type: boolean
    Vm:
      type: object
      required:
        - id
        - user_id
        - node_id
        - name
        - status
        - image
        - ram_mb
        - vcpu_count
        - disk_size_mb
        - created_at
        - updated_at
      properties:
        ai_mode:
          type:
            - string
            - 'null'
          description: |-
            Per-workspace override for the AI mode (`managed` or `byok`).
            `None` means inherit from `users.ai_mode` (the per-account default).
        cloned_from:
          type:
            - string
            - 'null'
          description: >-
            Bluegreen preview lineage. `None` = a normal workspace.
            `Some(source_id)`

            = this VM is a COW clone of `source_id`, booted as a hidden preview;

            promote repoints the prod subdomain's edge route to it. See

            [`Vm::is_preview`].
        created_at:
          type: string
          format: date-time
        creation_attempts:
          type: integer
          format: int32
        creation_started_at:
          type:
            - string
            - 'null'
          format: date-time
        disk_size_mb:
          type: integer
          format: int32
          minimum: 0
        env_vars:
          type:
            - object
            - 'null'
          additionalProperties:
            type: string
          propertyNames:
            type: string
        failure_code:
          type:
            - string
            - 'null'
        failure_reason:
          type:
            - string
            - 'null'
        id:
          type: string
        image:
          type: string
        image_digest:
          type:
            - string
            - 'null'
          description: >-
            Content-addressed image this workspace is pinned to. When set, the

            workspace boots from this registry image (staged as the rootfs on
            first

            boot) instead of the named base in `image`. `None` = the named-base
            path.
        ip_address:
          type:
            - string
            - 'null'
        name:
          type: string
        node_id:
          type: string
        ram_mb:
          type: integer
          format: int32
          minimum: 0
        service_spec_ids:
          type:
            - array
            - 'null'
          items:
            type: string
        setup_script_ids:
          type:
            - array
            - 'null'
          items:
            type: string
        status:
          $ref: '#/components/schemas/VmStatus'
        template_id:
          type:
            - string
            - 'null'
        updated_at:
          type: string
          format: date-time
        user_id:
          type: string
        vcpu_count:
          type: integer
          format: int32
          minimum: 0
    VmStatus:
      type: string
      enum:
        - provisioned
        - provisioning
        - starting
        - running
        - stopping
        - stopped
        - deleting
        - failed
  securitySchemes:
    bearer:
      type: http
      scheme: bearer

````