box.openapi.yaml

# Copyright 2024-2026 BoxLite Contributors
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

---
openapi: 3.1.1
info:
  title: BoxLite Box API
  version: 0.1.0
  description: |
    HTTP API for BoxLite boxes — hardware-isolated VMs for secure code
    execution. Exposes box lifecycle management, command execution, file
    transfer, service tunnels, and image management as a multi-tenant
    service.

    ## Image API migration (breaking change)

    The image catalog replaces the former pull and digest-ID operations.
    `POST /{prefix}/images/pull` and `HEAD /{prefix}/images/{image_id}` are
    removed. Create a box with an image reference to pull it. Replace the
    former `GET /{prefix}/images/{image_id}` with
    `GET /{prefix}/images/{image_name}`, using the URL-encoded registry and
    repository as one path segment. The response is now ImageDetail with
    versions; inspect their digests to check for a particular build.
    Regenerate clients from this specification before upgrading servers.

    ## Design Principles

    This specification follows industry-standard HTTP API patterns:
    - Versioned URL prefix (`/v1/`) for graceful API evolution
    - Multi-tenancy via an opaque `{prefix}` URL segment
    - Capability discovery via `GET /v1/config`
    - Optional idempotency keys for safe mutation retries
    - Opaque page-token pagination
    - Standard error model with typed error codes

    ## Vendor-agnostic routing — the `{prefix}` slot

    Box-scoped endpoints include a `{prefix}` URL path segment whose
    semantics are **deployment-defined**. This contract is
    intentionally silent on what the slot means — a vendor may use it
    for an organization id, a workspace, a warehouse / catalog, a
    region+team pair, or any other routing scope. Clients **MUST**
    treat the value as an opaque substring and substitute it verbatim
    into the URL, including any internal `/` characters (multi-segment
    values are supported).

    Clients discover the value to use via `Principal.path_prefix`
    from `GET /v1/me`. A `null` (or empty) value means the deployment
    does **not** use a routing slot; clients then build URLs without
    the segment (`/v1/boxes/…` instead of `/v1/<prefix>/boxes/…`).
    This is the canonical shape for single-tenant deployments such as
    the `boxlite serve` local server.

    Identity / discovery endpoints (`GET /v1/me`, `GET /v1/config`)
    sit at the version root and **never** include the `{prefix}`
    segment, by spec.

    ## Authentication

    All endpoints (except `GET /v1/config`) require an opaque token in the
    `Authorization: Bearer` header (RFC 6750). The server is **bearer-
    format-agnostic** — any token its validation pipeline can verify is
    accepted. See the `BearerAuth` security scheme for the supported token
    sources, which include BoxLite-issued API keys, plus (configurable per
    deployment) federated SSO JWTs, third-party OIDC tokens, and customer-
    issued gateway tokens.

    Token acquisition is out of scope for this contract: dashboard API
    keys are issued by the BoxLite dashboard; other token sources are
    configured at the customer's gateway or IdP layer.

    Validate a freshly-acquired token via `GET /v1/me`.

    ## Execution Model

    Command execution is two-step:
    1. `POST /exec` creates the execution and returns an `execution_id`.
    2. `GET /executions/{exec_id}/attach` upgrades to a bidirectional
       WebSocket carrying stdin, stdout, stderr, and in-band control
       (resize, signal, exit). One attach at a time per exec; the exec
       continues running across WebSocket close so a client can reattach.

    Out-of-band control endpoints exist for clients that prefer a
    request/response style: `GET /executions/{exec_id}` (status),
    `POST .../resize`, `POST .../signal`, `DELETE /executions/{exec_id}`
    (kill).
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: BoxLite
    url: https://github.com/boxlite-ai/boxlite

servers:
  - url: "{scheme}://{host}{basePath}/v1"
    description: BoxLite Box API v1
    variables:
      scheme:
        default: https
        enum: [https, http]
      host:
        default: api.boxlite.ai
      basePath:
        description: |
          Deployment-defined hostpath prefix. Empty on every deployment:
          `boxlite serve` answers at `http://localhost:8100/v1/…` and a cloud
          stage at `https://api.boxlite.ai/v1/…`. Cloud stages also still
          answer the older `/api` form, which is what clients configured before
          the control plane had a hostname of its own hold.
        default: ""

# ---------------------------------------------------------------------------
# Security
# ---------------------------------------------------------------------------
security:
  - BearerAuth: []

tags:
  - name: Configuration
    description: Server capability discovery
  - name: Authentication
    description: Credential validation and identity lookup
  - name: Boxes
    description: Box lifecycle management
  - name: Execution
    description: Command execution and streaming
  - name: Files
    description: File upload and download
  - name: Network
    description: Box networking and service access
  - name: Metrics
    description: Runtime and per-box metrics
  - name: Images
    description: Container image management
  - name: Volumes
    description: Managed persistent volumes
  - name: Registries
    description: Logins the server pulls private images with
  - name: Domains
    description: Names the organization holds and the box ports they route to

# ===========================================================================
# Paths
# ===========================================================================
paths:

  # -------------------------------------------------------------------------
  # Configuration & Discovery
  # -------------------------------------------------------------------------
  /config:
    get:
      operationId: getConfig
      summary: Get server configuration and capabilities
      description: |
        Returns server defaults, enforced limits, and supported features.
        Clients should call this on startup to adapt behavior.
        No authentication required.
      tags: [Configuration]
      security: []
      responses:
        "200":
          description: Server configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServerConfig"

  # -------------------------------------------------------------------------
  # Authentication
  # -------------------------------------------------------------------------
  /me:
    get:
      operationId: getCurrentPrincipal
      summary: Identity and scopes for the calling credential
      description: |
        Returns the principal (user or service account) and granted scopes
        for the Bearer credential in the request. Typical uses: validating
        a freshly-issued credential, and rendering an identity / scopes
        banner for the current session.
      tags: [Authentication]
      responses:
        "200":
          description: Authenticated principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Principal"
        "401":
          $ref: "#/components/responses/UnauthorizedError"

  # -------------------------------------------------------------------------
  # Volumes
  # -------------------------------------------------------------------------
  /{prefix}/volumes:
    parameters:
      - $ref: "#/components/parameters/prefix"

    post:
      operationId: createVolume
      summary: Create a managed persistent volume
      description: Creates a volume and waits until its backing object storage is ready.
      tags: [Volumes]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateVolumeRequest"
      responses:
        "201":
          description: Volume created and ready for use
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Volume"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "408":
          $ref: "#/components/responses/RequestTimeoutError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"

    get:
      operationId: listVolumes
      summary: List managed persistent volumes
      tags: [Volumes]
      responses:
        "200":
          description: List of volumes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListVolumesResponse"

  /{prefix}/volumes/{volume_id}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/volumeId"

    get:
      operationId: getVolume
      summary: Get managed persistent volume metadata
      tags: [Volumes]
      responses:
        "200":
          description: Volume metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Volume"
        "404":
          $ref: "#/components/responses/NotFoundError"

    delete:
      operationId: removeVolume
      summary: Remove a managed persistent volume
      tags: [Volumes]
      parameters:
        - name: force
          in: query
          description: Treat an already deleting or missing volume as successfully removed
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Volume removal accepted
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  # -------------------------------------------------------------------------
  # Boxes
  # -------------------------------------------------------------------------
  /{prefix}/boxes:
    parameters:
      - $ref: "#/components/parameters/prefix"

    post:
      operationId: createBox
      summary: Create a new box
      description: |
        Creates a new box with the specified configuration.
        The box starts in `configured` status. Call `POST /start` to
        initialize the VM, or it will start lazily on first `exec`.
      tags: [Boxes]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateBoxRequest"
      responses:
        "201":
          description: Box created
          headers:
            Location:
              description: URL of the created box
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Box"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "422":
          $ref: "#/components/responses/UnprocessableEntityError"
        "429":
          $ref: "#/components/responses/ResourceExhaustedError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"

    get:
      operationId: listBoxes
      summary: List all boxes
      description: |
        Returns a paginated list of boxes in the workspace.
        Optionally filter by status or name.
      tags: [Boxes]
      parameters:
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/pageToken"
        - name: status
          in: query
          description: Filter by box status
          schema:
            $ref: "#/components/schemas/BoxStatus"
      responses:
        "200":
          description: List of boxes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListBoxesResponse"

  /{prefix}/boxes/{box_id}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"

    get:
      operationId: getBox
      summary: Get box details
      description: Returns full metadata for a box. Accepts box ID (ULID) or name.
      tags: [Boxes]
      responses:
        "200":
          description: Box details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Box"
        "404":
          $ref: "#/components/responses/NotFoundError"

    head:
      operationId: boxExists
      summary: Check if a box exists
      description: Returns 204 if the box exists, 404 if not. No response body.
      tags: [Boxes]
      responses:
        "204":
          description: Box exists
        "404":
          description: Box not found

    delete:
      operationId: removeBox
      summary: Remove a box
      description: |
        Removes a box and all its associated data (disk, config, state).
        Use `?force=true` to force-remove a running box.
      tags: [Boxes]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
        - name: force
          in: query
          description: Force remove even if the box is running
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Box removed
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  # -------------------------------------------------------------------------
  # Box Lifecycle
  # -------------------------------------------------------------------------
  /{prefix}/boxes/{box_id}/start:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: startBox
      summary: Start a box (initialize VM)
      description: |
        Initializes the VM for a box. Idempotent: if already running, returns
        current state. Transitions: configured → running, stopped → running.
      tags: [Boxes]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
      responses:
        "200":
          description: Box started (or already running)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Box"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/stop:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: stopBox
      summary: Stop a box (terminate VM)
      description: |
        Gracefully stops the VM. The box transitions to `stopped` status.
        AutoDelete may later delete the stopped box according to its configured interval.
      tags: [Boxes]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StopBoxRequest"
      responses:
        "200":
          description: Box stopped
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Box"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/ssh:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: configureSsh
      summary: Configure guest SSH
      description: |
        Replaces the guest's complete SSH configuration; every accepted call
        fully restarts the listener, so it must not be retried automatically.
        May start a `configured` or resume a `stopped` box on the image's
        default command; in those two states an explicit `cmd`/`entrypoint`
        requires a prior start (a running box with an explicit command is
        supported), and a stopped box with `auto_resume=false` returns 409. An
        invalid configuration is rejected without changing the listener
        already running.
      tags: [Boxes]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SshConfig"
      responses:
        "200":
          description: SSH enabled; the response describes the new listener
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SshStatus"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    get:
      operationId: getSshStatus
      summary: Get guest SSH status
      description: |
        Observes the listener without starting the VM or its main command; a
        valid `configured` or `stopped` box reports disabled status with
        generation zero and empty identity fields.
      tags: [Boxes]
      responses:
        "200":
          description: Current SSH status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SshStatus"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"
    delete:
      operationId: disableSsh
      summary: Disable guest SSH
      description: Stops guest SSH and disconnects clients; idempotent, and never starts the VM or its main command.
      tags: [Boxes]
      responses:
        "200":
          description: SSH disabled or already disabled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SshStatus"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "503":
          $ref: "#/components/responses/ServiceUnavailableError"

  # -------------------------------------------------------------------------
  # Snapshot / Portability
  # -------------------------------------------------------------------------
  /{prefix}/boxes/{box_id}/snapshots:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: createSnapshot
      summary: Create a snapshot
      description: |
        Creates a named snapshot from the box's current stopped disk state.
        The box must be stopped.
      tags: [Boxes]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSnapshotRequest"
      responses:
        "201":
          description: Snapshot created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
    get:
      operationId: listSnapshots
      summary: List box snapshots
      tags: [Boxes]
      responses:
        "200":
          description: Snapshot list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListSnapshotsResponse"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /{prefix}/boxes/{box_id}/snapshots/{snapshot_name}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
      - name: snapshot_name
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getSnapshot
      summary: Get snapshot details
      tags: [Boxes]
      responses:
        "200":
          description: Snapshot details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Snapshot"
        "404":
          $ref: "#/components/responses/NotFoundError"
    delete:
      operationId: removeSnapshot
      summary: Remove a snapshot
      tags: [Boxes]
      responses:
        "204":
          description: Snapshot removed
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/snapshots/{snapshot_name}/restore:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
      - name: snapshot_name
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: restoreSnapshot
      summary: Restore box from snapshot
      description: Restores the box's stopped disks from a named snapshot.
      tags: [Boxes]
      responses:
        "204":
          description: Snapshot restored
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/clone:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: cloneBox
      summary: Clone a box
      description: |
        Creates a new box cloned from the source box's current stopped disk state.
        The source box must be stopped.
      tags: [Boxes]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CloneBoxRequest"
      responses:
        "201":
          description: Cloned box created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Box"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/export:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: exportBox
      summary: Export a box archive
      description: Exports a stopped box as a portable archive payload.
      tags: [Boxes]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExportBoxRequest"
      responses:
        "200":
          description: Archive payload
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary

  /{prefix}/boxes/import:
    parameters:
      - $ref: "#/components/parameters/prefix"
    post:
      operationId: importBox
      summary: Import a box from an archive
      description: |
        Imports a `.boxlite` archive (produced by the export endpoint) to create
        a new box. The archive is uploaded as a binary payload and treated as
        untrusted: archived security settings are replaced by the server's
        defaults. Archives selecting server host paths through a local rootfs or
        volume mount are rejected, as are archives requiring host-only
        experimental features such as custom kernels or nested virtualization.
      tags: [Boxes]
      parameters:
        - name: name
          in: query
          description: Name for the imported box (auto-generated if omitted)
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: Imported box created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Box"
        "400":
          $ref: "#/components/responses/BadRequestError"

  # -------------------------------------------------------------------------
  # Execution
  # -------------------------------------------------------------------------
  /{prefix}/boxes/{box_id}/exec:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: startExecution
      summary: Start an asynchronous command execution
      description: |
        Starts a command in the box and returns an execution ID immediately.
        The box is automatically started if not already running.

        Use the returned `execution_id` to:
        - Attach stdio: `GET /executions/{exec_id}/attach` (WebSocket)
        - Check status: `GET /executions/{exec_id}`
        - Send signal: `POST /executions/{exec_id}/signal`
        - Resize PTY: `POST /executions/{exec_id}/resize`
        - Kill: `DELETE /executions/{exec_id}`
      tags: [Execution]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecRequest"
      responses:
        "201":
          description: Execution started
          headers:
            Location:
              description: URL of the execution resource
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecResponse"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/executions/{exec_id}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
      - $ref: "#/components/parameters/execId"
    get:
      operationId: getExecution
      summary: Get execution status
      description: Returns the current status and result of an execution.
      tags: [Execution]
      responses:
        "200":
          description: Execution status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecutionInfo"
        "404":
          $ref: "#/components/responses/NotFoundError"
    delete:
      operationId: killExecution
      summary: Kill execution (SIGKILL + evict)
      description: |
        Terminates the execution with SIGKILL and removes it from the
        server's session map atomically. Use this rather than
        `POST /signal` with `signal=9` — the signal endpoint rejects
        SIGKILL because it cannot perform the eviction half of the
        operation.

        On success, any attached WebSocket on `/attach` is closed; the
        client observes an `{"type":"exit","exit_code":...}` text frame
        followed by a normal close.
      tags: [Execution]
      responses:
        "204":
          description: Execution killed and evicted.
        "404":
          $ref: "#/components/responses/NotFoundError"

  /{prefix}/boxes/{box_id}/attach:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    get:
      operationId: attachBox
      summary: Attach to the box's main command session (WebSocket)
      description: |
        Opens a WebSocket on the box's **main command session** — the container
        init, which is what `run IMAGE COMMAND` starts. Docker's
        `POST /containers/{id}/attach`, as distinct from its exec-attach.

        The session is opened lazily on the first attach. Its execution id rides
        back on the upgrade response in the `x-boxlite-execution-id` header,
        after which the client can address it through the ordinary
        `/executions/{exec_id}/…` routes.

        The frame protocol, single-attach rule and keepalive are identical to
        [`attachExecution`](#operation/attachExecution).
      tags: [Execution]
      parameters:
        - name: stdin
          in: query
          required: false
          schema:
            type: string
            enum: ["0", "1", "false", "true"]
            default: "1"
          description: |
            Identical to `attachExecution`'s `stdin`: `0` or `false` opens a
            **read-only attach** — docker's `--no-stdin` — and a value outside
            this enum is rejected with `400`, never treated as the writable
            default.
      responses:
        "101":
          description: WebSocket upgrade successful; bidirectional protocol begins.
          headers:
            x-boxlite-execution-id:
              description: |
                The main command session's execution id, assigned when the
                session is opened. Address it through the ordinary
                `/executions/{exec_id}/…` routes.
              schema:
                type: string
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          description: Another client is already attached to this box's main session.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /{prefix}/boxes/{box_id}/executions/{exec_id}/attach:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
      - $ref: "#/components/parameters/execId"
    get:
      operationId: attachExecution
      summary: Attach to an execution (WebSocket)
      description: |
        Opens a bidirectional WebSocket carrying stdin, stdout, stderr, and
        in-band control for a previously-created execution. This is the
        canonical streaming path for an execution.

        **Single-attach.** Only one client may be attached at a time. A
        second `GET /attach` to the same `exec_id` while one is connected
        returns `409 Conflict` (no upgrade). The exec keeps running across
        WebSocket close — a client can reconnect to the same `exec_id` and
        resume streaming. Orphaned sessions are reaped per the runner's
        configured policy (default: SIGHUP after 5 min idle).

        **Frame protocol.**

        Client → Server:
        - **Binary frame** — raw bytes appended to the execution's stdin pipe.
        - **Text frame** (JSON) — control messages:
          - `{"type":"resize","cols":120,"rows":40}` — terminal resize.
          - `{"type":"signal","sig":15}` — send a Unix signal. Whitelist
            matches `POST /signal` (HUP/INT/QUIT/ABRT/USR1/USR2/TERM/WINCH);
            non-whitelisted signals respond with a `{"type":"error",...}`
            text frame and the connection stays open.
          - `{"type":"stdin_eof"}` — close stdin (EOF to the PTY).

        Server → Client:
        - **Binary frame** — `[channel:u8][payload:bytes]`. Channel is
          `0x01` for stdout, `0x02` for stderr. TTY-mode executions only
          emit `0x01` since the kernel merges stdout/stderr into the PTY.
        - **Text frame** (JSON) — control messages:
          - `{"type":"exit","exit_code":N}` on process exit. Followed by a
            normal WebSocket close (1000).
          - `{"type":"error","message":"..."}` on non-fatal internal errors
            (e.g., rejected signal value). Connection stays open.

        **Keepalive.** The server emits a WebSocket `Ping` control frame
        every 15 seconds. Clients are expected to respond with `Pong`
        (most libraries do this automatically). Either side may treat the
        absence of frames for >45s as a dead connection.
      tags: [Execution]
      parameters:
        - name: stdin
          in: query
          required: false
          schema:
            type: string
            enum: ["0", "1", "false", "true"]
            default: "1"
          description: |
            `0` or `false` opens a **read-only attach** — docker's
            `--no-stdin`. The server then refuses stdin data frames,
            `stdin_eof`, `signal` and `resize` on this socket, answering the
            first of each kind with an
            `{"type":"error","code":"read_only_attach",...}` text frame and
            ignoring repeats of a kind already refused; a stdin data frame
            additionally closes the connection with WebSocket status 1008.

            Read-only is a property of the individual WebSocket, not of the
            session: other clients attaching to the same session are
            unaffected.

            A value outside this enum is rejected with `400`, never treated as
            the writable default.
      responses:
        "101":
          description: WebSocket upgrade successful; bidirectional protocol begins.
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          description: Another client is already attached to this execution.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /{prefix}/boxes/{box_id}/executions/{exec_id}/signal:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
      - $ref: "#/components/parameters/execId"
    post:
      operationId: signalExecution
      summary: Send a signal to an execution
      description: |
        Sends a POSIX signal to the running execution.
        Common signals: 9 (SIGKILL), 15 (SIGTERM), 2 (SIGINT).
      tags: [Execution]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignalRequest"
      responses:
        "204":
          description: Signal sent
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/executions/{exec_id}/resize:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
      - $ref: "#/components/parameters/execId"
    post:
      operationId: resizeExecution
      summary: Resize execution TTY
      description: |
        Resizes the pseudo-terminal for a TTY-enabled execution.
        Only applicable to executions started with `tty: true`.
      tags: [Execution]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResizeRequest"
      responses:
        "204":
          description: TTY resized
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  # -------------------------------------------------------------------------
  # Files
  # -------------------------------------------------------------------------
  /{prefix}/boxes/{box_id}/files:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"

    put:
      operationId: uploadFiles
      summary: Upload files into the box
      description: |
        Uploads a tar archive and extracts it at the specified path
        inside the container. The box must be running.

        Transfer operates on the container's root filesystem. A destination
        at or under a mount inside the container, or an archive entry that
        would land on one, is rejected with `400` — such a write would not be
        visible to processes in the box. Extracted files are owned by the
        container's configured user.
      tags: [Files]
      parameters:
        - name: path
          in: query
          required: true
          description: Destination path inside the container
          schema:
            type: string
          example: /app
        - name: overwrite
          in: query
          description: Overwrite existing files at destination
          schema:
            type: boolean
            default: true
      requestBody:
        required: true
        content:
          application/x-tar:
            schema:
              type: string
              format: binary
              description: Tar archive to extract at destination
      responses:
        "204":
          description: Upload successful
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

    get:
      operationId: downloadFiles
      summary: Download files from the box
      description: |
        Downloads files from the specified path inside the container
        as a tar archive. The box must be running.

        A `path` ending in `/.` (`docker cp`'s spelling) asks for a
        directory's contents rather than the directory itself.

        Transfer operates on the container's root filesystem. A source at or
        under a mount inside the container, or a directory containing one, is
        rejected with `400` — the archive would carry the underlying files
        rather than the ones processes in the box see.
      tags: [Files]
      parameters:
        - name: path
          in: query
          required: true
          description: |
            Source path inside the container. End a directory with `/.` to
            download its contents rather than the directory itself.
          schema:
            type: string
          example: /app/output
        - name: follow_symlinks
          in: query
          description: Follow symlinks when archiving
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Tar archive of requested path
          content:
            application/x-tar:
              schema:
                type: string
                format: binary
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  # -------------------------------------------------------------------------
  # Network
  # -------------------------------------------------------------------------
  /{prefix}/boxes/{box_id}/network/tunnel:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    post:
      operationId: prepareTunnel
      summary: Prepare a box service tunnel
      description: |
        Returns the URI and access policy for a TCP service inside the box.
        Safe to repeat: the server may provision tunnel routing on
        first call and returns the current descriptor thereafter.
        isPublic defaults to true. A private tunnel returns its complete token
        only when created, and a masked token on later calls. Stop/resume does
        not rotate it; revoke followed by prepare does. Changing the mode of an
        active tunnel requires revoke first (otherwise 409).

        HTTP services are reachable directly at the URI. For a raw
        TCP byte stream to the service port, clients connect to the
        URI and issue an HTTP/1.1 `CONNECT` for its authority; the
        host upgrades each accepted `CONNECT` into one connection to
        the in-box service. `CONNECT` is a transport handshake on the
        URI's host, not an operation of this API.
        SDKs send API-key/JWT credentials in X-BoxLite-Authorization on CONNECT.
        External visitors may use X-BoxLite-Access-Token or boxlite-access-token
        in the URL query. Inbound disabled blocks both public and private tunnels.

        Returns 409 while the box's inbound access is `disabled`. Enable it
        with `network.inbound.mode` at create, or later with
        `PUT /{prefix}/boxes/{box_id}/network/inbound`.

        The URI is always the port's generated one. Domains bound to the
        port (`bindDomain`) start answering once it is declared here; list
        them with `listDomains`.
      tags: [Network]
      parameters:
        - name: port
          in: query
          required: true
          description: TCP port the service listens on inside the box
          schema:
            type: integer
            minimum: 1
            maximum: 65535
          example: 3000
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                isPublic:
                  type: boolean
                  default: true
              additionalProperties: false
      responses:
        "200":
          description: Service tunnel descriptor
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelDescriptor"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
    delete:
      operationId: revokeTunnel
      summary: Revoke a box service tunnel
      description: |
        Withdraws access to one public or private box port that `prepareTunnel`
        opened. New requests and `CONNECT`s to its URI get `404` within
        3 seconds; connections already open run until they close. Other
        ports of the box are unaffected.

        Safe to repeat, and succeeds for a port that was never opened.
        Calling `prepareTunnel` again reopens the port at the same URI. A
        platform hostname bound to the port stays bound: it answers `404`
        while the port is revoked and serves again once it is reopened.
      tags: [Network]
      parameters:
        - name: port
          in: query
          required: true
          description: TCP port the service listens on inside the box
          schema:
            type: integer
            minimum: 1
            maximum: 65535
          example: 3000
      responses:
        "204":
          description: The tunnel declaration is revoked
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  /{prefix}/boxes/{box_id}/network/inbound:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    put:
      operationId: updateInboundNetwork
      summary: Change a box's inbound access
      description: |
        Enables or disables inbound access to an existing box, the policy
        `network.inbound` sets at create. `enabled` permits access through
        the proxy subject to each tunnel's policy; `disabled` blocks all
        callers. `prepareTunnel` follows the new mode at once; the
        proxy applies it to new connections once its visibility cache
        expires, and does not close connections already open.

        Servers that support this advertise
        `capabilities.inbound_update_enabled` in `GET /config`.
      tags: [Network]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/InboundNetworkSpec"
      responses:
        "200":
          description: The box's inbound access after the change
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InboundNetworkSpec"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/boxes/{box_id}/network/outbound:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    put:
      operationId: updateOutboundNetwork
      summary: Replace a running box's outbound policy
      description: |
        Replaces mode and the entire allow_net list without changing inbound.
        Enabled with an omitted or empty list clears allowlist restrictions.
        Disabled with a non-empty list is invalid. Requires a running box
        created with a NIC; unsupported backends return an explicit error.

        New TCP/UDP flows use the replacement allowlist. Existing flows retain
        their policy. Disabled suspends NIC traffic, including DNS and inbound,
        while preserving the control channel for re-enabling.

        Success confirms application and persistence. Timeouts or failed
        rollback can leave live and stored policy different; retry the full
        replacement. GET box reports the last persisted policy.
      tags: [Network]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/OutboundNetworkSpec"
      responses:
        "200":
          description: Applied outbound policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutboundNetworkSpec"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"
        "500":
          description: Application or persistence failed; retry the complete policy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /{prefix}/domains:
    parameters:
      - $ref: "#/components/parameters/prefix"
    get:
      operationId: listDomains
      summary: List the domains the organization holds
      description: |
        Every held hostname and its Box/App target, or null while unbound,
        with the organization's allowance. Unbound domains still occupy slots.
        `domain_suffix` is the configured platform hostname suffix, or null
        when requests are unavailable; `min_length` applies to new claims only.
      tags: [Domains]
      responses:
        "200":
          description: Held domains and the organization's allowance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DomainList"
    post:
      operationId: claimDomain
      summary: Request a platform domain using a short name
      description: |
        Claims a short name for the organization and returns its full hostname,
        initially unbound. Dashboard > Domains uses this operation. A repeated
        claim by the owner returns the held domain without changing its target.
        Only new claims check the minimum length and domain count allowance.
        Names use letters, digits and hyphens, cannot start/end with a hyphen,
        match `<digits>-…`, or use a reserved platform or REST collection name.
        Error codes: `platform_domain_not_configured`, `subdomain_too_short`,
        `domain_count_limit_reached` (400), `subdomain_taken` (409).
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 63
                  description: A short label, not a full hostname; normalized to lowercase.
                  example: demo-app
      responses:
        "201":
          description: The acquired domain, preserving any existing binding
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/domains/{domain}/target:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - name: domain
        in: path
        required: true
        description: An owned full hostname; short names and URLs are rejected, case and a trailing root dot are normalized.
        schema:
          type: string
          minLength: 3
          maxLength: 254
          pattern: '^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+\.?$'
        example: demo-app.apps.example
    put:
      operationId: bindDomain
      summary: Route an owned domain to a box port
      description: |
        Updates a full hostname already owned by the organization; never claims
        or expands a short name. Unknown names and names owned by another
        organization return `domain_not_owned` (404), directing the caller to
        Dashboard > Domains to request a domain first. Owned names remain
        bindable independently of the configured suffix, minimum, or quota.
        The port is not declared public: the domain answers once the tunnel is
        public and the Box allows inbound access, in either order.
        A name bound to another port moves here; other names stay in place.
        Error codes: `region_not_supported` and `app_target_not_supported` (400).
        App binding is reserved and remains unsupported.
      tags: [Domains]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DomainTarget"
      responses:
        "200":
          description: The domain as now bound
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Domain"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
    delete:
      operationId: unbindDomain
      summary: Stop routing a domain
      description: |
        Stops routing the exact full hostname, independently of the configured
        suffix. The organization keeps the name and it still occupies a slot.
        New requests get 404; existing connections run until they close.
        The port's own URL stays public until revokeTunnel.
        Safe to repeat for an owned name; a name not owned by the caller is 404.
      tags: [Domains]
      responses:
        "204":
          description: The domain routes nowhere
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  # -------------------------------------------------------------------------
  # Metrics
  # -------------------------------------------------------------------------
  /{prefix}/metrics:
    parameters:
      - $ref: "#/components/parameters/prefix"
    get:
      operationId: getRuntimeMetrics
      summary: Get runtime-wide metrics
      description: |
        Returns aggregate metrics across all boxes in the workspace.
        All counters are monotonic (never decrease).
      tags: [Metrics]
      responses:
        "200":
          description: Runtime metrics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeMetrics"

  /{prefix}/boxes/{box_id}/metrics:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/boxId"
    get:
      operationId: getBoxMetrics
      summary: Get per-box metrics
      description: |
        Returns resource usage and execution metrics for a specific box.
        Includes CPU, memory, network, and stage-level boot timing.
      tags: [Metrics]
      responses:
        "200":
          description: Box metrics
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BoxMetrics"
        "404":
          $ref: "#/components/responses/NotFoundError"

  # -------------------------------------------------------------------------
  # Images
  # -------------------------------------------------------------------------
  /{prefix}/images:
    parameters:
      - $ref: "#/components/parameters/prefix"
    get:
      operationId: listImages
      summary: List images
      description: |
        The images this deployment can boot from, one entry per reference:
        each tag at the build it points to, and each build no tag points to
        by its digest. A single-host server answers from its image cache; a
        server shared between callers answers from the caller's catalog. A
        server may answer every entry at once, leaving `next_page_token` out.
      tags: [Images]
      parameters:
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/pageToken"
      responses:
        "200":
          description: Images the caller can boot from
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListImagesResponse"

  /{prefix}/images/usage:
    parameters:
      - $ref: "#/components/parameters/prefix"
    get:
      operationId: getImageUsage
      summary: Get image usage
      description: |
        How many images the routing slot holds against the most it may hold.
        A server with no such limit answers `UnsupportedError`.
      tags: [Images]
      responses:
        "200":
          description: Images held and the limit
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageUsage"
        "400":
          $ref: "#/components/responses/BadRequestError"

  /{prefix}/images/{image_name}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/imageName"

    get:
      operationId: getImage
      summary: Get an image
      description: Every build held under an image name.
      tags: [Images]
      responses:
        "200":
          description: The image and its builds
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageDetail"
        "404":
          $ref: "#/components/responses/NotFoundError"

    delete:
      operationId: removeImage
      summary: Remove an image
      description: |
        Stop holding an image name, every tag of it. Layers are not deleted.
        A server refuses with `InvalidStateError` while a box can still boot
        from the image.
      tags: [Images]
      responses:
        "204":
          description: The image is no longer held
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/images/{image_name}/aliases:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/imageName"
    post:
      operationId: createImageAlias
      summary: Create an image alias
      description: |
        Create a catalog alias for a ready build of this image. Existing aliases
        are refused with AlreadyExistsError, including an identical binding.
        Delete an alias explicitly before creating it again. The registry and
        existing boxes are unchanged, and nothing is pulled. A local runtime
        without a catalog answers UnsupportedError.
      tags: [Images]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateImageAliasRequest"
      responses:
        "201":
          description: Image details including the created alias
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageDetail"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

  /{prefix}/images/{image_name}/aliases/{alias}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/imageName"
      - $ref: "#/components/parameters/imageAlias"
    delete:
      operationId: deleteImageAlias
      summary: Delete an image alias
      description: |
        Remove only this catalog binding. Versions, creation history, the
        upstream registry and existing boxes remain unchanged. An absent image
        or alias answers NotFoundError. Local runtimes answer UnsupportedError.
      tags: [Images]
      responses:
        "204":
          description: The alias was deleted
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"

  # -------------------------------------------------------------------------
  # Registries
  # -------------------------------------------------------------------------
  /{prefix}/images/registries:
    parameters:
      - $ref: "#/components/parameters/prefix"

    get:
      operationId: listRegistries
      summary: List registry logins
      description: |
        The logins the server presents when it pulls a private image for a
        box, oldest first. No login carries its password.
      tags: [Registries]
      responses:
        "200":
          description: The routing slot's registry logins
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListRegistriesResponse"

    post:
      operationId: createRegistry
      summary: Add a registry login
      description: |
        The password is stored where the server cannot read it back, and is
        never returned. A login is held per registry and prefix: a second one
        for the same pair is refused with `AlreadyExistsError`. A server that
        cannot pull private images answers `UnsupportedError`.
      tags: [Registries]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRegistryRequest"
      responses:
        "201":
          description: The login, without its password
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegistryCredential"
        "400":
          $ref: "#/components/responses/BadRequestError"
        "409":
          description: A login is already held for this registry and prefix
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                error:
                  message: "A credential for ghcr.io/acme/ already exists; remove it before adding another"
                  type: AlreadyExistsError
                  code: already_exists
        "501":
          description: This server does not pull private images
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /{prefix}/images/registries/{registry_id}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/registryId"

    delete:
      operationId: removeRegistry
      summary: Remove a registry login
      description: |
        Removes the login and destroys its password. A server refuses with
        `InvalidStateError`, naming the boxes, while a box still pulls through
        the login.
      tags: [Registries]
      responses:
        "204":
          description: The login is gone, and its password destroyed
        "400":
          $ref: "#/components/responses/BadRequestError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "409":
          $ref: "#/components/responses/ConflictError"

# ===========================================================================
# Components
# ===========================================================================
components:

  # -------------------------------------------------------------------------
  # Security Schemes
  # -------------------------------------------------------------------------
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer authentication. The wire format is RFC 6750 — an opaque token
        passed as `Authorization: Bearer <token>`. The server is **format-
        agnostic**: any token its validation pipeline can verify is accepted.

        ## Token sources the server validates

        Which sources are enabled depends on deployment configuration. The
        validation pipeline is pluggable; new sources can be added without
        client changes.

          1. **BoxLite-issued** (always enabled). Dashboard-issued API keys
             (`blk_live_…` / `blk_test_…`) — long-lived, org-scoped,
             revoked when the member who created it leaves or is removed
             from the organization. Issued at
             `https://app.boxlite.ai/settings/api-keys`.
          2. **Federated SSO / enterprise JWTs** (optional, per-deployment).
             JWTs issued by a configured enterprise IdP (Okta, Auth0,
             Azure AD, Google Workspace). Validated against the IdP's JWKS;
             `iss`, `aud`, `sub`, `exp` claims checked. Principal is
             projected from claims into the BoxLite identity model.
          3. **Third-party OIDC tokens** (optional, per-deployment). Access
             tokens from public IdPs (GitHub, Google, Anthropic). Validated
             by introspection against the IdP's userinfo endpoint. Used by
             "Sign in with X" integrations.
          4. **Customer-issued passthrough tokens** (optional, when a
             customer fronts the BoxLite gateway with their own auth layer).
             The customer's gateway authenticates the request, attaches a
             token in a configured format, and BoxLite trusts the upstream
             chain.

        All sources are treated identically by clients — opaque strings
        carried in `Authorization: Bearer`. Token acquisition is out of
        scope for this contract.

  # -------------------------------------------------------------------------
  # Parameters
  # -------------------------------------------------------------------------
  parameters:
    prefix:
      name: prefix
      in: path
      required: true
      allowReserved: true
      description: |
        Deployment-defined routing slot. Opaque to the client; the
        value is whatever the server told the client to use via
        `Principal.path_prefix` (see `GET /v1/me`), substituted
        verbatim into the URL. Internal `/` characters are preserved,
        enabling multi-segment routing values such as
        `us-east/team-42`.

        The slot's semantics are vendor-specific — boxlite cloud uses
        it for the organization id; another implementer might use it
        for a workspace, a catalog, or a region+team pair. Empty /
        `null` values mean the deployment does not use a routing
        slot, and clients build URLs without the segment.
      schema:
        type: string
        maxLength: 128
      example: acme-corp

    boxId:
      name: box_id
      in: path
      required: true
      description: |
        Server-assigned opaque box identifier, or a user-defined name.
        Clients MUST treat the value as opaque and pass it back verbatim
        in subsequent box-scoped requests. Examples seen in deployed
        servers (non-normative): ULID (`01HJK4TNRPQSXYZ8WM6NCVT9R5`),
        12-character Base62 (`aB3cD4eF5gH6`), UUID
        (`d406c59d-eb09-4bc3-9b3a-62455c7e8f32`), prefixed (`sb_abc123`),
        user-defined name (`my-box`).
      schema:
        type: string
        minLength: 1
        maxLength: 128
      example: 01HJK4TNRPQSXYZ8WM6NCVT9R5

    execId:
      name: exec_id
      in: path
      required: true
      description: Execution identifier returned by `POST /exec`
      schema:
        type: string
      example: exec-01HJK5ABCDEF

    imageName:
      name: image_name
      in: path
      required: true
      description: |
        Registry and repository, without a tag or digest. It has slashes, so
        it is sent URL-encoded as one segment.
      schema:
        type: string
      example: "quay.io%2Facme%2Fapp"

    imageAlias:
      name: alias
      in: path
      required: true
      description: Catalog alias to delete
      schema:
        type: string
      example: stable

    registryId:
      name: registry_id
      in: path
      required: true
      description: Server-assigned registry login identifier
      schema:
        type: string
        format: uuid

    volumeId:
      name: volume_id
      in: path
      required: true
      description: Server-assigned managed volume identifier
      schema:
        type: string
        minLength: 1

    pageSize:
      name: pageSize
      in: query
      description: Maximum number of results per page
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100

    pageToken:
      name: pageToken
      in: query
      description: |
        Opaque token for the next page of results.
        Returned as `next_page_token` in list responses.
        Clients must not parse or interpret this value.
      schema:
        type: string

    idempotencyKey:
      name: Idempotency-Key
      in: header
      description: |
        Optional client-provided UUID for safe request retries.
        If the server has already processed a request with this key,
        it returns the original response without re-executing.
        Same key with different payload returns 422.
        Keys expire after the duration advertised in `GET /v1/config`.
      schema:
        type: string
        format: uuid
      example: "017f22e2-79b0-7cc3-98c4-dc0c0c07398f"

  # -------------------------------------------------------------------------
  # Responses (Error Templates)
  # -------------------------------------------------------------------------
  responses:
    BadRequestError:
      description: Invalid request parameters or body
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "invalid argument: cpus must be between 1 and 16"
              type: InvalidArgumentError
              code: invalid_argument
              request_id: req_01HZK4TNRPQSXYZ8WM6NCVT9R5

    UnauthorizedError:
      description: Missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "invalid or missing API key"
              type: AuthError
              code: unauthenticated
              request_id: req_01HZK4TNRPQSXYZ8WM6NCVT9R5

    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "box not found: 01HJK4TNRPQSXYZ8WM6NCVT9R5"
              type: NotFoundError
              code: not_found
              request_id: req_01HZK4TNRPQSXYZ8WM6NCVT9R5

    ConflictError:
      description: Resource state conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "invalid state: box is already running"
              type: InvalidStateError
              code: invalid_state
              request_id: req_01HZK4TNRPQSXYZ8WM6NCVT9R5

    UnprocessableEntityError:
      description: Request understood but cannot be processed
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            error:
              message: "images error: manifest unknown for python:nonexistent"
              type: ImageError
              code: image_pull_failed
              request_id: req_01HZK4TNRPQSXYZ8WM6NCVT9R5

    RequestTimeoutError:
      description: The operation did not reach its target state before the timeout
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

    ResourceExhaustedError:
      description: The organization has reached its plan's non-finalized Box limit
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            path: /api/v1/org/boxes
            timestamp: "2026-09-02T06:55:28.000Z"
            statusCode: 429
            error: Too Many Requests
            message: "Organization box creation limit reached: 2 of 2 boxes are already counted"
            code: resource_exhausted

    ServiceUnavailableError:
      description: A required backend service is not configured or available
      headers:
        Retry-After:
          description: Seconds to wait when Box creation admission is temporarily contended
          schema:
            type: integer
            minimum: 1
            example: 5
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  # -------------------------------------------------------------------------
  # Schemas
  # -------------------------------------------------------------------------
  schemas:

    # =======================================================================
    # Configuration
    # =======================================================================
    ServerConfig:
      type: object
      description: Server configuration and capabilities (the `GET /v1/config` response).
      properties:
        defaults:
          type: object
          description: Default values applied when not specified in requests
          properties:
            cpus:
              type: integer
              description: Default vCPU count
              example: 2
            memory_mib:
              type: integer
              description: Default memory in MiB
              example: 512
            disk_size_gb:
              type: integer
              description: Default disk size in GB
              example: 10
            auto_delete:
              type: integer
              description: Default AutoDelete interval in seconds; 0 disables AutoDelete
              example: 0
        overrides:
          type: object
          description: Server-enforced overrides that clients cannot change
          additionalProperties:
            type: string
        capabilities:
          type: object
          description: Server capability limits and feature flags
          properties:
            linux_capabilities_enabled:
              type: boolean
              description: Whether Docker-style Linux capability add/drop policy is supported
              example: true
            max_cpus:
              type: integer
              description: Maximum allowed vCPUs per box
              example: 16
            max_memory_mib:
              type: integer
              description: Maximum allowed memory in MiB
              example: 16384
            max_disk_size_gb:
              type: integer
              description: Maximum allowed disk size in GB
              example: 100
            max_boxes_per_path_prefix:
              type: integer
              description: Maximum boxes per routing-slot scope
              example: 50
            max_concurrent_executions:
              type: integer
              description: Maximum concurrent executions per box
              example: 10
            file_transfer_max_bytes:
              type: integer
              description: Maximum file upload/download size in bytes
              example: 1073741824
            exec_timeout_max_seconds:
              type: number
              description: Maximum allowed execution timeout in seconds
              example: 3600
            tty_enabled:
              type: boolean
              description: Whether WebSocket TTY sessions are supported
              example: true
            streaming_enabled:
              type: boolean
              description: Whether WebSocket attach output streaming is supported
              example: true
            snapshots_enabled:
              type: boolean
              description: Whether snapshot create/list/get/remove/restore is supported
              example: true
            clone_enabled:
              type: boolean
              description: Whether box clone is supported
              example: true
            export_enabled:
              type: boolean
              description: Whether box export is supported
              example: true
            inbound_update_enabled:
              type: boolean
              description: Whether `PUT /{prefix}/boxes/{box_id}/network/inbound` is supported
              example: true
            private_tunnels_enabled:
              type: boolean
              description: Whether prepareTunnel honors a private `isPublic` of false; clients check it before every private prepare
              example: true
            exec_user_enabled:
              type: boolean
              description: Server honors `ExecRequest.user`.
              example: true
            idempotency_key_lifetime:
              type: string
              description: How long idempotency keys are retained (ISO 8601 duration)
              example: PT24H

    # =======================================================================
    # Authentication
    # =======================================================================
    Principal:
      type: object
      description: |
        Identity and scope payload returned by `GET /v1/me`. Clients
        typically use `email` / `display_name` to render an identity
        banner after credential validation, and inspect `scopes` so
        under-scoped credentials surface at validation time rather than
        mid-flow.
      required: [sub, principal_type, scopes]
      properties:
        sub:
          type: string
          description: |
            Stable opaque principal identifier. Clients MUST treat the value
            as opaque — the server may change format (UUID, ULID, Base62, or
            prefixed) without notice. Survives email and display-name renames.
        principal_type:
          type: string
          enum: [user, service_account]
          description: |
            `user` for interactive dashboard-issued keys; `service_account`
            for automation keys. Modeled as an enum rather than a nullable
            `user_id` field so clients can dispatch by variant.
        email:
          type: string
          format: email
          description: |
            Email of the user behind the key. Absent for `service_account`
            principals.
        display_name:
          type: string
          description: Human-readable label. Optional.
        path_prefix:
          type: [string, "null"]
          description: |
            Routing-slot value the client should substitute into the
            `{prefix}` URL parameter on box-scoped requests. Opaque
            to the client — the server decides what goes here (an
            organization id, a workspace name, a catalog, a multi-
            segment routing key, etc.).

            `null` when the deployment does not use a routing slot
            (single-tenant servers such as `boxlite serve`) **or** when
            the credential has no scope assigned yet (mid-provisioning
            service accounts, first OIDC login before scope assignment).
            In either case clients build URLs without the segment
            (`/v1/boxes/…` rather than `/v1/<prefix>/boxes/…`).

            The field is always present in the response envelope, never
            omitted; the distinction between absent and explicit `null`
            is not significant.
        scopes:
          type: array
          items:
            type: string
            example: "boxes:read"
          description: |
            Granted scope strings (`boxes:read`, `boxes:write`, etc.).
            Clients typically check these at credential-validation time
            so under-scoped credentials surface immediately rather than
            at first use.
        expires_at:
          type: [string, "null"]
          format: date-time
          description: |
            Optional expiry. `null` for long-lived dashboard-issued keys;
            ISO 8601 timestamp for rotating credentials.

    # =======================================================================
    # Error Model
    # =======================================================================
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          $ref: "#/components/schemas/ErrorModel"

    ErrorModel:
      type: object
      description: |
        Standard error response.

        - `message` is human-readable text (English) for logs and
          developer display.
        - `type` is a stable PascalCase identifier (K8s `Status.reason`
          style). Useful for log filtering. The canonical dispatch
          field is `code`, not `type`.
        - `code` is the stable snake_case machine identifier (Stripe
          `code` style). Clients SHOULD pattern-match on `code` for
          typed error handling.
        - `request_id` is propagated from the `X-Request-Id` response
          header. Include this when reporting issues; it round-trips
          to server logs verbatim.

        The HTTP numeric status is in the response status line, not in
        the body — duplicating it added no information.
      required: [message, type, code]
      properties:
        message:
          type: string
          description: Human-readable error message with context
          example: "box not found: 01HJK4TNRPQSXYZ8WM6NCVT9R5"
        type:
          type: string
          description: PascalCase error type identifier (matches BoxliteError variants)
          enum:
            - InvalidArgumentError
            - UnsupportedError
            - AuthError
            - NotFoundError
            - SessionReapedError
            - AlreadyExistsError
            - InvalidStateError
            - StoppedError
            - ImageError
            - ExecutionError
            - ResourceExhaustedError
            - NetworkError
            - UpstreamUnavailableError
            - EngineError
            - StorageError
            - DatabaseError
            - MetadataError
            - ConfigError
            - InternalError
            - TimeoutError
          example: NotFoundError
        code:
          type: string
          description: |
            Stable snake_case machine identifier. Clients should
            pattern-match on this field for typed error handling.
          enum:
            - invalid_argument
            - unsupported
            - unauthenticated
            - permission_denied
            - not_found
            - session_reaped
            - already_exists
            - invalid_state
            - stopped
            - image_pull_failed
            - execution_failed
            - resource_exhausted
            - network_unavailable
            - upstream_unavailable
            - engine_unavailable
            - storage_error
            - database_error
            - metadata_error
            - config_error
            - internal
            - timeout
          example: not_found
        request_id:
          type: string
          description: |
            Request id propagated from the `X-Request-Id` response
            header. Mirrors the server log entry — include when
            reporting issues.
          example: req_01HZK4TNRPQSXYZ8WM6NCVT9R5
        stack:
          type: array
          description: Stack trace (only included when server debug mode is enabled)
          items:
            type: string

    # =======================================================================
    # Box
    # =======================================================================
    Box:
      type: object
      description: REST box metadata
      required: [box_id, status, created_at, updated_at, image, cpus, memory_mib]
      properties:
        box_id:
          type: string
          description: |
            Server-assigned opaque identifier. Clients MUST treat the value
            as opaque and pass it back verbatim in subsequent box-scoped
            requests. The server is the authority on identifier format —
            implementations have used 26-character ULID, 12-character
            Base62, UUID, prefixed strings (`sb_abc123`), and other shapes.
            Clients should accept any printable URL-/path-safe string up
            to the documented length bound.
          minLength: 1
          maxLength: 128
          example: 01HJK4TNRPQSXYZ8WM6NCVT9R5
        name:
          type: [string, "null"]
          description: User-defined name (unique within the routing-slot scope)
          example: my-box
        status:
          $ref: "#/components/schemas/BoxStatus"
        created_at:
          type: string
          format: date-time
          description: Box creation timestamp (UTC)
        updated_at:
          type: string
          format: date-time
          description: Last state change timestamp (UTC)
        last_activity_at:
          type: string
          format: date-time
          description: |
            Last recorded activity on the box (UTC) — the clock AutoStop
            measures idleness against. Absent when the server recorded no
            activity, which is always the case for a server without an
            AutoStop sweeper.
        pid:
          type: [integer, "null"]
          description: VMM subprocess PID (null if not running)
        image:
          type: string
          description: OCI image reference or rootfs path
          example: python:3.11-slim
        cpus:
          type: integer
          minimum: 1
          maximum: 32
          description: Allocated vCPU cores
          example: 2
        memory_mib:
          type: integer
          minimum: 128
          description: Allocated memory in MiB
          example: 512
        labels:
          type: object
          additionalProperties:
            type: string
          description: User-defined key-value labels
        auto_stop:
          type: integer
          minimum: 0
          default: 900
          description: Idle time in seconds before AutoStop; 0 disables AutoStop
        auto_delete:
          type: integer
          minimum: 0
          default: 0
          description: Time in seconds after a successful stop before AutoDelete; 0 disables AutoDelete
        auto_resume:
          type: boolean
          default: true
          description: Whether the box automatically resumes when accessed after AutoStop
        exit_code:
          type: integer
          description: |
            How the box's main command ended, present once the box has
            stopped and the runtime recorded it. A command that exited on its
            own reports its own code; one ended by a signal reports
            `128 + n`. Stopping a box signals that command — `SIGTERM`, then
            `SIGKILL` after a grace period — so a stop is recorded here too:
            the command's own code when it handles `SIGTERM`, and `137`
            when it does not. Absent while the box is running, because
            starting one clears it, and absent when nothing was recorded: a
            box that never reached its command, or one whose exit went
            unobserved.

            `0` is a real value here: it is how a command that succeeded is
            told apart from one that did not. Absence, not `0`, is what
            means "no exit code recorded", so a client must distinguish the
            missing field from a zero one.

            A server may leave it out of any response other than a direct
            read of one box — listing boxes, and the replies to create, start,
            stop, clone and import — because the code lives with the runner
            that owns the box, and fetching it per box does not scale to a
            list. So absence in those responses says nothing either way: read
            the box itself to find out.
          example: 137
        network:
          $ref: "#/components/schemas/NetworkInfo"
          description: |
            The box's effective network policy, both directions. Absent from
            a server that predates the field; a client then reports network
            metadata as unknown rather than as any particular policy.

    NetworkInfo:
      type: object
      description: |
        Network policy as the server holds it. Mirrors the `network` of
        `CreateBoxRequest` field for field, minus the deprecated flat
        shape; `inbound.allow_net` is always empty today.
      required: [outbound, inbound]
      properties:
        outbound:
          $ref: "#/components/schemas/OutboundNetworkSpec"
        inbound:
          $ref: "#/components/schemas/InboundNetworkSpec"

    BoxStatus:
      type: string
      description: |
        Box lifecycle state machine:
        - `configured`: Created, VM not yet started
        - `running`: VM active, accepting commands
        - `stopping`: Graceful shutdown in progress (transient)
        - `stopped`: VM terminated, can be restarted
        - `paused`: VM frozen via SIGSTOP (during snapshot/export)
        - `failed`: Initialization failed; diagnostic state is retained
        - `unknown`: Error recovery state
      enum:
        - configured
        - running
        - stopping
        - stopped
        - paused
        - failed
        - unknown

    CreateBoxRequest:
      type: object
      description: |
        REST-supported configuration for creating a new box. Host port
        publication is intentionally absent; use the box network tunnel
        endpoint for remote service access.

        Sandbox isolation is likewise absent, and deliberately so: it is the
        operator's policy, set server-side. A client able to select a preset
        would be choosing its own isolation level, so `additionalProperties:
        false` above makes any attempt to supply one an error rather than a
        quiet fall-through.
      additionalProperties: false
      properties:
        advanced:
          $ref: "#/components/schemas/CreateBoxAdvancedOptions"
        name:
          type: string
          description: Unique name within the workspace
          minLength: 1
          maxLength: 128
          pattern: "^[a-zA-Z0-9][a-zA-Z0-9._-]*$"
          example: dev-box
        image:
          type: string
          description: OCI image reference
          default: "alpine:latest"
          example: python:3.11-slim
        rootfs_path:
          type: string
          description: |
            Path to a pre-built rootfs (alternative to `image`).
            Mutually exclusive with `image`.
        cpus:
          type: integer
          minimum: 1
          maximum: 16
          description: Number of vCPUs to allocate
          example: 2
        memory_mib:
          type: integer
          minimum: 128
          description: Memory in MiB to allocate
          example: 512
        disk_size_gb:
          type: integer
          minimum: 1
          description: Disk size in GB (sparse, grows as needed)
        working_dir:
          type: string
          description: Default working directory inside the container
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variables as key-value pairs
          example:
            PYTHONPATH: /app
            DEBUG: "1"
        entrypoint:
          type: array
          items:
            type: string
          description: Override image ENTRYPOINT
        cmd:
          type: array
          items:
            type: string
          description: Override image CMD
        user:
          type: string
          description: "User to run as (format: <name|uid>[:<group|gid>])"
          example: "1000:1000"
        volumes:
          type: array
          items:
            $ref: "#/components/schemas/VolumeSpec"
        network:
          $ref: "#/components/schemas/NetworkSpec"
          description: |
            Optional network policy. Omitting `network` defaults inbound
            service access to `disabled`.
          default:
            inbound:
              mode: disabled
        secrets:
          type: array
          items:
            $ref: "#/components/schemas/SecretSpec"
          description: |
            Secret placeholder rules for outbound HTTPS requests.
            Matching requests replace `placeholder` with `value` on the host side.
        detach:
          type: boolean
          description: Box survives parent process exit
          default: false
        tty:
          type: boolean
          default: false
          description: |
            Run the box's main command on a pseudo-terminal (docker `run -t`).
            A property of the box, not of an attach: the main command is the
            container's init, so whether it gets a terminal is fixed at create
            time and no later client can add one. The terminal's size is set by
            the attaching client, since a box outlives any one client.
        auto_stop:
          type: integer
          minimum: 0
          default: 900
          description: |
            Idle time in seconds before AutoStop; 0 disables AutoStop. A floor
            on non-zero values is vendor-specific — boxlite cloud rejects
            anything below 60, because a shorter window is outrun by the
            interval at which its proxy renews the idle timer; a single-tenant
            server sweeping on its own timer has no such floor.
        auto_delete:
          type: integer
          minimum: 0
          default: 0
          description: Time in seconds after a successful stop before AutoDelete; 0 disables AutoDelete
        auto_resume:
          type: boolean
          default: true
          description: Whether the box automatically resumes when accessed after AutoStop

    CreateBoxAdvancedOptions:
      type: object
      description: Expert-only container options.
      additionalProperties: false
      properties:
        capabilities:
          $ref: "#/components/schemas/CreateContainerCapabilities"

    CreateContainerCapabilities:
      type: object
      description: Linux capability additions and removals for container processes.
      additionalProperties: false
      properties:
        add:
          type: array
          items:
            type: string
          default: []
          description: |
            Linux capabilities to add to the default container capability set.
            Names are case-insensitive, may include the `CAP_` prefix, and may be `ALL`.
          example: [SYS_ADMIN]
        drop:
          type: array
          items:
            type: string
          default: []
          description: |
            Linux capabilities to remove from the container capability set.
            Names are case-insensitive, may include the `CAP_` prefix, and may be `ALL`.
          example: [NET_RAW]

    VolumeSpec:
      type: object
      description: |
        Managed volume mounted into a box. Host bind mounts have no
        representation here: the path would name the server's filesystem, not
        the caller's, so the only mount source this API accepts is a managed
        volume.
      additionalProperties: false
      required: [managed_volume, guest_path]
      properties:
        managed_volume:
          type: string
          minLength: 1
          description: |
            The volume's server-assigned `id` or its `name` — both resolve to
            the same volume, and a name is unique within the owning scope.
          example: vol_01K2EXAMPLE
        guest_path:
          type: string
          description: Mount point inside the container
        read_only:
          type: boolean
          default: false
          enum: [false]
          description: |
            Read-only managed mounts are not implemented yet; `true` is
            rejected rather than silently downgraded to read-write.

    VolumeState:
      type: string
      description: Managed volume lifecycle state
      enum: [creating, ready, pending_create, pending_delete, deleting, deleted, error]

    VolumeSummary:
      type: object
      description: Managed persistent volume summary, as returned by the list endpoint
      additionalProperties: false
      required: [id, name, state, created_at]
      properties:
        id:
          type: string
          description: Server-assigned managed volume identifier
        name:
          type: string
          description: User-assigned volume name
        state:
          $ref: "#/components/schemas/VolumeState"
        created_at:
          type: string
          format: date-time
          description: Volume creation timestamp (UTC)

    CreateVolumeRequest:
      type: object
      description: Body for volume creation. Omit entirely to create an unnamed volume.
      additionalProperties: false
      properties:
        name:
          type: string
          description: |
            Volume name, unique within the owning scope. Mountable in place of
            the volume's id. Defaults to the server-assigned id when omitted.
          pattern: "^[a-zA-Z0-9][a-zA-Z0-9_.-]+$"
          minLength: 2
          example: my-data

    Volume:
      type: object
      description: Managed persistent volume detail, as returned by create/get
      additionalProperties: false
      required: [id, name, state, created_at, updated_at]
      properties:
        id:
          type: string
          description: Server-assigned managed volume identifier
        name:
          type: string
          description: User-assigned volume name
        state:
          $ref: "#/components/schemas/VolumeState"
        created_at:
          type: string
          format: date-time
          description: Volume creation timestamp (UTC)
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp (UTC)
        last_used_at:
          type: string
          format: date-time
          description: Last time the volume was attached to a box, if ever
        error_reason:
          type: string
          description: Failure detail when state is "error"

    ListVolumesResponse:
      type: object
      additionalProperties: false
      required: [volumes]
      properties:
        volumes:
          type: array
          items:
            $ref: "#/components/schemas/VolumeSummary"

    NetworkSpec:
      type: object
      description: |
        Structured network configuration for the box.

        Send the nested `outbound`/`inbound` shape. The pre-split flat
        `mode`/`allow_net` pair is still accepted for already-deployed
        callers and normalized server side, but is deprecated and will be
        removed; mixing it with the nested fields in one request is
        rejected with 400.
      additionalProperties: false
      properties:
        outbound:
          $ref: "#/components/schemas/OutboundNetworkSpec"
        inbound:
          $ref: "#/components/schemas/InboundNetworkSpec"
          description: |
            Optional inbound service access policy. Omission means
            `mode=disabled`, including for legacy flat network requests.
            Send `mode=enabled` to let exposed services be reached through the
            proxy under each tunnel's access policy: public tunnels need no
            sign-in, private ones need their token or organization membership.
          default:
            mode: disabled
        mode:
          deprecated: true
          type: string
          enum: [enabled, disabled]
          description: |
            Deprecated: use `outbound.mode`. Legacy flat outbound mode.
        allow_net:
          deprecated: true
          type: array
          items:
            type: string
          description: |
            Deprecated: use `outbound.allow_net`. Legacy flat outbound
            allowlist; implies `mode=enabled` when sent without `mode`.

    OutboundNetworkSpec:
      type: object
      description: Outbound guest network policy
      additionalProperties: false
      required: [mode]
      properties:
        mode:
          type: string
          enum: [enabled, disabled]
          description: |
            `enabled` allows guest networking. `disabled` removes the guest network interface.
        allow_net:
          type: array
          items:
            type: string
          description: |
            Optional outbound allowlist used only when `mode=enabled`.
            Empty or omitted means full outbound access.
            Supports hostnames, wildcard hostnames, IPs, and CIDRs.
            A host matched by a configured secret is additionally reachable on
            port 443 without a rule of its own, so this is not the only egress
            gate. That connection is dialed by name, and under a non-empty
            list an answer in a private, loopback or CGNAT range is refused
            unless an IP or CIDR rule covers it.

    InboundNetworkSpec:
      type: object
      description: >
        Inbound service access policy. Aligned field-for-field with
        OutboundNetworkSpec.
      additionalProperties: false
      required: [mode]
      properties:
        mode:
          type: string
          enum: [enabled, disabled]
          description: |
            `enabled` means service endpoints exposed from the box are
            reachable through the proxy subject to the tunnel's access policy. `disabled`
            makes them unreachable through the proxy, even with a credential.
        allow_net:
          type: array
          items:
            type: string
          description: |
            Not supported yet: a non-empty value is rejected with 400. The
            field exists for shape symmetry with `OutboundNetworkSpec`; no
            layer enforces an inbound allowlist today, so inbound access is
            controlled by `mode` alone. Omit it, or send an empty array.

    SecretSpec:
      type: object
      description: Outbound HTTPS secret substitution rule
      required: [name, value]
      properties:
        name:
          type: string
          description: Human-readable secret name
        value:
          type: string
          description: Real secret value. Never enters the guest VM.
        hosts:
          type: array
          items:
            type: string
          description: Matching hosts for this secret. Empty means no host restriction.
        placeholder:
          type: string
          description: |
            Placeholder string visible inside the guest.
            Defaults to `<BOXLITE_SECRET:{name}>` when omitted.

    Snapshot:
      type: object
      required:
        - id
        - box_id
        - name
        - created_at
        - guest_disk_bytes
        - container_disk_bytes
        - size_bytes
      properties:
        id:
          type: string
          description: Snapshot ULID
        box_id:
          type: string
          description: Owning box ULID
        name:
          type: string
          description: Snapshot name unique per box
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (seconds)
        guest_disk_bytes:
          type: integer
          format: int64
        container_disk_bytes:
          type: integer
          format: int64
        size_bytes:
          type: integer
          format: int64

    CreateSnapshotRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128

    ListSnapshotsResponse:
      type: object
      required: [snapshots]
      properties:
        snapshots:
          type: array
          items:
            $ref: "#/components/schemas/Snapshot"

    CloneBoxRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 128
          description: Name for the cloned box (auto-generated if omitted)

    ExportBoxRequest:
      type: object
      description: Forward-compatible export options (no configurable fields yet).

    StopBoxRequest:
      type: object
      properties:
        timeout_seconds:
          type: number
          minimum: 0
          description: Graceful shutdown timeout in seconds. After expiry, force-kill.
          default: 30

    ListBoxesResponse:
      type: object
      required: [boxes]
      properties:
        boxes:
          type: array
          items:
            $ref: "#/components/schemas/Box"
        next_page_token:
          type: [string, "null"]
          description: |
            Opaque token for next page. Null or absent if no more results.

    # =======================================================================
    # Execution
    # =======================================================================
    ExecRequest:
      type: object
      description: Command execution request (maps to BoxCommand)
      required: [command]
      properties:
        command:
          type: string
          description: Program to execute
          example: python3
        args:
          type: array
          items:
            type: string
          description: Command arguments
          example: ["-c", "print('hello')"]
        env:
          type: object
          additionalProperties:
            type: string
          description: Environment variable overrides for this execution
        timeout_seconds:
          type: number
          minimum: 0.1
          description: Execution timeout in seconds
        working_dir:
          type: string
          description: Working directory override for this execution
        tty:
          type: boolean
          default: false
          description: Enable pseudo-terminal allocation
        user:
          type: string
          description: >-
            User to run the command as, Docker format `<name|uid>[:<group|gid>]`.
            Absent or empty uses the box default user. Unknown users or groups return 400.
          example: "1000:1000"

    ExecResponse:
      type: object
      description: Response from starting an async execution
      required: [execution_id]
      properties:
        execution_id:
          type: string
          description: Unique execution identifier
          example: exec-01HJK5ABCDEF

    ExecutionInfo:
      type: object
      description: Execution status and result
      required: [execution_id, status]
      properties:
        execution_id:
          type: string
        status:
          type: string
          description: Current execution status
          enum:
            - running
            - completed
            - killed
            - timed_out
        exit_code:
          type: [integer, "null"]
          description: Process exit code (null while running)
        started_at:
          type: string
          format: date-time
        duration_ms:
          type: [integer, "null"]
          description: Total execution duration in milliseconds
        error_message:
          type: [string, "null"]
          description: Diagnostic message if process died unexpectedly

    SignalRequest:
      type: object
      required: [signal]
      properties:
        signal:
          type: integer
          description: |
            POSIX signal number to send.
            Common values: 2 (SIGINT), 9 (SIGKILL), 15 (SIGTERM).
          example: 9

    ResizeRequest:
      type: object
      required: [cols, rows]
      properties:
        cols:
          type: integer
          minimum: 1
          description: Terminal width in columns
          example: 120
        rows:
          type: integer
          minimum: 1
          description: Terminal height in rows
          example: 40

    SshConfig:
      type: object
      description: Complete replacement SSH configuration; never persisted or logged by the runtime.
      required: [listen_address, host_private_key, accounts]
      additionalProperties: false
      properties:
        listen_address:
          type: string
          description: Address the guest SSH listener binds.
        host_private_key:
          type: string
          writeOnly: true
          description: Unencrypted OpenSSH host private key; never returned.
        accounts:
          type: array
          minItems: 1
          description: Credentials accepted for SSH logins.
          items:
            $ref: "#/components/schemas/SshAccount"

    SshAccount:
      type: object
      description: Credentials accepted for one SSH login (not a container OS identity).
      required: [login]
      additionalProperties: false
      properties:
        login:
          type: string
          description: SSH login name.
        authorized_keys:
          type: array
          default: []
          description: |
            OpenSSH public keys for this login; defaults to empty, but the guest
            requires a key or CA to accept the account.
          items:
            type: string
        ca:
          description: Optional certificate authority; null means keys only.
          oneOf:
            - $ref: "#/components/schemas/SshCaConfig"
            - type: "null"

    SshCaConfig:
      type: object
      description: Certificate authority and required certificate principal.
      required: [public_key, principal]
      additionalProperties: false
      properties:
        public_key:
          type: string
          description: OpenSSH public key of the certificate authority.
        principal:
          type: string
          description: Certificate principal required for this account.

    SshStatus:
      type: object
      description: |
        Guest SSH listener state; contains no credentials. Every field is
        required: never read a partial one as a disabled status.
      required: [enabled, generation, listen_address, host_public_key, host_key_fingerprint]
      properties:
        enabled:
          type: boolean
          description: Whether the guest SSH listener is running.
        generation:
          type: integer
          minimum: 0
          description: Increments on each successful listener start.
        listen_address:
          type: string
          description: Actual bound address; empty while disabled.
        host_public_key:
          type: string
          description: Comment-free host public key; empty while disabled.
        host_key_fingerprint:
          type: string
          description: SHA-256 host key fingerprint; empty while disabled.

    # =======================================================================
    # Network
    # =======================================================================
    TunnelDescriptor:
      type: object
      description: Service tunnel descriptor. A complete private token is returned only on creation.
      required: [uri, isPublic, token]
      properties:
        uri:
          type: string
          format: uri
          description: |
            Public URI for the box service. Clients MUST treat the
            value as opaque — its shape is deployment-defined.
          example: "https://3000-01hjk4tnrpqsxyz8wm6ncvt9r5.proxy.example.test"
        isPublic:
          type: boolean
        token:
          type: [string, "null"]
          description: Null for public tunnels; complete on private creation, masked on subsequent calls.

    DomainTarget:
      description: A Box port or a reserved App reference. App binding currently returns 400 app_target_not_supported.
      oneOf:
        - $ref: "#/components/schemas/BoxDomainTarget"
        - $ref: "#/components/schemas/AppDomainTarget"
      discriminator:
        propertyName: type
        mapping:
          box: "#/components/schemas/BoxDomainTarget"
          app: "#/components/schemas/AppDomainTarget"

    BoxDomainTarget:
      type: object
      additionalProperties: false
      description: |
        A Box port. `box` selects the resource and `port` the guest service.
      required: [type, box, port]
      properties:
        type:
          type: string
          enum: [box]
        box:
          type: string
          description: |
            The box, by id or name, when binding; the box id when read back.
          example: web-a
        port:
          type: integer
          minimum: 1
          maximum: 65535
          example: 3000

    AppDomainTarget:
      type: object
      additionalProperties: false
      description: Reserved App identity; App binding is unavailable until the App resource exists.
      required: [type, app]
      properties:
        type:
          type: string
          enum: [app]
        app:
          type: string
          minLength: 1
          maxLength: 255
          pattern: '\S'
          description: An opaque App reference.
          example: shop

    Domain:
      type: object
      description: A domain the organization holds and what it currently routes to.
      required: [hostname, url, target]
      properties:
        hostname:
          type: string
          example: demo-app.app.example.test
        url:
          type: string
          example: https://demo-app.app.example.test
        target:
          description: Where the domain routes; null while it is held but unbound.
          oneOf:
            - $ref: "#/components/schemas/DomainTarget"
            - type: "null"

    DomainList:
      type: object
      required: [domains, limit, used, remaining, min_length, domain_suffix]
      properties:
        domains:
          type: array
          items:
            $ref: "#/components/schemas/Domain"
        limit:
          type: integer
          description: How many domains the organization may hold, bound or not.
          example: 1
        used:
          type: integer
          description: How many it holds now.
          example: 1
        remaining:
          type: integer
          minimum: 0
          example: 0
        domain_suffix:
          type: [string, "null"]
          description: Platform hostname suffix for new requests; null when unavailable.
          example: apps.example
        min_length:
          type: integer
          minimum: 1
          maximum: 63
          description: The shortest platform name a new claim may use.
          example: 5

    # =======================================================================
    # Metrics
    # =======================================================================
    RuntimeMetrics:
      type: object
      description: Aggregate metrics across all boxes (maps to RuntimeMetrics)
      properties:
        boxes_created_total:
          type: integer
          description: Total boxes created since runtime startup (monotonic)
        boxes_failed_total:
          type: integer
          description: Total boxes that failed to start (monotonic)
        boxes_stopped_total:
          type: integer
          description: Total boxes stopped (monotonic)
        num_running_boxes:
          type: integer
          description: Currently running boxes (calculated)
        total_commands_executed:
          type: integer
          description: Total commands across all boxes (monotonic)
        total_exec_errors:
          type: integer
          description: Total execution errors across all boxes (monotonic)

    BoxMetrics:
      type: object
      description: Per-box resource usage and execution metrics (maps to BoxMetrics)
      properties:
        commands_executed_total:
          type: integer
          description: Commands executed on this box (monotonic)
        exec_errors_total:
          type: integer
          description: Execution errors on this box (monotonic)
        bytes_sent_total:
          type: integer
          description: Bytes sent to box via stdin (monotonic)
        bytes_received_total:
          type: integer
          description: Bytes received from box via stdout/stderr (monotonic)
        cpu_percent:
          type: [number, "null"]
          format: float
          description: CPU usage percentage (0.0 - 100.0)
        memory_bytes:
          type: [integer, "null"]
          description: Current memory usage in bytes
        network_bytes_sent:
          type: [integer, "null"]
          description: Network bytes sent (host → guest)
        network_bytes_received:
          type: [integer, "null"]
          description: Network bytes received (guest → host)
        network_tcp_connections:
          type: [integer, "null"]
          description: Current ESTABLISHED TCP connections
        network_tcp_errors:
          type: [integer, "null"]
          description: Total failed TCP connection attempts
        boot_timing:
          $ref: "#/components/schemas/BootTiming"

    BootTiming:
      type: object
      description: Stage-level initialization timing breakdown (milliseconds)
      properties:
        total_create_ms:
          type: [integer, "null"]
          description: Total time from create() to box ready
        guest_boot_ms:
          type: [integer, "null"]
          description: Time from subprocess spawn to guest agent ready
        filesystem_setup_ms:
          type: [integer, "null"]
          description: "Stage 1: directory structure creation"
        image_prepare_ms:
          type: [integer, "null"]
          description: "Stage 2: image pull and layer extraction"
        guest_rootfs_ms:
          type: [integer, "null"]
          description: "Stage 3: guest rootfs bootstrap"
        box_config_ms:
          type: [integer, "null"]
          description: "Stage 4: disk and network configuration"
        box_spawn_ms:
          type: [integer, "null"]
          description: "Stage 5: subprocess spawn"
        container_init_ms:
          type: [integer, "null"]
          description: "Stage 6: container initialization inside guest"

    # =======================================================================
    # Images
    # =======================================================================
    ImageInfo:
      type: object
      description: One reference a server holds (maps to ImageInfo)
      required: [reference, repository, tag, id, cached_at]
      properties:
        reference:
          type: string
          description: Full image reference
          example: docker.io/library/python:3.11-slim
        repository:
          type: string
          description: Repository name
          example: docker.io/library/python
        tag:
          type: string
          description: Image tag
          example: 3.11-slim
        id:
          type: string
          description: Image manifest digest
          example: "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4"
        cached_at:
          type: string
          format: date-time
          description: When the build this reference names was recorded
        size_bytes:
          type: [integer, "null"]
          description: Image size in bytes

    ImageDetail:
      type: object
      description: An image name and every build held under it (maps to ImageDetail)
      required: [name, aliases, curated, versions]
      properties:
        name:
          type: string
          description: Registry and repository, without a tag
          example: quay.io/acme/app
        aliases:
          type: array
          items:
            type: string
        curated:
          type: boolean
          description: Provided by the operator rather than recorded from a pull
        versions:
          type: array
          description: Each build held, newest first
          items:
            $ref: "#/components/schemas/ImageVersion"
        history:
          type: array
          description: |
            Where each tag has pointed, newest first. A server may keep only
            the most recent moves; one that keeps no catalog answers it empty.
          items:
            $ref: "#/components/schemas/ImageAliasEvent"

    ImageVersion:
      type: object
      required: [digest, source_ref, recorded_at]
      properties:
        digest:
          type: string
          description: Manifest digest
        size_bytes:
          type: [integer, "null"]
          description: Sum of the layer sizes the manifest declares, when known
        source_ref:
          type: string
          description: The reference that was pulled to get this build
        recorded_at:
          type: string
          format: date-time
        aliases:
          type: array
          description: Tags that point at this build now
          items:
            type: string
        last_used_at:
          type: [string, "null"]
          format: date-time
          description: When a box last started from this build. Null when that is not known
        upstream_missing_at:
          type: [string, "null"]
          format: date-time
          description: |
            When a pull first found the build gone from its registry. Runners
            that cached it still start it. Null while it is not known to be gone.

    ImageAliasEvent:
      type: object
      description: One alias creation, including an alias seeded by a registry pull
      required: [alias, to_digest, recorded_at]
      properties:
        alias:
          type: string
          example: stable
        from_digest:
          type: [string, "null"]
          description: Build the tag pointed at before. Null when the tag did not exist yet
        to_digest:
          type: string
          description: Build the tag points at from then on
        actor:
          type: [string, "null"]
          description: Who moved the tag. Null when a pull recorded it
        recorded_at:
          type: string
          format: date-time

    CreateImageAliasRequest:
      type: object
      required: [alias, digest]
      properties:
        alias:
          type: string
          description: New catalog alias; existing names cannot be overwritten
          pattern: "^[A-Za-z0-9_][A-Za-z0-9._-]{0,127}$"
          example: stable
        digest:
          type: string
          description: Manifest digest of a build the image holds
          pattern: "^sha256:[a-f0-9]{64}$"
          example: "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4"

    ImageUsage:
      type: object
      required: [count, limit, known_bytes]
      properties:
        count:
          type: integer
          description: Images held
        limit:
          type: integer
          description: Most images the routing slot may hold
        known_bytes:
          type: integer
          description: |
            Sum of the sizes the held builds' manifests declare. Not the bytes
            stored: a layer two builds share is counted for each.

    ListImagesResponse:
      type: object
      required: [images]
      properties:
        images:
          type: array
          items:
            $ref: "#/components/schemas/ImageInfo"
        next_page_token:
          type: [string, "null"]
          description: Opaque token for next page

    # =======================================================================
    # Registries
    # =======================================================================
    CreateRegistryRequest:
      type: object
      required: [registry_host, username, password]
      properties:
        registry_host:
          type: string
          description: The registry the login is for; the server says which it takes logins for
          example: ghcr.io
        repository_prefix:
          type: string
          description: |
            The repositories it covers, as whole path segments ending in `/`.
            Omitted or empty for the whole registry.
          maxLength: 255
          example: acme/
        username:
          type: string
          minLength: 1
          maxLength: 255
          example: acme-bot
        password:
          type: string
          description: Password or access token. Never returned.
          writeOnly: true
          minLength: 1
          maxLength: 8192

    RegistryCredential:
      type: object
      description: A registry login. There is no password field.
      required: [id, registry_host, repository_prefix, username, created_at]
      properties:
        id:
          type: string
          format: uuid
        registry_host:
          type: string
          example: ghcr.io
        repository_prefix:
          type: string
          description: Empty for the whole registry
          example: acme/
        username:
          type: string
          example: acme-bot
        created_by:
          type: [string, "null"]
          description: The user who added it
        created_at:
          type: string
          format: date-time

    ListRegistriesResponse:
      type: object
      required: [registries]
      properties:
        registries:
          type: array
          items:
            $ref: "#/components/schemas/RegistryCredential"