Skip to content

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

120 KB
Raw Blame
openapi: 3.1.0
info:
  title: OpenSandbox Lifecycle API
  version: 0.1.0
  description: |
    The Sandbox Lifecycle API coordinates how untrusted workloads are created,
    executed, paused, resumed, and finally disposed. This specification focuses on
    the primary lifecycle flows for the `sandbox` domain concept. Sandboxes can
    be provisioned directly from container images or restored from snapshots.

    ## Sandbox Lifecycle

    A sandbox follows this lifecycle:

    1. **Creation** → Sandbox is provisioned and enters `Running` state
    2. **Execution** → Sandbox is running and ready to accept requests
    3. **Pause** (optional) → `Pausing` → `Paused` (asynchronous process)
    4. **Resume** (optional) → `Resuming` → `Running` (asynchronous process)
    5. **Termination** → `Stopping` → `Terminated` (can be triggered by kill action, TTL expiry, or error)
    6. **Error** → Any state can transition to `Failed` on critical errors

    The `status` field provides fine-grained details through `state`, `reason`, and `message`.

    ## 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: Sandboxes
    description: Provision and transition sandboxes through their lifecycle
  - name: Snapshots
    description: Create, list, and delete persistent sandbox snapshots
  - name: Templates
    description: Fsb golden-image template management (runtime.type=fsb only)
  - name: Metrics
    description: Best-effort SDK telemetry ingestion for server-side aggregation
paths:
  /sandboxes/{sandboxId}/networkpolicy:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    get:
      tags: [Sandboxes]
      operationId: getSandboxNetworkPolicy
      summary: Read sandbox network policy
      description: |
        Fsb reads the egress-held policy record — the response reflects
        exactly what the egress enforces, not the create-time binding input.
        Other backends proxy the sandbox-side egress service. Requires
        lifecycle API authentication.
      responses:
        '200':
          description: Policy intent (Fsb) or sidecar policy (other backends).
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyStatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: Policy state is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags: [Sandboxes]
      operationId: replaceSandboxNetworkPolicy
      summary: Replace the complete sandbox network policy
      description: |
        Replaces defaultAction and all rules, rather than merging them. Fsb
        relays the replacement to the egress-held policy record through the
        FastPath handler relay — the ack means the egress applied it (and, with
        policy persistence, that it is durable). The create-time binding input
        is the bootstrap only; runtime changes never rewrite it, and a paused
        (sealed) sandbox rejects mutations until resume. Other backends proxy
        the sandbox-side egress service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NetworkPolicy'
      responses:
        '200':
          description: Committed policy intent; Fsb omits enforcementMode.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: FastPath or policy state is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [Sandboxes]
      operationId: patchSandboxNetworkPolicy
      summary: Patch sandbox network policy rules
      description: |
        Merges egress rules into the current policy using the same semantics
        as the sandbox-side egress service PATCH endpoint: incoming rules
        take priority over existing rules with the same target and replace
        them in place; within one patch payload, the first rule for a target
        wins; existing rules for other targets and the current defaultAction
        are preserved. Fsb composes the merge server-side (relay GET → merge
        → relay PUT carrying the read revision) — a concurrent writer wins
        and the stale merge is a 409. Other backends proxy the sandbox-side
        egress service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/NetworkRule'
      responses:
        '200':
          description: Committed policy intent; Fsb omits enforcementMode.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: FastPath or policy state is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Sandboxes]
      operationId: deleteSandboxNetworkPolicyRules
      summary: Delete sandbox network policy rules by target
      description: |
        Removes egress rules whose target matches one of the provided
        entries. Matching is by exact target string; unknown targets are
        silently ignored (idempotent). The current defaultAction is
        preserved. Other backends proxy the sandbox-side egress service.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Committed policy intent; Fsb omits enforcementMode.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyStatusResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: FastPath or policy state is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sandboxes/{sandboxId}/credential-vault:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    post:
      tags: [Sandboxes]
      operationId: createSandboxCredentialVault
      summary: Create the sandbox Credential Vault
      description: |
        Creates the initial Credential Vault revision and activates it for
        credential injection. Inline credential values are write-only and are
        never returned by any read. Credential Vault requires a network
        policy; `defaultAction: deny` is strongly recommended.

        For Fsb the server relays the revision to the egress-held vault over
        the FastPath handler relay; the relay response is the synchronous
        egress-validated ack, so success means the sandbox has loaded the
        revision (create-only: 409 when a vault already exists, atomic across
        server replicas). Other backends proxy the sandbox-side egress
        service with sidecar semantics.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialVaultCreateRequest'
      responses:
        '201':
          description: Credential Vault created and acknowledged (sanitized state).
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialVaultState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags: [Sandboxes]
      operationId: getSandboxCredentialVault
      summary: Read sanitized sandbox Credential Vault state
      description: |
        Returns the sanitized Credential Vault state: credential names,
        source types, binding metadata and the current revision. Credential
        values are never returned on any read surface. Readback after a lost
        mutation ack resolves the current revision (retry anchor for 412).
        Other backends proxy the sandbox-side egress service.
      responses:
        '200':
          description: Sanitized Credential Vault state.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialVaultState'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags: [Sandboxes]
      operationId: patchSandboxCredentialVault
      summary: Atomically mutate sandbox credentials and bindings
      description: |
        Applies one atomic mutation set: `delete` first, then `replace`, then
        `add` (per set). Every mentioned name must resolve exactly once —
        `add` requires the name to be absent; `replace` and `delete` require
        it to exist. `expectedRevision`, when provided, must match the
        current revision (412 otherwise).

        For Fsb the merge is composed server-side (relay read → in-memory
        merge → relay replace) and validated by the egress vault; a rejected
        mutation never leaves a partially applied revision (last-good kept).
        Other backends proxy the sandbox-side egress service. On 412, re-read
        the state and retry with the fresh revision.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CredentialVaultMutationRequest'
      responses:
        '200':
          description: Mutation applied and acknowledged (sanitized state).
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialVaultState'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '412':
          $ref: '#/components/responses/PreconditionFailed'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags: [Sandboxes]
      operationId: deleteSandboxCredentialVault
      summary: Delete the sandbox Credential Vault
      description: |
        Removes all credentials and bindings; the network policy is kept.
        Other backends proxy the sandbox-side egress service.
      responses:
        '204':
          description: Credential Vault deleted.
          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'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sandboxes/{sandboxId}/credential-vault/credentials:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    get:
      tags: [Sandboxes]
      operationId: listSandboxCredentialVaultCredentials
      summary: List sanitized credential metadata
      description: |
        Returns sanitized credential metadata (names, source types,
        per-record revisions); values are never returned. Other backends
        proxy the sandbox-side egress service.
      responses:
        '200':
          description: Sanitized credential metadata.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sandboxes/{sandboxId}/credential-vault/credentials/{credentialName}:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
      - name: credentialName
        in: path
        required: true
        schema:
          type: string
        description: Credential name
    get:
      tags: [Sandboxes]
      operationId: getSandboxCredentialVaultCredential
      summary: Get sanitized metadata for one credential
      description: |
        Returns sanitized metadata for a single credential; values are never
        returned. Other backends proxy the sandbox-side egress service.
      responses:
        '200':
          description: Sanitized credential metadata.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sandboxes/{sandboxId}/credential-vault/bindings:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    get:
      tags: [Sandboxes]
      operationId: listSandboxCredentialVaultBindings
      summary: List sanitized credential binding metadata
      description: |
        Returns sanitized credential binding metadata (matchers and auth
        shapes without credential values). Other backends proxy the
        sandbox-side egress service.
      responses:
        '200':
          description: Sanitized binding metadata.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialBindingListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /sandboxes/{sandboxId}/credential-vault/bindings/{bindingName}:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
      - name: bindingName
        in: path
        required: true
        schema:
          type: string
        description: Credential binding name
    get:
      tags: [Sandboxes]
      operationId: getSandboxCredentialVaultBinding
      summary: Get sanitized metadata for one binding
      description: |
        Returns sanitized metadata for a single credential binding; values
        are never returned. Other backends proxy the sandbox-side egress
        service.
      responses:
        '200':
          description: Sanitized binding metadata.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialBindingMetadata'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          description: The vault backend is temporarily unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /metrics/events:
    post:
      tags: [Metrics]
      operationId: reportMetricsEvent
      summary: Report an SDK metrics event
      description: |
        Accepts best-effort telemetry from SDKs (Phase 1: sandbox creation latency).

        SDKs SHOULD fire-and-forget this call after `create` + readiness complete
        (or after a failed creation attempt). Failures to report MUST NOT affect
        sandbox usability. The server accepts events even when OpenTelemetry
        export is disabled (noop recording).

        SDK language and version are taken from the HTTP `User-Agent` header
        (for example `OpenSandbox-Python-SDK/0.1.14`), not from the JSON body.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MetricsEvent'
            example:
              eventType: sandbox.create
              sandboxId: sbx_01HZYEXAMPLE
              image: python:3.12
              createDurationMs: 1842
              success: true
      responses:
        '204':
          description: Event accepted
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes:
    get:
      tags: [ Sandboxes ]
      summary: List sandboxes
      description: |
        List all sandboxes with optional filtering and pagination using query parameters.
        All filter conditions use AND logic. Multiple `state` parameters use OR logic within states.
      parameters:
        - name: state
          in: query
          description: |
            Filter by lifecycle state. Pass multiple times for OR logic.
            Example: `?state=Running&state=Paused`
          schema:
            type: array
            items:
              type: string
          style: form
          explode: true
        - name: metadata
          in: query
          description: |
            Arbitrary metadata key-value pairs for filtering,keys and values must be url encoded
            Example: To filter by `project=Apollo` and `note=Demo Test`: `?metadata=project%3DApollo%26note%3DDemo%252520Test`
          schema:
            type: string
          style: form
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        '200':
          description: Paginated collection of sandboxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSandboxesResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      tags: [Sandboxes]
      summary: Create a sandbox
      description: |
        Creates a new sandbox from a container image, restores one from a
        persistent sandbox snapshot, or allocates one from a pre-configured
        Pool, with optional resource limits, environment variables, and metadata.

        Standard mode requires exactly one startup source:
        - `image` to provision directly from a container image.
        - `snapshotId` to restore from a previously created snapshot.

        Pool mode uses `extensions.poolRef` to select the pre-created Pod and
        schedules a per-allocation task; `image` and `snapshotId` are not
        required.

        When `image` is provided, `entrypoint` is required. When `snapshotId` is
        provided, `entrypoint` is optional. If omitted, the server defaults the
        sandbox entrypoint to `["tail", "-f", "/dev/null"]`.

        ## Authentication

        API Key authentication is required via:
        - `OPEN-SANDBOX-API-KEY: <api-key>` header
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
            examples:
              deny-with-allowlist:
                summary: Deny by default with allowed domains
                value:
                  image:
                    uri: python:3.11
                  timeout: 3600
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/app/main.py"]
                  networkPolicy:
                    defaultAction: deny
                    egress:
                      - action: allow
                        target: "pypi.org"
              allow-with-denylist:
                summary: Allow by default with a deny rule
                value:
                  image:
                    uri: python:3.11
                  timeout: 3600
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/app/main.py"]
                  networkPolicy:
                    defaultAction: allow
                    egress:
                      - action: deny
                        target: "bad.example.com"
              manual-cleanup:
                summary: Manual cleanup without automatic expiration
                value:
                  image:
                    uri: python:3.11
                  platform:
                    os: linux
                    arch: amd64
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/app/main.py"]
              secure-access:
                summary: Enable secured access for sandbox endpoints in Kubernetes gateway mode
                value:
                  image:
                    uri: python:3.11
                  timeout: 3600
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/app/main.py"]
                  secureAccess: true
              restore-snapshot:
                summary: Restore from a snapshot
                value:
                  snapshotId: snap_123
                  timeout: 3600
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
              restore-snapshot-with-entrypoint:
                summary: Restore from a snapshot with a custom entrypoint
                value:
                  snapshotId: snap_123
                  timeout: 3600
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/workspace/app.py"]
              lifecycle-hooks:
                summary: Restore content before startup and checkpoint it periodically
                value:
                  image:
                    uri: python:3.11
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/app/main.py"]
                  lifecycle:
                    preStart:
                      command: ["/opt/hooks/restore.sh"]
                      timeoutSeconds: 60
                    periodic:
                      - name: checkpoint
                        schedule: "*/5 * * * *"
                        command: ["/opt/hooks/checkpoint.sh"]
                        timeoutSeconds: 60
              idle-policy:
                summary: Auto-pause after five idle minutes and wake on access
                value:
                  image:
                    uri: python:3.11
                  resourceLimits:
                    cpu: "500m"
                    memory: "512Mi"
                  entrypoint: ["python", "/app/main.py"]
                  timeout: 86400
                  lifecycle:
                    idlePolicy:
                      idleTimeoutSeconds: 300
                      onIdle: pause
                      wakeOnAccess: true
      responses:
        '202':
          description: |
            Sandbox created and provisioned successfully.

            The returned sandbox includes:
            - `id`: Unique sandbox identifier
            - `status.state: "Running"` (provisioning completed synchronously)
            - `status.reason` and `status.message` indicating current state
            - `metadata`, `expiresAt`, `createdAt`: Core sandbox information

            Note: startup source details and `updatedAt` are not included in the create response.
            Use GET /sandboxes/{sandboxId} to retrieve the complete sandbox information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSandboxResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: |
            Namespace ResourceQuota exhausted — the sandbox was not admitted.

            The returned `ErrorResponse.code` is `KUBERNETES::QUOTA_EXCEEDED` and
            `message` carries the Kubernetes admission rejection details.

            This fail-fast behavior applies when the `agent-sandbox` workload
            provider is used. With the default `batchsandbox` provider, quota
            exhaustion currently waits for the sandbox creation timeout.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          description: Pool capacity remained unavailable before the acquisition timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /snapshots:
    get:
      tags: [Snapshots]
      summary: List snapshots
      description: |
        List all snapshots with optional filtering and pagination using query parameters.
        Snapshots are persistent captures of sandbox state and may outlive the source sandbox.
      parameters:
        - name: sandboxId
          in: query
          description: Filter snapshots by source sandbox identifier
          schema:
            type: string
        - name: name
          in: query
          description: Filter snapshots by exact snapshot name
          schema:
            type: string
        - name: state
          in: query
          description: |
            Filter by snapshot lifecycle state. Pass multiple times for OR logic.
            Example: `?state=Ready&state=Failed`
          schema:
            type: array
            items:
              $ref: '#/components/schemas/SnapshotState'
          style: form
          explode: true
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        '200':
          description: Paginated collection of snapshots
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSnapshotsResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /snapshots/{snapshotId}:
    parameters:
      - $ref: '#/components/parameters/SnapshotId'
    get:
      tags: [Snapshots]
      summary: Fetch a snapshot by id
      description: Returns snapshot state and metadata.
      responses:
        '200':
          description: Snapshot current state and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags: [Snapshots]
      summary: Delete a snapshot
      description: |
        Delete a persistent sandbox snapshot by id. Snapshots that are still
        being created cannot be deleted.

        For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
        and Kubernetes coordination resources, but does not guarantee removal
        of pushed OCI images from the configured registry. Use registry
        retention or garbage collection policies for image lifecycle cleanup.
      responses:
        '204':
          description: Snapshot successfully deleted
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    get:
      tags: [Sandboxes]
      summary: Fetch a sandbox by id
      description: |
        Returns the complete sandbox information including:
        - `id`, `status`, `metadata`, `expiresAt`, `createdAt`: Core information
        - `image` or `snapshotId`: Startup source information (not included in create response)
        - `entrypoint`: Entry process specification

        This is the complete representation of the sandbox resource.
      responses:
        '200':
          description: Sandbox current state and metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          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'
    delete:
      tags: [Sandboxes]
      summary: Delete a sandbox
      description: |
        Request sandbox deletion. Runtime cleanup may continue after the response.
        For Kubernetes BatchSandbox workloads, queries report Stopping during cleanup
        and return 404 once the resource is removed.
      responses:
        '204':
          description: |
            Sandbox deletion accepted. Runtime cleanup may still be in progress.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}/metadata:
    parameters:
      - $ref: '#/components/parameters/SandboxId'
    patch:
      tags: [Sandboxes]
      summary: Patch sandbox metadata
      description: |
        Update sandbox metadata using JSON Merge Patch semantics (RFC 7396).

        **Merge Patch rules:**
        | Request body key/value | Behavior |
        |---|---|
        | `"key": "value"` | Add or replace the key |
        | `"key": null` | Delete the key (silently ignored if key does not exist) |
        | key absent | Keep current value (no change) |
        | Empty `{}` | No-op, returns current metadata |

        Metadata keys and values must comply with Kubernetes label rules:
        - Keys must be valid DNS label names or prefixed DNS subdomains
        - Keys with the `opensandbox.io/` prefix are reserved and rejected
        - Values must be 63 characters or less, matching `[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?`

        This operation does not restart or recreate the sandbox container/pod.

        **Concurrency:** On the Docker runtime concurrent PATCH requests apply
        one after another, last write wins per key. On Kubernetes a PATCH
        writes back the whole label set it read, with no `resourceVersion`
        check, so a concurrent PATCH may revert a value another PATCH changed
        or resurrect a key it deleted. A PATCH on an fsb sandbox sends only its
        own keys, fenced by the sandbox UID and generation. Use a single writer
        or coordinate out-of-band when concurrent modifications to the same
        key are expected.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSandboxMetadataRequest'
            examples:
              add-and-replace:
                summary: Add new keys and replace existing values
                value:
                  team: "platform"
                  version: "2.0"
              delete-key:
                summary: Delete a metadata key
                value:
                  deprecated-key: null
              mixed-operations:
                summary: Add, replace, and delete in a single request
                value:
                  project: "new-project"
                  team: null
                  environment: "production"
              empty-body:
                summary: No-op (returns current metadata)
                value: {}
      responses:
        '200':
          description: |
            Metadata patched successfully. Returns the complete sandbox resource
            with updated metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sandbox'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}/snapshots:
    post:
      tags: [Snapshots]
      summary: Create a snapshot from a sandbox
      description: |
        Create a persistent point-in-time snapshot from the sandbox's current state.
        The source sandbox must be `Running`. The returned snapshot id identifies
        the created artifact. Snapshot creation may temporarily pause the sandbox
        while the runtime captures provider-supported state, then the source
        sandbox continues running.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSnapshotRequest'
            examples:
              default:
                summary: Create an unnamed snapshot
                value: {}
              named:
                summary: Create a named snapshot
                value:
                  name: checkpoint-before-import
      responses:
        '202':
          description: |
            Snapshot creation accepted.

            The returned snapshot includes `status.state: "Creating"`.
            Poll GET /snapshots/{snapshotId} to track progress until the snapshot
            transitions to `Ready` or `Failed`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Snapshot'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            Location:
              $ref: '#/components/headers/Location'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}/pause:
    post:
      tags: [Sandboxes]
      summary: Pause execution while retaining state
      description: Pause a running sandbox while preserving its state. Poll GET /sandboxes/{sandboxId} to track state transition through Pausing and eventually Paused.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      responses:
        '202':
          description: |
            Pause operation accepted.

            Sandbox will transition to Pausing state and eventually Paused.
            Poll GET /sandboxes/{sandboxId} to track progress.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}/resume:
    post:
      tags: [Sandboxes]
      summary: Resume a paused sandbox
      description: Resume execution of a paused sandbox. Poll GET /sandboxes/{sandboxId} to track state transition through Resuming and eventually Running.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      responses:
        '202':
          description: |
            Resume operation accepted.

            Sandbox will transition from Paused → Resuming → Running.
            Poll GET /sandboxes/{sandboxId} to track progress.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}/renew-expiration:
    post:
      tags: [Sandboxes]
      summary: Renew sandbox expiration
      description: |
        Set the absolute expiration time of a sandbox to the supplied future timestamp.
        This may shorten, preserve, or extend the current expiration.
        The server configuration `server.max_sandbox_timeout_seconds` applies only
        to `timeout` on creation and does not limit this operation.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenewSandboxExpirationRequest'
      responses:
        '200':
          description: |
            Sandbox expiration updated successfully.

            Returns only the updated expiresAt field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenewSandboxExpirationResponse'
          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'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /sandboxes/{sandboxId}/endpoints/{port}:
    get:
      tags: [Sandboxes]
      summary: Get sandbox access endpoint
      description: |
        Get the public access endpoint URL for accessing a service running on a specific port
        within the sandbox. The service must be listening on the specified port inside
        the sandbox for the endpoint to be available.
      parameters:
        - $ref: '#/components/parameters/SandboxId'
        - name: port
          in: path
          required: true
          description: Port number where the service is listening inside the sandbox
          schema:
            type: integer
            minimum: 1
            maximum: 65535
        - name: use_server_proxy
          in: query
          description: Whether to return a server-proxied URL. Cannot be combined with `expires`.
          schema:
            type: boolean
            default: false
        - name: expires
          in: query
          required: false
          description: |
            Optional. When set, the server **issues a signed** access route (OSEP-0011). The value
            is **Linux / Unix epoch seconds** — a decimal `uint64` count of **whole seconds** since
            the Unix epoch (`1970-01-01 00:00:00` UTC, same as POSIX / `time(2)`), not
            milliseconds. Normalized to `expires_b36` for the four-segment route token. Omit to
            get the unsigned/legacy response shape. Cannot be combined with `use_server_proxy=true`.
          schema:
            type: string
            pattern: '^(0|[1-9][0-9]*)$'
            minLength: 1
            maxLength: 20
      responses:
        '200':
          description: |
            Endpoint retrieved successfully.

            Returns the public URL for accessing the service on the specified port.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
            OpenSandboxOrigin:
              $ref: '#/components/headers/SandboxOrigin'
        '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'
  /templates:
    post:
      tags: [Templates]
      summary: Create a fsb template
      description: |
        Declares a golden-image build executed by fast-sandbox.
        Available on Kubernetes-backed runtimes (`kubernetes` and `fsb`);
        501 otherwise (e.g. the Docker runtime).

        The build is asynchronous: the response carries `status.phase: Pending`;
        poll `GET /templates/{templateId}` until `Succeeded` (or `Failed` with
        `status.message`). Only `Succeeded` templates can back template-based
        sandbox creation. Kernel, execd and guest init are server-side build
        inputs supplied from the `[fsb]` configuration, not client fields.

        Templates are tenant-private: every template is scoped to the
        requester's fast-sandbox namespace.
      operationId: createTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateFsbTemplateRequest'
      responses:
        '201':
          description: Template build accepted; the phase starts at Pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FsbTemplate'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '409':
          $ref: '#/components/responses/Conflict'
        '501':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/InternalServerError'
    get:
      tags: [Templates]
      summary: List fsb templates
      description: |
        Lists the current tenant's templates with optional metadata filtering
        (AND logic) and pagination. Results never include other tenants'
        templates.
      operationId: listTemplates
      parameters:
        - name: metadata
          in: query
          description: |
            Arbitrary metadata key-value pairs for filtering, keys and values
            must be url encoded. Example: `?metadata=project%3DApollo%26env%3Dprod`
          schema:
            type: string
          style: form
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: pageSize
          in: query
          description: Number of items per page
          schema:
            type: integer
            minimum: 1
            default: 20
      responses:
        '200':
          description: Paginated collection of templates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListFsbTemplatesResponse'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '501':
          $ref: '#/components/responses/InternalServerError'
  /templates/{templateId}:
    parameters:
      - name: templateId
        in: path
        required: true
        description: Template identifier (`tpl_<uuid>`)
        schema:
          type: string
          minLength: 1
    get:
      tags: [Templates]
      summary: Get a fsb template
      description: |
        Returns one template with its build status. The status is lazily
        synced from the fast-sandbox SandboxTemplate CRD, so the response
        reflects the latest build phase.
      operationId: getTemplate
      responses:
        '200':
          description: Template status and artifact references
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FsbTemplate'
          headers:
            X-Request-ID:
              $ref: '#/components/headers/XRequestId'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '501':
          $ref: '#/components/responses/InternalServerError'
    delete:
      tags: [Templates]
      summary: Delete a fsb template
      description: |
        Deletes the catalog row and the backing SandboxTemplate CRD.
        Sandboxes already created from the template are unaffected: their
        Sandbox CRs hold their own artifact references.
      operationId: deleteTemplate
      responses:
        '204':
          description: Template deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '501':
          $ref: '#/components/responses/InternalServerError'
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
    SnapshotId:
      name: snapshotId
      in: path
      required: true
      description: Unique snapshot identifier
      schema:
        type: string
  headers:
    SandboxOrigin:
      description: |
        Origin of the sandbox: `template` when the sandbox runs on a fsb
        golden-image template (no sandbox-side egress sidecar; egress policy
        is managed through the lifecycle control plane). The set of values
        may grow over time; clients must treat a missing or unknown value as
        "not template-backed" and keep using the egress sidecar.
      schema:
        type: string
        example: template
    XRequestId:
      description: Unique request identifier for tracing
      schema:
        type: string
        format: uuid
    Location:
      description: URI of the newly created or related resource
      schema:
        type: string
        format: uri
    RetryAfter:
      description: Suggested delay in seconds before retrying
      schema:
        type: integer
        minimum: 1
  responses:
    Error:
      description: Error response envelope
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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 resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    Conflict:
      description: The operation conflicts with the current state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/XRequestId'
    PreconditionFailed:
      description: The provided expectedRevision does not match the current revision
      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'
  schemas:
    MetricsEvent:
      type: object
      description: |
        SDK-reported metrics event. Phase 1 covers sandbox creation latency from
        the start of create until readiness succeeds or creation fails.

        SDK language and package version are identified via the request
        `User-Agent` header (for example `OpenSandbox-Go-SDK/0.1.0`), not body fields.
      properties:
        eventType:
          type: string
          description: Metric event type
          enum: [sandbox.create]
        sandboxId:
          type: string
          description: Sandbox identifier when available (may be omitted if create failed before an ID was assigned)
        image:
          type: string
          description: Container image URI or snapshot startup source label
        createDurationMs:
          type: integer
          minimum: 0
          description: Wall-clock duration in milliseconds from create start to ready or failure
        success:
          type: boolean
          description: Whether create + readiness completed successfully
      required: [eventType, createDurationMs, success]
    ListSandboxesResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Sandbox'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
      required: [items, pagination]
    ListSnapshotsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/Snapshot'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
      required: [items, pagination]
    PaginationInfo:
      type: object
      description: Pagination metadata for list responses
      properties:
        page:
          type: integer
          minimum: 1
          description: Current page number
        pageSize:
          type: integer
          minimum: 1
          description: Number of items per page
        totalItems:
          type: integer
          minimum: 0
          description: Total number of items matching the filter
        totalPages:
          type: integer
          minimum: 0
          description: Total number of pages
        hasNextPage:
          type: boolean
          description: Whether there are more pages after the current one
      required: [page, pageSize, totalItems, totalPages, hasNextPage]
    CreateSandboxResponse:
      type: object
      description: Response from creating a new sandbox. Contains essential information without startup source details and updatedAt.
      properties:
        id:
          type: string
          description: Unique sandbox identifier

        status:
          $ref: '#/components/schemas/SandboxStatus'
          description: Current lifecycle status and detailed state information

        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom metadata from creation request

        extensions:
          type: object
          additionalProperties:
            type: string
          description: Opaque extension data restored from provider-specific storage

        platform:
          $ref: '#/components/schemas/PlatformSpec'
          description: |
            Platform constraint echoed from request or workload template.
            Null when no scheduling constraint is provided.

        expiresAt:
          type: string
          format: date-time
          description: Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.

        createdAt:
          type: string
          format: date-time
          description: Sandbox creation timestamp

        entrypoint:
          type: array
          items:
            type: string
          description: |
            Entry process specification for the sandbox. For image-created sandboxes,
            this is copied from the creation request. For snapshot-created sandboxes,
            this is restored from the snapshot.

      required:
        - id
        - status
        - createdAt
        - entrypoint

    CreateSnapshotRequest:
      type: object
      description: Optional settings for creating a sandbox snapshot.
      properties:
        name:
          type: string
          description: Optional human-readable snapshot name.
          minLength: 1
      additionalProperties: false

    Snapshot:
      type: object
      description: Persistent point-in-time capture of a sandbox.
      properties:
        id:
          type: string
          description: Unique snapshot identifier

        sandboxId:
          type: string
          description: Source sandbox identifier used to create this snapshot

        name:
          type: string
          description: Optional human-readable snapshot name

        status:
          $ref: '#/components/schemas/SnapshotStatus'
          description: Current snapshot lifecycle status and detailed state information

        createdAt:
          type: string
          format: date-time
          description: Snapshot creation timestamp

      required:
        - id
        - sandboxId
        - status
        - createdAt
      additionalProperties: false

    SnapshotState:
      type: string
      description: |
        Snapshot lifecycle state.

        Common state values:
        - Creating: Snapshot creation has been accepted and runtime capture is in progress.
        - Deleting: Snapshot deletion has been requested and cleanup is in progress.
        - Ready: Snapshot is available for restoring sandboxes.
        - Failed: Snapshot creation failed.

        Note: New state values may be added in future versions.
        Clients should handle unknown state values gracefully.

    SnapshotStatus:
      type: object
      description: Detailed snapshot status information with lifecycle state and transition details.
      properties:
        state:
          $ref: '#/components/schemas/SnapshotState'
          description: Current lifecycle state of the snapshot

        reason:
          type: string
          description: |
            Short machine-readable reason code for the current state.
            Examples: "snapshot_accepted", "snapshot_ready", "snapshot_capture_failed"

        message:
          type: string
          description: Human-readable message describing the current state or failure reason

        lastTransitionAt:
          type: string
          format: date-time
          description: Timestamp of the last state transition

      required: [state]
      additionalProperties: false

    Sandbox:
      type: object
      description: Runtime execution environment provisioned from a container image or restored from a snapshot
      properties:
        id:
          type: string
          description: Unique sandbox identifier

        image:
          $ref: '#/components/schemas/ImageSpec'
          description: |
            Container image specification used to provision this sandbox.
            Present when the sandbox was created directly from a container image.
            Not returned in createSandbox response.

        snapshotId:
          type: string
          description: |
            Snapshot identifier used to restore this sandbox.
            Present when the sandbox was restored from a snapshot.
            Not returned in createSandbox response.

        platform:
          $ref: '#/components/schemas/PlatformSpec'
          description: |
            Platform constraint echoed from request or workload template.
            Null when no scheduling constraint is provided.

        status:
          $ref: '#/components/schemas/SandboxStatus'
          description: Current lifecycle status and detailed state information

        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom metadata from creation request

        extensions:
          type: object
          additionalProperties:
            type: string
          description: Opaque extension data restored from provider-specific storage

        allocation:
          $ref: '#/components/schemas/AllocationSummary'
          description: |
            Current runtime-confirmed pool allocation. Omitted unless an active pool
            allocation is confirmed; this is not a request echo, allocation history,
            readiness signal, or Kubernetes introspection result.

        entrypoint:
          type: array
          items:
            type: string
          description: |
            The command to execute as the sandbox's entry process.
            Always present in responses. For image-created sandboxes, this is copied
            from the creation request. For snapshot-created sandboxes, this is restored
            from the snapshot.

        expiresAt:
          type: string
          format: date-time
          description: Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.

        createdAt:
          type: string
          format: date-time
          description: Sandbox creation timestamp

      required:
        - id
        - status
        - createdAt
        - entrypoint
    AllocationSummary:
      type: object
      description: Public summary of a confirmed active pool allocation.
      properties:
        mode:
          type: string
          enum: [pool]
          description: Allocation mode.
        poolRef:
          type: string
          description: Concrete pool reference currently allocated.
        state:
          type: string
          enum: [allocated]
          description: Current confirmed allocation state.
      required: [mode, poolRef, state]
      additionalProperties: false
    SandboxState:
      type: string
      description: |
        High-level lifecycle state of the sandbox.

        Common state values:
        - Pending: Sandbox is being provisioned
        - Running: Sandbox is running and ready to accept requests
        - Pausing: Sandbox is in the process of pausing
        - Paused: Sandbox has been paused while retaining its state
        - Resuming: Sandbox is being restored after a pause
        - Stopping: Sandbox is being terminated
        - Terminated: Sandbox has been successfully terminated
        - Failed: Sandbox encountered a critical error

        State transitions:
        - Pending → Running (after creation completes)
        - Running → Pausing (when pause is requested)
        - Pausing → Paused (pause operation completes)
        - Paused → Resuming (when resume is requested)
        - Resuming → Running (when resume operation completes)
        - Running/Paused → Stopping (when kill is requested or TTL expires)
        - Stopping → Terminated (kill/timeout operation completes)
        - Pending/Running/Paused/Resuming → Failed (on error)

        Note: New state values may be added in future versions.
        Clients should handle unknown state values gracefully.
    SandboxStatus:
      type: object
      description: Detailed status information with lifecycle state and transition details
      properties:
        state:
          $ref: '#/components/schemas/SandboxState'
          description: Current lifecycle state of the sandbox

        reason:
          type: string
          description: |
            Short machine-readable reason code for the current state.
            Examples: "user_delete", "ttl_expiry", "provision_timeout", "runtime_error"

        message:
          type: string
          description: Human-readable message describing the current state or reason for state transition

        lastTransitionAt:
          type: string
          format: date-time
          description: Timestamp of the last state transition

      required: [state]
    ImageSpec:
      type: object
      required: [uri]
      description: |
        Container image specification for sandbox provisioning.

        Supports public registry images and private registry images with authentication.
      properties:
        uri:
          type: string
          description: |
            Container image URI in standard format.

            Examples:
              - "python:3.11" (Docker Hub)
              - "ubuntu:22.04"
              - "gcr.io/my-project/model-server:v1.0"
              - "private-registry.company.com:5000/app:latest"

        auth:
          type: object
          description: Registry authentication credentials (required for private registries)
          properties:
            username:
              type: string
              description: Registry username or service account
            password:
              type: string
              description: Registry password or authentication token
          additionalProperties: false

      additionalProperties: false
    PlatformSpec:
      type: object
      required: [os, arch]
      description: |
        Runtime platform constraint used for scheduling/provisioning.

        This field is independent from `image` and expresses the expected target
        OS and CPU architecture for sandbox execution.

        Behavioral notes:
        - If omitted, the runtime applies its own default platform selection behavior.
          For Docker, requests are created without an explicit platform override.
          For Kubernetes, no `kubernetes.io/os` or `kubernetes.io/arch` constraint
          is injected unless provided by request or workload template.
        - If provided and cannot be satisfied by runtime/template/pool constraints,
          request must fail explicitly.
      properties:
        os:
          type: string
          enum: [linux, windows]
          description: Target operating system (for example `linux` or `windows`).
          example: linux
        arch:
          type: string
          enum: [amd64, arm64]
          description: Target CPU architecture (for example `amd64` or `arm64`).
          example: arm64
      additionalProperties: false
    LifecycleHook:
      type: object
      required: [command]
      description: |
        A lifecycle command executed directly as an argv array. No implicit shell
        expansion is performed. Use an explicit shell command such as
        `["sh", "-c", "..."]` when shell syntax is required.
      properties:
        command:
          type: array
          minItems: 1
          items:
            type: string
          description: Command and arguments to execute.
        timeoutSeconds:
          type: integer
          minimum: 1
          maximum: 10800
          description: Maximum execution time in seconds, up to 3 hours (10800 seconds) for `preStart`. The server defaults to 60 when omitted.
      additionalProperties: false
    PeriodicLifecycleHook:
      type: object
      required: [name, schedule, command]
      description: A named lifecycle command scheduled inside the sandbox by execd.
      properties:
        name:
          type: string
          minLength: 1
          description: Name unique among periodic hooks in this sandbox.
        schedule:
          type: string
          minLength: 1
          description: |
            Five-field cron expression or descriptor such as `@hourly` or
            `@every 30s`. An `@every` interval must be a whole number of
            seconds with a minimum of one second.
        command:
          type: array
          minItems: 1
          items:
            type: string
          description: Command and arguments to execute without implicit shell expansion.
        timeoutSeconds:
          type: integer
          minimum: 1
          maximum: 300
          description: Maximum execution time in seconds, up to 300. The server defaults to 60 when omitted.
      additionalProperties: false
    SandboxLifecycle:
      type: object
      description: |
        Extensible container for sandbox lifecycle configuration. All fields
        are optional. Future lifecycle events are added as new optional
        fields without changing the semantics of existing fields.

        `preStart` and `periodic` are hooks executed inside the sandbox by
        execd. `idlePolicy` (OSEP-0024) and `renewalPolicy` (OSEP-0009) are
        control-plane policies: they tell the server how to treat the
        sandbox's state machine and never reach the guest.
      properties:
        preStart:
          $ref: '#/components/schemas/LifecycleHook'
          description: |
            Runs in execd after its HTTP server is ready and before the user
            entrypoint on every sandbox container start. A failed or timed-out
            hook prevents the user entrypoint from starting.
        periodic:
          type: array
          items:
            $ref: '#/components/schemas/PeriodicLifecycleHook'
          description: |
            Scheduled hooks run by execd while the sandbox is running. Runs of
            the same named hook never overlap; a scheduled run is skipped when
            its previous run is still active.
        idlePolicy:
          $ref: '#/components/schemas/IdlePolicy'
          description: |
            Auto-pause and wake-on-access behavior (OSEP-0024). Supported only
            by the fast-sandbox backend; other backends reject the field.
            Omitting `idlePolicy` preserves non-automated behavior exactly:
            the sandbox is never auto-paused and never auto-woken.
        renewalPolicy:
          $ref: '#/components/schemas/RenewalPolicy'
          description: |
            Renew-on-access behavior (OSEP-0009): each ingress-observed or
            proxied access extends the sandbox expiration. Control-plane
            state and never reaches the guest. Supported by the docker and
            Kubernetes (pod) backends; the fast-sandbox backend rejects the
            field. Supersedes the deprecated
            `extensions["access.renew.extend.seconds"]` creation key, which
            remains supported throughout 1.x and is removed in 2.0.
      additionalProperties: false
    RenewalPolicy:
      type: object
      description: |
        Renew-on-access behavior declared by the sandbox (OSEP-0009). The
        policy is desired control-plane state: when the ingress gateway or
        the server proxy observes traffic for the sandbox, the server extends
        the sandbox expiration without client involvement. The policy never
        reaches the guest.

        Setting the policy has no effect unless the server operator enabled
        the renew-intent integration (`[renew_intent]`). A missing policy
        means the sandbox never auto-renews.
      required: [extendSeconds]
      properties:
        extendSeconds:
          type: integer
          minimum: 300
          maximum: 86400
          description: |
            Extension window X in seconds for each access-driven renewal:
            the expiration is moved to `max(now + X, current expiresAt)`.
            Must be between 300 (5 minutes) and 86400 (24 hours) inclusive.
      additionalProperties: false
    IdlePolicy:
      type: object
      description: |
        Idle behavior declared by the sandbox (OSEP-0024). The policy is
        desired state: the server validates it and persists it as the
        reserved `sandbox.opensandbox.io/idle-policy` Sandbox CR annotation.

        With `idleTimeoutSeconds`, the sandbox is auto-paused after that many
        seconds without ingress-observed activity. Without it, the policy is
        wake-only: the sandbox is never auto-paused, but a (manually) paused
        sandbox wakes on access. A missing, malformed, or invalid policy is
        treated exactly as absent — never as an implicit opt-in.

        Constraints: `idleTimeoutSeconds` must not exceed the server's
        configured activity TTL (default 1800), so a present-but-stale
        activity key always implies idle-by-value. Enabling deployment flags
        never changes the behavior of sandboxes that do not declare a policy.
      properties:
        idleTimeoutSeconds:
          type: integer
          minimum: 30
          maximum: 86400
          description: |
            Idle threshold X in seconds: the sandbox is auto-paused after X
            continuously idle seconds. Absent together with `onIdle` means a
            wake-only policy.
        onIdle:
          type: string
          enum: [pause]
          description: |
            Action taken at the idle threshold. Required with, and only
            valid with, `idleTimeoutSeconds`. Only `pause` exists today; the
            enum exists so future actions are additive.
        wakeOnAccess:
          type: boolean
          description: |
            Whether incoming traffic may wake the sandbox from `Paused`.
            Defaults to `true` when omitted.
            `false` keeps today's paused behavior (permanent 503 through the
            gateway) and only `POST /sandboxes/{sandboxId}/resume` restores
            the sandbox.
        activeProbe:
          $ref: '#/components/schemas/ActivityProbe'
          description: |
            Application-declared activity probe. When the sandbox is
            otherwise idle, the server issues `GET {path}` on `{port}`;
            `200 {"active": true}` counts as activity and resets the idle
            clock, while `{"active": false}`, any failure, or a timeout
            records nothing. Relevant only with auto-pause.
      additionalProperties: false
    ActivityProbe:
      type: object
      required: [port, path]
      description: |
        Endpoint inside the sandbox that answers `{"active": bool,
        "message"?: string}` with 200 while work is in progress.
      properties:
        port:
          type: integer
          minimum: 1
          maximum: 65535
          description: Sandbox port serving the probe endpoint.
        path:
          type: string
          minLength: 1
          maxLength: 512
          pattern: '^/'
          description: |
            Absolute HTTP path of the probe endpoint. Must not contain
            whitespace or control characters.
        timeoutSeconds:
          type: integer
          minimum: 1
          maximum: 10
          description: Probe request budget in seconds. The server defaults to 2 when omitted.
      additionalProperties: false
    PatchSandboxMetadataRequest:
      type: object
      description: |
        JSON Merge Patch (RFC 7396) request body for updating sandbox metadata.

        The request body is the metadata object itself:
        - Present keys with non-null values add or replace
        - Keys with `null` values are deleted
        - Absent keys are left unchanged

        Keys with the `opensandbox.io/` prefix are reserved and rejected.
      additionalProperties:
        type:
          - string
          - 'null'
      example:
        project: "new-project"
        team: null
        environment: "production"

    CreateSandboxRequest:
      type: object
      description: |
        Request to create a new sandbox from either a container image, a snapshot,
        or a pre-configured pool (via `extensions.poolRef`).

        **Standard mode**: Exactly one of `image` or `snapshotId` must be provided,
        and `resourceLimits` is required.

        When `image` is provided, `entrypoint` is required. When `snapshotId` is
        provided, `entrypoint` is optional. If omitted, the server defaults the
        sandbox entrypoint to `["tail", "-f", "/dev/null"]`.

        **Pool mode**: When `extensions.poolRef` is set, the sandbox is created from
        a pre-configured on-demand Pool. In this case `image` and `resourceLimits`
        are optional and defined by the Pool CRD template. `entrypoint` is also
        optional; when omitted, the server creates a per-allocation task using
        `['tail', '-f', '/dev/null']`. The Pool must run task-executor and provide
        bootstrap plus execd.
        `snapshotId`, `networkPolicy`, `platform`, `volumes`, and
        `credentialProxy.enabled` must not be provided together with `poolRef`.

        **Note**: API Key authentication is required via the `OPEN-SANDBOX-API-KEY` header.
      properties:
        image:
          $ref: '#/components/schemas/ImageSpec'
          description: |
            Container image specification for the sandbox.
            Mutually exclusive with `snapshotId`.

        snapshotId:
          type: string
          description: |
            Snapshot identifier to restore from.
            Mutually exclusive with `image`.

        templateId:
          type: string
          minLength: 1
          description: |
            Fsb (fast-sandbox microVM) template to create the sandbox from; on the
            `kubernetes` runtime this routes the create to the fsb catalog.
            Mutually exclusive with `image` and `snapshotId`; in template mode
            the workload shape is fixed by the template's golden image, so
            `entrypoint`, `env`, `resourceLimits`, `resourceRequests`,
            `volumes`, `platform`, `secureAccess` and
            lifecycle hooks are rejected (400), and `timeout` is required.
            `credentialProxy` is accepted and ignored: the vault is not
            carried at create time — it is configured after creation through
            the server-routed Credential Vault API
            (`/sandboxes/{sandboxId}/credential-vault`).
            `lifecycle.idlePolicy` is allowed: it is control-plane state,
            not workload shape.
            The template must belong to the requester's tenant and be
            `Succeeded`; anything else yields 404 (no existence leak).

        platform:
          $ref: '#/components/schemas/PlatformSpec'
          description: |
            Optional platform constraint for sandbox scheduling/runtime selection.

            If omitted, runtime default behavior applies (runtime-specific and not
            a fixed architecture guarantee). If specified, the runtime must satisfy
            this constraint or fail explicitly.
            This field is only meaningful when scheduling constraints are set.

        timeout:
          oneOf:
            - type: integer
              minimum: 60
            - type: 'null'
          description: |
            Sandbox timeout in seconds. The sandbox will automatically terminate after this duration.
            The maximum is controlled by the server configuration (`server.max_sandbox_timeout_seconds`).
            Omit this field or set it to null to disable automatic expiration and require explicit cleanup.
            Note: manual cleanup support is runtime-dependent; Kubernetes providers may reject
            omitted or null timeout when the underlying workload provider does not support non-expiring sandboxes.

        resourceLimits:
          $ref: '#/components/schemas/ResourceLimits'
          description: |
            Runtime resource constraints (hard caps) for the sandbox instance.
            Required when `extensions.poolRef` is not set.
            Optional when using pool mode (resource limits are defined by the Pool CRD template).
            SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi").

        resourceRequests:
          $ref: '#/components/schemas/ResourceLimits'
          description: |
            Resource reservations (guaranteed minimums) for the sandbox instance.
            When provided, these values are used as Kubernetes resource `requests`,
            enabling Burstable QoS class (where `requests < limits`).
            When omitted, `resourceLimits` values are used for both limits and requests,
            resulting in Guaranteed QoS class.
            Only meaningful for Kubernetes-based runtimes; ignored by Docker runtime.

        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables to inject into the sandbox runtime.
          example:
            API_KEY: "secret-key"
            DEBUG: "true"
            LOG_LEVEL: "info"

        metadata:
          type: object
          additionalProperties:
            type: string
          description: |
            Custom key-value metadata for management, filtering, and tagging.
            Use "name" key for a human-readable identifier.
          example:
            name: "Data Processing Sandbox"
            project: "data-processing"
            team: "ml"
            environment: "staging"

        lifecycle:
          $ref: '#/components/schemas/SandboxLifecycle'
          description: |
            Optional declarative sandbox lifecycle configuration. `preStart`
            and `periodic` are hooks; the server transports them to execd and
            callers must not depend on the internal transport mechanism. The
            configuration is not included in Sandbox responses.

            Lifecycle hooks are not supported together with
            `extensions.poolRef`, because Pool Pods are pre-created before
            request-specific hooks are known. Runtimes that do not implement
            lifecycle hook transport reject hooks. `lifecycle.idlePolicy` is
            not a hook and may accompany `extensions.poolRef`; it is honored
            only by the fast-sandbox backend and rejected by others.
            `lifecycle.renewalPolicy` is likewise not a hook: it may
            accompany `extensions.poolRef` and is honored by the docker and
            Kubernetes (pod) backends, while the fast-sandbox backend rejects
            it. Setting both `lifecycle.renewalPolicy` and the deprecated
            `extensions["access.renew.extend.seconds"]` is accepted only when
            their parsed values match; conflicting values are rejected with
            HTTP 400.

        entrypoint:
          type: array
          items:
            type: string
          minItems: 1
          description: |
            The command to execute as the sandbox's entry process.

            Required when `image` is provided.

            Optional when `snapshotId` is provided. If omitted for snapshot
            restore, the server defaults to `["tail", "-f", "/dev/null"]`.

            Optional when `extensions.poolRef` is provided. If omitted for Pool
            mode, the server uses the same default in a per-allocation task.

            Explicitly specifies the user's expected main process, allowing the sandbox management
            service to reliably inject control processes before executing this command.

            Format: [executable, arg1, arg2, ...]

            Examples:
            - ["python", "/app/main.py"]
            - ["/bin/bash"]
            - ["java", "-jar", "/app/app.jar"]
            - ["node", "server.js"]
          example:
            - "python"
            - "/app/main.py"

        networkPolicy:
          $ref: '#/components/schemas/NetworkPolicy'
          description: |
            Optional outbound network policy for the sandbox.
            Shape matches the sidecar `/policy` endpoint. If omitted or empty,
            the sidecar starts in allow-all mode until updated.
            For Fsb, an omitted policy still registers an egress binding,
            seeded with a no-op default-allow record (the sandbox behaves
            like a policy-less one until changed): runtime changes go
            through the networkpolicy endpoints (handler relay), which
            require that registration.
            Not supported together with `extensions.poolRef`; pooled pods are
            pre-created, so the server rejects this combination instead of
            silently ignoring the requested policy.

        credentialProxy:
          $ref: '#/components/schemas/CredentialProxyConfig'
          description: |
            Optional Credential Vault proxy startup settings. Set `enabled: true`
            to enable transparent MITM support for credential injection. Plain
            `networkPolicy` does not enable transparent MITM unless this option
            is set. On fsb template-backed sandboxes the field is accepted and
            ignored at create time: the shared-Fastlet egress has no per-sandbox
            sidecar, and the vault is configured after creation through the
            server-routed Credential Vault API.

        secureAccess:
          type: boolean
          default: false
          description: |
            Opts the sandbox into secured access for endpoint access.
            This is currently supported only for Kubernetes sandboxes exposed
            through ingress gateway mode. When enabled, the server provisions
            access credentials and returns the required request headers with
            endpoint responses. Clients must include those endpoint headers when
            calling the sandbox. When omitted or false, endpoints remain
            accessible without the additional access token for backward
            compatibility.

        volumes:
          type: array
          description: |
            Storage mounts for the sandbox. Each volume entry specifies a named backend-specific
            storage source and common mount settings. Exactly one backend type must be specified
            per volume entry.
          items:
            $ref: '#/components/schemas/Volume'

        extensions:
          type: object
          additionalProperties:
            type: string
          description: |
            Opaque container for provider-specific or transient parameters not supported by the core API.

            **Note**: This field is reserved for internal features, experimental flags, or temporary behaviors. Standard parameters should be proposed as core API fields.

            **Best Practices**:
            - **Namespacing**: Use prefixed keys (e.g., `storage.id`) to prevent collisions.
            - **Pass-through**: SDKs and middleware must treat this object as opaque and pass it through transparently.

            **Well-known keys**:
            - `access.renew.extend.seconds` (**deprecated**): Decimal integer
              string from **300** to **86400** (5 minutes to 24 hours
              inclusive). Opts the sandbox into OSEP-0009 renew-on-access and
              sets per-renewal extension seconds. Omit to disable. Invalid
              values are rejected at creation with HTTP 400 (validated on the
              lifecycle create endpoint via `validate_extensions` in server
              `src/extensions/validation.py`). Superseded by
              `lifecycle.renewalPolicy.extendSeconds`: prefer the structured
              field in new code. The extensions key remains supported
              throughout 1.x and is removed in 2.0; when both are set, their
              parsed values must match or creation fails with HTTP 400.
    ResourceLimits:
      type: object
      description: |
        Runtime resource constraints as key-value pairs. Similar to Kubernetes resource specifications,
        allows flexible definition of resource limits. Common resource types include:
        - `cpu`: CPU allocation in millicores (e.g., "250m" for 0.25 CPU cores)
        - `memory`: Memory allocation in bytes or human-readable format (e.g., "512Mi", "1Gi")
        - `gpu`: Number of GPU devices (e.g., "1")

        New resource types can be added without API changes.
      additionalProperties:
        type: string
      example:
        cpu: "500m"
        memory: "512Mi"
        gpu: "1"
    RenewSandboxExpirationRequest:
      type: object
      required: [expiresAt]
      properties:
        expiresAt:
          type: string
          format: date-time
          description: |
            New absolute expiration time in UTC (RFC 3339 format).
            Must be in the future. May be earlier than, equal to, or later than the current expiresAt.
            The creation-time limit `server.max_sandbox_timeout_seconds` does not apply.

            Example: "2025-11-16T14:30:45Z"
      additionalProperties: false
    RenewSandboxExpirationResponse:
      type: object
      required: [expiresAt]
      properties:
        expiresAt:
          type: string
          format: date-time
          description: |
            The new absolute expiration time in UTC (RFC 3339 format).

            Example: "2025-11-16T14:30:45Z"
      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 (e.g., INVALID_REQUEST, NOT_FOUND, INTERNAL_ERROR).
            Use this for programmatic error handling.
        message:
          type: string
          description: Human-readable error message describing what went wrong and how to fix it.
      required: [code, message]
      additionalProperties: false
    Endpoint:
      type: object
      description: |
        Endpoint for accessing a service running in the sandbox.
        The service must be listening on the specified port inside the sandbox for the endpoint to be available.
      properties:
        endpoint:
          type: string
          description: |
            Public URL to access the service from outside the sandbox.
            Format: {endpoint-host}/sandboxes/{sandboxId}/port/{port}
            Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
        headers:
          type: object
          additionalProperties:
            type: string
          description: |
            Requests targeting the sandbox must include the corresponding header(s).
      required:
        - endpoint
      additionalProperties: false

    PolicyStatusResponse:
      type: object
      description: |
        Policy intent for Fsb, or the sidecar policy for other backends.
        Fsb does not report live enforcement state or enforcementMode.
      properties:
        status:
          type: string
          example: ok
        mode:
          type: string
          description: Mode derived from the returned policy.
          example: deny_all
        enforcementMode:
          type: string
          description: Optional sidecar enforcement backend; omitted for Fsb.
        reason:
          type: string
          description: Optional context returned by the sidecar.
        policy:
          $ref: '#/components/schemas/NetworkPolicy'
      additionalProperties: false
    NetworkPolicy:
      type: object
      description: |
        Egress network policy matching the sidecar `/policy` request body.
        If `defaultAction` is omitted, the sidecar defaults to "deny"; passing an empty
        object or null results in allow-all behavior at startup.
      properties:
        defaultAction:
          type: string
          enum: [allow, deny]
          description: Default action when no egress rule matches. Defaults to "deny".
        egress:
          type: array
          description: List of egress rules evaluated in order.
          items:
            $ref: '#/components/schemas/NetworkRule'
      additionalProperties: false

    CredentialProxyConfig:
      type: object
      description: |
        Credential Vault proxy startup settings. This is an explicit opt-in for
        transparent MITM support used by credential injection. Credential Vault
        requires `dns+nft` enforcement and a network policy. A deny-default policy
        is strongly recommended; default-allow remains temporarily supported for
        backward compatibility and emits a security warning.
      properties:
        enabled:
          type: boolean
          default: false
          description: |
            When true, the server starts the egress sidecar with transparent
            MITM enabled and installs the runtime-managed MITM CA bundle into
            the sandbox container. Requires `networkPolicy` and server
            `[egress].mode = "dns+nft"`. `defaultAction: deny` is strongly
            recommended; default-allow support is deprecated.
      additionalProperties: false

    NetworkRule:
      type: object
      description: >-
        Egress rule. At least one of `target` or `ports` must be provided;
        when both are present the rule applies to `ports` on `target` only.
        Enforced by the server and the egress sidecar.
      properties:
        action:
          type: string
          enum: [allow, deny]
          description: Whether to allow or deny matching targets.
        target:
          type: string
          description: |
            FQDN, wildcard domain (e.g., "example.com", "*.example.com"), IP
            address, or CIDR. May be omitted when `ports` is set (see below);
            otherwise required.
        ports:
          type: array
          minItems: 1
          maxItems: 256
          uniqueItems: true
          items:
            type: integer
            minimum: 1
            maximum: 65535
          description: |
            Restricts this rule to specific TCP destination ports.

            - `target` omitted, `ports` set: the rule applies to these ports
              across all IPv4/IPv6 destinations.
            - `target` is an IP or CIDR, `ports` set: the rule applies to that
              destination only on these ports.
            - `target` is a domain: `ports` is rejected with a validation
              error. Domain rules are evaluated at the DNS layer, which has no
              port dimension; combining them is not supported yet.

            TCP only for now; UDP port scoping is not supported.

            Under `defaultAction: deny`, the DNS proxy still denies hostname
            lookups for targetless allow rules (it matches domain rules
            only), so this shape serves direct-IP clients; hostname access
            requires explicit domain rules or stable IPs.
      required: [action]
      additionalProperties: false

    CredentialVaultCreateRequest:
      type: object
      description: |
        Initial Credential Vault revision. Inline credential values are
        write-only. The vault requires a network policy; `defaultAction:
        deny` is strongly recommended.
      properties:
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
        bindings:
          type: array
          items:
            $ref: '#/components/schemas/CredentialBinding'
      required: [credentials, bindings]
      additionalProperties: false
    CredentialVaultMutationRequest:
      type: object
      description: |
        One atomic mutation set. Applied per set as delete → replace → add;
        every mentioned name must resolve exactly once (add requires the
        name to be absent, replace and delete require it to exist).
      properties:
        expectedRevision:
          type: integer
          description: Optional optimistic concurrency guard; mismatch fails with 412.
        credentials:
          $ref: '#/components/schemas/CredentialMutationSet'
        bindings:
          $ref: '#/components/schemas/CredentialBindingMutationSet'
      additionalProperties: false
    CredentialMutationSet:
      type: object
      properties:
        add:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
        replace:
          type: array
          items:
            $ref: '#/components/schemas/Credential'
        delete:
          type: array
          items:
            type: string
      additionalProperties: false
    CredentialBindingMutationSet:
      type: object
      properties:
        add:
          type: array
          items:
            $ref: '#/components/schemas/CredentialBinding'
        replace:
          type: array
          items:
            $ref: '#/components/schemas/CredentialBinding'
        delete:
          type: array
          items:
            type: string
      additionalProperties: false
    CredentialVaultState:
      type: object
      description: Sanitized Credential Vault state — credential values never appear.
      properties:
        revision:
          type: integer
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/CredentialMetadata'
        bindings:
          type: array
          items:
            $ref: '#/components/schemas/CredentialBindingMetadata'
      required: [revision, credentials, bindings]
      additionalProperties: false
    CredentialListResponse:
      type: object
      properties:
        revision:
          type: integer
        credentials:
          type: array
          items:
            $ref: '#/components/schemas/CredentialMetadata'
      required: [revision, credentials]
      additionalProperties: false
    CredentialBindingListResponse:
      type: object
      properties:
        revision:
          type: integer
        bindings:
          type: array
          items:
            $ref: '#/components/schemas/CredentialBindingMetadata'
      required: [revision, bindings]
      additionalProperties: false
    CredentialMetadata:
      type: object
      properties:
        name:
          type: string
        sourceType:
          type: string
          description: Credential source kind (`inline` or `exchange`).
        revision:
          type: integer
          description: |
            Revision that last touched this record. Fsb stamps records with
            the read revision (the relay surface does not carry per-record
            revisions); other backends track per-record revisions.
      required: [name, sourceType, revision]
      additionalProperties: false
    CredentialBindingMetadata:
      type: object
      properties:
        name:
          type: string
        revision:
          type: integer
          description: See CredentialMetadata.revision for the Fsb caveat.
        match:
          $ref: '#/components/schemas/CredentialMatch'
        auth:
          $ref: '#/components/schemas/CredentialAuthMetadata'
      required: [name, revision]
      additionalProperties: false
    CredentialAuthMetadata:
      type: object
      description: Sanitized auth shape — `type` (plus `name` for `apiKey`) for static kinds; `credential` only for the typeless exchange form.
      properties:
        type:
          type: string
        name:
          type: string
        credential:
          type: string
      additionalProperties: false
    Credential:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        source:
          $ref: '#/components/schemas/CredentialSource'
      required: [name, source]
      additionalProperties: false
    CredentialSource:
      type: object
      required: [type]
      description: |
        Where the credential material comes from. Exactly one kind, selected
        by `type`:

        - `inline`: the secret value travels in this request via `value`.
          Inline values are write-only and never appear in reads.
        - `exchange`: no local material. Egress resolves header sets per
          request from a header-resolver service addressed by `endpoint`.
          Supported endpoint forms are `unix:///absolute/path` (HTTP over a
          Unix domain socket) and `https://host[:port]` (TLS); anything else
          is rejected with 400.

        Fields of the other kind must be absent; for example `value` together
        with `type: exchange` is rejected with 400.
      properties:
        type:
          type: string
          enum: [inline, exchange]
        value:
          type: string
          writeOnly: true
          description: |
            Inline secret value. Required when `type` is `inline`; must be
            absent otherwise.
        endpoint:
          type: string
          description: |
            Header-resolver endpoint. Required when `type` is `exchange`; must
            be absent otherwise.
      additionalProperties: false
    CredentialBinding:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        match:
          $ref: '#/components/schemas/CredentialMatch'
        auth:
          $ref: '#/components/schemas/CredentialAuth'
      required: [name, match, auth]
      additionalProperties: false
    CredentialMatch:
      type: object
      properties:
        schemes:
          type: array
          items:
            type: string
            enum: [https, http]
          default: [https]
        ports:
          type: array
          items:
            type: integer
          deprecated: true
          description: "Deprecated. Port is derived from scheme (https→443, http→80). Values other than 80 or 443 are rejected with a validation error. Standard values (80/443) are accepted but ignored."
        hosts:
          type: array
          minItems: 1
          items:
            type: string
        methods:
          type: array
          items:
            type: string
          default: [GET, POST, PUT, PATCH, DELETE]
        paths:
          type: array
          items:
            type: string
          default: ["/*"]
      required: [hosts]
      additionalProperties: false
    CredentialAuth:
      type: object
      description: |
        How a binding injects credential material. Exactly one auth kind:

        - `bearer`: `type: bearer` plus `credential`.
        - `basic`: `type: basic` plus `credential`.
        - `apiKey`: `type: apiKey` plus `name` and `credential`.
        - `customHeaders`: `type: customHeaders` plus `headers`.
        - `passthrough`: `type: passthrough`, no credential reference.
        - typeless exchange: `type` omitted with only `credential` set. The
          referenced credential must be exchange-sourced; egress resolves the
          header set per request from the credential's endpoint.

        Static kinds must reference inline-sourced credentials, and the
        typeless form must reference an exchange-sourced credential and must
        not set `name`, `headers`, or `substitutions`. The five static kinds
        accept optional `substitutions`. Violations are rejected with 400.
      properties:
        type:
          type: string
          enum: [bearer, basic, apiKey, customHeaders, passthrough]
          description: Static auth kind. Omit entirely for the typeless exchange form.
        credential:
          type: string
          minLength: 1
          description: |
            Name of the sandbox-local credential whose value is injected. For
            `bearer` the value becomes the bearer token; for `basic` it
            contains pre-encoded base64(username:password). Required for
            `bearer`, `basic`, `apiKey`, and the typeless exchange form; must
            be absent otherwise.
        name:
          type: string
          pattern: '^[A-Za-z0-9!#$%&''*+\-.^_`|~]+$'
          description: Request header name. Required for `apiKey`; must be absent otherwise.
        headers:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CustomHeaderEntry'
          description: Static header set. Required for `customHeaders`; must be absent otherwise.
        substitutions:
          type: array
          items:
            $ref: '#/components/schemas/CredentialSubstitution'
          description: |
            Optional placeholder replacement set. Accepted for the five static
            kinds; must be absent for the typeless exchange form.
      additionalProperties: false
    CustomHeaderEntry:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          pattern: '^[A-Za-z0-9!#$%&''*+\-.^_`|~]+$'
        credential:
          type: string
          minLength: 1
          description: Credential name whose value is injected.
      required: [name, credential]
      additionalProperties: false
    CredentialSubstitution:
      type: object
      description: Literal case-sensitive placeholder replacement for selected request surfaces. Replacement is opt-in and scoped per binding.
      properties:
        credential:
          type: string
          minLength: 1
          description: Name of the sandbox-local credential used as the replacement value.
        placeholder:
          type: string
          minLength: 1
          description: Literal placeholder to replace.
        in:
          type: array
          minItems: 1
          items:
            type: string
            enum: [path, query, header, body]
          description: Request surfaces where the placeholder may be replaced.
      required: [credential, placeholder, in]
      additionalProperties: false

    Volume:
      type: object
      description: |
        Storage mount definition for a sandbox. Each volume entry contains:
        - A unique name identifier
        - Exactly one backend struct (host, pvc, ossfs, etc.) with backend-specific fields
        - Common mount settings (mountPath, readOnly, subPath)
      required: [name, mountPath]
      properties:
        name:
          type: string
          description: |
            Unique identifier for the volume within the sandbox.
            Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
          pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
          maxLength: 63
        host:
          $ref: '#/components/schemas/Host'
        pvc:
          $ref: '#/components/schemas/PVC'
        ossfs:
          $ref: '#/components/schemas/OSSFS'
        mountPath:
          type: string
          description: |
            Absolute path inside the container where the volume is mounted.
            Must start with '/'.
          pattern: "^/.*"
        readOnly:
          type: boolean
          description: |
            If true, the volume is mounted as read-only. Defaults to false (read-write).
          default: false
        subPath:
          type: string
          description: |
            Optional subdirectory under the backend path to mount.
            For `ossfs` backend, this field is used as the bucket prefix.
            Must be a relative path without '..' components.
      additionalProperties: false

    Host:
      type: object
      description: |
        Host path bind mount backend. Maps a directory on the host filesystem
        into the container. Only available when the runtime supports host mounts.

        Security note: Host paths are restricted by server-side allowlist.
        Users must specify paths under permitted prefixes.
      required: [path]
      properties:
        path:
          type: string
          description: |
            Absolute path on the host filesystem to mount.
            Must start with '/' (Unix) or a drive letter such as 'C:\' or 'D:/'
            (Windows), and be under an allowed prefix.
          pattern: "^(/|[A-Za-z]:[\\\\/])"
      additionalProperties: false

    PVC:
      type: object
      description: |
        Platform-managed named volume backend. A runtime-neutral abstraction
        for referencing a platform-managed named volume. If `createIfNotExists`
        is true (the default) and the volume does not yet exist, it will be
        created automatically using the provisioning hints below.

        - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
        - Docker: maps to a Docker named volume (created via `docker volume create`).
      required: [claimName]
      properties:
        claimName:
          type: string
          description: |
            Name of the volume on the target platform.
            In Kubernetes this is the PVC name; in Docker this is the named
            volume name. Must be a valid DNS label.
          pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
          maxLength: 253
        createIfNotExists:
          type: boolean
          default: true
          description: |
            When true (the default), the volume is automatically created if
            it does not exist. When false, referencing a non-existent volume
            fails with an error.
        deleteOnSandboxTermination:
          type: boolean
          default: false
          description: |
            When true, the volume is automatically removed when the sandbox
            is deleted. Only applies to volumes that were auto-created by the
            server on this request; pre-existing volumes are never removed.
            For Kubernetes, the resulting PVC delete triggers the bound PV's
            StorageClass reclaim policy (`Retain`/`Delete`).
        storageClass:
          type: string
          nullable: true
          description: |
            Kubernetes StorageClass name for auto-created PVCs. Null means
            use the cluster default. Ignored for Docker volumes.
        storage:
          type: string
          nullable: true
          description: |
            Storage capacity request for auto-created PVCs (e.g. "1Gi",
            "10Gi"). Defaults to the server-configured `volume_default_size`
            when omitted. Ignored for Docker volumes.
          pattern: "^\\d+(\\.\\d+)?(Ki|Mi|Gi|Ti|Pi|Ei)?$"
        accessModes:
          type: array
          nullable: true
          items:
            type: string
          description: |
            Access modes for auto-created PVCs (e.g. ["ReadWriteOnce"]).
            Defaults to ["ReadWriteOnce"] when omitted. Ignored for Docker
            volumes.
      additionalProperties: false

    OSSFS:
      type: object
      description: |
        Alibaba Cloud OSS mount backend via ossfs.

        The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
        and bind-mounts the resolved path into the sandbox container.
        Prefix selection is expressed via `Volume.subPath`.
        In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
      required: [bucket, endpoint, accessKeyId, accessKeySecret]
      properties:
        bucket:
          type: string
          description: OSS bucket name.
          minLength: 3
          maxLength: 63
        endpoint:
          type: string
          description: OSS endpoint (e.g., `oss-cn-hangzhou.aliyuncs.com`).
          minLength: 1
        version:
          type: string
          description: ossfs major version used by runtime mount integration.
          enum: ["1.0", "2.0"]
          default: "2.0"
        options:
          type: array
          description: |
            Additional ossfs mount options.
            Runtime encodes options by `version`:
            - `1.0`: mounts with `ossfs ... -o <option>`
            - `2.0`: mounts with `ossfs2 mount ... -c <config-file>` and encodes options as `--<option>` lines in the config file
            Option values must be provided as raw payloads without leading `-`.
          items:
            type: string
        accessKeyId:
          type: string
          description: OSS access key ID for inline credentials mode.
          minLength: 1
        accessKeySecret:
          type: string
          description: OSS access key secret for inline credentials mode.
          minLength: 1
      additionalProperties: false

    FsbTemplateReadiness:
      type: object
      description: Build-side readiness gate for a fsb template.
      properties:
        probe:
          type: string
          description: |
            Readiness probe checked first during the golden-image build;
            e.g. `tcp://127.0.0.1:44772` or `cmd://<command>`.
        warmupSeconds:
          type: integer
          minimum: 0
          description: Fallback warmup window in seconds (default 60).
      additionalProperties: false

    CreateFsbTemplateRequest:
      type: object
      description: |
        Request to create a Fast Sandbox template: a fast-sandbox golden-image build
        The server persists the build intent, projects it onto a
        SandboxTemplate CRD, and reports the asynchronous build through the
        template status. Kernel, execd and guest init are server-side build
        inputs supplied from the `[fsb]` configuration, not client fields.
      properties:
        image:
          type: string
          minLength: 1
          description: Source OCI image reference the golden image is built from.
        resourceLimits:
          $ref: '#/components/schemas/ResourceLimits'
          description: |
            Guest machine sizing: `cpu` -> guest vCPUs, `memory` -> guest memory,
            `disk` -> logical size of the guest rootfs (parallel resource keys).
            The artifact set is stored and P2P-pulled at the `disk` size, so keep
            it just above the expanded source image. Defaults when omitted:
            cpu `1`, memory `512Mi`, disk `2Gi`.
        entrypoint:
          type: array
          minItems: 1
          items:
            type: string
          description: |
            Guest business command (argv); empty defaults to
            `["tail", "-f", "/dev/null"]`.
        env:
          type: object
          additionalProperties:
            type: string
          description: |
            Environment variables baked into the golden image (injected as
            `/etc/sandbox-init.env` in the guest; literal values only). The
            source image's own OCI `Config.Env` is inherited like a container
            runtime would; an env with the same name here overrides the
            inherited value. Names must be valid shell variable names
            (`[A-Za-z_][A-Za-z0-9_]*`).
          example:
            LOG_LEVEL: "info"
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value metadata for management, filtering, and tagging.
        readiness:
          $ref: '#/components/schemas/FsbTemplateReadiness'
        publish:
          type: string
          minLength: 1
          description: |
            Publish destination: `s3://bucket/publish` for native artifacts or
            `oci://registry/repository` for overlaybd artifacts. OCI targets
            must not contain a tag or digest; the builder generates unique
            tags per build. Registry credentials are configured on the server.
        format:
          type: string
          enum: [native, overlaybd]
          default: overlaybd
          description: Storage encoding of the produced snapshot set.
      required: [image, publish]
      additionalProperties: false

    FsbTemplateStatus:
      type: object
      description: Status of a fsb template build.
      properties:
        phase:
          type: string
          enum: [Pending, Building, Succeeded, Failed]
          description: Build lifecycle phase.
        manifestRef:
          type: string
          description: |
            Published S3 manifest reference or immutable OCI reference
            (`oci://registry/repository@sha256:...`); present when Succeeded.
        message:
          type: string
          description: Failure reason when phase is Failed.
      required: [phase]
      additionalProperties: false

    FsbTemplate:
      type: object
      description: |
        A fsb template: a golden image whose build is declared and executed
        by fast-sandbox.
      properties:
        templateId:
          type: string
          description: Server-generated template ID (`tpl_<uuid>`).
        image:
          type: string
          description: Source OCI image reference.
        resourceLimits:
          $ref: '#/components/schemas/ResourceLimits'
        entrypoint:
          type: array
          items:
            type: string
          description: Guest business command (argv).
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables baked into the golden image.
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom metadata from the creation request.
        readiness:
          $ref: '#/components/schemas/FsbTemplateReadiness'
        publish:
          type: string
          description: S3-compatible or repository-only OCI publish target.
        format:
          type: string
          enum: [native, overlaybd]
          description: Snapshot storage encoding.
        status:
          $ref: '#/components/schemas/FsbTemplateStatus'
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp (RFC 3339 UTC).
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp (RFC 3339 UTC).
      required: [templateId, image, publish, format, status, createdAt, updatedAt]
      additionalProperties: false

    ListFsbTemplatesResponse:
      type: object
      description: Paginated collection of fsb templates.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/FsbTemplate'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
      required: [items, pagination]
      additionalProperties: false