basePath: /
definitions:
  api.CoreAPIError:
    properties:
      code:
        type: string
        x-nullable: true
      details:
        description: |-
          Details contains only documented, Core-owned facts: string, finite number,
          boolean, null or string array values. Never include request echoes, secrets
          or native/provider error text. Empty or invalid details are omitted.
        type: object
      message:
        type: string
      param:
        type: string
        x-nullable: true
      type:
        type: string
    required:
      - message
      - type
    type: object
  api.CoreErrorResponse:
    properties:
      error:
        $ref: '#/definitions/api.CoreAPIError'
    required:
      - error
    type: object
  api.NativeInstallationClaim:
    properties:
      executor_token:
        type: string
    type: object
  deployment.Enrollment:
    properties:
      backend_fingerprint:
        type: string
      core_url:
        description: The Core origin this node stores and connects to, such as https://core.example. It must equal the installation public URL; otherwise enrollment gets 409 sandbox_node_address_mismatch and the token stays unused.
        type: string
      credential:
        type: string
      deployment_generation:
        type: integer
      name:
        type: string
      node_id:
        type: string
      provider:
        type: string
      specification_digest:
        type: string
    type: object
  deployment.NodeConfiguration:
    properties:
      core_url:
        type: string
      generation:
        type: integer
      installation_id:
        type: string
      max_active:
        type: integer
      max_retained:
        type: integer
      provider:
        type: string
      specification:
        $ref: '#/definitions/sandbox.DeploymentSpec'
      specification_digest:
        type: string
    type: object
  deployment.NodeIdentity:
    properties:
      deployment_generation:
        type: integer
      installation_id:
        type: string
      max_active:
        type: integer
      max_retained:
        type: integer
      node_id:
        type: string
      provider:
        type: string
      specification_digest:
        type: string
    type: object
  deployment.NodeStatus:
    properties:
      connected:
        type: boolean
      deployment_generation:
        type: integer
      installation_id:
        type: string
      max_active:
        type: integer
      max_retained:
        type: integer
      node_id:
        type: string
      provider:
        type: string
      provider_ready:
        type: boolean
      specification_digest:
        type: string
    type: object
  sandbox.DeploymentSpec:
    properties:
      resources:
        $ref: '#/definitions/sandbox.Resources'
      runtime:
        $ref: '#/definitions/sandbox.RuntimeRelease'
    type: object
  sandbox.Resources:
    properties:
      cpus:
        type: integer
      environment_disk_mib:
        type: integer
      memory_mib:
        type: integer
      root_disk_mib:
        type: integer
    type: object
  sandbox.RuntimeRelease:
    properties:
      firmware_sha256:
        type: string
      image_id:
        type: string
      image_manifest_digest:
        type: string
      microsandbox_ref:
        type: string
      runtime_sha256:
        type: string
      source_commit:
        type: string
    type: object
  v1.APIError:
    properties:
      code:
        type: string
        x-nullable: true
      message:
        type: string
      param:
        type: string
        x-nullable: true
      type:
        type: string
    required:
      - message
      - type
    type: object
  v1.ErrorResponse:
    properties:
      error:
        $ref: '#/definitions/v1.APIError'
    required:
      - error
    type: object
  v1.NativeInstallationContext:
    properties:
      environment_id:
        type: string
      harness:
        type: string
      protocol_version:
        type: string
      remote_url:
        type: string
      version:
        type: string
      workspace_directory:
        type: string
    type: object
info:
  contact: {}
  description: Machine connection routes under /api/v1. Sandbox nodes authenticate with a one-use enrollment token or their node credential; Project API keys and the Core key are not accepted. See each operation's security requirements.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  title: OpenAgentCore Machine Connections
  version: "1"
paths:
  /api/v1/agent-daemon/installation:
    post:
      description: Accepts a short-lived Environment installation Bearer authorization, not a Project or Core key. Returns frozen connection constraints; it does not claim or rotate credentials.
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/v1.NativeInstallationContext'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
        "503":
          description: Service Unavailable
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
      summary: Resolve a native installation authorization
      tags:
        - Native Installation
  /api/v1/agent-daemon/installation/claim:
    post:
      consumes:
        - application/json
      description: A valid installation Bearer authorization can claim one connect-only key. The client persists its generated secret before submitting it. Retries must present that same secret; a different, rotated or revoked credential is never replaced.
      parameters:
        - description: Locally persisted executor secret
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/api.NativeInstallationClaim'
      responses:
        "204":
          description: No Content
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
        "503":
          description: Service Unavailable
          schema:
            $ref: '#/definitions/api.CoreErrorResponse'
      summary: Claim an Environment's installation credential
      tags:
        - Native Installation
  /api/v1/sandbox-node/configuration:
    get:
      description: Authenticates with an unconsumed enrollment token, or a retained node credential with X-OAC-Node-ID. Does not consume the token or expose E2B credentials. Node files cannot override this specification.
      parameters:
        - description: Retained node UUID
          in: header
          name: X-OAC-Node-ID
          type: string
        - description: Exact kept generation (registered nodes only); omitted reads the current target
          in: query
          name: generation
          type: integer
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/deployment.NodeConfiguration'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "503":
          description: Service Unavailable
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
      security:
        - NodeEnrollmentAuth: []
      summary: Read the active configuration for node installation
      tags:
        - Sandbox Node
  /api/v1/sandbox-node/enroll:
    post:
      consumes:
        - application/json
      description: Node machine connection. Consumes a one-use enrollment token; grants no project or administrator access. Responses contain only explicit safe fields. core_url is required and must equal the installation public URL; a different address gets 409 sandbox_node_address_mismatch and leaves the token unused.
      parameters:
        - description: Request
          in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/deployment.Enrollment'
      produces:
        - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/deployment.NodeIdentity'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "503":
          description: Service Unavailable
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
      security:
        - NodeEnrollmentAuth: []
      summary: Enroll a sandbox node
      tags:
        - Sandbox Node
  /api/v1/sandbox-node/identity:
    get:
      description: Node machine connection. Authenticates with the retained node credential; grants no project or administrator access. Responses contain only explicit safe fields.
      parameters:
        - description: Sandbox node UUID
          in: query
          name: node_id
          required: true
          type: string
      produces:
        - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/deployment.NodeStatus'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "404":
          description: Not Found
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "409":
          description: Conflict
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
        "503":
          description: Service Unavailable
          schema:
            $ref: '#/definitions/v1.ErrorResponse'
      security:
        - NodeAuth: []
      summary: Recover an enrolled sandbox node identity and observe its readiness
      tags:
        - Sandbox Node
schemes:
  - http
  - https
securityDefinitions:
  NodeAuth:
    in: header
    name: Authorization
    type: apiKey
  NodeEnrollmentAuth:
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"