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

# Open a live connection to a task's machine

> Opens a live connection to the machine a task runs on, and answers ready with the socket's address and a ticket, starting while its sandbox is on its way up, or stopped.

Use this tool when you need to:
- Open the live socket that carries a task's files, git, terminals, ports, live agent text and activity
- Start a task's stopped sandbox, once the person chose to, and follow it until it is up

Examples:
- POST /tasks/{taskID}/connect {"protocols": [1]}
- POST /tasks/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/connect {"start_sandbox": true, "protocols": [1, 2]}

Hints:
- taskID is the task's lowercase uuid; protocols is required, the live protocol versions the client speaks (422 from the schema when missing or empty); start_sandbox is optional, false by default, so opening a page never starts a sandbox.
- Answers 200 with a union on state: ready carries live_connection_id, websocket_url, a ticket, ticket_expires_at, protocol, frame_key (null for a sandbox) and preview_url_template; starting carries since, retry_after_ms and waiting (sandbox_starting, sandbox_preparing, sandbox_stopping or sandbox_suspending, with a sentence): call again after the delay; stopped means the sandbox is stopped and start_sandbox was false: offer to start it, then call again with start_sandbox true.
- Dial websocket_url within 30 seconds, offering the WebSocket subprotocols bearer and the ticket, never in an address; the ticket opens one socket once. Every attempt to open a socket starts with a fresh call. For a sandbox, protocol is the highest one both the client and the sandbox's run speak; every sandbox speaks protocol 1, so a client that does not list 1 is refused with 409 live_protocol_unsupported.
- A task on a computer answers ready or is refused, never starting or stopped: websocket_url is the relay's, which joins the client's socket to the computer's machine bridge; protocol is the highest one both the client and that bridge list (409 live_protocol_unsupported when none); frame_key is 64 lower-case hex characters, the key that seals every frame between the two ends, which the relay never sees; preview_url_template is null. A computer whose bridge is not connected is refused with 409 computer_unreachable, and one whose bridge serves no live connection with 409 computer_cli_outdated: update the aether CLI there. At most 8 live connections are open to one computer: beyond them the call is refused with 409 too_many_live_connections; a connection the relay does not hold stops counting once its ticket has run out and the relay, asked at the cap or by the lease every 30 seconds, answers; while the relay cannot be asked it keeps counting. Try again with backoff.
- The task's can.connect_live shows every refusal before the call: 409 task_start_pending, task_start_failed, sandbox_deleted, sandbox_failed, sandbox_needs_message or task_creator_deleted, and for a task on a computer 409 computer_cli_outdated or computer_unreachable. sandbox_needs_message is a sandbox that is not running and that only the task's next message starts: it has no machine, or the task errored (a start never revives an errored task). The call answers the same codes for a task that changed since it was read.
- A start that a stop or suspend of the sandbox still holds answers starting (sandbox_stopping or sandbox_suspending, since that stop or suspend began).
- A start the platform has no room for right now is 503 with Retry-After in seconds: call again after it.
- A start that runtime admission refuses is a 402 whose code is the refusal kind (billing_blocked, org_task_concurrency_exceeded, credits_exhausted or workspace_run_unavailable), with tier, vm_size and org_id.
- Use getTask instead to read can.connect_live without opening anything.
- Restricted to the task's creator or an owner or admin of its organization, with a web or phone sign-in or an API key: another member is refused with 403 control_forbidden, a viewer or billing member with 403 org_role_insufficient, a suspended account or organization with 403 user_suspended or org_suspended, an agent's or a client app's grant, or a sign-in that names no session, with 403 credential_kind_not_admitted, and a task the caller cannot see is 404; a sign-in whose session has ended (signed out) is 401 unauthenticated, as authentication refuses a revoked API key; 503 when the membership or sign-in check is unavailable. A task on a computer is its person's alone, from a web or phone sign-in: an admin is refused with 403 control_forbidden, and an API key with 403 credential_kind_not_admitted.



## OpenAPI

````yaml api-reference/openapi.json POST /tasks/{taskID}/connect
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /tasks/{taskID}/connect:
    post:
      tags:
        - tasks
      summary: Open a live connection to a task's machine
      description: >-
        Opens a live connection to the machine a task runs on, and answers ready
        with the socket's address and a ticket, starting while its sandbox is on
        its way up, or stopped.


        Use this tool when you need to:

        - Open the live socket that carries a task's files, git, terminals,
        ports, live agent text and activity

        - Start a task's stopped sandbox, once the person chose to, and follow
        it until it is up


        Examples:

        - POST /tasks/{taskID}/connect {"protocols": [1]}

        - POST /tasks/6f1c2a9e-3b7d-4c55-9a2e-0d8b1f4e7c21/connect
        {"start_sandbox": true, "protocols": [1, 2]}


        Hints:

        - taskID is the task's lowercase uuid; protocols is required, the live
        protocol versions the client speaks (422 from the schema when missing or
        empty); start_sandbox is optional, false by default, so opening a page
        never starts a sandbox.

        - Answers 200 with a union on state: ready carries live_connection_id,
        websocket_url, a ticket, ticket_expires_at, protocol, frame_key (null
        for a sandbox) and preview_url_template; starting carries since,
        retry_after_ms and waiting (sandbox_starting, sandbox_preparing,
        sandbox_stopping or sandbox_suspending, with a sentence): call again
        after the delay; stopped means the sandbox is stopped and start_sandbox
        was false: offer to start it, then call again with start_sandbox true.

        - Dial websocket_url within 30 seconds, offering the WebSocket
        subprotocols bearer and the ticket, never in an address; the ticket
        opens one socket once. Every attempt to open a socket starts with a
        fresh call. For a sandbox, protocol is the highest one both the client
        and the sandbox's run speak; every sandbox speaks protocol 1, so a
        client that does not list 1 is refused with 409
        live_protocol_unsupported.

        - A task on a computer answers ready or is refused, never starting or
        stopped: websocket_url is the relay's, which joins the client's socket
        to the computer's machine bridge; protocol is the highest one both the
        client and that bridge list (409 live_protocol_unsupported when none);
        frame_key is 64 lower-case hex characters, the key that seals every
        frame between the two ends, which the relay never sees;
        preview_url_template is null. A computer whose bridge is not connected
        is refused with 409 computer_unreachable, and one whose bridge serves no
        live connection with 409 computer_cli_outdated: update the aether CLI
        there. At most 8 live connections are open to one computer: beyond them
        the call is refused with 409 too_many_live_connections; a connection the
        relay does not hold stops counting once its ticket has run out and the
        relay, asked at the cap or by the lease every 30 seconds, answers; while
        the relay cannot be asked it keeps counting. Try again with backoff.

        - The task's can.connect_live shows every refusal before the call: 409
        task_start_pending, task_start_failed, sandbox_deleted, sandbox_failed,
        sandbox_needs_message or task_creator_deleted, and for a task on a
        computer 409 computer_cli_outdated or computer_unreachable.
        sandbox_needs_message is a sandbox that is not running and that only the
        task's next message starts: it has no machine, or the task errored (a
        start never revives an errored task). The call answers the same codes
        for a task that changed since it was read.

        - A start that a stop or suspend of the sandbox still holds answers
        starting (sandbox_stopping or sandbox_suspending, since that stop or
        suspend began).

        - A start the platform has no room for right now is 503 with Retry-After
        in seconds: call again after it.

        - A start that runtime admission refuses is a 402 whose code is the
        refusal kind (billing_blocked, org_task_concurrency_exceeded,
        credits_exhausted or workspace_run_unavailable), with tier, vm_size and
        org_id.

        - Use getTask instead to read can.connect_live without opening anything.

        - Restricted to the task's creator or an owner or admin of its
        organization, with a web or phone sign-in or an API key: another member
        is refused with 403 control_forbidden, a viewer or billing member with
        403 org_role_insufficient, a suspended account or organization with 403
        user_suspended or org_suspended, an agent's or a client app's grant, or
        a sign-in that names no session, with 403 credential_kind_not_admitted,
        and a task the caller cannot see is 404; a sign-in whose session has
        ended (signed out) is 401 unauthenticated, as authentication refuses a
        revoked API key; 503 when the membership or sign-in check is
        unavailable. A task on a computer is its person's alone, from a web or
        phone sign-in: an admin is refused with 403 control_forbidden, and an
        API key with 403 credential_kind_not_admitted.
      operationId: connectTask
      parameters:
        - in: path
          name: taskID
          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:
              $ref: '#/components/schemas/ConnectTaskRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LiveConnection'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Unauthorized
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceRuntimeAdmissionError'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/TasksErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
                  - $ref: '#/components/schemas/ControlForbiddenErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Conflict
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Internal Server Error
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksErrorResponse'
          description: Service Unavailable
components:
  schemas:
    ConnectTaskRequest:
      additionalProperties: false
      properties:
        protocols:
          description: >-
            The live protocol versions the client speaks. The answer names the
            highest one the machine speaks too.
          items:
            format: int64
            type: integer
          maxItems: 8
          minItems: 1
          type: array
        start_sandbox:
          description: >-
            Start a stopped sandbox first. Send true once, on the first call
            after the person chose to start, and false or nothing on every later
            call of that attempt.
          type: boolean
      required:
        - protocols
      type: object
    LiveConnection:
      description: 'A live connection to the task''s machine: ready, starting or stopped.'
      discriminator:
        mapping:
          ready: '#/components/schemas/LiveConnectionReady'
          starting: '#/components/schemas/LiveConnectionStarting'
          stopped: '#/components/schemas/LiveConnectionStopped'
        propertyName: state
      oneOf:
        - $ref: '#/components/schemas/LiveConnectionReady'
        - $ref: '#/components/schemas/LiveConnectionStarting'
        - $ref: '#/components/schemas/LiveConnectionStopped'
    TasksErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - 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_starts_no_agents
            - computer_starts_no_forks
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - creator_github_access_missing
            - 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_claim_unverified
            - github_failed
            - github_identity_mismatch
            - github_identity_required
            - github_push_access_required
            - github_reconnect_required
            - github_ref_not_found
            - 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
            - 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_turn_running
            - 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_answered_in_terminal
            - permission_prompt_expired
            - permission_prompt_open
            - permission_prompt_stopped
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_archived
            - project_has_no_repository
            - project_repo_disconnected
            - project_repository_differs
            - project_required
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - push_file_too_large
            - push_rejected
            - push_secret_detected
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - repository_administration_not_granted
            - repository_already_connected
            - repository_create_forbidden
            - repository_create_rejected
            - repository_created_not_linked
            - repository_not_connected
            - repository_owner_not_caller
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - save_in_progress
            - save_requires_task_creator
            - service_unavailable
            - session_file_missing
            - session_gone
            - session_not_started_by_aether
            - slash_command
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - stream_delivery_gap
            - stream_event_conflict
            - task_already_saved
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_bound_at_creation
            - task_branch_diverged
            - task_branch_is_default
            - task_branch_mismatch
            - task_branch_missing
            - task_connection_disconnected
            - task_creator_deleted
            - task_executing
            - task_file_too_large
            - task_has_no_branch
            - task_has_no_commits
            - task_has_no_files
            - task_has_no_repository
            - task_history_has_merges
            - task_ineligible
            - task_is_child
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_rebase_in_progress
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_run_running
            - 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
            - working_tree_dirty
            - 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
    WorkspaceRuntimeAdmissionError:
      additionalProperties: false
      properties:
        code:
          enum:
            - user_suspended
            - org_suspended
            - billing_blocked
            - org_task_concurrency_exceeded
            - credits_exhausted
            - workspace_run_unavailable
          type: string
        error:
          minLength: 1
          type: string
        org_id:
          format: uuid
          type: string
        tier:
          enum:
            - free
            - starter
            - pro
            - max
            - team
          type:
            - string
            - 'null'
        vm_size:
          enum:
            - small
            - medium
            - large
            - xl
          type: string
      required:
        - error
        - code
        - tier
        - vm_size
        - org_id
      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
    ControlForbiddenErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - control_forbidden
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    LiveConnectionReady:
      additionalProperties: false
      properties:
        frame_key:
          description: >-
            The key that seals every frame of a socket the relay joins, a task
            on a computer's: 64 lower-case hex characters, the 32 bytes of a
            ChaCha20-Poly1305 key. Null: the API answers this socket itself, a
            sandbox's, and frames are not sealed.
          pattern: ^[0-9a-f]{64}$
          type:
            - string
            - 'null'
        live_connection_id:
          description: The connection's id.
          format: uuid
          type: string
        preview_url_template:
          description: >-
            The address of a port on the machine, with {port} in its leftmost
            label to fill with an integer from 1 to 65535, or null when the
            machine's ports cannot be reached from the client.
          type:
            - string
            - 'null'
        protocol:
          description: >-
            The live protocol version the socket speaks: the highest one both
            the client and the machine speak.
          enum:
            - 1
            - 2
          type: integer
        state:
          description: >-
            The machine can be dialled now: open the socket before
            ticket_expires_at.
          enum:
            - ready
          type: string
        ticket:
          description: >-
            Opens the socket once, until ticket_expires_at. Offer the WebSocket
            subprotocols bearer and the ticket; never put it in an address.
          pattern: ^live\.v1\.[0-9a-f-]{36}\.client\.[0-9]+\.[0-9a-f]{64}$
          type: string
        ticket_expires_at:
          description: >-
            When the ticket stops opening the socket, 30 seconds after this
            answer. It bounds opening the socket, not its life.
          format: date-time
          type: string
        websocket_url:
          description: >-
            The absolute wss (ws locally) address to dial:
            /live/{live_connection_id}.
          format: uri
          type: string
      required:
        - state
        - live_connection_id
        - websocket_url
        - ticket
        - ticket_expires_at
        - protocol
        - frame_key
        - preview_url_template
      type: object
    LiveConnectionStarting:
      additionalProperties: false
      properties:
        retry_after_ms:
          description: How long to wait before calling again.
          minimum: 1
          type: integer
        since:
          description: >-
            When the sandbox began what it waits on, from which a client counts
            its own deadline.
          format: date-time
          type: string
        state:
          description: >-
            The sandbox is on its way up, or between two states: call again
            after retry_after_ms.
          enum:
            - starting
          type: string
        waiting:
          additionalProperties: false
          description: What the sandbox waits on, and the sentence a person reads.
          properties:
            code:
              enum:
                - sandbox_starting
                - sandbox_preparing
                - sandbox_stopping
                - sandbox_suspending
              type: string
            message:
              minLength: 1
              type: string
          required:
            - code
            - message
          type: object
      required:
        - state
        - since
        - retry_after_ms
        - waiting
      type: object
    LiveConnectionStopped:
      additionalProperties: false
      properties:
        state:
          description: >-
            The sandbox is stopped and start_sandbox was false: offer to start
            it, then call again with start_sandbox true.
          enum:
            - stopped
          type: string
      required:
        - state
      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
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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