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

# List your computers

> Lists the computers the caller registered with aether setup, oldest first: where their work-tree tasks live.

Use this tool when you need to:
- Name the computer a work-tree task lives on, from the computer_id its machine carries
- Tell whether a computer is reachable, and when it was last seen
- Check from a computer whether aether setup registered it

Examples:
- GET /computers

Hints:
- There are no parameters; the list is the caller's alone and is returned whole as {items}.
- reachable is whether the computer's machine bridge is connected to Aether: it is while the bridge's connection lives, and stops at once when the bridge disconnects, or 20 seconds after the hold of its last poll ends (at most 45 seconds after that poll began) when the bridge stops polling without disconnecting. last_seen_at is when the computer last registered, connected or polled.
- Use registerComputer to register a computer, updateComputer to rename one or turn off its agent starts, removeComputer to remove one, and findWorkTreeTask to find the task of a checkout on one.
- The caller may list with a session, an API key, or the grant of their coding agent's bridge.



## OpenAPI

````yaml api-reference/openapi.json GET /computers
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers:
    get:
      tags:
        - computers
      summary: List your computers
      description: >-
        Lists the computers the caller registered with aether setup, oldest
        first: where their work-tree tasks live.


        Use this tool when you need to:

        - Name the computer a work-tree task lives on, from the computer_id its
        machine carries

        - Tell whether a computer is reachable, and when it was last seen

        - Check from a computer whether aether setup registered it


        Examples:

        - GET /computers


        Hints:

        - There are no parameters; the list is the caller's alone and is
        returned whole as {items}.

        - reachable is whether the computer's machine bridge is connected to
        Aether: it is while the bridge's connection lives, and stops at once
        when the bridge disconnects, or 20 seconds after the hold of its last
        poll ends (at most 45 seconds after that poll began) when the bridge
        stops polling without disconnecting. last_seen_at is when the computer
        last registered, connected or polled.

        - Use registerComputer to register a computer, updateComputer to rename
        one or turn off its agent starts, removeComputer to remove one, and
        findWorkTreeTask to find the task of a checkout on one.

        - The caller may list with a session, an API key, or the grant of their
        coding agent's bridge.
      operationId: listComputers
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Computer'
                    type: array
                required:
                  - items
                type: object
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '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.