lifecycle.ts

// Copyright 2026 Alibaba Group Holding Ltd..
// 
// 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.

/**
 * This file was auto-generated by openapi-typescript.
 * Do not make direct changes to the file.
 */

export interface paths {
    "/sandboxes": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        /**
         * List sandboxes
         * @description List all sandboxes with optional filtering and pagination using query parameters.
         *     All filter conditions use AND logic. Multiple `state` parameters use OR logic within states.
         */
        get: {
            parameters: {
                query?: {
                    /**
                     * @description Filter by lifecycle state. Pass multiple times for OR logic.
                     *     Example: `?state=Running&state=Paused`
                     */
                    state?: string[];
                    /**
                     * @description Arbitrary metadata key-value pairs for filtering，keys and values must be url encoded
                     *     Example: To filter by `project=Apollo` and `note=Demo Test`: `?metadata=project%3DApollo%26note%3DDemo%252520Test`
                     */
                    metadata?: string;
                    /** @description Page number for pagination */
                    page?: number;
                    /** @description Number of items per page */
                    pageSize?: number;
                };
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description Paginated collection of sandboxes */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["ListSandboxesResponse"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                500: components["responses"]["InternalServerError"];
            };
        };
        put?: never;
        /**
         * Create a sandbox
         * @description Creates a new sandbox from a container image or restores one from a
         *     persistent sandbox snapshot with optional resource limits, environment
         *     variables, and metadata.
         *
         *     Exactly one startup source must be provided:
         *     - `image` to provision directly from a container image.
         *     - `snapshotId` to restore from a previously created snapshot.
         *
         *     When `image` is provided, `entrypoint` is required. When `snapshotId` is
         *     provided, `entrypoint` is optional. If omitted, the server defaults the
         *     sandbox entrypoint to `["tail", "-f", "/dev/null"]`.
         *
         *     ## Authentication
         *
         *     API Key authentication is required via:
         *     - `OPEN-SANDBOX-API-KEY: <api-key>` header
         */
        post: {
            parameters: {
                query?: never;
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["CreateSandboxRequest"];
                };
            };
            responses: {
                /**
                 * @description Sandbox created and accepted for provisioning.
                 *
                 *     The returned sandbox includes:
                 *     - `id`: Unique sandbox identifier
                 *     - `status.state: "Pending"` (auto-starting provisioning or restore)
                 *     - `status.reason` and `status.message` indicating initialization stage
                 *     - `metadata`, `expiresAt`, `createdAt`: Core sandbox information
                 *
                 *     Note: startup source details and `updatedAt` are not included in the create response.
                 *     Use GET /sandboxes/{sandboxId} to retrieve the complete sandbox information.
                 *
                 *     To track provisioning progress, poll GET /sandboxes/{sandboxId}.
                 *     The sandbox will automatically transition to `Running` state once provisioning or restore completes.
                 */
                202: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        Location: components["headers"]["Location"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["CreateSandboxResponse"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/snapshots": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        /**
         * List snapshots
         * @description List all snapshots with optional filtering and pagination using query parameters.
         *     Snapshots are persistent captures of sandbox state and may outlive the source sandbox.
         */
        get: {
            parameters: {
                query?: {
                    /** @description Filter snapshots by source sandbox identifier */
                    sandboxId?: string;
                    /**
                     * @description Filter by snapshot lifecycle state. Pass multiple times for OR logic.
                     *     Example: `?state=Ready&state=Failed`
                     */
                    state?: components["schemas"]["SnapshotState"][];
                    /** @description Page number for pagination */
                    page?: number;
                    /** @description Number of items per page */
                    pageSize?: number;
                };
                header?: never;
                path?: never;
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description Paginated collection of snapshots */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["ListSnapshotsResponse"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                500: components["responses"]["InternalServerError"];
            };
        };
        put?: never;
        post?: never;
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/snapshots/{snapshotId}": {
        parameters: {
            query?: never;
            header?: never;
            path: {
                /** @description Unique snapshot identifier */
                snapshotId: components["parameters"]["SnapshotId"];
            };
            cookie?: never;
        };
        /**
         * Fetch a snapshot by id
         * @description Returns snapshot state and metadata.
         */
        get: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique snapshot identifier */
                    snapshotId: components["parameters"]["SnapshotId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description Snapshot current state and metadata */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["Snapshot"];
                    };
                };
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        put?: never;
        post?: never;
        /**
         * Delete a snapshot
         * @description Delete a persistent sandbox snapshot by id. Snapshots that are still
         *     being created cannot be deleted.
         *
         *     For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
         *     and Kubernetes coordination resources, but does not guarantee removal
         *     of pushed OCI images from the configured registry. Use registry
         *     retention or garbage collection policies for image lifecycle cleanup.
         */
        delete: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique snapshot identifier */
                    snapshotId: components["parameters"]["SnapshotId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description Snapshot successfully deleted */
                204: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content?: never;
                };
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/sandboxes/{sandboxId}": {
        parameters: {
            query?: never;
            header?: never;
            path: {
                /** @description Unique sandbox identifier */
                sandboxId: components["parameters"]["SandboxId"];
            };
            cookie?: never;
        };
        /**
         * Fetch a sandbox by id
         * @description Returns the complete sandbox information including:
         *     - `id`, `status`, `metadata`, `expiresAt`, `createdAt`: Core information
         *     - `image` or `snapshotId`: Startup source information (not included in create response)
         *     - `entrypoint`: Entry process specification
         *
         *     This is the complete representation of the sandbox resource.
         */
        get: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /** @description Sandbox current state and metadata */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["Sandbox"];
                    };
                };
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                500: components["responses"]["InternalServerError"];
            };
        };
        put?: never;
        post?: never;
        /**
         * Delete a sandbox
         * @description Delete a sandbox, terminating its execution. The sandbox will transition through Stopping state to Terminated.
         */
        delete: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /**
                 * @description Sandbox successfully deleted.
                 *
                 *     Sandbox has been scheduled for termination and will transition to Stopping state, then Terminated.
                 */
                204: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content?: never;
                };
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/sandboxes/{sandboxId}/metadata": {
        parameters: {
            query?: never;
            header?: never;
            path: {
                /** @description Unique sandbox identifier */
                sandboxId: components["parameters"]["SandboxId"];
            };
            cookie?: never;
        };
        get?: never;
        put?: never;
        post?: never;
        delete?: never;
        options?: never;
        head?: never;
        /**
         * Patch sandbox metadata
         * @description Update sandbox metadata using JSON Merge Patch semantics (RFC 7396).
         *
         *     **Merge Patch rules:**
         *     | Request body key/value | Behavior |
         *     |---|---|
         *     | `"key": "value"` | Add or replace the key |
         *     | `"key": null` | Delete the key (silently ignored if key does not exist) |
         *     | key absent | Keep current value (no change) |
         *     | Empty `{}` | No-op, returns current metadata |
         *
         *     Metadata keys and values must comply with Kubernetes label rules:
         *     - Keys must be valid DNS label names or prefixed DNS subdomains
         *     - Keys with the `opensandbox.io/` prefix are reserved and rejected
         *     - Values must be 63 characters or less, matching `[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?`
         *
         *     This operation does not restart or recreate the sandbox container/pod.
         *
         *     **Concurrency:** This endpoint uses read-modify-write without optimistic
         *     locking (no `resourceVersion` check). Concurrent PATCH requests may
         *     interleave and silently drop updates. Use a single writer or coordinate
         *     out-of-band when concurrent modifications to the same key are expected.
         */
        patch: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["PatchSandboxMetadataRequest"];
                };
            };
            responses: {
                /**
                 * @description Metadata patched successfully. Returns the complete sandbox resource
                 *     with updated metadata.
                 */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["Sandbox"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        trace?: never;
    };
    "/sandboxes/{sandboxId}/snapshots": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        get?: never;
        put?: never;
        /**
         * Create a snapshot from a sandbox
         * @description Create a persistent point-in-time snapshot from the sandbox's current state.
         *     The source sandbox must be `Running`. The returned snapshot id identifies
         *     the created artifact. Snapshot creation may temporarily pause the sandbox
         *     while the runtime captures provider-supported state, then the source
         *     sandbox continues running.
         */
        post: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody?: {
                content: {
                    "application/json": components["schemas"]["CreateSnapshotRequest"];
                };
            };
            responses: {
                /**
                 * @description Snapshot creation accepted.
                 *
                 *     The returned snapshot includes `status.state: "Creating"`.
                 *     Poll GET /snapshots/{snapshotId} to track progress until the snapshot
                 *     transitions to `Ready` or `Failed`.
                 */
                202: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        Location: components["headers"]["Location"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["Snapshot"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/sandboxes/{sandboxId}/pause": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        get?: never;
        put?: never;
        /**
         * Pause execution while retaining state
         * @description Pause a running sandbox while preserving its state. Poll GET /sandboxes/{sandboxId} to track state transition through Pausing and eventually Paused.
         */
        post: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /**
                 * @description Pause operation accepted.
                 *
                 *     Sandbox will transition to Pausing state and eventually Paused.
                 *     Poll GET /sandboxes/{sandboxId} to track progress.
                 */
                202: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content?: never;
                };
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/sandboxes/{sandboxId}/resume": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        get?: never;
        put?: never;
        /**
         * Resume a paused sandbox
         * @description Resume execution of a paused sandbox. Poll GET /sandboxes/{sandboxId} to track state transition through Resuming and eventually Running.
         */
        post: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /**
                 * @description Resume operation accepted.
                 *
                 *     Sandbox will transition from Paused → Resuming → Running.
                 *     Poll GET /sandboxes/{sandboxId} to track progress.
                 */
                202: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content?: never;
                };
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/sandboxes/{sandboxId}/renew-expiration": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        get?: never;
        put?: never;
        /**
         * Renew sandbox expiration
         * @description Renew the absolute expiration time of a sandbox.
         */
        post: {
            parameters: {
                query?: never;
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                };
                cookie?: never;
            };
            requestBody: {
                content: {
                    "application/json": components["schemas"]["RenewSandboxExpirationRequest"];
                };
            };
            responses: {
                /**
                 * @description Sandbox expiration updated successfully.
                 *
                 *     Returns only the updated expiresAt field.
                 */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["RenewSandboxExpirationResponse"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                409: components["responses"]["Conflict"];
                500: components["responses"]["InternalServerError"];
            };
        };
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
    "/sandboxes/{sandboxId}/endpoints/{port}": {
        parameters: {
            query?: never;
            header?: never;
            path?: never;
            cookie?: never;
        };
        /**
         * Get sandbox access endpoint
         * @description Get the public access endpoint URL for accessing a service running on a specific port
         *     within the sandbox. The service must be listening on the specified port inside
         *     the sandbox for the endpoint to be available.
         */
        get: {
            parameters: {
                query?: {
                    /** @description Whether to return a server-proxied URL */
                    use_server_proxy?: boolean;
                    /**
                     * @description Optional. When set, the server **issues a signed** access route (OSEP-0011). The value
                     *     is **Linux / Unix epoch seconds** — a decimal `uint64` count of **whole seconds** since
                     *     the Unix epoch (`1970-01-01 00:00:00` UTC, same as POSIX / `time(2)`), not
                     *     milliseconds. Normalized to `expires_b36` for the four-segment route token. Omit to
                     *     get the unsigned/legacy response shape.
                     */
                    expires?: string;
                };
                header?: never;
                path: {
                    /** @description Unique sandbox identifier */
                    sandboxId: components["parameters"]["SandboxId"];
                    /** @description Port number where the service is listening inside the sandbox */
                    port: number;
                };
                cookie?: never;
            };
            requestBody?: never;
            responses: {
                /**
                 * @description Endpoint retrieved successfully.
                 *
                 *     Returns the public URL for accessing the service on the specified port.
                 */
                200: {
                    headers: {
                        "X-Request-ID": components["headers"]["XRequestId"];
                        [name: string]: unknown;
                    };
                    content: {
                        "application/json": components["schemas"]["Endpoint"];
                    };
                };
                400: components["responses"]["BadRequest"];
                401: components["responses"]["Unauthorized"];
                403: components["responses"]["Forbidden"];
                404: components["responses"]["NotFound"];
                500: components["responses"]["InternalServerError"];
            };
        };
        put?: never;
        post?: never;
        delete?: never;
        options?: never;
        head?: never;
        patch?: never;
        trace?: never;
    };
}
export type webhooks = Record<string, never>;
export interface components {
    schemas: {
        ListSandboxesResponse: {
            items: components["schemas"]["Sandbox"][];
            pagination: components["schemas"]["PaginationInfo"];
        };
        ListSnapshotsResponse: {
            items: components["schemas"]["Snapshot"][];
            pagination: components["schemas"]["PaginationInfo"];
        };
        /** @description Pagination metadata for list responses */
        PaginationInfo: {
            /** @description Current page number */
            page: number;
            /** @description Number of items per page */
            pageSize: number;
            /** @description Total number of items matching the filter */
            totalItems: number;
            /** @description Total number of pages */
            totalPages: number;
            /** @description Whether there are more pages after the current one */
            hasNextPage: boolean;
        };
        /** @description Response from creating a new sandbox. Contains essential information without startup source details and updatedAt. */
        CreateSandboxResponse: {
            /** @description Unique sandbox identifier */
            id: string;
            /** @description Current lifecycle status and detailed state information */
            status: components["schemas"]["SandboxStatus"];
            /** @description Custom metadata from creation request */
            metadata?: {
                [key: string]: string;
            };
            /**
             * @description Platform constraint echoed from request or workload template.
             *     Null when no scheduling constraint is provided.
             */
            platform?: components["schemas"]["PlatformSpec"];
            /**
             * Format: date-time
             * @description Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
             */
            expiresAt?: string;
            /**
             * Format: date-time
             * @description Sandbox creation timestamp
             */
            createdAt: string;
            /**
             * @description Entry process specification for the sandbox. For image-created sandboxes,
             *     this is copied from the creation request. For snapshot-created sandboxes,
             *     this is restored from the snapshot.
             */
            entrypoint: string[];
        };
        /** @description Optional settings for creating a sandbox snapshot. */
        CreateSnapshotRequest: {
            /** @description Optional human-readable snapshot name. */
            name?: string;
        };
        /** @description Persistent point-in-time capture of a sandbox. */
        Snapshot: {
            /** @description Unique snapshot identifier */
            id: string;
            /** @description Source sandbox identifier used to create this snapshot */
            sandboxId: string;
            /** @description Optional human-readable snapshot name */
            name?: string;
            /** @description Current snapshot lifecycle status and detailed state information */
            status: components["schemas"]["SnapshotStatus"];
            /**
             * Format: date-time
             * @description Snapshot creation timestamp
             */
            createdAt: string;
        };
        /**
         * @description Snapshot lifecycle state.
         *
         *     Common state values:
         *     - Creating: Snapshot creation has been accepted and runtime capture is in progress.
         *     - Deleting: Snapshot deletion has been requested and cleanup is in progress.
         *     - Ready: Snapshot is available for restoring sandboxes.
         *     - Failed: Snapshot creation failed.
         *
         *     Note: New state values may be added in future versions.
         *     Clients should handle unknown state values gracefully.
         */
        SnapshotState: string;
        /** @description Detailed snapshot status information with lifecycle state and transition details. */
        SnapshotStatus: {
            /** @description Current lifecycle state of the snapshot */
            state: components["schemas"]["SnapshotState"];
            /**
             * @description Short machine-readable reason code for the current state.
             *     Examples: "snapshot_accepted", "snapshot_ready", "snapshot_capture_failed"
             */
            reason?: string;
            /** @description Human-readable message describing the current state or failure reason */
            message?: string;
            /**
             * Format: date-time
             * @description Timestamp of the last state transition
             */
            lastTransitionAt?: string;
        };
        /** @description Runtime execution environment provisioned from a container image or restored from a snapshot */
        Sandbox: {
            /** @description Unique sandbox identifier */
            id: string;
            /**
             * @description Container image specification used to provision this sandbox.
             *     Present when the sandbox was created directly from a container image.
             *     Not returned in createSandbox response.
             */
            image?: components["schemas"]["ImageSpec"];
            /**
             * @description Snapshot identifier used to restore this sandbox.
             *     Present when the sandbox was restored from a snapshot.
             *     Not returned in createSandbox response.
             */
            snapshotId?: string;
            /**
             * @description Platform constraint echoed from request or workload template.
             *     Null when no scheduling constraint is provided.
             */
            platform?: components["schemas"]["PlatformSpec"];
            /** @description Current lifecycle status and detailed state information */
            status: components["schemas"]["SandboxStatus"];
            /** @description Custom metadata from creation request */
            metadata?: {
                [key: string]: string;
            };
            /**
             * @description The command to execute as the sandbox's entry process.
             *     Always present in responses. For image-created sandboxes, this is copied
             *     from the creation request. For snapshot-created sandboxes, this is restored
             *     from the snapshot.
             */
            entrypoint: string[];
            /**
             * Format: date-time
             * @description Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
             */
            expiresAt?: string;
            /**
             * Format: date-time
             * @description Sandbox creation timestamp
             */
            createdAt: string;
        };
        /**
         * @description High-level lifecycle state of the sandbox.
         *
         *     Common state values:
         *     - Pending: Sandbox is being provisioned
         *     - Running: Sandbox is running and ready to accept requests
         *     - Pausing: Sandbox is in the process of pausing
         *     - Paused: Sandbox has been paused while retaining its state
         *     - Resuming: Sandbox is being restored after a pause
         *     - Stopping: Sandbox is being terminated
         *     - Terminated: Sandbox has been successfully terminated
         *     - Failed: Sandbox encountered a critical error
         *
         *     State transitions:
         *     - Pending → Running (after creation completes)
         *     - Running → Pausing (when pause is requested)
         *     - Pausing → Paused (pause operation completes)
         *     - Paused → Resuming (when resume is requested)
         *     - Resuming → Running (when resume operation completes)
         *     - Running/Paused → Stopping (when kill is requested or TTL expires)
         *     - Stopping → Terminated (kill/timeout operation completes)
         *     - Pending/Running/Paused/Resuming → Failed (on error)
         *
         *     Note: New state values may be added in future versions.
         *     Clients should handle unknown state values gracefully.
         */
        SandboxState: string;
        /** @description Detailed status information with lifecycle state and transition details */
        SandboxStatus: {
            /** @description Current lifecycle state of the sandbox */
            state: components["schemas"]["SandboxState"];
            /**
             * @description Short machine-readable reason code for the current state.
             *     Examples: "user_delete", "ttl_expiry", "provision_timeout", "runtime_error"
             */
            reason?: string;
            /** @description Human-readable message describing the current state or reason for state transition */
            message?: string;
            /**
             * Format: date-time
             * @description Timestamp of the last state transition
             */
            lastTransitionAt?: string;
        };
        /**
         * @description Container image specification for sandbox provisioning.
         *
         *     Supports public registry images and private registry images with authentication.
         */
        ImageSpec: {
            /**
             * @description Container image URI in standard format.
             *
             *     Examples:
             *       - "python:3.11" (Docker Hub)
             *       - "ubuntu:22.04"
             *       - "gcr.io/my-project/model-server:v1.0"
             *       - "private-registry.company.com:5000/app:latest"
             */
            uri: string;
            /** @description Registry authentication credentials (required for private registries) */
            auth?: {
                /** @description Registry username or service account */
                username?: string;
                /** @description Registry password or authentication token */
                password?: string;
            };
        };
        /**
         * @description Runtime platform constraint used for scheduling/provisioning.
         *
         *     This field is independent from `image` and expresses the expected target
         *     OS and CPU architecture for sandbox execution.
         *
         *     Behavioral notes:
         *     - If omitted, the runtime applies its own default platform selection behavior.
         *       For Docker, requests are created without an explicit platform override.
         *       For Kubernetes, no `kubernetes.io/os` or `kubernetes.io/arch` constraint
         *       is injected unless provided by request or workload template.
         *     - If provided and cannot be satisfied by runtime/template/pool constraints,
         *       request must fail explicitly.
         */
        PlatformSpec: {
            /**
             * @description Target operating system (for example `linux` or `windows`).
             * @example linux
             * @enum {string}
             */
            os: "linux" | "windows";
            /**
             * @description Target CPU architecture (for example `amd64` or `arm64`).
             * @example arm64
             * @enum {string}
             */
            arch: "amd64" | "arm64";
        };
        /**
         * @description JSON Merge Patch (RFC 7396) request body for updating sandbox metadata.
         *
         *     The request body is the metadata object itself:
         *     - Present keys with non-null values add or replace
         *     - Keys with `null` values are deleted
         *     - Absent keys are left unchanged
         *
         *     Keys with the `opensandbox.io/` prefix are reserved and rejected.
         * @example {
         *       "project": "new-project",
         *       "team": null,
         *       "environment": "production"
         *     }
         */
        PatchSandboxMetadataRequest: {
            [key: string]: string | null;
        };
        /**
         * @description Request to create a new sandbox from either a container image or a snapshot.
         *     Exactly one of `image` or `snapshotId` must be provided.
         *
         *     When `image` is provided, `entrypoint` is required. When `snapshotId` is
         *     provided, `entrypoint` is optional. If omitted, the server defaults the
         *     sandbox entrypoint to `["tail", "-f", "/dev/null"]`.
         *
         *     **Note**: API Key authentication is required via the `OPEN-SANDBOX-API-KEY` header.
         */
        CreateSandboxRequest: {
            /**
             * @description Container image specification for the sandbox.
             *     Mutually exclusive with `snapshotId`.
             */
            image?: components["schemas"]["ImageSpec"];
            /**
             * @description Snapshot identifier to restore from.
             *     Mutually exclusive with `image`.
             */
            snapshotId?: string;
            /**
             * @description Optional platform constraint for sandbox scheduling/runtime selection.
             *
             *     If omitted, runtime default behavior applies (runtime-specific and not
             *     a fixed architecture guarantee). If specified, the runtime must satisfy
             *     this constraint or fail explicitly.
             *     This field is only meaningful when scheduling constraints are set.
             */
            platform?: components["schemas"]["PlatformSpec"];
            /**
             * @description Sandbox timeout in seconds. The sandbox will automatically terminate after this duration.
             *     The maximum is controlled by the server configuration (`server.max_sandbox_timeout_seconds`).
             *     Omit this field or set it to null to disable automatic expiration and require explicit cleanup.
             *     Note: manual cleanup support is runtime-dependent; Kubernetes providers may reject
             *     omitted or null timeout when the underlying workload provider does not support non-expiring sandboxes.
             */
            timeout?: number | null;
            /**
             * @description Runtime resource constraints for the sandbox instance.
             *     SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi").
             */
            resourceLimits: components["schemas"]["ResourceLimits"];
            /**
             * @description Environment variables to inject into the sandbox runtime.
             * @example {
             *       "API_KEY": "secret-key",
             *       "DEBUG": "true",
             *       "LOG_LEVEL": "info"
             *     }
             */
            env?: {
                [key: string]: string;
            };
            /**
             * @description Custom key-value metadata for management, filtering, and tagging.
             *     Use "name" key for a human-readable identifier.
             * @example {
             *       "name": "Data Processing Sandbox",
             *       "project": "data-processing",
             *       "team": "ml",
             *       "environment": "staging"
             *     }
             */
            metadata?: {
                [key: string]: string;
            };
            /**
             * @description The command to execute as the sandbox's entry process.
             *
             *     Required when `image` is provided.
             *
             *     Optional when `snapshotId` is provided. If omitted for snapshot
             *     restore, the server defaults to `["tail", "-f", "/dev/null"]`.
             *
             *     Explicitly specifies the user's expected main process, allowing the sandbox management
             *     service to reliably inject control processes before executing this command.
             *
             *     Format: [executable, arg1, arg2, ...]
             *
             *     Examples:
             *     - ["python", "/app/main.py"]
             *     - ["/bin/bash"]
             *     - ["java", "-jar", "/app/app.jar"]
             *     - ["node", "server.js"]
             * @example [
             *       "python",
             *       "/app/main.py"
             *     ]
             */
            entrypoint?: string[];
            /**
             * @description Optional outbound network policy for the sandbox.
             *     Shape matches the sidecar `/policy` endpoint. If omitted or empty,
             *     the sidecar starts in allow-all mode until updated.
             */
            networkPolicy?: components["schemas"]["NetworkPolicy"];
            /**
             * @description Opts the sandbox into secured access for endpoint access.
             *     This is currently supported only for Kubernetes sandboxes exposed
             *     through ingress gateway mode. When enabled, the server provisions
             *     access credentials and returns the required request headers with
             *     endpoint responses. Clients must include those endpoint headers when
             *     calling the sandbox. When omitted or false, endpoints remain
             *     accessible without the additional access token for backward
             *     compatibility.
             * @default false
             */
            secureAccess: boolean;
            /**
             * @description Storage mounts for the sandbox. Each volume entry specifies a named backend-specific
             *     storage source and common mount settings. Exactly one backend type must be specified
             *     per volume entry.
             */
            volumes?: components["schemas"]["Volume"][];
            /**
             * @description Opaque container for provider-specific or transient parameters not supported by the core API.
             *
             *     **Note**: This field is reserved for internal features, experimental flags, or temporary behaviors. Standard parameters should be proposed as core API fields.
             *
             *     **Best Practices**:
             *     - **Namespacing**: Use prefixed keys (e.g., `storage.id`) to prevent collisions.
             *     - **Pass-through**: SDKs and middleware must treat this object as opaque and pass it through transparently.
             *
             *     **Well-known keys**:
             *     - `access.renew.extend.seconds` (optional): Decimal integer string from **300** to **86400** (5 minutes to 24 hours inclusive). Opts the sandbox into OSEP-0009 renew-on-access and sets per-renewal extension seconds. Omit to disable. Invalid values are rejected at creation with HTTP 400 (validated on the lifecycle create endpoint via `validate_extensions` in server `src/extensions/validation.py`).
             */
            extensions?: {
                [key: string]: string;
            };
        };
        /**
         * @description Runtime resource constraints as key-value pairs. Similar to Kubernetes resource specifications,
         *     allows flexible definition of resource limits. Common resource types include:
         *     - `cpu`: CPU allocation in millicores (e.g., "250m" for 0.25 CPU cores)
         *     - `memory`: Memory allocation in bytes or human-readable format (e.g., "512Mi", "1Gi")
         *     - `gpu`: Number of GPU devices (e.g., "1")
         *
         *     New resource types can be added without API changes.
         * @example {
         *       "cpu": "500m",
         *       "memory": "512Mi",
         *       "gpu": "1"
         *     }
         */
        ResourceLimits: {
            [key: string]: string;
        };
        RenewSandboxExpirationRequest: {
            /**
             * Format: date-time
             * @description New absolute expiration time in UTC (RFC 3339 format).
             *     Must be in the future and after the current expiresAt time.
             *
             *     Example: "2025-11-16T14:30:45Z"
             */
            expiresAt: string;
        };
        RenewSandboxExpirationResponse: {
            /**
             * Format: date-time
             * @description The new absolute expiration time in UTC (RFC 3339 format).
             *
             *     Example: "2025-11-16T14:30:45Z"
             */
            expiresAt: string;
        };
        /**
         * @description Standard error response for all non-2xx HTTP responses.
         *     HTTP status code indicates the error category; code and message provide details.
         */
        ErrorResponse: {
            /**
             * @description Machine-readable error code (e.g., INVALID_REQUEST, NOT_FOUND, INTERNAL_ERROR).
             *     Use this for programmatic error handling.
             */
            code: string;
            /** @description Human-readable error message describing what went wrong and how to fix it. */
            message: string;
        };
        /**
         * @description Endpoint for accessing a service running in the sandbox.
         *     The service must be listening on the specified port inside the sandbox for the endpoint to be available.
         */
        Endpoint: {
            /**
             * @description Public URL to access the service from outside the sandbox.
             *     Format: {endpoint-host}/sandboxes/{sandboxId}/port/{port}
             *     Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
             */
            endpoint: string;
            /** @description Requests targeting the sandbox must include the corresponding header(s). */
            headers?: {
                [key: string]: string;
            };
        };
        /**
         * @description Egress network policy matching the sidecar `/policy` request body.
         *     If `defaultAction` is omitted, the sidecar defaults to "deny"; passing an empty
         *     object or null results in allow-all behavior at startup.
         */
        NetworkPolicy: {
            /**
             * @description Default action when no egress rule matches. Defaults to "deny".
             * @enum {string}
             */
            defaultAction?: "allow" | "deny";
            /** @description List of egress rules evaluated in order. */
            egress?: components["schemas"]["NetworkRule"][];
        };
        NetworkRule: {
            /**
             * @description Whether to allow or deny matching targets.
             * @enum {string}
             */
            action: "allow" | "deny";
            /**
             * @description FQDN or wildcard domain (e.g., "example.com", "*.example.com").
             *     IP/CIDR not yet supported in the egress MVP.
             */
            target: string;
        };
        /**
         * @description Storage mount definition for a sandbox. Each volume entry contains:
         *     - A unique name identifier
         *     - Exactly one backend struct (host, pvc, ossfs, etc.) with backend-specific fields
         *     - Common mount settings (mountPath, readOnly, subPath)
         */
        Volume: {
            /**
             * @description Unique identifier for the volume within the sandbox.
             *     Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
             */
            name: string;
            host?: components["schemas"]["Host"];
            pvc?: components["schemas"]["PVC"];
            ossfs?: components["schemas"]["OSSFS"];
            /**
             * @description Absolute path inside the container where the volume is mounted.
             *     Must start with '/'.
             */
            mountPath: string;
            /**
             * @description If true, the volume is mounted as read-only. Defaults to false (read-write).
             * @default false
             */
            readOnly: boolean;
            /**
             * @description Optional subdirectory under the backend path to mount.
             *     For `ossfs` backend, this field is used as the bucket prefix.
             *     Must be a relative path without '..' components.
             */
            subPath?: string;
        };
        /**
         * @description Host path bind mount backend. Maps a directory on the host filesystem
         *     into the container. Only available when the runtime supports host mounts.
         *
         *     Security note: Host paths are restricted by server-side allowlist.
         *     Users must specify paths under permitted prefixes.
         */
        Host: {
            /**
             * @description Absolute path on the host filesystem to mount.
             *     Must start with '/' (Unix) or a drive letter such as 'C:\' or 'D:/'
             *     (Windows), and be under an allowed prefix.
             */
            path: string;
        };
        /**
         * @description Platform-managed named volume backend. A runtime-neutral abstraction
         *     for referencing a platform-managed named volume. If `createIfNotExists`
         *     is true (the default) and the volume does not yet exist, it will be
         *     created automatically using the provisioning hints below.
         *
         *     - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
         *     - Docker: maps to a Docker named volume (created via `docker volume create`).
         */
        PVC: {
            /**
             * @description Name of the volume on the target platform.
             *     In Kubernetes this is the PVC name; in Docker this is the named
             *     volume name. Must be a valid DNS label.
             */
            claimName: string;
            /**
             * @description When true (the default), the volume is automatically created if
             *     it does not exist. When false, referencing a non-existent volume
             *     fails with an error.
             * @default true
             */
            createIfNotExists: boolean;
            /**
             * @description When true, the volume is automatically removed when the sandbox
             *     is deleted. Only applies to volumes that were auto-created by the
             *     server (Docker only). Pre-existing volumes are never removed.
             *     Has no effect on Kubernetes PVCs, whose lifecycle is managed by
             *     the StorageClass reclaim policy.
             * @default false
             */
            deleteOnSandboxTermination: boolean;
            /**
             * @description Kubernetes StorageClass name for auto-created PVCs. Null means
             *     use the cluster default. Ignored for Docker volumes.
             */
            storageClass?: string | null;
            /**
             * @description Storage capacity request for auto-created PVCs (e.g. "1Gi",
             *     "10Gi"). Defaults to the server-configured `volume_default_size`
             *     when omitted. Ignored for Docker volumes.
             */
            storage?: string | null;
            /**
             * @description Access modes for auto-created PVCs (e.g. ["ReadWriteOnce"]).
             *     Defaults to ["ReadWriteOnce"] when omitted. Ignored for Docker
             *     volumes.
             */
            accessModes?: string[] | null;
            /**
             * @description Static PersistentVolume spec for Kubernetes. When provided,
             *     the server creates a PV with this spec bound to the auto-created PVC.
             *     Defaults to dynamic provisioning when omitted. Ignored for Docker volumes.
             */
            pv?: Record<string, unknown> | null;
        };
        /**
         * @description Alibaba Cloud OSS mount backend via ossfs.
         *
         *     The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
         *     and bind-mounts the resolved path into the sandbox container.
         *     Prefix selection is expressed via `Volume.subPath`.
         *     In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
         */
        OSSFS: {
            /** @description OSS bucket name. */
            bucket: string;
            /** @description OSS endpoint (e.g., `oss-cn-hangzhou.aliyuncs.com`). */
            endpoint: string;
            /**
             * @description ossfs major version used by runtime mount integration.
             * @default 2.0
             * @enum {string}
             */
            version: "1.0" | "2.0";
            /**
             * @description Additional ossfs mount options.
             *     Runtime encodes options by `version`:
             *     - `1.0`: mounts with `ossfs ... -o <option>`
             *     - `2.0`: mounts with `ossfs2 mount ... -c <config-file>` and encodes options as `--<option>` lines in the config file
             *     Option values must be provided as raw payloads without leading `-`.
             */
            options?: string[];
            /** @description OSS access key ID for inline credentials mode. */
            accessKeyId: string;
            /** @description OSS access key secret for inline credentials mode. */
            accessKeySecret: string;
        };
    };
    responses: {
        /** @description Error response envelope */
        Error: {
            headers: {
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
        /** @description The request was invalid or malformed */
        BadRequest: {
            headers: {
                "X-Request-ID": components["headers"]["XRequestId"];
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
        /** @description Authentication credentials are missing or invalid */
        Unauthorized: {
            headers: {
                "X-Request-ID": components["headers"]["XRequestId"];
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
        /** @description The authenticated user lacks permission for this operation */
        Forbidden: {
            headers: {
                "X-Request-ID": components["headers"]["XRequestId"];
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
        /** @description The requested resource does not exist */
        NotFound: {
            headers: {
                "X-Request-ID": components["headers"]["XRequestId"];
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
        /** @description The operation conflicts with the current state */
        Conflict: {
            headers: {
                "X-Request-ID": components["headers"]["XRequestId"];
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
        /** @description An unexpected server error occurred */
        InternalServerError: {
            headers: {
                "X-Request-ID": components["headers"]["XRequestId"];
                [name: string]: unknown;
            };
            content: {
                "application/json": components["schemas"]["ErrorResponse"];
            };
        };
    };
    parameters: {
        /** @description Unique sandbox identifier */
        SandboxId: string;
        /** @description Unique snapshot identifier */
        SnapshotId: string;
    };
    requestBodies: never;
    headers: {
        /** @description Unique request identifier for tracing */
        XRequestId: string;
        /** @description URI of the newly created or related resource */
        Location: string;
        /** @description Suggested delay in seconds before retrying */
        RetryAfter: number;
    };
    pathItems: never;
}
export type $defs = Record<string, never>;
export type operations = Record<string, never>;