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

# Admit a headless Computer operation

> Admits one mutating headless operation — filesystem write or remove, or process start, inspect, or signal — for the exact Computer attachment, fenced by…



## OpenAPI

````yaml /openapi.json post /v1/computers/{id}/headless-operations
openapi: 3.1.0
info:
  title: Checkfu API
  version: '2026-08-31'
  description: >-
    Authentication is declared per operation: API-key, runtime, or connector
    bearer; Automation signature; bootstrap poll token; or anonymous bootstrap
    creation and credential-free pairing redemption. Every general Checkfu REST
    request requires the dated `Checkfu-Version` header (one of: 2026-08-31);
    the three MCP JSON-RPC transports use `MCP-Protocol-Version`, A2A uses
    `A2A-Version`, and the provider OAuth callback carries neither Checkfu
    header. API keys resolve one Workspace without a request selector;
    authenticated responses identify it with `Checkfu-Workspace-Id`.
servers:
  - url: https://api.checkfu.com
security:
  - bearerAuth: []
tags:
  - name: organizations
  - name: sourceRepositories
  - name: tenants
  - name: workspaces
  - name: principals
  - name: principalGroups
  - name: principalAccessCredentials
  - name: apiKeys
  - name: agents
  - name: harnesses
  - name: harnessRuntime
  - name: computerProfiles
  - name: permissionAssignments
  - name: actionPolicies
  - name: files
  - name: memoryStores
  - name: dreams
  - name: modelCredentials
  - name: modelRoutingProfiles
  - name: blueprintInstallations
  - name: toolSources
  - name: skills
  - name: skillSources
  - name: agentBlueprints
  - name: skillProposals
  - name: instructionProposals
  - name: catalog
  - name: concepts
  - name: support
  - name: bootstrapRequests
  - name: connections
  - name: connectionVaults
  - name: connectionAssignments
  - name: connectedRuntimes
  - name: fileTrees
  - name: collaboration
  - name: automationGraphs
  - name: automations
  - name: projects
  - name: actionApprovals
  - name: standingApprovals
  - name: workloadReviewPolicies
  - name: usage
  - name: models
  - name: outcomes
  - name: budgets
  - name: billing
  - name: sessions
  - name: audit
  - name: sessionExports
  - name: runs
  - name: runnerPools
  - name: transcripts
  - name: sessionWatches
  - name: sessionHandoffs
  - name: sessionCapsules
  - name: sessionTrajectories
  - name: webhookEndpoints
  - name: integrationGateway
  - name: workEnvironments
  - name: computers
  - name: computerScreens
  - name: computerBrowserObservations
  - name: computerBrowserActions
  - name: environments
  - name: computerHeadlessOperations
  - name: vaults
  - name: apiMcp
  - name: a2a
paths:
  /v1/computers/{id}/headless-operations:
    post:
      tags:
        - computerHeadlessOperations
      summary: Admit a headless Computer operation
      description: >-
        Admits one mutating headless operation — filesystem write or remove, or
        process start, inspect, or signal — for the exact Computer attachment,
        fenced by the caller's expected mutation epoch and a short deadline.
        Session-proven ingress is revalidated by the owning Session against its
        current RunAttempt and lease before the Computer admits anything;
        terminal ingress additionally presents the terminal grant token in the
        x-checkfu-computer-ingress-token header, verified against the live grant
        ledger, generation, and epoch, and a revoked or expired grant refuses
        before any effect. A filesystem write must reference a payload staged
        and sealed with the same digest and length. The server derives identity,
        generation, and clocks, returns a secret-free dispatch-or-queue receipt,
        and an exact replay with the same Idempotency-Key returns the original
        admission.


        Checkfu support posture: alpha; hosted. No release evidence journey
        applies to this operation.
      operationId: computerHeadlessOperations.createComputerHeadlessOperation
      parameters:
        - name: id
          in: path
          schema:
            $ref: '#/components/schemas/ComputerId'
          required: true
        - name: checkfu-version
          in: header
          schema:
            type: string
            enum:
              - '2026-08-31'
          required: true
        - name: idempotency-key
          in: header
          schema:
            type: string
            allOf:
              - maxLength: 255
          required: false
        - name: x-checkfu-computer-ingress-token
          in: header
          schema:
            type: string
            allOf:
              - pattern: ^[0-9a-f]{64}$
          required: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateComputerHeadlessOperation'
        required: true
      responses:
        '202':
          description: >-
            Admission receipt for one headless Computer operation: the
            server-derived operation identity, whether the Computer's serialized
            mutation slot dispatched or queued it, and whether the request
            replayed an existing admission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerHeadlessOperationAdmission'
          headers:
            checkfu-workspace-id:
              description: The Workspace resolved from the authenticated bearer credential.
              required: true
              schema:
                $ref: '#/components/schemas/WorkspaceId'
        '400':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - validation.malformed
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#validation-malformed
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    required:
                      - type
                      - message
                      - more
                    additionalProperties: false
                additionalProperties: false
        '401':
          description: Typed Checkfu wire error
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                      - more
                    properties:
                      type:
                        type: string
                        enum:
                          - auth.invalid_key
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#auth-invalid-key
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    additionalProperties: false
                additionalProperties: false
        '403':
          description: >-
            The organization, tenant, or workspace backing this key is
            administratively disabled. | Deployment governance or retention
            policy denied the request.
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    required:
                      - error
                    properties:
                      error:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - auth.disabled_tenancy
                          message:
                            type: string
                          more:
                            type: string
                            enum:
                              - >-
                                https://docs.checkfu.com/reference/errors#auth-disabled-tenancy
                            description: >-
                              Stable public documentation and remedy for this
                              error type.
                        required:
                          - type
                          - message
                          - more
                        additionalProperties: false
                    additionalProperties: false
                  - $ref: '#/components/schemas/PolicyDeniedError'
        '404':
          description: >-
            The requested resource does not exist in the resolved deployment
            boundary.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationNotFoundError'
        '409':
          description: >-
            The request conflicts with the resource's current state. | An
            idempotent mutation conflicts with a completed or in-progress
            request for the same key.
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationConflictError'
                  - $ref: '#/components/schemas/IdempotencyConflictError'
        '429':
          description: Typed Checkfu wire error
          headers:
            retry-after:
              description: >-
                Delay in seconds for rate limits or deployment quotas with a
                known release or UTC reset boundary
              required: false
              schema:
                type: integer
                minimum: 1
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: object
                    required:
                      - type
                      - message
                      - more
                    properties:
                      type:
                        type: string
                        enum:
                          - budget.exceeded
                      message:
                        type: string
                      more:
                        type: string
                        enum:
                          - >-
                            https://docs.checkfu.com/reference/errors#budget-exceeded
                        description: >-
                          Stable public documentation and remedy for this error
                          type.
                    additionalProperties: false
                additionalProperties: false
        '500':
          description: >-
            An unexpected internal failure occurred; the message contains an
            opaque incident reference.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeInternalError'
      security:
        - bearerAuth: []
components:
  schemas:
    ComputerId:
      type: string
      allOf:
        - pattern: ^comp_[0-9a-f]{32}$
    CreateComputerHeadlessOperation:
      type: object
      properties:
        attachment_id:
          $ref: '#/components/schemas/ComputerAttachmentId'
        session_id:
          $ref: '#/components/schemas/SessionId'
        expected_mutation_epoch:
          type: integer
          allOf:
            - minimum: 0
        deadline:
          $ref: '#/components/schemas/CurrentTimestamp'
        operation:
          $ref: '#/components/schemas/ComputerHeadlessOperationIntent'
        ingress:
          $ref: '#/components/schemas/ComputerHeadlessOperationIngress'
      required:
        - attachment_id
        - session_id
        - expected_mutation_epoch
        - deadline
        - operation
        - ingress
      additionalProperties: false
      description: >-
        Caller-selected headless operation ingress: the exact Computer
        attachment, its Session, the mutation-epoch fence, a short deadline, the
        operation itself, and whether authority is proven by the owning Run
        (whose id the ingress carries) or a terminal ingress grant (whose token
        rides the request headers). The server derives identity, generation,
        clocks, and provenance.
    ComputerHeadlessOperationAdmission:
      type: object
      properties:
        operation_id:
          $ref: '#/components/schemas/ComputerOperationId'
        disposition:
          type: string
          enum:
            - dispatched
            - queued
            - settled
        replayed:
          type: boolean
      required:
        - operation_id
        - disposition
        - replayed
      additionalProperties: false
      description: >-
        Admission receipt for one headless Computer operation: the
        server-derived operation identity, whether the Computer's serialized
        mutation slot dispatched or queued it, and whether the request replayed
        an existing admission.
    WorkspaceId:
      type: string
      allOf:
        - pattern: ^wrkspc_[0-9a-f]{32}$
    PolicyDeniedError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - policy.denied
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#policy-denied
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: Deployment governance or retention policy denied the request.
    ValidationNotFoundError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.not_found
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-not-found
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        The requested resource does not exist in the resolved deployment
        boundary.
    ValidationConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.conflict
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#validation-conflict
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: The request conflicts with the resource's current state.
    IdempotencyConflictError:
      anyOf:
        - $ref: '#/components/schemas/ValidationIdempotencyConflictError'
        - $ref: '#/components/schemas/ValidationIdempotencyInProgressError'
      description: >-
        An idempotent mutation conflicts with a completed or in-progress request
        for the same key.
    RuntimeInternalError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - runtime.internal
            message:
              type: string
            more:
              type: string
              enum:
                - https://docs.checkfu.com/reference/errors#runtime-internal
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        An unexpected internal failure occurred; the message contains an opaque
        incident reference.
    ComputerAttachmentId:
      type: string
      allOf:
        - pattern: ^catt_[0-9a-f]{32}$
    SessionId:
      type: string
      allOf:
        - pattern: ^sess_[0-9a-f]{32}$
    CurrentTimestamp:
      type: string
      allOf:
        - maxLength: 24
        - pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$
          description: A canonical UTC ISO-8601 timestamp with millisecond precision.
    ComputerHeadlessOperationIntent:
      anyOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - filesystem_write
            path:
              type: string
              allOf:
                - maxLength: 4096
            content_digest:
              type: string
              allOf:
                - pattern: ^sha256:[0-9a-f]{64}$
            byte_length:
              type: integer
              allOf:
                - minimum: 0
                - maximum: 16777216
          required:
            - type
            - path
            - content_digest
            - byte_length
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - filesystem_remove
            path:
              type: string
              allOf:
                - maxLength: 4096
            recursive:
              type: boolean
          required:
            - type
            - path
            - recursive
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - process_start
            executable:
              type: string
              allOf:
                - maxLength: 4096
                - pattern: >-
                    ^\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+)*$
            working_directory:
              type: string
              allOf:
                - maxLength: 4096
                - pattern: >-
                    ^\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+(?:\/(?!\.{1,2}(?:\/|$))[A-Za-z0-9._-]+)*$
            arguments:
              $ref: '#/components/schemas/HarnessProcessArgumentVectorUtf8Bytes'
          required:
            - type
            - executable
            - working_directory
            - arguments
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - process_inspect
            process_id:
              type: string
              allOf:
                - minLength: 1
                - maxLength: 255
                - pattern: ^\S+$
          required:
            - type
            - process_id
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - process_signal
            process_id:
              type: string
              allOf:
                - minLength: 1
                - maxLength: 255
                - pattern: ^\S+$
            signal:
              type: string
              enum:
                - interrupt
                - terminate
                - kill
          required:
            - type
            - process_id
            - signal
          additionalProperties: false
      description: >-
        One mutating headless Computer operation: a filesystem write or remove
        with its content-addressed digest, or a process start, inspect, or
        signal. Paths stay inside the attached workspace's mutable tree and
        every bound is enforced at admission.
    ComputerHeadlessOperationIngress:
      anyOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - session_run
            run_id:
              $ref: '#/components/schemas/RunId'
          required:
            - type
            - run_id
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - terminal_grant
          required:
            - type
          additionalProperties: false
      description: >-
        The provenance one headless operation ingress carries: either the
        Session Run whose live attempt-and-lease authority is revalidated by the
        owning Session, or a terminal Computer ingress grant whose token rides
        the request headers.
    ComputerOperationId:
      type: string
      allOf:
        - pattern: ^cop_[0-9a-f]{32}$
    ValidationIdempotencyConflictError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.idempotency_conflict
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-conflict
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: The Idempotency-Key is already bound to a different request.
    ValidationIdempotencyInProgressError:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - validation.idempotency_in_progress
            message:
              type: string
            more:
              type: string
              enum:
                - >-
                  https://docs.checkfu.com/reference/errors#validation-idempotency-in-progress
              description: Stable public documentation and remedy for this error type.
          required:
            - type
            - message
            - more
          additionalProperties: false
      required:
        - error
      additionalProperties: false
      description: >-
        An identical idempotent request is still in progress and may be retried
        later.
    HarnessProcessArgumentVectorUtf8Bytes:
      type: array
      items:
        $ref: '#/components/schemas/HarnessProcessArgumentUtf8Bytes'
      allOf:
        - maxItems: 256
          description: >-
            At most 256 exact process arguments and 131072 aggregate UTF-8 bytes
            including one terminator per argument
    RunId:
      type: string
      allOf:
        - pattern: ^run_[0-9a-f]{32}$
    HarnessProcessArgumentUtf8Bytes:
      type: string
      allOf:
        - maxLength: 65536
        - pattern: ^[^\u0000]*$
          description: >-
            Exact process argument text, preserving whitespace; U+0000 is
            forbidden and UTF-8 encoding is limited to 65536 bytes
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````