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

# Update a computer

> Changes one of the caller's computers: renames it, the name Aether shows it by wherever its work trees are listed, turns off its "let Aether start agents here" switch, so Aether starts no agent there, turns off its "changes from other devices" switch, so no other device opens a terminal or changes a file there, or resets it. What the body leaves out keeps.

Use this tool when you need to:
- Give a computer a name other than its host's, or tell two computers with one host name apart
- Stop Aether from starting agents on a computer, from the web app or the phone
- Stop other devices from opening a terminal or changing files on a computer, from the web app or the phone
- Cut off a copy of the computer's secret, from a backup or a copied folder, from the web app or the phone

Examples:
- PATCH /computers/{computerID} {"name": "Studio desktop"}
- PATCH /computers/{computerID} {"agent_starts": {"state": "off"}}
- PATCH /computers/{computerID} {"remote_changes": {"state": "off"}}
- PATCH /computers/{computerID} {"set_up": false}

Hints:
- The body holds name, agent_starts, remote_changes, set_up, or more than one, and at least one.
- set_up takes false alone, which resets the computer: in one transaction its secret is cleared, both switches turned off and its connection ended. It is unreachable at once: a poll its machine bridge holds answers 409 computer_connection_ended, and what is sent to it is not handed to the bridge. The bridge is refused with 403 computer_needs_setup until aether setup runs on the computer, which sets a new secret. set_up_at reads null until then. A reset ends no sign-in: signing out everywhere ends those. A reset e-mails the person, whatever their notification settings say.
- A reset takes a web or phone sign-in: an API key is refused with 403 credential_kind_not_admitted, and nothing in the body is changed.
- name is 1 to 100 characters with no surrounding space, no control or format character and no "://"; another is refused with 422. Registering the computer again with aether setup names it after its host again.
- agent_starts is the switch as listComputers lists it. A session or an API key only turns it off, {"state": "off"}: {"state": "on", "limit": 1..16} is refused with 403 agent_starts_on_from_computer_only, and nothing in the body is changed. Only the computer itself turns it on: run `aether computer agents on` (with --limit N for the most agents at once, 1 by default) in a terminal there.
- remote_changes is the switch as listComputers lists it. A session or an API key only turns it off, {"state": "off"}: {"state": "on"} is refused with 403 remote_changes_on_from_computer_only, and nothing in the body is changed. Only the computer itself turns it on: run `aether computer remote-changes on` in a terminal there. Turning it off ends every open live connection to the computer, closed with 4403 access_ended, and the bridge kills their shells.
- Setting a switch to the state it has changes nothing.
- A computerID that is not one of the caller's computers is refused with 404 not_found.
- Answers the computer as listComputers lists it.
- The caller changes a computer with a session, or an API key for all but a reset; a grant is refused with 403 credential_kind_not_admitted.



## OpenAPI

````yaml api-reference/openapi.json PATCH /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}:
    patch:
      tags:
        - computers
      summary: Update a computer
      description: >-
        Changes one of the caller's computers: renames it, the name Aether shows
        it by wherever its work trees are listed, turns off its "let Aether
        start agents here" switch, so Aether starts no agent there, turns off
        its "changes from other devices" switch, so no other device opens a
        terminal or changes a file there, or resets it. What the body leaves out
        keeps.


        Use this tool when you need to:

        - Give a computer a name other than its host's, or tell two computers
        with one host name apart

        - Stop Aether from starting agents on a computer, from the web app or
        the phone

        - Stop other devices from opening a terminal or changing files on a
        computer, from the web app or the phone

        - Cut off a copy of the computer's secret, from a backup or a copied
        folder, from the web app or the phone


        Examples:

        - PATCH /computers/{computerID} {"name": "Studio desktop"}

        - PATCH /computers/{computerID} {"agent_starts": {"state": "off"}}

        - PATCH /computers/{computerID} {"remote_changes": {"state": "off"}}

        - PATCH /computers/{computerID} {"set_up": false}


        Hints:

        - The body holds name, agent_starts, remote_changes, set_up, or more
        than one, and at least one.

        - set_up takes false alone, which resets the computer: in one
        transaction its secret is cleared, both switches turned off and its
        connection ended. It is unreachable at once: a poll its machine bridge
        holds answers 409 computer_connection_ended, and what is sent to it is
        not handed to the bridge. The bridge is refused with 403
        computer_needs_setup until aether setup runs on the computer, which sets
        a new secret. set_up_at reads null until then. A reset ends no sign-in:
        signing out everywhere ends those. A reset e-mails the person, whatever
        their notification settings say.

        - A reset takes a web or phone sign-in: an API key is refused with 403
        credential_kind_not_admitted, and nothing in the body is changed.

        - name is 1 to 100 characters with no surrounding space, no control or
        format character and no "://"; another is refused with 422. Registering
        the computer again with aether setup names it after its host again.

        - agent_starts is the switch as listComputers lists it. A session or an
        API key only turns it off, {"state": "off"}: {"state": "on", "limit":
        1..16} is refused with 403 agent_starts_on_from_computer_only, and
        nothing in the body is changed. Only the computer itself turns it on:
        run `aether computer agents on` (with --limit N for the most agents at
        once, 1 by default) in a terminal there.

        - remote_changes is the switch as listComputers lists it. A session or
        an API key only turns it off, {"state": "off"}: {"state": "on"} is
        refused with 403 remote_changes_on_from_computer_only, and nothing in
        the body is changed. Only the computer itself turns it on: run `aether
        computer remote-changes on` in a terminal there. Turning it off ends
        every open live connection to the computer, closed with 4403
        access_ended, and the bridge kills their shells.

        - Setting a switch to the state it has changes nothing.

        - A computerID that is not one of the caller's computers is refused with
        404 not_found.

        - Answers the computer as listComputers lists it.

        - The caller changes a computer with a session, or an API key for all
        but a reset; a grant is refused with 403 credential_kind_not_admitted.
      operationId: updateComputer
      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:
                agent_starts:
                  $ref: '#/components/schemas/ComputerAgentStarts'
                name:
                  maxLength: 100
                  minLength: 1
                  type: string
                  x-aether-string-length-unit: unicode-code-point
                remote_changes:
                  $ref: '#/components/schemas/ComputerRemoteChanges'
                set_up:
                  $ref: '#/components/schemas/ComputerReset'
              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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Not Found
        '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:
    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'
    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'
    ComputerReset:
      description: >-
        false resets the computer: its secret is cleared, its agent starts and
        its remote changes turn off and its connection ends, until aether setup
        runs on it again.
      enum:
        - false
      type: boolean
    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
    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
    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
    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
    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
    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
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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