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.

    ## 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 for local servers
          (`boxlite serve` at `http://localhost:8100/v1/…`); typically
          `/api` for cloud deployments (`https://api.boxlite.ai/api/v1/…`).
        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

# ===========================================================================
# 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"

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

        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
          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 public URI 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.

        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.
      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:
        "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"

  # -------------------------------------------------------------------------
  # 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/pull:
    parameters:
      - $ref: "#/components/parameters/prefix"
    post:
      operationId: pullImage
      summary: Pull a container image
      description: |
        Pulls a container image from a registry and caches it locally.
        Returns 200 with image info when the pull completes.
      tags: [Images]
      parameters:
        - $ref: "#/components/parameters/idempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PullImageRequest"
      responses:
        "200":
          description: Image pulled and cached
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageInfo"
        "422":
          $ref: "#/components/responses/UnprocessableEntityError"

  /{prefix}/images:
    parameters:
      - $ref: "#/components/parameters/prefix"
    get:
      operationId: listImages
      summary: List cached images
      description: Returns a paginated list of locally cached container images.
      tags: [Images]
      parameters:
        - $ref: "#/components/parameters/pageSize"
        - $ref: "#/components/parameters/pageToken"
      responses:
        "200":
          description: List of cached images
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListImagesResponse"

  /{prefix}/images/{image_id}:
    parameters:
      - $ref: "#/components/parameters/prefix"
      - $ref: "#/components/parameters/imageId"

    get:
      operationId: getImage
      summary: Get image details
      description: Returns metadata for a cached image by its manifest digest.
      tags: [Images]
      responses:
        "200":
          description: Image details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImageInfo"
        "404":
          $ref: "#/components/responses/NotFoundError"

    head:
      operationId: imageExists
      summary: Check if an image is cached
      description: Returns 204 if the image exists in the local cache, 404 if not.
      tags: [Images]
      responses:
        "204":
          description: Image exists
        "404":
          description: Image not found

# ===========================================================================
# 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,
             survives teammate offboarding. 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

    imageId:
      name: image_id
      in: path
      required: true
      description: Image manifest digest (e.g., `sha256:abc123...`)
      schema:
        type: string
      example: "sha256:a3ed95caeb02ffe68cdd9fd84406680ae93d633cb16422d00e8a7c22955b46d4"

    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 32"
              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: 32
            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
            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
          nullable: true
          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
          format: date-time
          nullable: true
          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
          nullable: true
          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
          nullable: true
          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

    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: 32
          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"
        secrets:
          type: array
          items:
            $ref: "#/components/schemas/SecretSpec"
          description: |
            Secret placeholder rules for outbound HTTP(S) 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
        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"
        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.

    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 publicly
            reachable through the remote proxy. `disabled` means private.
        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 HTTP(S) 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
          nullable: true
          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

    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
          nullable: true
          description: Process exit code (null while running)
        started_at:
          type: string
          format: date-time
        duration_ms:
          type: integer
          nullable: true
          description: Total execution duration in milliseconds
        error_message:
          type: string
          nullable: true
          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

    # =======================================================================
    # Network
    # =======================================================================
    TunnelDescriptor:
      type: object
      description: Public descriptor for a box service tunnel.
      required: [uri]
      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"

    # =======================================================================
    # 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
          format: float
          nullable: true
          description: CPU usage percentage (0.0 - 100.0)
        memory_bytes:
          type: integer
          nullable: true
          description: Current memory usage in bytes
        network_bytes_sent:
          type: integer
          nullable: true
          description: Network bytes sent (host → guest)
        network_bytes_received:
          type: integer
          nullable: true
          description: Network bytes received (guest → host)
        network_tcp_connections:
          type: integer
          nullable: true
          description: Current ESTABLISHED TCP connections
        network_tcp_errors:
          type: integer
          nullable: true
          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
          nullable: true
          description: Total time from create() to box ready
        guest_boot_ms:
          type: integer
          nullable: true
          description: Time from subprocess spawn to guest agent ready
        filesystem_setup_ms:
          type: integer
          nullable: true
          description: "Stage 1: directory structure creation"
        image_prepare_ms:
          type: integer
          nullable: true
          description: "Stage 2: image pull and layer extraction"
        guest_rootfs_ms:
          type: integer
          nullable: true
          description: "Stage 3: guest rootfs bootstrap"
        box_config_ms:
          type: integer
          nullable: true
          description: "Stage 4: disk and network configuration"
        box_spawn_ms:
          type: integer
          nullable: true
          description: "Stage 5: subprocess spawn"
        container_init_ms:
          type: integer
          nullable: true
          description: "Stage 6: container initialization inside guest"

    # =======================================================================
    # Images
    # =======================================================================
    ImageInfo:
      type: object
      description: Cached container image metadata (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 image was pulled into the local cache
        size_bytes:
          type: integer
          nullable: true
          description: Image size in bytes

    PullImageRequest:
      type: object
      required: [reference]
      properties:
        reference:
          type: string
          description: Image reference to pull from registry
          example: python:3.11-slim

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