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

# Start or rotate the preferred managed desktop viewer session



## OpenAPI

````yaml /openapi.yaml post /v1/machines/{id}/desktop/stream/start
openapi: 3.1.0
info:
  title: Nullspace API
  version: 0.1.0
  description: |
    Cloud machine platform for AI agents. Create on-demand microVMs,
    execute commands, manage files, automate desktop environments,
    and stream output over WebSocket.
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.13-215-85-171.sslip.io
    description: Private beta
  - url: https://nullspace.example
    description: Self-hosted single-host owned-domain
  - url: http://localhost
    description: Self-hosted single-host localhost/no-domain via Caddy
  - url: http://localhost:3000
    description: Local development direct API
security:
  - bearerAuth: []
tags:
  - name: Health
    description: Public process-liveness check (no auth required)
  - name: Machines
    description: Machine lifecycle, execution, and process management
  - name: Files
    description: Filesystem operations within a machine
  - name: Git
    description: First-class structured git operations within a machine
  - name: Desktop
    description: Desktop automation (mouse, keyboard, screenshots)
  - name: Recording
    description: Screen recording management
  - name: PTY
    description: Pseudo-terminal session management
  - name: Templates
    description: Machine template management
  - name: Agent Deployments
    description: Named, versioned agent deployment control plane
  - name: Volumes
    description: Persistent volume control plane and attached volume actions
  - name: WebSocket
    description: Streaming execution and PTY over WebSocket
  - name: Monitor
    description: In-repo WebSocket stream for machine health, metrics, and process updates
  - name: API Keys
    description: Runtime API key metadata and dormant self-serve key management
  - name: Account
    description: Dormant Supabase-session account profile, export, and deletion routes
  - name: Admin
    description: Supabase-session operator console APIs for account support
  - name: Auth
    description: Dormant self-serve Auth proxy routes gated by deployment config
  - name: Code
    description: Stateful code execution via Jupyter kernels (Code Interpreter)
  - name: Internal Operations
    description: Operator-only internal API surfaces; not part of the public SDK contract
paths:
  /v1/machines/{id}/desktop/stream/start:
    parameters:
      - $ref: '#/components/parameters/MachineId'
    post:
      tags:
        - Desktop
      summary: Start or rotate the preferred managed desktop viewer session
      operationId: startDesktopStream
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartDesktopStreamRequest'
      responses:
        '201':
          description: >-
            Managed desktop viewer session started. When raw VNC is not public,
            the raw host, port, and VNC URL fields may be omitted while the
            managed viewer URL and auth token remain available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedDesktopStreamInfo'
components:
  parameters:
    MachineId:
      name: id
      in: path
      required: true
      schema:
        type: string
      description: Machine ID (e.g. mch_a1b2c3d4)
  schemas:
    StartDesktopStreamRequest:
      type: object
      properties:
        view_only:
          type: boolean
    ManagedDesktopStreamInfo:
      type: object
      required:
        - protocol
        - viewer_url
        - auth_key
        - view_only
        - expires_at
      properties:
        protocol:
          type: string
        host:
          type: string
          nullable: true
        port:
          type: integer
          format: uint16
          nullable: true
        url:
          type: string
          nullable: true
        vnc_url:
          type: string
          nullable: true
        viewer_url:
          type: string
          description: >-
            Public managed viewer URL. In edge mode this points to the reserved
            `desktop-{machine_id}` edge host rather than the API origin.
        auth_key:
          type: string
        view_only:
          type: boolean
        expires_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````