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

# Stream reconnectable template build logs

> Firecracker-only endpoint. Replays durable build log entries from the requested offset or cursor and, when `follow=true`, continues streaming live entries from the active build broadcaster. Owned custom-template builds are caller-scoped; reconnecting with a different authenticated caller returns not found rather than revealing build existence.




## OpenAPI

````yaml /openapi.yaml get /v1/templates/builds/{build_id}/logs
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/templates/builds/{build_id}/logs:
    parameters:
      - name: build_id
        in: path
        required: true
        schema:
          type: string
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          format: uint64
        description: First durable log offset to replay. Takes precedence over cursor.
      - name: cursor
        in: query
        required: false
        schema:
          type: integer
          format: uint64
        description: Alias for offset for reconnecting SSE clients.
      - name: follow
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Keep the SSE stream open and forward live build log entries.
    get:
      tags:
        - Templates
      summary: Stream reconnectable template build logs
      description: >
        Firecracker-only endpoint. Replays durable build log entries from the
        requested offset or cursor and, when `follow=true`, continues streaming
        live entries from the active build broadcaster. Owned custom-template
        builds are caller-scoped; reconnecting with a different authenticated
        caller returns not found rather than revealing build existence.
      operationId: streamTemplateBuildLogs
      responses:
        '200':
          description: SSE stream of template build log entries
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/TemplateBuildLogEntry'
              examples:
                logEntry:
                  summary: Build log SSE event
                  value: >
                    id: 10

                    event: log

                    data:
                    {"build_id":"tb_123","template_id":"tmpl_123","offset":10,"timestamp":"2026-03-17T00:00:12Z","kind":"message","level":"info","message":"Snapshot
                    complete"}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/TemplateResourceNotFound'
        '503':
          $ref: '#/components/responses/FeatureUnavailable'
components:
  schemas:
    TemplateBuildLogEntry:
      type: object
      description: A single structured build log entry emitted during template build
      required:
        - build_id
        - template_id
        - offset
        - timestamp
        - kind
        - level
        - message
      properties:
        build_id:
          type: string
        template_id:
          type: string
        offset:
          type: integer
          format: uint64
        timestamp:
          type: string
          format: date-time
        kind:
          $ref: '#/components/schemas/TemplateBuildLogKind'
        level:
          $ref: '#/components/schemas/TemplateBuildLogLevel'
        message:
          type: string
          description: Canonical human-readable log message for this build entry
        error_detail:
          $ref: '#/components/schemas/TemplateFailureDetail'
        result:
          $ref: '#/components/schemas/TemplateInfo'
        result_metadata:
          $ref: '#/components/schemas/TemplateBuildResultMetadata'
        phase:
          type: string
          description: >-
            Build phase: cache, preparing, vm_create, step, sync, startup,
            readiness, snapshot, finalize, cleanup, retry
        step_index:
          type: integer
          description: 1-indexed current build step number
        total_steps:
          type: integer
          description: Total number of build steps
        attempt:
          type: integer
          description: Current retry attempt (1-indexed)
        max_attempts:
          type: integer
          description: Maximum number of retry attempts allowed
        cache_kind:
          type: string
          enum:
            - file_blob
            - layer
            - final_artifact
          description: Cache layer this event describes
        cache_status:
          type: string
          enum:
            - hit
            - miss
            - stored
            - bypass
          description: Cache outcome for this event
        cache_reason:
          type: string
          enum:
            - whole_build_skip_cache
            - builder_cache_boundary
            - force_upload
            - missing_or_incompatible
          description: Optional reason for a cache miss or bypass
        cache_subject:
          type: string
          description: >-
            Human-readable cache target such as a build-context path or step
            description
    TemplateBuildLogKind:
      type: string
      enum:
        - start
        - message
        - cache
        - retry
        - warning
        - error
        - cancelled
        - end
    TemplateBuildLogLevel:
      type: string
      enum:
        - debug
        - info
        - warn
        - error
    TemplateFailureDetail:
      type: object
      required:
        - code
        - message
        - phase
        - retryable
        - suggested_action
      properties:
        code:
          type: string
          enum:
            - unauthorized
            - file_upload_error
            - build_error
            - internal_error
        message:
          type: string
        phase:
          $ref: '#/components/schemas/TemplateFailurePhase'
        retryable:
          type: boolean
        suggested_action:
          type: string
        step_index:
          type: integer
        attempt:
          type: integer
        max_attempts:
          type: integer
        cache_subject:
          type: string
        build_id:
          type: string
        request_id:
          type: string
          description: >-
            Present on terminal request-originated failures and blocking error
            responses.
        details:
          type: object
          additionalProperties: true
          description: >-
            Stable failure metadata. Includes a `reason` key plus phase-specific
            fields such as `blob_id`, `path`, digest/size mismatch values,
            `command`, or `alias`.
    TemplateInfo:
      type: object
      required:
        - id
        - name
        - description
        - builtin
        - canonical_ref
        - namespace_slug
        - visibility
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        tags:
          type: array
          items:
            type: string
        default_tag:
          type: string
        builtin:
          type: boolean
        canonical_ref:
          type: string
        namespace_slug:
          type: string
        visibility:
          $ref: '#/components/schemas/TemplateVisibility'
        runtime_defaults:
          $ref: '#/components/schemas/TemplateRuntimeDefaults'
    TemplateBuildResultMetadata:
      type: object
      description: >-
        Additional metadata attached to terminal build log entries and durable
        build attempts.
      properties:
        runtime_defaults:
          $ref: '#/components/schemas/TemplateRuntimeDefaults'
        oci_metadata:
          $ref: '#/components/schemas/TemplateOciImageMetadata'
    ErrorResponse:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: Machine-readable error code
          enum:
            - invalid_request
            - machine_not_found
            - snapshot_not_found
            - template_not_found
            - template_build_not_found
            - template_name_claim_not_found
            - machine_not_ready
            - unauthorized
            - auth_failed
            - auth_locked
            - auth_proxy_error
            - auth_proxy_unavailable
            - invalid_auth_redirect
            - invalid_oauth_provider
            - captcha_required
            - captcha_failed
            - captcha_unavailable
            - disposable_email
            - signup_rate_limited
            - oauth_rate_limited
            - email_action_rate_limited
            - database_error
            - email_not_verified
            - account_deleted
            - operator_required
            - account_not_found
            - account_not_soft_deleted
            - account_hard_delete_active_resources
            - file_upload_error
            - build_error
            - exec_timeout
            - exec_failed
            - file_error
            - not_implemented
            - capacity_exceeded
            - QUOTA_EXCEEDED
            - feature_unavailable
            - snapshot_in_use
            - no_eligible_runtime_host
            - same_host_required
            - incompatible_snapshot
            - rebuild_required
            - rate_limit_exceeded
            - transition_in_progress
            - transition_conflict
            - agent_deployment_not_found
            - agent_deployment_version_not_found
            - agent_run_not_found
            - agent_service_instance_not_found
            - agent_deployment_name_conflict
            - agent_deployment_idempotency_mismatch
            - agent_deployment_invalid_config
            - agent_deployment_invalid_state
            - volume_beta_restriction
            - volume_invalid_mount_path
            - volume_overlapping_mounts
            - volume_backend_capability_unsupported
            - volume_quota_exceeded
            - volume_mount_credential_issue_failed
            - volume_backend_unavailable
            - volume_stale_revision
            - volume_busy
            - volume_read_only
            - volume_limit_exceeded
            - internal_error
        error_detail:
          $ref: '#/components/schemas/ErrorDetail'
        request_id:
          type: string
          description: Request correlation ID returned in the `x-request-id` header
        build_id:
          type: string
          description: Template build ID when the error is associated with a tracked build
    TemplateFailurePhase:
      type: string
      enum:
        - auth
        - preflight
        - blob_upload
        - prepare
        - build_step
        - readiness
        - snapshot
        - finalize
        - interrupted
    TemplateVisibility:
      type: string
      enum:
        - private
        - public
    TemplateRuntimeDefaults:
      type: object
      description: >-
        Effective runtime defaults retained for a built template. Environment
        values are intentionally omitted; only keys are exposed.
      properties:
        default_env_keys:
          type: array
          items:
            type: string
        start_cmd:
          type: string
        default_user:
          type: string
        default_workdir:
          type: string
        readiness:
          $ref: '#/components/schemas/TemplateReadinessProbe'
    TemplateOciImageMetadata:
      type: object
      description: >-
        OCI image metadata retained from Dockerfile or OCI imports. Volume
        declarations are metadata only and do not create persistent Nullspace
        volumes.
      properties:
        labels:
          type: object
          additionalProperties:
            type: string
        exposed_ports:
          type: array
          items:
            type: string
        volumes:
          type: array
          items:
            type: string
        healthcheck:
          $ref: '#/components/schemas/TemplateOciHealthcheckMetadata'
    ErrorDetail:
      oneOf:
        - $ref: '#/components/schemas/TemplateFailureDetail'
        - $ref: '#/components/schemas/UploadFailureDetail'
    TemplateReadinessProbe:
      oneOf:
        - type: object
          required:
            - kind
            - port
          properties:
            kind:
              type: string
              enum:
                - tcp
            port:
              type: integer
              format: int32
            timeout_secs:
              type: integer
              format: int32
            interval_ms:
              type: integer
              format: int64
            startup_grace_secs:
              type: integer
              format: int32
          example:
            kind: tcp
            port: 3000
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
        - type: object
          required:
            - kind
            - timeout_ms
          properties:
            kind:
              type: string
              enum:
                - timeout
            timeout_ms:
              type: integer
              format: int64
          example:
            kind: timeout
            timeout_ms: 20000
        - type: object
          required:
            - kind
            - port
            - path
          properties:
            kind:
              type: string
              enum:
                - http
            port:
              type: integer
              format: int32
            path:
              type: string
            timeout_secs:
              type: integer
              format: int32
            interval_ms:
              type: integer
              format: int64
            startup_grace_secs:
              type: integer
              format: int32
          example:
            kind: http
            port: 3000
            path: /ready
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
        - type: object
          required:
            - kind
            - command
          properties:
            kind:
              type: string
              enum:
                - command
            command:
              type: string
            timeout_secs:
              type: integer
              format: int32
            interval_ms:
              type: integer
              format: int64
            startup_grace_secs:
              type: integer
              format: int32
          example:
            kind: command
            command: test -e /tmp/template-ready
            timeout_secs: 30
            interval_ms: 500
            startup_grace_secs: 2
      discriminator:
        propertyName: kind
    TemplateOciHealthcheckMetadata:
      type: object
      properties:
        test:
          type: array
          items:
            type: string
        interval_ns:
          type: integer
          format: int64
        timeout_ns:
          type: integer
          format: int64
        start_period_ns:
          type: integer
          format: int64
        retries:
          type: integer
          format: int32
        mapped_readiness:
          $ref: '#/components/schemas/TemplateReadinessProbe'
    UploadFailureDetail:
      type: object
      required:
        - reason
        - message
        - retryable
      properties:
        reason:
          $ref: '#/components/schemas/UploadFailureReason'
        message:
          type: string
        retryable:
          type: boolean
        upload_id:
          type: string
        request_id:
          type: string
        path:
          type: string
          description: >-
            Normalized absolute machine path associated with the failed upload
            when available.
        part_number:
          type: integer
          format: uint32
        details:
          type: object
          additionalProperties: true
          description: >-
            Additional failure diagnostics; keys depend on the failure reason,
            deliberately open.
    UploadFailureReason:
      type: string
      enum:
        - insufficient_staging_space
        - size_limit_exceeded
        - invalid_part_checksum
        - part_out_of_range
        - part_size_mismatch
        - whole_checksum_mismatch
        - upload_expired
        - upload_aborted
        - upload_already_completed
        - target_conflict
        - directory_extract_invalid_path
        - directory_extract_invalid_symlink
        - directory_extract_unsupported_entry
        - missing_parts
  responses:
    Unauthorized:
      description: Missing or invalid bearer credential
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unauthorized:
              summary: Missing or invalid bearer credential
              value:
                error: Missing or invalid bearer credential
                code: unauthorized
                request_id: req_123
    TemplateResourceNotFound:
      description: Template or template build not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    FeatureUnavailable:
      description: Feature is unavailable in current deployment mode
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````