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

# List app CVMs

> Returns CVM instances for an app. Admins see all instances; users see only their own.



## OpenAPI

````yaml /openapi.json get /api/v1/apps/{app_id}/cvms
openapi: 3.1.0
info:
  title: Phala Cloud API
  version: 0.1.0
servers:
  - url: https://cloud-api.phala.com
security: []
tags:
  - name: CVMs
    description: Confidential Virtual Machine (CVM) lifecycle management on Phala Network
  - name: Apps
    description: App template management and CVM deployment from app blueprints
  - name: Webhooks
    description: Manage webhook endpoints and monitor delivery history
  - name: SSH Keys
    description: SSH public key management for CVM access
  - name: KMS
    description: >-
      Key Management Service — key derivation, on-chain anchoring, and
      inspection
  - name: Instance Types
    description: Available hardware configurations for CVM deployment
  - name: Attestations
    description: Remote attestation and TEE verification endpoints
paths:
  /api/v1/apps/{app_id}/cvms:
    get:
      tags:
        - Apps
      summary: List app CVMs
      description: >-
        Returns CVM instances for an app. Admins see all instances; users see
        only their own.
      operationId: handle_get_app_cvms_api_v1_apps__app_id__cvms_get
      parameters:
        - name: app_id
          in: path
          required: true
          schema:
            type: string
            title: App Id
            description: Hex app identifier
          description: Hex app identifier
      responses:
        '200':
          description: List of CVM instances
          content:
            application/json:
              schema:
                anyOf:
                  - type: array
                    items:
                      $ref: '#/components/schemas/HostedCvm'
                  - type: array
                    items:
                      $ref: >-
                        #/components/schemas/teehouse__api__routes__cvms__v20260121__schemas__CVMInfo
                title: Response Handle Get App Cvms Api V1 Apps  App Id  Cvms Get
        '401':
          description: Not authenticated
        '403':
          description: No workspace access
        '404':
          description: App not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2AuthorizationCodeBearer: []
        - APIKeyHeader: []
components:
  schemas:
    HostedCvm:
      properties:
        hosted:
          $ref: '#/components/schemas/VmInfo'
        name:
          type: string
          title: Name
        managed_user:
          anyOf:
            - $ref: '#/components/schemas/ManagedUser'
            - type: 'null'
        node:
          anyOf:
            - $ref: '#/components/schemas/CvmNode'
            - type: 'null'
        listed:
          type: boolean
          title: Listed
          default: false
        status:
          type: string
          title: Status
        in_progress:
          type: boolean
          title: In Progress
          default: false
        dapp_dashboard_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Dapp Dashboard Url
        syslog_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Syslog Endpoint
        allow_upgrade:
          type: boolean
          title: Allow Upgrade
          default: false
        project_id:
          anyOf:
            - type: string
              pattern: ^prj_.+
              format: hashid
              title: HashedId[projects]
              description: A hashed identifier that maps to an internal database ID
              examples:
                - prj_0123abcd
            - type: 'null'
          title: Project Id
        project_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Type
        billing_period:
          anyOf:
            - type: string
            - type: 'null'
          title: Billing Period
        kms_info:
          anyOf:
            - $ref: '#/components/schemas/KMSInfo'
            - type: 'null'
        contract_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Contract Address
        deployer_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Deployer Address
        vcpu:
          anyOf:
            - type: integer
            - type: 'null'
          title: Vcpu
        memory:
          anyOf:
            - type: integer
            - type: 'null'
          title: Memory
        disk_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: Disk Size
        gateway_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Gateway Domain
        public_urls:
          items:
            $ref: '#/components/schemas/CvmNetworkUrls'
          type: array
          title: Public Urls
      type: object
      required:
        - hosted
        - name
        - status
        - public_urls
      title: HostedCvm
    teehouse__api__routes__cvms__v20260121__schemas__CVMInfo:
      properties:
        id:
          type: string
          pattern: ^cvm_.+
          format: hashid
          title: HashedId[cvms]
          description: A hashed identifier that maps to an internal database ID
          examples:
            - cvm_0123abcd
        name:
          type: string
          title: Name
        app_id:
          anyOf:
            - type: string
            - type: 'null'
          title: App Id
        vm_uuid:
          anyOf:
            - type: string
            - type: 'null'
          title: Vm Uuid
        instance_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance Id
        resource:
          $ref: '#/components/schemas/CVMResourceInfo'
        node_info:
          anyOf:
            - $ref: '#/components/schemas/NodeRef'
            - type: 'null'
        os:
          anyOf:
            - $ref: '#/components/schemas/CVMOSInfo'
            - type: 'null'
        kms_type:
          anyOf:
            - $ref: '#/components/schemas/KmsType'
            - type: 'null'
        kms_info:
          anyOf:
            - $ref: '#/components/schemas/CVMKmsInfo'
            - type: 'null'
        status:
          type: string
          title: Status
        in_progress:
          type: boolean
          title: In Progress
          default: false
        progress:
          anyOf:
            - $ref: '#/components/schemas/CVMProgressInfo'
            - type: 'null'
        compose_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Compose Hash
        docker_compose_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Docker Compose Hash
        pre_launch_script_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Launch Script Hash
        gateway:
          $ref: '#/components/schemas/CVMGatewayInfo'
        logs:
          $ref: '#/components/schemas/CVMLogUrls'
        services:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Services
        endpoints:
          anyOf:
            - items:
                $ref: '#/components/schemas/CvmNetworkUrls'
              type: array
            - type: 'null'
          title: Endpoints
        public_logs:
          type: boolean
          title: Public Logs
          default: false
        public_sysinfo:
          type: boolean
          title: Public Sysinfo
          default: false
        public_tcbinfo:
          type: boolean
          title: Public Tcbinfo
          default: true
        gateway_enabled:
          type: boolean
          title: Gateway Enabled
          default: false
        secure_time:
          type: boolean
          title: Secure Time
          default: false
        storage_fs:
          type: string
          title: Storage Fs
          default: zfs
        workspace:
          anyOf:
            - $ref: '#/components/schemas/WorkspaceRef'
            - type: 'null'
        creator:
          anyOf:
            - $ref: '#/components/schemas/UserRef'
            - type: 'null'
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
        deleted_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Deleted At
        listed:
          type: boolean
          title: Listed
          default: false
        project_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Project Type
      type: object
      required:
        - id
        - name
        - resource
        - status
        - gateway
      title: CVMInfo
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    VmInfo:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        status:
          type: string
          title: Status
        uptime:
          type: string
          title: Uptime
        app_url:
          anyOf:
            - type: string
            - type: 'null'
          title: App Url
        app_id:
          type: string
          title: App Id
        instance_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance Id
        configuration:
          anyOf:
            - $ref: '#/components/schemas/VmConfiguration'
            - type: 'null'
        exited_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Exited At
        boot_progress:
          anyOf:
            - type: string
            - type: 'null'
          title: Boot Progress
        boot_error:
          anyOf:
            - type: string
            - type: 'null'
          title: Boot Error
        shutdown_progress:
          anyOf:
            - type: string
            - type: 'null'
          title: Shutdown Progress
        image_version:
          anyOf:
            - type: string
            - type: 'null'
          title: Image Version
        events:
          items:
            $ref: '#/components/schemas/GuestEvent'
          type: array
          title: Events
      type: object
      required:
        - id
        - name
        - status
        - uptime
        - app_id
      title: VmInfo
      description: Mapping from Teepod RPC's VmInfo.
    ManagedUser:
      properties:
        id:
          type: integer
          title: Id
        username:
          type: string
          title: Username
      type: object
      required:
        - id
        - username
      title: ManagedUser
    CvmNode:
      properties:
        id:
          type: integer
          title: Id
        name:
          type: string
          title: Name
        region_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Region Identifier
      type: object
      required:
        - id
        - name
      title: CvmNode
    KMSInfo:
      properties:
        id:
          type: string
          pattern: ^kms_.+
          format: hashid
          title: HashedId[kms]
          description: Hashed KMS identifier (kms_xxxxx)
          examples:
            - kms_0123abcd
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
          description: Human-readable KMS name
        url:
          type: string
          title: Url
          description: KMS endpoint URL
        version:
          type: string
          title: Version
          description: KMS software version
        chain_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Chain Id
          description: Blockchain chain ID if onchain
        kms_contract_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Kms Contract Address
          description: Smart contract address if onchain
        gateway_app_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Gateway App Id
          description: Gateway application ID
      type: object
      required:
        - id
        - url
        - version
      title: KMSInfo
      description: KMS instance information.
    CvmNetworkUrls:
      properties:
        app:
          type: string
          title: App
        instance:
          type: string
          title: Instance
      type: object
      required:
        - app
        - instance
      title: CvmNetworkUrls
      description: Model representing public URLs for a CVM port
    CVMResourceInfo:
      properties:
        instance_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Instance Type
        vcpu:
          anyOf:
            - type: integer
            - type: 'null'
          title: Vcpu
        memory_in_gb:
          anyOf:
            - type: number
            - type: 'null'
          title: Memory In Gb
        disk_in_gb:
          anyOf:
            - type: integer
            - type: 'null'
          title: Disk In Gb
        gpus:
          anyOf:
            - type: integer
            - type: 'null'
          title: Gpus
        compute_billing_price:
          anyOf:
            - type: string
              format: decimal
              description: A monetary value with precise decimal arithmetic
              examples:
                - '19.99'
                - '123.456000'
            - type: 'null'
          title: Compute Billing Price
        billing_period:
          anyOf:
            - $ref: '#/components/schemas/BillingPeriod'
            - type: 'null'
      type: object
      title: CVMResourceInfo
    NodeRef:
      properties:
        object_type:
          type: string
          const: node
          title: Object Type
          description: Fixed value 'node'
          default: node
        id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Id
          description: Teepod numeric ID
        node_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Node Id
          description: Physical node numeric ID
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Node display name
        region:
          anyOf:
            - type: string
            - type: 'null'
          title: Region
          description: Region identifier
        device_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Device Id
          description: Device ID
        ppid:
          anyOf:
            - type: string
            - type: 'null'
          title: Ppid
          description: PPID
        status:
          anyOf:
            - $ref: '#/components/schemas/TeepodStatus'
            - type: 'null'
          description: Node status
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
          description: Teepod version
      type: object
      title: NodeRef
      description: Minimal node/teepod reference for embedding in responses.
    CVMOSInfo:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        version:
          anyOf:
            - type: string
            - type: 'null'
          title: Version
        is_dev:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Dev
        os_image_hash:
          anyOf:
            - type: string
            - type: 'null'
          title: Os Image Hash
      type: object
      title: CVMOSInfo
    KmsType:
      type: string
      enum:
        - phala
        - ethereum
        - base
        - legacy
      title: KmsType
    CVMKmsInfo:
      properties:
        chain_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Chain Id
        dstack_kms_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Dstack Kms Address
        dstack_app_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Dstack App Address
        deployer_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Deployer Address
        rpc_endpoint:
          anyOf:
            - type: string
            - type: 'null'
          title: Rpc Endpoint
        encrypted_env_pubkey:
          anyOf:
            - type: string
            - type: 'null'
          title: Encrypted Env Pubkey
      type: object
      title: CVMKmsInfo
    CVMProgressInfo:
      properties:
        target:
          anyOf:
            - type: string
            - type: 'null'
          title: Target
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
        correlation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Correlation Id
      type: object
      title: CVMProgressInfo
    CVMGatewayInfo:
      properties:
        base_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Base Domain
        cname:
          anyOf:
            - type: string
            - type: 'null'
          title: Cname
      type: object
      title: CVMGatewayInfo
    CVMLogUrls:
      properties:
        serial:
          anyOf:
            - type: string
            - type: 'null'
          title: Serial
        stdout:
          anyOf:
            - type: string
            - type: 'null'
          title: Stdout
        stderr:
          anyOf:
            - type: string
            - type: 'null'
          title: Stderr
        container_log_base:
          anyOf:
            - type: string
            - type: 'null'
          title: Container Log Base
      type: object
      title: CVMLogUrls
    WorkspaceRef:
      properties:
        object_type:
          type: string
          const: workspace
          title: Object Type
          description: Fixed value 'workspace'
          default: workspace
        id:
          type: string
          pattern: ^wks_.+
          format: hashid
          title: HashedId[teams]
          description: Hashed workspace ID
          examples:
            - wks_0123abcd
        name:
          type: string
          title: Name
          description: Workspace display name
        slug:
          anyOf:
            - type: string
            - type: 'null'
          title: Slug
          description: URL-safe workspace identifier
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar Url
          description: Workspace avatar URL from profile
      type: object
      required:
        - id
        - name
      title: WorkspaceRef
      description: Minimal workspace reference for embedding in responses.
    UserRef:
      properties:
        object_type:
          type: string
          const: user
          title: Object Type
          description: Fixed value 'user'
          default: user
        id:
          anyOf:
            - type: string
              pattern: ^usr_.+
              format: hashid
              title: HashedId[users]
              description: A hashed identifier that maps to an internal database ID
              examples:
                - usr_0123abcd
            - type: 'null'
          title: Id
          description: Hashed user ID
        username:
          anyOf:
            - type: string
            - type: 'null'
          title: Username
          description: Display username
        avatar_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar Url
          description: Gravatar or OAuth provider avatar URL
      type: object
      title: UserRef
      description: Minimal user reference for embedding in responses.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    VmConfiguration:
      properties:
        name:
          type: string
          title: Name
        image:
          type: string
          title: Image
        compose_file:
          anyOf:
            - $ref: '#/components/schemas/AppComposeV2'
            - type: 'null'
        vcpu:
          type: integer
          title: Vcpu
        memory:
          type: integer
          title: Memory
        disk_size:
          type: integer
          title: Disk Size
        ports:
          anyOf:
            - items:
                $ref: '#/components/schemas/PortMapping'
              type: array
            - type: 'null'
          title: Ports
        encrypted_env:
          anyOf:
            - type: string
            - type: 'null'
          title: Encrypted Env
        app_id:
          anyOf:
            - type: string
            - type: 'null'
          title: App Id
        user_config:
          anyOf:
            - type: string
            - type: 'null'
          title: User Config
        hugepages:
          type: boolean
          title: Hugepages
          default: false
        pin_numa:
          type: boolean
          title: Pin Numa
          default: false
        gpus:
          anyOf:
            - $ref: '#/components/schemas/GpuConfig'
            - type: 'null'
          default:
            gpus: []
            attach_mode: listed
        kms_urls:
          items:
            type: string
          type: array
          title: Kms Urls
          default: []
        gateway_urls:
          items:
            type: string
          type: array
          title: Gateway Urls
          default: []
      type: object
      required:
        - name
        - image
        - vcpu
        - memory
        - disk_size
      title: VmConfiguration
      description: Mapping from Teepod RPC's VmConfiguration.
    GuestEvent:
      properties:
        event:
          type: string
          title: Event
        body:
          type: string
          title: Body
        timestamp:
          type: integer
          title: Timestamp
          default: 0
      type: object
      required:
        - event
        - body
      title: GuestEvent
      description: >-
        Structured lifecycle event emitted by the guest or runtime. Since VMM
        v0.5.7.
    BillingPeriod:
      type: string
      enum:
        - skip
        - hourly
        - monthly
      title: BillingPeriod
    TeepodStatus:
      type: string
      enum:
        - ONLINE
        - OFFLINE
        - MAINTENANCE
      title: TeepodStatus
    AppComposeV2:
      properties:
        allowed_envs:
          items:
            type: string
          type: array
          title: Allowed Envs
        bash_script:
          anyOf:
            - type: string
            - type: 'null'
          title: Bash Script
        default_gateway_domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Default Gateway Domain
        docker_compose_file:
          anyOf:
            - type: string
            - type: 'null'
          title: Docker Compose File
        init_script:
          anyOf:
            - type: string
            - type: 'null'
          title: Init Script
        kms_enabled:
          type: boolean
          title: Kms Enabled
          default: true
        local_key_provider_enabled:
          type: boolean
          title: Local Key Provider Enabled
          default: false
        manifest_version:
          type: integer
          title: Manifest Version
          default: 2
        name:
          type: string
          title: Name
        no_instance_id:
          type: boolean
          title: No Instance Id
          default: false
        pre_launch_script:
          anyOf:
            - type: string
            - type: 'null'
          title: Pre Launch Script
        public_logs:
          type: boolean
          title: Public Logs
          default: true
        public_sysinfo:
          type: boolean
          title: Public Sysinfo
          default: true
        public_tcbinfo:
          type: boolean
          title: Public Tcbinfo
          default: true
        runner:
          type: string
          title: Runner
          default: docker-compose
        gateway_enabled:
          type: boolean
          title: Gateway Enabled
          default: true
        features:
          items:
            type: string
          type: array
          title: Features
          default:
            - kms
            - tproxy-net
        salt:
          anyOf:
            - type: string
            - type: 'null'
          title: Salt
        secure_time:
          type: boolean
          title: Secure Time
          default: false
        storage_fs:
          anyOf:
            - type: string
              const: ext4
            - type: string
              const: zfs
            - type: 'null'
          title: Storage Fs
          default: zfs
        tproxy_enabled:
          type: boolean
          title: Tproxy Enabled
          default: true
      type: object
      required:
        - name
      title: AppComposeV2
    PortMapping:
      properties:
        protocol:
          type: string
          title: Protocol
        host_port:
          type: integer
          title: Host Port
        vm_port:
          type: integer
          title: Vm Port
        host_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Host Address
      type: object
      required:
        - protocol
        - host_port
        - vm_port
      title: PortMapping
    GpuConfig:
      properties:
        gpus:
          items:
            $ref: '#/components/schemas/GpuSpec'
          type: array
          title: Gpus
        attach_mode:
          anyOf:
            - type: string
              enum:
                - listed
                - all
            - type: string
          title: Attach Mode
          default: listed
      type: object
      required:
        - gpus
      title: GpuConfig
    GpuSpec:
      properties:
        slot:
          type: string
          title: Slot
        product_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Product Id
      type: object
      required:
        - slot
      title: GpuSpec
  securitySchemes:
    OAuth2AuthorizationCodeBearer:
      type: oauth2
      flows:
        authorizationCode:
          scopes: {}
          authorizationUrl: ''
          tokenUrl: token
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````