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

# Create a runner

> Registers a runner of your own and returns its `token`, once. Start the runner with it; it connects out to GuidingHand and serves only your org. Needs the admin role or an API key.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/runners
openapi: 3.1.0
info:
  title: GuidingHand API
  version: 1.0.0
  description: >-
    Create sessions (an invite link with a code for the person at the computer),
    run tasks on their computer with one of your agents, follow them, answer
    their questions and approvals, and fetch history and recordings. Test your
    agents with evals: test cases on fresh machines, run in test sets, scored by
    a check script or a rubric. Agents are versioned (save a draft, publish it),
    have tools (their own file system, and your HTTP endpoints), and every
    change is in the org’s audit log.
servers:
  - url: https://guidinghand.ai
    description: Production
  - url: https://dev.guidinghand.ai
    description: Development (Stripe test mode)
security:
  - bearerAuth: []
tags:
  - name: Agents
  - name: Agent files
  - name: Agent tools
  - name: Sessions
  - name: Tasks
  - name: Webhooks
  - name: Audit log
  - name: Test cases
  - name: Test sets
  - name: Test runs
  - name: Start states
  - name: Runners
paths:
  /v1/runners:
    post:
      tags:
        - Runners
      summary: Create a runner
      description: >-
        Registers a runner of your own and returns its `token`, once. Start the
        runner with it; it connects out to GuidingHand and serves only your org.
        Needs the admin role or an API key.
      operationId: createRunner
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 80
                  example: lenovo-lab-1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunnerCreated'
        '400':
          $ref: '#/components/responses/E400'
        '401':
          $ref: '#/components/responses/E401'
        '403':
          $ref: '#/components/responses/E403'
components:
  schemas:
    RunnerCreated:
      allOf:
        - $ref: '#/components/schemas/Runner'
        - type: object
          properties:
            token:
              type: string
              description: The runner’s token (`gh_rn_…`). Shown once.
    Runner:
      type: object
      description: >-
        A process next to a hypervisor that makes, runs and saves test machines.
        It connects out to GuidingHand.
      properties:
        object:
          const: runner
        runner_id:
          type: string
          example: rn_T2Lc0aQ3Vb7s
        name:
          type: string
          example: lenovo-lab-1
        scope:
          type: string
          enum:
            - org
            - cloud
          description: >-
            `org`: your own, serving only your org. `cloud`: GuidingHand’s,
            serving every org. Attempts go to your own runners first.
        status:
          type: string
          enum:
            - online
            - offline
        provider:
          type:
            - string
            - 'null'
          example: qemu
        labels:
          type: array
          items:
            type: string
          example:
            - vm
        slots:
          type: integer
          description: Machines it runs at once.
        busy:
          type: integer
        images:
          type: array
          items:
            type: string
          example:
            - win10-22h2
        version:
          type:
            - string
            - 'null'
        last_seen_at:
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - message
          properties:
            type:
              type: string
              enum:
                - invalid_request
                - authentication
                - payment_required
                - permission
                - not_found
                - conflict
                - rate_limit
                - server_error
            message:
              type: string
            code:
              type: string
              description: >-
                Why it was refused, when there’s more to say than the status.
                Starting a task: `insufficient_balance`,
                `auto_topup_limit_reached` or `card_needs_attention` (402: the
                balance can’t cover a minute; add funds, raise the auto top-up
                limit, or update the card), `concurrency_limit` (429),
                `model_unavailable` (503: the agent’s `model` can’t run on this
                server; choose another). On `/respond`: `already_answered`
                (someone answered or decided first: see `answered_by`) or
                `not_pending` (that question or approval isn’t open any more).
                The GuidingHand app hears two more, which the API never returns:
                `customer_answers_off` and `customer_approvals_off` (the agent
                keeps its questions or approvals for your team). Deleting a
                start state that test cases use: `in_use` (409, with
                `test_case_ids`).
            answered_by:
              type: string
              enum:
                - customer
                - operator
                - timeout
              description: >-
                With `already_answered`: who answered or decided first
                (`customer`: the person at the computer; `timeout`: nobody
                decided an approval within the agent’s
                `approval_timeout_minutes`, so it was denied).
            test_case_ids:
              type: array
              items:
                type: string
              description: 'With `in_use`: the test cases that use the start state.'
  responses:
    E400:
      description: The request is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E401:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    E403:
      description: Your role can’t do this.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An org API key (`gh_live_…`) from Settings → API keys in the console.

````