Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

16.4 KB
Raw Blame
openapi: 3.1.0
info:
  title: OpenSandbox Diagnostics API
  version: 0.1.0
  description: |
    The OpenSandbox Diagnostics API exposes structured routing context and
    best-effort plain-text diagnostic snapshots for a sandbox. It is intended for
    humans and troubleshooting agents that need to locate the runtime backend and
    collect troubleshooting material without depending on a stable structured
    observability model.

    This API is not an audit log API and does not define the canonical
    observability schema for OpenSandbox. Structured telemetry, long-term
    retention, filtering, pagination, and streaming may be provided separately.

    Successful log and event responses return a JSON descriptor whose diagnostic
    payload is either embedded inline or made available through a download URL.
    The diagnostic payload itself is display-oriented `text/plain` content. Clients
    should not parse individual payload lines as a stable schema. Servers may
    impose implementation-defined retention and response size limits.

    ## Authentication

    API Key authentication is required for all operations:

    1. **HTTP Header**
       ```
       OPEN-SANDBOX-API-KEY: your-api-key
       ```

    2. **Environment Variable** (for SDK clients)
       ```
       OPEN_SANDBOX_API_KEY=your-api-key
       ```

       SDK clients will automatically pick up this environment variable.
servers:
  - url: http://localhost:8080/v1
    description: Local development
security:
  - apiKeyAuth: []
tags:
  - name: Diagnostics
    description: Sandbox troubleshooting context and payload descriptors
paths:
  /sandboxes/{sandboxId}/diagnostics/context:
    get:
      tags: [Diagnostics]
      summary: Get diagnostic context
      description: |
        Retrieve structured context for routing further diagnostics of a sandbox.

        `backendType` identifies the implementation that currently owns the
        sandbox. `backendIdentifiers` contains implementation-defined identifiers
        that may be used to correlate the sandbox with resources in that backend.
        Identifier keys are scoped to the backend type and are not defined by this
        API. The map may be empty when the backend does not expose additional
        identifiers.

        This endpoint does not return diagnostic logs or events. Use the dedicated
        `logs` and `events` endpoints after resolving the diagnostic context.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      responses:
        '200':
          description: Sandbox diagnostic context
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticContextResponse'
              examples:
                fastSandbox:
                  summary: Fast Sandbox without additional backend identifiers
                  value:
                    sandboxId: fsb-abc123
                    state: Running
                    backendType: fast-sandbox
                    backendIdentifiers: {}
                kubernetes:
                  summary: Kubernetes sandbox with backend identifiers
                  value:
                    sandboxId: sbx_123
                    state: Running
                    backendType: kubernetes
                    backendIdentifiers:
                      namespace: default
                      podName: sandbox-sbx-123
                      podUid: 86c4fb10-15f7-4c6e-b72e-8dd15d7d5c48
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
  /sandboxes/{sandboxId}/diagnostics/logs:
    get:
      tags: [Diagnostics]
      summary: Get diagnostic logs
      description: |
        Retrieve a best-effort descriptor for sandbox diagnostic log text.

        Logs are not limited to a structured observability model. Depending on the
        selected `scope` and server configuration, log text may include sandbox
        container stdout/stderr, lifecycle diagnostic text, network diagnostic text,
        or other implementation-defined diagnostic material.

        This endpoint does not provide streaming, pagination, or a stable line-level
        schema in this version. The server returns a JSON descriptor for currently
        available diagnostic text for the requested scope, subject to
        implementation-defined retention and response size limits. The descriptor
        either embeds the text as `content` or returns a `contentUrl` where the
        text can be downloaded.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
        - $ref: '#/components/parameters/DiagnosticScope'
      responses:
        '200':
          description: Diagnostic log content descriptor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticContentResponse'
              examples:
                inline:
                  summary: Inline container log text
                  value:
                    sandboxId: sbx_123
                    kind: logs
                    scope: container
                    delivery: inline
                    contentType: text/plain; charset=utf-8
                    content: |
                      2026-03-25T10:01:13Z execd started
                      2026-03-25T10:01:14Z sandbox process ready
                    truncated: false
                url:
                  summary: Downloadable container log text
                  value:
                    sandboxId: sbx_123
                    kind: logs
                    scope: container
                    delivery: url
                    contentType: text/plain; charset=utf-8
                    contentUrl: https://example.com/diagnostics/sbx_123/logs.txt
                    contentLength: 10485760
                    expiresAt: "2026-04-14T10:30:00Z"
                    truncated: false
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
  /sandboxes/{sandboxId}/diagnostics/events:
    get:
      tags: [Diagnostics]
      summary: Get diagnostic events
      description: |
        Retrieve a best-effort descriptor for sandbox diagnostic event text.

        Events are rendered as diagnostic text rather than exposed as a stable
        structured event model. Depending on the selected `scope` and runtime, event
        text may include lifecycle transitions, runtime or platform events such as
        Kubernetes Events, network diagnostic events, process activity events, or
        other implementation-defined event material.

        This endpoint does not provide streaming, pagination, or a stable line-level
        schema in this version. The server returns a JSON descriptor for currently
        available diagnostic event text for the requested scope, subject to
        implementation-defined retention and response size limits. The descriptor
        either embeds the text as `content` or returns a `contentUrl` where the
        text can be downloaded.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
        - $ref: '#/components/parameters/DiagnosticScope'
      responses:
        '200':
          description: Diagnostic event content descriptor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DiagnosticContentResponse'
              examples:
                inline:
                  summary: Inline runtime event text
                  value:
                    sandboxId: sbx_123
                    kind: events
                    scope: runtime
                    delivery: inline
                    contentType: text/plain; charset=utf-8
                    content: |
                      2026-03-25T10:01:13Z runtime Normal Scheduled Successfully assigned sandbox pod
                      2026-03-25T10:01:14Z runtime Normal Pulled Container image pulled
                    truncated: false
                url:
                  summary: Downloadable runtime event text
                  value:
                    sandboxId: sbx_123
                    kind: events
                    scope: runtime
                    delivery: url
                    contentType: text/plain; charset=utf-8
                    contentUrl: https://example.com/diagnostics/sbx_123/events.txt
                    contentLength: 5242880
                    expiresAt: "2026-04-14T10:30:00Z"
                    truncated: false
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: OPEN-SANDBOX-API-KEY
      description: |
        API Key for authentication. Can be provided via:
        1. HTTP Header: OPEN-SANDBOX-API-KEY: your-api-key
        2. Environment variable: OPEN_SANDBOX_API_KEY (for SDK clients)
  parameters:
    SandboxId:
      name: sandboxId
      in: path
      required: true
      description: Unique sandbox identifier
      schema:
        type: string
    DiagnosticScope:
      name: scope
      in: query
      required: true
      description: |
        Required diagnostic scope selector. Known scopes may include `container`,
        `lifecycle`, `runtime`, `network`, `process`, and `all`. Supported scopes
        are implementation-defined; servers may add new scopes over time.

        On deployments that still expose the legacy DevOps plain-text behavior on
        this path, requests without `scope` are treated as deprecated legacy
        requests and may return `text/plain` instead of this JSON descriptor.
      schema:
        type: string
      examples:
        container:
          summary: Sandbox container diagnostics
          value: container
        runtime:
          summary: Runtime or platform diagnostics
          value: runtime
        all:
          summary: Best-effort aggregate across supported scopes
          value: all
  headers:
    XRequestId:
      description: Unique request identifier for tracing
      schema:
        type: string
        format: uuid
  responses:
    BadRequest:
      description: The request was invalid or malformed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    Unauthorized:
      description: Authentication credentials are missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    Forbidden:
      description: The authenticated user lacks permission for this operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    NotFound:
      description: The requested sandbox does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    InternalServerError:
      description: An unexpected server error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    NotImplemented:
      description: The stable Diagnostics API is not implemented by this server
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
  schemas:
    DiagnosticContextResponse:
      type: object
      description: Structured context for routing sandbox diagnostics.
      required: [sandboxId, backendType, backendIdentifiers]
      properties:
        sandboxId:
          type: string
          description: Unique sandbox identifier accepted by the OpenSandbox API.
        state:
          type: string
          description: Current OpenSandbox lifecycle state, when available.
        backendType:
          type: string
          description: Implementation-defined backend type.
          examples: [fast-sandbox, kubernetes, docker]
        backendIdentifiers:
          type: object
          description: |
            Backend-defined identifiers used to correlate this sandbox with
            backend resources. Keys are scoped to `backendType`; values are strings.
          additionalProperties:
            type: string
      additionalProperties: false
    DiagnosticContentResponse:
      type: object
      description: |
        Descriptor for diagnostic text content.

        When `delivery` is `inline`, servers MUST include `content` with the
        diagnostic text and MUST omit `contentUrl` / `expiresAt`.

        When `delivery` is `url`, servers MUST include `contentUrl` and `expiresAt`
        to identify where the diagnostic text can be downloaded and MUST omit
        `content`.
      required: [sandboxId, kind, scope, delivery, contentType, truncated]
      properties:
        sandboxId:
          type: string
          description: Unique sandbox identifier.
        kind:
          type: string
          description: Diagnostic payload kind.
          enum: [logs, events]
        scope:
          type: string
          description: Diagnostic scope used for this response.
        delivery:
          type: string
          description: How the diagnostic text payload is delivered.
          enum: [inline, url]
        contentType:
          type: string
          description: Media type of the diagnostic payload.
          examples: ["text/plain; charset=utf-8"]
        content:
          type: string
          description: Inline diagnostic text payload. Present when `delivery` is `inline`.
        contentUrl:
          type: string
          format: uri
          description: URL where the diagnostic text payload can be downloaded. Present when `delivery` is `url`.
        contentLength:
          type: integer
          minimum: 0
          description: Payload size in bytes when known.
        expiresAt:
          type: string
          format: date-time
          description: Expiration time for the download URL. Present when `delivery` is `url`.
        truncated:
          type: boolean
          description: |
            Whether the diagnostic payload returned inline or by URL was
            intentionally truncated by the server. This does not indicate backend
            retention gaps such as expired Kubernetes Events; those should be
            reported through `warnings` when available.
        warnings:
          type: array
          description: Non-fatal warnings about payload completeness or availability.
          items:
            type: string
      additionalProperties: false
    ErrorResponse:
      type: object
      description: |
        Standard error response for all non-2xx HTTP responses.
        HTTP status code indicates the error category; code and message provide details.
      properties:
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable error message describing what went wrong.
      required: [code, message]
      additionalProperties: false