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

# Register a computer

> Registers the computer the caller runs aether setup on, under the id its CLI chose and keeps, with a name: the host name unless they chose another.

Use this tool when you need to:
- Register this computer so that work-tree tasks can live in its checkouts
- Name this computer again after registering it

Examples:
- PUT /computers/{computerID} {"name": "Ada's MacBook Pro", "secret": "<the 64 hex characters aether setup made>"}
- PUT /computers/0f3c9d2a-6b1e-4c7d-8a5f-2e9b1d4c6a08 {"name": "studio"}, with the computer's secret in Aether-Computer-Secret

Hints:
- computerID is a lowercase uuid the CLI chose once on the computer; registering the same id again is idempotent: it keeps the computer, sets its name and records it seen, and answers 200 with it.
- name is 1 to 100 characters with no surrounding space, no control or format character and no "://"; another is refused with 422.
- An id another person registered is refused with 409 computer_registered_to_another_person.
- secret, 64 lower-case hex characters, is the computer's own secret, which aether setup makes and keeps on it; the API keeps only its hash, and set_up_at says when it was set. Only a secret in the body makes a computer or sets the secret of one that has none, and only under a sign-in that began at most 15 minutes earlier: an older one is refused with 403 computer_needs_fresh_sign_in, and nothing is stored. A registration that sets the secret e-mails the person, whatever their notification settings say.
- A registration whose body carries no secret presents the one in its Aether-Computer-Secret header, as every call that names the computer does. It makes no computer and sets no secret: a new computer, or one that has no secret, is refused with 403 computer_needs_setup, and nothing is stored.
- For a computer that has a secret, under a sign-in of any age, the same secret, in the body or the header, is answered as the registration that set it was; another, or none, is refused with 403 computer_set_up_elsewhere.
- Only the grant of the caller's coding agent's bridge registers a computer, a write grant: a session or an API key is refused with 403 credential_kind_not_admitted, and a read grant with 403 grant_scope_insufficient.



## OpenAPI

````yaml api-reference/openapi.json PUT /computers/{computerID}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}:
    put:
      tags:
        - computers
      summary: Register a computer
      description: >-
        Registers the computer the caller runs aether setup on, under the id its
        CLI chose and keeps, with a name: the host name unless they chose
        another.


        Use this tool when you need to:

        - Register this computer so that work-tree tasks can live in its
        checkouts

        - Name this computer again after registering it


        Examples:

        - PUT /computers/{computerID} {"name": "Ada's MacBook Pro", "secret":
        "<the 64 hex characters aether setup made>"}

        - PUT /computers/0f3c9d2a-6b1e-4c7d-8a5f-2e9b1d4c6a08 {"name":
        "studio"}, with the computer's secret in Aether-Computer-Secret


        Hints:

        - computerID is a lowercase uuid the CLI chose once on the computer;
        registering the same id again is idempotent: it keeps the computer, sets
        its name and records it seen, and answers 200 with it.

        - name is 1 to 100 characters with no surrounding space, no control or
        format character and no "://"; another is refused with 422.

        - An id another person registered is refused with 409
        computer_registered_to_another_person.

        - secret, 64 lower-case hex characters, is the computer's own secret,
        which aether setup makes and keeps on it; the API keeps only its hash,
        and set_up_at says when it was set. Only a secret in the body makes a
        computer or sets the secret of one that has none, and only under a
        sign-in that began at most 15 minutes earlier: an older one is refused
        with 403 computer_needs_fresh_sign_in, and nothing is stored. A
        registration that sets the secret e-mails the person, whatever their
        notification settings say.

        - A registration whose body carries no secret presents the one in its
        Aether-Computer-Secret header, as every call that names the computer
        does. It makes no computer and sets no secret: a new computer, or one
        that has no secret, is refused with 403 computer_needs_setup, and
        nothing is stored.

        - For a computer that has a secret, under a sign-in of any age, the same
        secret, in the body or the header, is answered as the registration that
        set it was; another, or none, is refused with 403
        computer_set_up_elsewhere.

        - Only the grant of the caller's coding agent's bridge registers a
        computer, a write grant: a session or an API key is refused with 403
        credential_kind_not_admitted, and a read grant with 403
        grant_scope_insufficient.
      operationId: registerComputer
      parameters:
        - in: path
          name: computerID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                name:
                  maxLength: 100
                  minLength: 1
                  type: string
                  x-aether-string-length-unit: unicode-code-point
                secret:
                  description: >-
                    The computer's own secret, 32 random bytes as 64 lower-case
                    hex characters (^[0-9a-f]{64}$), which aether setup made and
                    keeps on it.
                  type: string
              required:
                - name
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Computer'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ComputersErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Internal Server Error
components:
  schemas:
    Computer:
      additionalProperties: false
      properties:
        agent_starts:
          $ref: '#/components/schemas/ComputerAgentStarts'
        agents:
          description: >-
            The agents the computer's machine bridge declared as it last
            connected, kept while the computer is unreachable; none for a bridge
            that declared nothing.
          items:
            $ref: '#/components/schemas/ComputerAgent'
          type: array
        bridge:
          $ref: '#/components/schemas/ComputerBridge'
        id:
          format: uuid
          type: string
        last_seen_at:
          format: date-time
          type: string
        name:
          maxLength: 100
          minLength: 1
          type: string
          x-aether-string-length-unit: unicode-code-point
        reachable:
          description: Whether the computer's machine bridge is connected to Aether.
          type: boolean
        registered_at:
          format: date-time
          type: string
        remote_changes:
          $ref: '#/components/schemas/ComputerRemoteChanges'
        set_up_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: >-
            When aether setup last set the computer's own secret; null while it
            has none.
      required:
        - id
        - name
        - reachable
        - registered_at
        - last_seen_at
        - set_up_at
        - bridge
        - agent_starts
        - remote_changes
        - agents
      type: object
    ComputersErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - agent_starts_on_from_computer_only
            - agent_uses_own_sign_in
            - answer_on_its_way
            - app_identity_missing
            - attachments_unsupported
            - attribution_unavailable
            - bad_gateway
            - bad_request
            - base_branch_unusable
            - branch_exists
            - caller_inactive
            - chat_archived
            - chat_being_forked
            - chat_moved
            - chat_not_removable
            - chat_settings_fixed
            - chats_not_addable
            - checkout_not_archivable
            - cli_upgrade_required
            - client_outdated
            - computer_cli_outdated
            - computer_needs_fresh_sign_in
            - computer_needs_setup
            - computer_registered_to_another_person
            - computer_set_up_elsewhere
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_task_start_moved
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - credential_kind_not_admitted
            - credential_named_file
            - detached_head
            - download_unsupported
            - embeddings_unavailable
            - feature_unsupported
            - file_references_unsupported
            - fix_not_requested
            - fix_requests_unrecorded
            - forbidden
            - fork_branch_delete_unsupported
            - fork_forbidden
            - fork_in_progress
            - fork_unsupported
            - gateway_timeout
            - github_failed
            - github_identity_required
            - github_push_access_required
            - gone
            - handed_branch_protected
            - head_moved
            - html_render_nul_byte
            - html_render_too_large
            - idempotency_key_conflict
            - idempotency_key_reused
            - idle_compaction_not_pending
            - idle_compaction_skipped
            - inference_proxy_unavailable
            - insufficient_credits
            - insufficient_inference_balance
            - interaction_mode_unsupported
            - internal_error
            - invalid_request
            - last_queued_message
            - live_protocol_unsupported
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - message_not_waiting
            - method_not_allowed
            - mode_forbidden
            - name_follows_session
            - no_checkout_on_computer
            - no_checkpoint_yet
            - no_commit
            - no_dispatch_target
            - no_main_chat
            - no_origin
            - no_work_tree_folder
            - not_acceptable
            - not_found
            - not_implemented
            - onboarding_already_completed
            - onboarding_requirements_missing
            - open_in_terminal
            - org_id_required
            - org_role_insufficient
            - org_suspended
            - payment_required
            - pending_input_answered
            - permission_prompt_open
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_not_a_choice
            - project_required
            - prompt_decisions_refused
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - remote_changes_on_from_computer_only
            - repository_not_connected
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - service_unavailable
            - session_file_generation
            - session_file_hole
            - session_file_missing
            - session_file_range_differs
            - session_gone
            - session_not_started_by_aether
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - start_cancelled
            - stream_delivery_gap
            - stream_event_conflict
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_connection_disconnected
            - task_creator_deleted
            - task_has_no_branch
            - task_has_no_repository
            - task_ineligible
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_prompt_closed_otherwise
            - terminal_chat_prompt_differs
            - terminal_chat_prompt_not_answered
            - terminal_chat_removed
            - terminal_chat_run_moved
            - terminal_question
            - too_large
            - too_many_live_connections
            - too_many_waiting_messages
            - turn_running
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - user_suspended
            - validation_failed
            - work_tree_repository_differs
            - workspace_git_unavailable
            - workspace_gone
            - workspace_outdated
            - workspace_rejected
            - workspace_start_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    ComputerAgentStarts:
      description: >-
        The computer's "let Aether start agents here" switch: off, or on with
        the most agents Aether runs on it at once.
      discriminator:
        mapping:
          'off': '#/components/schemas/ComputerAgentStartsOff'
          'on': '#/components/schemas/ComputerAgentStartsOn'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/ComputerAgentStartsOff'
        - $ref: '#/components/schemas/ComputerAgentStartsOn'
    ComputerAgent:
      additionalProperties: false
      properties:
        agent_type:
          description: >-
            The agent's id: the catalog's for an agent Aether knows
            (claude-code), and as the bridge declared it for another.
          pattern: ^[a-z][a-z0-9_-]{0,63}$
          type: string
        label:
          description: >-
            The agent's name: the catalog's for an agent Aether knows, and its
            id for another.
          minLength: 1
          type: string
        problem:
          anyOf:
            - $ref: '#/components/schemas/ComputerAgentProblem'
            - type: 'null'
          description: >-
            Why Aether cannot start the agent on the computer, as the bridge
            found it as it connected; null when it found none, which includes a
            check it could not finish in time: null is no known problem, not a
            check that passed. It refuses nothing: whether a start runs is found
            on the computer each time.
        version:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The agent's own version on the computer; null when the bridge could
            not read it.
      required:
        - agent_type
        - label
        - version
        - problem
      type: object
    ComputerBridge:
      additionalProperties: false
      properties:
        problem:
          anyOf:
            - $ref: '#/components/schemas/ComputerProblem'
            - type: 'null'
          description: >-
            What its person fixes on the computer with the aether CLI there;
            null for nothing. A computer whose bridge failed to update itself is
            still reachable while that bridge is connected. Every refusal that
            the computer is not connected carries its message.
        version:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The release of the aether CLI the computer's machine bridge last
            connected with, kept once the connection ends; null while none is on
            record.
      required:
        - version
        - problem
      type: object
    ComputerRemoteChanges:
      description: >-
        The computer's "changes from other devices" switch: on, a live
        connection from another device may open a terminal and change the files
        of its task on the computer; off, it may not. Only the computer itself
        turns it on.
      discriminator:
        mapping:
          'off': '#/components/schemas/ComputerRemoteChangesOff'
          'on': '#/components/schemas/ComputerRemoteChangesOn'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/ComputerRemoteChangesOff'
        - $ref: '#/components/schemas/ComputerRemoteChangesOn'
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    ComputerAgentStartsOff:
      additionalProperties: false
      properties:
        state:
          enum:
            - 'off'
          type: string
      required:
        - state
      type: object
    ComputerAgentStartsOn:
      additionalProperties: false
      properties:
        limit:
          description: The most agents Aether runs on the computer at once.
          maximum: 16
          minimum: 1
          type: integer
        state:
          enum:
            - 'on'
          type: string
      required:
        - state
        - limit
      type: object
    ComputerAgentProblem:
      additionalProperties: false
      properties:
        code:
          description: >-
            An open set: agent_not_installed when the bridge finds no such agent
            on the computer; not_signed_in when it is not signed in there. On a
            computer's agent, the message is the API's own for a code it knows;
            for another, the bridge's only when it is at most 200 characters,
            holds no control character and names no link, address or domain, and
            otherwise the API's sentence that the agent is not available there.
          pattern: ^[a-z][a-z0-9_]*$
          type: string
        message:
          description: What to do on the computer, for its person.
          maxLength: 500
          minLength: 1
          type: string
      required:
        - code
        - message
      type: object
    ComputerProblem:
      additionalProperties: false
      properties:
        code:
          description: >-
            computer_needs_setup while the computer has no secret;
            computer_cli_outdated while the release its machine bridge last
            connected with is older than the oldest aether CLI Aether serves, or
            while that bridge last declared that it failed to update itself to
            the installed aether CLI. The first is shown when both hold.
          enum:
            - computer_needs_setup
            - computer_cli_outdated
          type: string
        message:
          description: What to run on the computer, for its person.
          minLength: 1
          type: string
      required:
        - code
        - message
      type: object
    ComputerRemoteChangesOff:
      additionalProperties: false
      properties:
        state:
          enum:
            - 'off'
          type: string
      required:
        - state
      type: object
    ComputerRemoteChangesOn:
      additionalProperties: false
      properties:
        state:
          enum:
            - 'on'
          type: string
      required:
        - state
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.