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

# Choose what your agent runs on and its model

> Points your agent at Aether inference or one of your connections, and sets the model it converses on; both are required. aether runs on Aether inference, paid from your balance and held to the daily cap, and serves Claude models; stored runs on the connection connection_id names: a Claude plan or an Anthropic API key for Claude models, an OpenAI API key for GPT models, none paid from your balance or held to the cap. Scheduled jobs use Claude Haiku 5.5 or GPT-6 Luna, from the model's family. A changed selection restarts a running agent; the same selection issues nothing. 422 for a write outside the two shapes or an unknown value, and 400 model_not_on_aether_inference for a GPT model on Aether inference. 404 connection_not_found for a connection you do not hold. 409 connection_kind_not_runnable for a connection your agent cannot run on (a ChatGPT plan, an OpenCode auth file, an OpenRouter API key), and 409 connection_not_of_agent_family for a connection serving the other family than the model's. 409 agent_credential_unreadable while the connection cannot be read; 409 agent_host_illegal_transition while going to sleep or pausing.



## OpenAPI

````yaml api-reference/openapi.json PUT /agent/inference
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /agent/inference:
    put:
      tags:
        - agent
      summary: Choose what your agent runs on and its model
      description: >-
        Points your agent at Aether inference or one of your connections, and
        sets the model it converses on; both are required. aether runs on Aether
        inference, paid from your balance and held to the daily cap, and serves
        Claude models; stored runs on the connection connection_id names: a
        Claude plan or an Anthropic API key for Claude models, an OpenAI API key
        for GPT models, none paid from your balance or held to the cap.
        Scheduled jobs use Claude Haiku 5.5 or GPT-6 Luna, from the model's
        family. A changed selection restarts a running agent; the same selection
        issues nothing. 422 for a write outside the two shapes or an unknown
        value, and 400 model_not_on_aether_inference for a GPT model on Aether
        inference. 404 connection_not_found for a connection you do not hold.
        409 connection_kind_not_runnable for a connection your agent cannot run
        on (a ChatGPT plan, an OpenCode auth file, an OpenRouter API key), and
        409 connection_not_of_agent_family for a connection serving the other
        family than the model's. 409 agent_credential_unreadable while the
        connection cannot be read; 409 agent_host_illegal_transition while going
        to sleep or pausing.
      operationId: setAgentInference
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
                - additionalProperties: false
                  properties:
                    model:
                      description: >-
                        The model your agent converses on, in the family what it
                        runs on serves: Claude models on Aether inference, a
                        Claude plan or an Anthropic API key; GPT models on an
                        OpenAI API key. Scheduled jobs run on the family's
                        Claude Haiku 5.5 or GPT-6 Luna.
                      enum:
                        - claude-fable-5-1
                        - claude-opus-5-5
                        - claude-sonnet-5-5
                        - claude-haiku-5-5
                        - gpt-6.1-sol
                        - gpt-6-sol
                        - gpt-6-astra
                        - gpt-6-luna
                      type: string
                    runs_on:
                      description: >-
                        Aether inference, paid from your balance and held to the
                        daily cap.
                      enum:
                        - aether
                      type: string
                  required:
                    - runs_on
                    - model
                  type: object
                - additionalProperties: false
                  properties:
                    connection_id:
                      description: >-
                        A connection you hold that your agent runs on: a Claude
                        plan, an Anthropic API key or an OpenAI API key.
                      format: uuid
                      type: string
                    model:
                      description: >-
                        The model your agent converses on, in the family what it
                        runs on serves: Claude models on Aether inference, a
                        Claude plan or an Anthropic API key; GPT models on an
                        OpenAI API key. Scheduled jobs run on the family's
                        Claude Haiku 5.5 or GPT-6 Luna.
                      enum:
                        - claude-fable-5-1
                        - claude-opus-5-5
                        - claude-sonnet-5-5
                        - claude-haiku-5-5
                        - gpt-6.1-sol
                        - gpt-6-sol
                        - gpt-6-astra
                        - gpt-6-luna
                      type: string
                    runs_on:
                      description: The connection connection_id names.
                      enum:
                        - stored
                      type: string
                  required:
                    - runs_on
                    - connection_id
                    - model
                  type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Not Found
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentErrorResponse'
          description: Internal Server Error
components:
  schemas:
    Agent:
      additionalProperties: false
      properties:
        browser_tools:
          description: >-
            Whether your agent may drive a browser. Off by default; a change
            applies when Hermes next starts, which a running agent does at once.
          type: boolean
        connection_id:
          description: >-
            The connection your agent runs on; present exactly when runs_on is
            stored.
          format: uuid
          type: string
        created_at:
          format: date-time
          type: string
        cron_model:
          description: >-
            The model your agent's scheduled jobs run on, unless a job names
            another.
          enum:
            - claude-fable-5-1
            - claude-opus-5-5
            - claude-sonnet-5-5
            - claude-haiku-5-5
            - gpt-6.1-sol
            - gpt-6-sol
            - gpt-6-astra
            - gpt-6-luna
          type: string
        default_project_id:
          description: >-
            The project a task your agent starts runs on when it names no
            repository. Without it such a task is refused.
          format: uuid
          type: string
        id:
          format: uuid
          type: string
        last_used_at:
          description: >-
            When your agent was created or resumed, was sent a message, or last
            worked. Thirty days unused pauses it.
          format: date-time
          type: string
        model:
          description: The model your agent converses on.
          enum:
            - claude-fable-5-1
            - claude-opus-5-5
            - claude-sonnet-5-5
            - claude-haiku-5-5
            - gpt-6.1-sol
            - gpt-6-sol
            - gpt-6-astra
            - gpt-6-luna
          type: string
        runs_on:
          description: >-
            What your agent runs on: aether, Aether inference, paid from your
            balance and held to the daily cap; stored, your connection
            connection_id names, paid by its plan or key, neither from your
            balance nor held to the cap.
          enum:
            - aether
            - stored
          type: string
        state:
          description: >-
            The host's lifecycle state. running: Hermes takes messages now;
            suspending and idle: asleep, woken by the next message; waking,
            resuming: coming up for a message; provisioning and booting: being
            created; updating: moving onto a new image; pausing and paused:
            backed up after thirty days unused, or paused by you, and resumed by
            you (a message from the web does not resume it); lost: its machine
            is gone and only deleting it helps; destroying: being deleted.
          enum:
            - provisioning
            - booting
            - running
            - suspending
            - idle
            - waking
            - updating
            - pausing
            - paused
            - resuming
            - lost
            - destroying
            - destroyed
          type: string
      required:
        - id
        - state
        - browser_tools
        - runs_on
        - model
        - cron_model
        - last_used_at
        - created_at
      type: object
    AgentErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unavailable
            - aether_inference_unserved
            - agent_connector_not_found
            - agent_credential_unreadable
            - agent_default_project_archived
            - agent_event_not_found
            - agent_host_account_deleting
            - agent_host_command_not_found
            - agent_host_creation_disabled
            - agent_host_exists
            - agent_host_illegal_transition
            - agent_host_not_allowlisted
            - agent_host_not_found
            - agent_host_not_ready
            - agent_host_other_provider_app
            - agent_host_project_not_eligible
            - agent_host_provisioning_failed
            - agent_host_state_changed
            - agent_host_wake_failed
            - agent_line_unavailable
            - agent_link_code_picked_up
            - agent_link_expired
            - agent_link_invalid_code
            - agent_link_needs_web_session
            - agent_link_no_verified_phone
            - agent_link_not_found
            - agent_link_other_account
            - agent_link_takes_a_code
            - agent_link_takes_no_code
            - agent_link_used
            - agent_message_not_found
            - agent_message_pending
            - agent_not_found
            - bad_gateway
            - bad_request
            - conflict
            - connection_account_held
            - connection_agent_only
            - connection_harness_mismatch
            - connection_is_default
            - connection_kind_not_runnable
            - connection_name_taken
            - connection_not_found
            - connection_not_held
            - connection_not_of_agent_family
            - connection_option_mismatch
            - connection_runs_agent
            - connection_runs_profiles
            - control_forbidden
            - default_skill_required
            - forbidden
            - gateway_timeout
            - github_auth_check_unavailable
            - github_claim_unverified
            - github_identity_mismatch
            - github_reconnect_required
            - github_ref_not_found
            - gone
            - integration_auth_unexpected
            - integration_not_in_directory
            - integration_shape_changed
            - internal_error
            - line_exists
            - line_not_found
            - line_not_imessage
            - mcp_connection_github_not_connected
            - mcp_connection_oauth_not_accepted
            - mcp_connection_org_not_offered
            - mcp_connection_secret_invalid
            - mcp_connection_server_changed
            - mcp_connection_static_secret_not_accepted
            - mcp_credential_policy_not_applicable
            - mcp_credential_policy_org_unavailable
            - mcp_credential_policy_required
            - mcp_oauth_app_auth_method_unsupported
            - mcp_oauth_app_invalid
            - mcp_oauth_app_issuer_invalid
            - mcp_oauth_app_required
            - mcp_oauth_not_advertised
            - mcp_oauth_pkce_unsupported
            - mcp_oauth_registration_failed
            - mcp_repo_config_invalid
            - mcp_server_address_refused
            - mcp_server_aether_managed
            - mcp_server_api_key_not_applicable
            - mcp_server_args_invalid
            - mcp_server_auth_discovery_failed
            - mcp_server_auth_unsupported
            - mcp_server_directory_managed
            - mcp_server_directory_moved
            - mcp_server_display_name_invalid
            - mcp_server_env_invalid
            - mcp_server_headers_invalid
            - mcp_server_key_invalid
            - mcp_server_key_reserved
            - mcp_server_key_taken
            - mcp_server_kind_change_refused
            - mcp_server_not_from_directory
            - mcp_server_not_mcp
            - mcp_server_package_invalid
            - mcp_server_plugin_bundled
            - mcp_server_plugin_off
            - mcp_server_response_too_large
            - mcp_server_return_to_invalid
            - mcp_server_runtime_invalid
            - mcp_server_switched_off
            - mcp_server_unreachable
            - mcp_server_url_invalid
            - mcp_server_version_unpinned
            - method_not_allowed
            - model_not_on_aether_inference
            - no_dispatch_target
            - not_acceptable
            - not_an_agent_host
            - not_found
            - not_implemented
            - org_role_insufficient
            - org_suspended
            - payment_required
            - plugin_moved
            - plugin_name_taken
            - plugin_request_invalid
            - plugin_server_key_reserved
            - plugin_server_key_taken
            - plugin_server_probe_failed
            - plugin_server_required
            - plugin_skill_invalid
            - plugin_source_address_refused
            - plugin_source_empty
            - plugin_source_invalid
            - plugin_source_not_found
            - plugin_source_not_public
            - plugin_source_too_large
            - plugin_source_unreachable
            - plugin_source_unsupported
            - plugin_switched_off
            - plugin_undeliverable
            - precondition_failed
            - rate_limited
            - repository_not_reachable
            - request_canceled
            - request_timeout
            - request_too_large
            - service_unavailable
            - skill_slug_reserved
            - unauthenticated
            - unsupported_media_type
            - validation_failed
            - whatsapp_not_enabled
          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
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      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.