openapi: 3.2.0 info: title: Docker Sandboxes API version: v1 description: |- Use this API to create sandboxes, run processes, work with files, and manage sandbox resources. Start with a kit through the SDK, or use the HTTP operations here directly. Management requests use an Authorization bearer token. File and process requests go to the sandbox endpoint in core.endpoint.uri and require a short-lived scoped endpoint credential, not the management token. The SDK obtains that credential for you. Each operation also checks its declared permissions. Direct Unix socket access uses the operating system's socket access controls instead of HTTP authentication. Interactive WebSocket operations describe their supported credential transports separately. The Docker Cloud API base URL is https://connect.docker.com/sandboxes. Append each /v1 path without removing the base URL's path prefix. For sandbox endpoint operations, use the sandbox endpoint as the base URL instead. Operations list their success and error responses. A 202 response means work is still in progress; read the resource until it reaches the expected state. Errors contain a stable code, a message, and optional details. Inspect the code as well as the HTTP status. Send the current ETag in If-Match when an operation requires it. Operations that accept Idempotency-Key use that HTTP header to identify retries: the same key and payload return the first result; a different payload fails. Keys are retained for at least 24 hours. Lists use pageSize and pageToken. Continue with nextPageToken until it is empty. Supported filters and ordering are listed on each operation. Resource names contain immutable identifiers; displayName is a label. A 64-bit integer is returned as a JSON string; inputs accept a number or a string. contact: name: Docker Cloud Sandboxes url: https://github.com/docker/sandboxes-api servers: - url: https://connect.docker.com/sandboxes description: The API base URL. Append the /v1 paths while preserving this URL's path prefix. paths: /v1/files: get: tags: - Files summary: List lists directory entries by path ascending. description: List lists directory entries by path ascending. operationId: list parameters: - name: path in: query description: path is the directory path. required: true schema: type: string title: path minLength: 1 - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an optional continuation token. schema: type: string title: page_token required: false - name: orderBy in: query description: |- order_by is a single order field with optional direction; the portable field is path. schema: type: string title: order_by required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesListResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Files summary: Remove deletes a path. description: |- Remove deletes a path. Removing an absent path succeeds. A nonrecursive removal of a nonempty directory returns FAILED_PRECONDITION unchanged. A recursive removal that stops partway still answers OK: check RemoveResponse.failed_path, not the operation status. Removed paths stay removed. operationId: remove parameters: - name: path in: query description: path is the sandbox path to remove. required: true schema: type: string title: path minLength: 1 - name: recursive in: query description: recursive removes directory contents when true. schema: type: boolean title: recursive required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesRemoveResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/files/content: get: tags: - Files summary: ReadFile returns raw file content over HTTP; Stat exposes file metadata. description: |- ReadFile returns raw file content over HTTP; Stat exposes file metadata. Content above the unary message cap is refused, never truncated. operationId: readFile parameters: - name: path in: query description: path is the sandbox path of a regular file. required: true schema: type: string title: path minLength: 1 responses: "200": description: Success content: application/octet-stream: schema: contentMediaType: application/octet-stream headers: Content-Length: required: true description: Exact byte count of the complete file; this response does not use chunked transfer encoding. schema: type: integer minimum: 0 default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-http-transfer: response: mediaType: application/octet-stream bytesField: data x-sbx-request-schema: $ref: "#/components/schemas/FilesReadFileRequest" x-sbx-response-schema: $ref: "#/components/schemas/FilesReadFileResponse" put: tags: - Files summary: WriteFile accepts raw content with path and mode query parameters. description: |- WriteFile accepts raw content with path and mode query parameters. It replaces the complete target state and carries no request_id. operationId: writeFile parameters: - name: path in: query description: path is the sandbox path. required: true schema: type: string title: path minLength: 1 - name: mode in: query description: |- mode carries Unix permission bits. Upload applies mode & 0777, or 0644 when that value is zero, without subtracting umask; Download reports stored bits. schema: type: integer title: mode required: false requestBody: required: true content: application/octet-stream: schema: contentMediaType: application/octet-stream responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesWriteFileResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-http-transfer: request: mediaType: application/octet-stream bytesField: data x-sbx-request-schema: $ref: "#/components/schemas/FilesWriteFileRequest" x-sbx-response-schema: $ref: "#/components/schemas/FilesWriteFileResponse" /v1/files/directories: put: tags: - Files summary: Mkdir creates a directory. description: |- Mkdir creates a directory. Without parents, a missing parent returns NOT_FOUND without creating directories. A repeated Mkdir converges when the leaf already exists as a directory. A converged call leaves the directory's mode unchanged on every request. operationId: mkdir requestBody: content: application/json: schema: $ref: "#/components/schemas/FilesMkdirRequest" required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesMkdirResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/files/download: get: tags: - Files summary: Download streams file headers, bytes, and per-file errors. description: |- Download streams file headers, bytes, and per-file errors. A path that leaves the jail through a symlink, or names a non-regular object, reports a FileError with a error reason instead of reading through it. operationId: download parameters: - name: paths in: query description: |- paths naming stable regular files or absent entries at canonical absolute paths yield contiguous results in request order, including duplicates. required: true schema: type: array items: type: string title: paths minItems: 1 responses: "200": description: |- Success Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures. content: multipart/mixed: itemSchema: anyOf: - $ref: "#/components/schemas/FileHeader" - contentMediaType: application/octet-stream - $ref: "#/components/schemas/FileError" - $ref: "#/components/schemas/Error" itemEncoding: contentType: application/json, application/octet-stream headers: Content-Disposition: required: true schema: type: string enum: - attachment; name=metadata - attachment; name=content - attachment; name=error - attachment; name=stream-error x-sbx-framing: description: Read metadata followed by one continuous raw content part. JSON controls are separate parts with Content-Type application/json; binary content uses application/octet-stream. A final stream-error part carries the shared Error for a whole-stream failure. A clean closing delimiter with no stream-error is required for success; aborted connections are failures. parts: metadata: contentType: application/json schema: $ref: "#/components/schemas/FileHeader" content: contentType: application/octet-stream schema: contentMediaType: application/octet-stream error: contentType: application/json schema: $ref: "#/components/schemas/FileError" stream-error: contentType: application/json schema: $ref: "#/components/schemas/Error" repeatedItems: true requiresClosingDelimiter: true requiresTerminal: false default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-http-transfer: response: mediaType: multipart/mixed bytesField: data metadataField: header errorField: error repeatedItems: true x-sbx-request-schema: $ref: "#/components/schemas/FilesDownloadRequest" x-sbx-response-schema: $ref: "#/components/schemas/FilesDownloadResponse" /v1/files/move: post: tags: - Files summary: Move renames or moves a path. description: |- Move renames or moves a path. The destination is exact: an existing regular file is replaced, the source basename is never appended, and a directory destination is refused unchanged. A source or destination that leaves the jail through a symlink refuses with FAILED_PRECONDITION and a error reason. operationId: move requestBody: content: application/json: schema: $ref: "#/components/schemas/FilesMoveRequest" required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesMoveResponse" "409": description: |- The path resolves through a symlink that does not resolve to a target inside the sandbox jail. The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it. `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing. `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary. content: application/json: schema: $ref: "#/components/schemas/Error" examples: path_authority_symlink_escape: summary: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. value: code: failedPrecondition message: "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." path_authority_nonregular_object: summary: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. value: code: failedPrecondition message: "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." move_destination_is_directory: summary: "`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." value: code: failedPrecondition message: "move_destination_is_directory: `from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." move_destination_occupied: summary: "`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." value: code: failedPrecondition message: "move_destination_occupied: `from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." move_crosses_filesystem: summary: "`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." value: code: failedPrecondition message: "move_crosses_filesystem: `from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. reason: path_authority_symlink_escape - code: FAILED_PRECONDITION description: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. reason: path_authority_nonregular_object - code: FAILED_PRECONDITION description: "`from` names a regular file and `to` an existing directory, which `Move` refuses rather than moving the file into it." reason: move_destination_is_directory - code: FAILED_PRECONDITION description: "`from` names a directory and `to` an existing path, which `Move` refuses rather than replacing." reason: move_destination_occupied - code: FAILED_PRECONDITION description: "`from` and `to` are on different filesystems, and `Move` never copies the contents to cross the boundary." reason: move_crosses_filesystem servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/files/stat: get: tags: - Files summary: Stat reads metadata for one path. description: |- Stat reads metadata for one path. A metadata read has a different response from the file-content resource. operationId: stat parameters: - name: path in: query description: path is the sandbox path. required: true schema: type: string title: path minLength: 1 responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesStatResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/files/upload: post: tags: - Files summary: Upload streams one or more files. description: |- Upload streams one or more files. The first frame must be FileHeader. Writing through a symlink that leaves the jail, or onto an existing non-regular object, refuses with FAILED_PRECONDITION and a error reason. operationId: upload requestBody: required: true content: multipart/form-data: itemSchema: oneOf: - type: object properties: metadata: $ref: "#/components/schemas/FileHeader" required: - metadata additionalProperties: false - type: object properties: content: contentMediaType: application/octet-stream required: - content additionalProperties: false itemEncoding: contentType: application/json, application/octet-stream x-sbx-framing: description: Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path. partOrder: - metadata - content repeatedItems: true requiresClosingDelimiter: true description: Send ordered metadata/content pairs. Each metadata part is application/json; the following content part is application/octet-stream containing raw bytes, including an empty file. Content-Disposition is form-data with the corresponding part name. Content-Transfer-Encoding is refused. A clean closing multipart delimiter is required; truncated content never completes the current item. Malformed occurrences report invalidArgument with a BadRequest detail identifying the occurrence index and path. responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/FilesUploadResponse" "409": description: |- The path resolves through a symlink that does not resolve to a target inside the sandbox jail. The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: path_authority_symlink_escape: summary: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. value: code: failedPrecondition message: "path_authority_symlink_escape: The path resolves through a symlink that does not resolve to a target inside the sandbox jail." path_authority_nonregular_object: summary: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. value: code: failedPrecondition message: "path_authority_nonregular_object: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The path resolves through a symlink that does not resolve to a target inside the sandbox jail. reason: path_authority_symlink_escape - code: FAILED_PRECONDITION description: The path names an existing socket, FIFO, device, or other non-regular object where a regular file is required. reason: path_authority_nonregular_object servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesFilesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-http-transfer: request: mediaType: multipart/form-data bytesField: data metadataField: header repeatedItems: true itemPathField: header.path x-sbx-request-schema: $ref: "#/components/schemas/FilesUploadRequest" x-sbx-response-schema: $ref: "#/components/schemas/FilesUploadResponse" /v1/identity/exchange: post: tags: - Credentials summary: ExchangeDockerCredential consumes an identity token once for the authenticated owner. description: |- ExchangeDockerCredential consumes an identity token once for the authenticated owner. The exchanged credential is stored for that owner; the response is empty. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: exchangeDockerCredential requestBody: content: application/json: schema: $ref: "#/components/schemas/IdentityExchangeServiceExchangeDockerCredentialRequest" required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ExchangeCompositionCredentialResponse" "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - credentialsExchange x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/images: get: tags: - Images summary: ListImages lists images in the caller's owner scope. description: ListImages lists images in the caller's owner scope. operationId: listImages parameters: - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable fields are name, display_name, uid and status. schema: type: string title: filter required: false - name: orderBy in: query description: |- order_by is a single order field with optional direction; the portable fields are created_at and name. schema: type: string title: order_by required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListImagesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - imagesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false post: tags: - Images summary: CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox. description: CreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox. operationId: createImage requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateImageRequest" required: true responses: "201": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/Image" - not: properties: status: enum: - pending - waitingForPush - preparing required: - status headers: Cache-Control: required: true schema: type: string const: no-store ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Image" - properties: status: enum: - pending - waitingForPush - preparing required: - status headers: Cache-Control: required: true schema: type: string const: no-store ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. headers: Cache-Control: required: true schema: type: string enum: - no-store default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" headers: Cache-Control: required: true schema: type: string enum: - no-store x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - imagesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Image" parameters: - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. /v1/images/{image}: get: tags: - Images summary: GetImage reads one image by its resource name. description: GetImage reads one image by its resource name. operationId: getImage parameters: - name: image in: path description: The image id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Image" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - imagesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Images summary: DeleteImage deletes an image; deleting an already absent image succeeds. description: DeleteImage deletes an image; deleting an already absent image succeeds. operationId: deleteImage parameters: - name: image in: path description: The image id. required: true schema: type: string - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. responses: "204": description: Success. The response carries no body. "409": description: |- The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. content: application/json: schema: $ref: "#/components/schemas/Error" examples: deletion_preparation_incomplete: summary: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. value: code: failedPrecondition message: "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." deletion_content_lease_held: summary: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. value: code: failedPrecondition message: "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. reason: deletion_preparation_incomplete - code: FAILED_PRECONDITION description: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. reason: deletion_content_lease_held security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - imagesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/images/{image}/pull-spec: get: tags: - Images summary: GetImagePullSpec returns short-lived pull material through registry-transfer support. description: |- GetImagePullSpec returns short-lived pull material through registry-transfer support. Action: the pull spec is derived material about the image, not a sub-resource of it. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: getImagePullSpec parameters: - name: image in: path description: The image id. required: true schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ImagePullSpec" headers: Cache-Control: required: true schema: type: string const: no-store "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. headers: Cache-Control: required: true schema: type: string enum: - no-store default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" headers: Cache-Control: required: true schema: type: string enum: - no-store x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - imagesPull x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/mcp-servers/{mcpServer}/authorization: get: tags: - MCP gateways summary: GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write. description: GetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write. operationId: getMcpAuthorization parameters: - name: mcpServer in: path description: The mcpServer id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/McpAuthorization" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - mcpWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/mcp-servers/{mcpServer}/authorization/authorize: post: tags: - MCP gateways summary: AuthorizeMcpServer authorizes credentials for one named upstream. description: |- AuthorizeMcpServer authorizes credentials for one named upstream. Action: authorization runs an interactive grant whose result is not the request body. operationId: authorizeMcpServer parameters: - name: mcpServer in: path description: The mcpServer id. required: true schema: type: string - name: If-Match in: header description: Optional current authorization etag. A supplied stale value answers 412 with failedPrecondition; omission permits create or convergence, including forced reauthorization. schema: type: string title: If-Match description: (OPTIONAL) etag optionally pins the current authorization; a supplied stale value refuses. requestBody: content: application/json: schema: type: object properties: remoteUrl: type: - string - "null" format: uri description: remote_url binds authorization to a concrete upstream URL when supplied. forceReauth: type: boolean description: |- force_reauth starts a fresh flow while existing credentials serve until completion. Repeating a pending flow converges without reminting. title: AuthorizeMcpServerRequest additionalProperties: false description: AuthorizeMcpServerRequest starts or refreshes MCP upstream authorization. required: true responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/McpAuthorization" - not: properties: status: enum: - pending required: - status headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/McpAuthorization" - properties: status: enum: - pending required: - status headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - mcpWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/McpAuthorization" /v1/network-policies: get: tags: - Network policies summary: GetNetworkPolicies returns effective and exact views of the same installed generation. description: GetNetworkPolicies returns effective and exact views of the same installed generation. operationId: getNetworkPoliciesInOwnerScope parameters: - name: acceptedSelectorVersions in: query description: Omitted versions accept only destination.v1; an unsupported representation fails closed. schema: type: array items: type: string minLength: 1 description: "" title: accepted_selector_versions maxItems: 8 uniqueItems: true required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetNetworkPoliciesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - networkPoliciesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/policy-logs: get: tags: - Network policies summary: ListPolicyLogEntries lists observed policy decisions. description: ListPolicyLogEntries lists observed policy decisions. operationId: listPolicyLogEntriesInOwnerScope parameters: - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable field is domain. schema: type: string title: filter required: false - name: since in: query description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. schema: type: string examples: - 2023-01-15T01:30:15.01Z - 2024-12-25T12:00:00Z format: date-time required: false - name: until in: query description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. schema: type: string examples: - 2023-01-15T01:30:15.01Z - 2024-12-25T12:00:00Z format: date-time required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListPolicyLogEntriesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - networkPoliciesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/processes: get: tags: - Processes summary: ListProcesses lists processes in creation order. description: ListProcesses lists processes in creation order. operationId: listProcesses parameters: - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an optional continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable fields are session and state. schema: type: string title: filter required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListProcessesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false post: tags: - Processes summary: CreateProcess starts a durable interactive process and returns its resource name. description: CreateProcess starts a durable interactive process and returns its resource name. operationId: createProcess requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateProcessRequest" required: true responses: "201": description: Success content: application/json: schema: $ref: "#/components/schemas/Process" "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false parameters: - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. /v1/processes/exec: post: tags: - Processes summary: Exec runs one command to completion. description: |- Exec runs one command to completion. A retry after transport failure may run it again. Action at the collection root: it runs a command to completion instead of creating a process a caller can address. operationId: exec requestBody: content: application/json: schema: $ref: "#/components/schemas/ExecRequest" required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ExecResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/processes/{process}: get: tags: - Processes summary: GetProcess reads one process by its endpoint-scoped resource name. description: GetProcess reads one process by its endpoint-scoped resource name. operationId: getProcess parameters: - name: process in: path description: The process id. required: true schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Process" "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/processes/{process}/interact: get: tags: - Processes summary: Interact binds the complete process name from the path to the first Attach frame. description: |- Interact binds the complete process name from the path to the first Attach frame. A conflicting name is INVALID_ARGUMENT before any attach. operationId: interact parameters: - name: process in: path description: The process id. required: true schema: type: string responses: "101": description: "The connection becomes a sandboxes.v1 session: one InteractRequest per inbound text frame and one ProcessOutput per outbound one. Path parameters identify the target; the first attach frame must agree. Refusals after upgrade carry an error frame followed by a close code." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-websocket: subprotocol: sandboxes.v1 firstRequestField: attach resumeRequestField: attach.resumeFrom resumeResponseField: chunk.streamSequence bearerSubprotocolPrefix: sandboxes.bearer.v1. maxBearerTokenBytes: 4096 requestFrame: $ref: "#/components/schemas/InteractRequest" responseFrame: $ref: "#/components/schemas/ProcessOutput" terminalFrame: The last text frame before a close carries the one error body, because a close reason holds at most 123 bytes. errorFrame: $ref: "#/components/schemas/Error" authentication: Use exactly one sandbox-scoped Authorization bearer credential or, when endpoint credentialTransports advertises webSocketSubprotocol, offer sandboxes.bearer.v1. followed by canonical unpadded base64url of that credential alongside sandboxes.v1. The decoded token is limited to 4096 bytes. The server echoes only sandboxes.v1; mixed or duplicate credentials, query credentials and cookie-only authentication are refused. browser: Open a WSS endpoint using its scoped credential. Browsers may send cookies; the server ignores them as authority and permits cross-origin explicit bearer authentication. Browser WebSocket errors do not expose pre-upgrade HTTP status or bodies; only post-upgrade Error frames are typed. No reconnect or input replay is automatic. reconnect: Acquire a fresh scoped credential, open a new connection, and send attach with attach.resumeFrom set to the last received chunk.streamSequence. Resume replays output only; never replay stdin or process creation. preUpgradeStatus: "400": The request has an invalid subprotocol offer, mixed or malformed credentials, an oversized credential, or a query parameter. "401": The scoped credential is missing, invalid or expired. "403": The scoped credential does not grant this endpoint permission. "404": The scoped credential does not address this sandbox endpoint. closeCode: "1000": The service ended the stream, or the caller cancelled it. "1002": The handshake negotiated no subprotocol. "1003": A frame arrived as binary; every frame is text. "1007": A frame was not the public JSON request message. "1008": The service refused with a 4xx error, or the endpoint credential expired. "1009": A frame exceeded the route’s frame limit. "1011": The service failed with a code the front door maps to a 5xx. servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] - sandboxWebSocketBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-request-schema: $ref: "#/components/schemas/InteractRequest" x-sbx-response-schema: $ref: "#/components/schemas/ProcessOutput" /v1/processes/{process}/output: get: tags: - Processes summary: ReadOutput returns one page of retained output after a stream_sequence, the same cursor Interact resumes from, so a REST client can read what a process printed. description: |- ReadOutput returns one page of retained output after a stream_sequence, the same cursor Interact resumes from, so a REST client can read what a process printed. operationId: readOutput parameters: - name: process in: path description: The process id. required: true schema: type: string - name: resumeFrom in: query description: |- resume_from returns output after this stream_sequence; 0 means from the start. Missing output after this point fails with FAILED_PRECONDITION, as for Attach. schema: type: - integer - string title: resume_from format: int64 required: false - name: maxBytes in: query description: |- max_bytes is a soft bound on the page's data: whole chunks only, and the first retained chunk always fits so a caller always advances. 0 means the backend's default page. schema: type: integer title: max_bytes required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ReadOutputResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/processes/{process}/signal: post: tags: - Processes summary: Signal sends one signal to an existing process. description: |- Signal sends one signal to an existing process. Action: a signal is delivered to a running process and leaves no representation to replace. operationId: signal parameters: - name: process in: path description: The process id. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: signal: not: enum: - unspecified description: signal is the signal to send. $ref: "#/components/schemas/ProcessSignal" title: SignalRequest required: - signal additionalProperties: false description: SignalRequest sends one signal. required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/SignalResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" servers: - url: "{endpoint}" variables: endpoint: default: https://sandbox.invalid description: The sandbox API base URL from Sandbox.core.endpoint.uri; preserve its path prefix when appending /v1 routes. HTTP endpoints require a scoped endpoint bearer; direct Unix sockets use socket access control. security: - sandboxBearer: [] x-sbx-serving-surface: sandboxEndpoint x-sbx-plane: data x-sbx-required-permissions: - sandboxesExec x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes: get: tags: - Sandboxes summary: ListSandboxes lists sandboxes in the caller's owner scope. description: ListSandboxes lists sandboxes in the caller's owner scope. operationId: listSandboxes parameters: - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable fields are name, display_name, uid, status and agent. schema: type: string title: filter required: false - name: orderBy in: query description: |- order_by is a single order field with optional direction; the portable fields are created_at and name. schema: type: string title: order_by required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListSandboxesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false post: tags: - Sandboxes summary: CreateSandbox admits a sandbox. description: |- CreateSandbox admits a sandbox. Unknown fields at any level are rejected before replay lookup, reservation, policy binding, or workload effects. operationId: createSandbox requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateSandboxRequest" required: true responses: "201": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - not: properties: core: properties: status: enum: - creating - starting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - properties: core: properties: status: enum: - creating - starting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). Kit admission was refused; an available settled report describes the rejected fields. The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: Kit admission was refused; an available settled report describes the rejected fields. detailType: docker.sandboxes.v1.KitFieldOutcomeReport - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesCreate x-sbx-conditional-permissions: - permission: mcpWrite requestFieldPresent: mcp x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Sandbox" parameters: - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. x-sbx-error-details: KitFieldOutcomeReport: $ref: "#/components/schemas/KitFieldOutcomeReport" /v1/sandboxes/{sandbox}: get: tags: - Sandboxes summary: GetSandbox reads one sandbox by its resource name. description: GetSandbox reads one sandbox by its resource name. operationId: getSandbox parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Sandbox" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Sandboxes summary: DeleteSandbox returns the deleting resource while work remains, or an empty message when absent. description: DeleteSandbox returns the deleting resource while work remains, or an empty message when absent. operationId: deleteSandbox parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. - name: force in: query description: force requests deletion even when the backend would otherwise refuse the state. schema: type: boolean title: force required: false responses: "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - properties: core: properties: status: enum: - deleting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "204": description: Success. The response carries no body. "409": description: The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesDelete x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Sandbox" patch: tags: - Sandboxes summary: UpdateSandbox changes only the display label under the observed etag. description: |- UpdateSandbox changes only the display label under the observed etag. Its resource name, backing identity and child addresses remain unchanged. operationId: updateSandbox parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. required: true schema: type: string title: Idempotency-Key minLength: 1 description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. requestBody: content: application/json: schema: type: object properties: displayName: type: - string - "null" maxLength: 64 minLength: 1 pattern: ^[a-zA-Z0-9_-]+$ description: display_name must be present and retains the existing scoped label rules. title: UpdateSandboxRequest required: - displayName additionalProperties: false description: UpdateSandboxRequest changes only the display label under the observed etag. required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Sandbox" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesRename x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/endpoint-credentials: post: tags: - Sandboxes summary: CreateEndpointCredential grants short-lived access to one sandbox endpoint. description: |- CreateEndpointCredential grants short-lived access to one sandbox endpoint. Issuance checks current authority and never stores a token in the replay ledger. operationId: createEndpointCredential parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: permissions: type: array items: $ref: "#/components/schemas/Permission" enum: - sandboxesExec - sandboxesFilesRead - sandboxesFilesWrite minItems: 1 uniqueItems: true description: "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite." ttl: description: ttl defaults to five minutes; supplied durations are clamped to one second through five minutes. $ref: "#/components/schemas/Duration" title: CreateEndpointCredentialRequest required: - permissions additionalProperties: false description: CreateEndpointCredentialRequest requests only endpoint permissions the caller holds. required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/EndpointCredential" headers: Cache-Control: required: true schema: type: string const: no-store default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" headers: Cache-Control: required: true schema: type: string enum: - no-store security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesCredential x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/mcp-gateway: get: tags: - MCP gateways summary: GetMcpGateway reads gateway state for the sandbox. description: GetMcpGateway reads gateway state for the sandbox. operationId: getMcpGateway parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/McpGateway" "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - mcpRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/mcp-gateway/servers: post: tags: - MCP gateways summary: AddMcpGatewayServer adds one server to an existing ready gateway. description: AddMcpGatewayServer adds one server to an existing ready gateway. operationId: addMcpGatewayServer parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: server: type: string minLength: 1 description: |- server is the external configured key; a supplied registration must define this same key. A mismatch refuses FAILED_PRECONDITION before changing the gateway. title: AddMcpGatewayServerRequest required: - server additionalProperties: false description: AddMcpGatewayServerRequest adds one server to an existing ready gateway. required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/AddMcpGatewayServerResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - mcpWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/network-policies: get: tags: - Network policies summary: GetNetworkPolicies returns effective and exact views of the same installed generation. description: GetNetworkPolicies returns effective and exact views of the same installed generation. operationId: getNetworkPolicies parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: acceptedSelectorVersions in: query description: Omitted versions accept only destination.v1; an unsupported representation fails closed. schema: type: array items: type: string minLength: 1 description: "" title: accepted_selector_versions maxItems: 8 uniqueItems: true required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/GetNetworkPoliciesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - networkPoliciesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/policy-logs: get: tags: - Network policies summary: ListPolicyLogEntries lists observed policy decisions. description: ListPolicyLogEntries lists observed policy decisions. operationId: listPolicyLogEntries parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable field is domain. schema: type: string title: filter required: false - name: since in: query description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. schema: type: string examples: - 2023-01-15T01:30:15.01Z - 2024-12-25T12:00:00Z format: date-time required: false - name: until in: query description: An RFC 3339 timestamp, for example 2026-01-01T12:00:00Z. Fractional seconds may contain up to nine digits. The supported range is 0001-01-01T00:00:00Z through 9999-12-31T23:59:59.999999999Z. schema: type: string examples: - 2023-01-15T01:30:15.01Z - 2024-12-25T12:00:00Z format: date-time required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListPolicyLogEntriesResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - networkPoliciesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/ports: get: tags: - Sandboxes summary: ListPorts lists currently published ports for one sandbox. description: ListPorts lists currently published ports for one sandbox. operationId: listPorts parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListPortsResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false post: tags: - Sandboxes summary: CreatePort makes one sandbox port reachable outside the sandbox. description: CreatePort makes one sandbox port reachable outside the sandbox. operationId: createPort parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. requestBody: content: application/json: schema: type: object properties: port: description: port is the requested publication. $ref: "#/components/schemas/CreatePortRequestPortInput" title: CreatePortRequest required: - port additionalProperties: false description: CreatePortRequest publishes one sandbox port. required: true responses: "201": description: Success content: application/json: schema: $ref: "#/components/schemas/Port" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The sandbox already publishes this port number. The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: alreadyExists: summary: The sandbox already publishes this port number. value: code: alreadyExists message: The sandbox already publishes this port number. failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: ALREADY_EXISTS description: The sandbox already publishes this port number. - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesPorts x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/ports/{port}: get: tags: - Sandboxes summary: GetPort reads one published port by its resource name. description: GetPort reads one published port by its resource name. operationId: getPort parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: port in: path description: The port id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Port" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: No publication exists for this port resource name. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: No publication exists for this port resource name. value: code: notFound message: No publication exists for this port resource name. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: No publication exists for this port resource name. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Sandboxes summary: DeletePort withdraws one published port. description: |- DeletePort withdraws one published port. A name that is not published succeeds, so a retried delete reports the same result as the first. operationId: deletePort parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: port in: path description: The port id. required: true schema: type: string - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: etag identifies the publication version the caller intends to delete. responses: "204": description: Success. The response carries no body. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesPorts x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/renew-timeout: post: tags: - Sandboxes summary: RenewSandboxTimeout sets a TTL when timeout renewal is supported. description: |- RenewSandboxTimeout sets a TTL when timeout renewal is supported. The TTL starts at acceptance, and the response returns the new expires_at with the sandbox's timeout configuration preserved. Action: the TTL restarts at acceptance, so the result is not a value the caller could PUT. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: renewSandboxTimeout parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: timeout: description: timeout is the new TTL relative to server acceptance time. $ref: "#/components/schemas/Duration" title: RenewSandboxTimeoutRequest required: - timeout additionalProperties: false description: RenewSandboxTimeoutRequest sets a new remaining TTL. required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Sandbox" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesLifecycle x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/snapshots: post: tags: - Snapshots summary: CreateSnapshot checkpoints a running sandbox; a stopped source is rejected. description: CreateSnapshot checkpoints a running sandbox; a stopped source is rejected. operationId: createSnapshot parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. requestBody: content: application/json: schema: type: object properties: displayName: type: string not: type: string enum: - . - .. minLength: 1 pattern: ^[^/]+$ description: display_name is a scoped label; the backend assigns the immutable resource ID. description: type: string description: description is caller-supplied text. captureMode: description: |- capture_mode selects disk-only or memory plus disk capture. A value this enum does not define is rejected, never coerced to a capture. $ref: "#/components/schemas/CaptureMode" title: CreateSnapshotRequest required: - displayName additionalProperties: false description: CreateSnapshotRequest captures one running sandbox. required: true responses: "201": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/Snapshot" - not: properties: status: enum: - creating required: - status headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Snapshot" - properties: status: enum: - creating required: - status headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - snapshotsWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Snapshot" /v1/sandboxes/{sandbox}/ssh-certificates: post: tags: - Sandboxes summary: IssueSSHCert signs a caller-held public key for sandbox SSH access. description: |- IssueSSHCert signs a caller-held public key for sandbox SSH access. A create: each call mints one certificate under the sandbox's certificate collection. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: issueSSHCert parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string requestBody: content: application/json: schema: type: object properties: publicKey: type: string minLength: 1 description: public_key is the caller-held SSH public key. ttl: description: ttl is the requested certificate lifetime. $ref: "#/components/schemas/Duration" title: IssueSSHCertRequest required: - publicKey additionalProperties: false description: IssueSSHCertRequest asks the backend to sign a caller-held public key. required: true responses: "201": description: Success content: application/json: schema: $ref: "#/components/schemas/IssueSSHCertResponse" headers: Cache-Control: required: true schema: type: string const: no-store "409": description: Creation conflicts with an existing resource (ALREADY_EXISTS). content: application/json: schema: $ref: "#/components/schemas/Error" headers: Cache-Control: required: true schema: type: string enum: - no-store "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. headers: Cache-Control: required: true schema: type: string enum: - no-store default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" headers: Cache-Control: required: true schema: type: string enum: - no-store x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesSsh x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/sandboxes/{sandbox}/start: post: tags: - Sandboxes summary: StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. description: |- StartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. Action: a lifecycle transition is not a representation a caller can PUT. operationId: startSandbox parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. requestBody: content: application/json: schema: type: object properties: {} title: StartSandboxRequest additionalProperties: false description: StartSandboxRequest starts or resumes a sandbox. required: false responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - not: properties: core: properties: status: enum: - starting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - properties: core: properties: status: enum: - starting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesLifecycle x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Sandbox" /v1/sandboxes/{sandbox}/stop: post: tags: - Sandboxes summary: StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it. description: |- StopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it. Action: a lifecycle transition is not a representation a caller can PUT. operationId: stopSandbox parameters: - name: sandbox in: path description: The sandbox id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. requestBody: content: application/json: schema: type: object properties: {} title: StopSandboxRequest additionalProperties: false description: StopSandboxRequest stops a sandbox; a backend advertising memory preservation hibernates it. required: false responses: "200": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - not: properties: core: properties: status: enum: - stopping required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - properties: core: properties: status: enum: - stopping required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - sandboxesLifecycle x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Sandbox" /v1/secrets: get: tags: - Secrets summary: ListSecrets lists secret metadata in the caller's owner scope. description: |- ListSecrets lists secret metadata in the caller's owner scope. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: listSecrets parameters: - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable fields are name, display_name and uid. schema: type: string title: filter required: false - name: orderBy in: query description: |- order_by is a single order field with optional direction; the portable fields are created_at and name. schema: type: string title: order_by required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListSecretsResponse" "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - secretsRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false post: tags: - Secrets summary: CreateSecret stores new secret material. description: |- CreateSecret stores new secret material. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: createSecret requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateSecretRequest" required: true responses: "201": description: Success content: application/json: schema: $ref: "#/components/schemas/Secret" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - secretsWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false parameters: - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. /v1/secrets/{secret}: get: tags: - Secrets summary: GetSecret reads one secret's metadata; material is never returned. description: |- GetSecret reads one secret's metadata; material is never returned. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: getSecret parameters: - name: secret in: path description: The secret id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Secret" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - secretsRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false put: tags: - Secrets summary: UpdateSecret replaces secret metadata and material. description: |- UpdateSecret replaces secret metadata and material. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: updateSecret parameters: - name: secret in: path description: The secret id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateSecretBody" required: true responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Secret" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - secretsWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Secrets summary: DeleteSecret deletes a secret; deleting an already absent secret succeeds. description: |- DeleteSecret deletes a secret; deleting an already absent secret succeeds. Its response carries the credential fence receipt, so it answers 200 with a body rather than the 204 an empty-response delete declares. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: deleteSecret parameters: - name: secret in: path description: The secret id. required: true schema: type: string - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/DeleteSecretResponse" "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - secretsWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/snapshots: get: tags: - Snapshots summary: ListSnapshots lists snapshots in the caller's owner scope. description: ListSnapshots lists snapshots in the caller's owner scope. operationId: listSnapshots parameters: - name: sandbox in: query description: (OPTIONAL) sandbox is the complete resource name, in the form sandboxes/{sandbox}. required: false schema: type: string title: sandbox pattern: ^(?:sandboxes/[^/]+)?$ - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable fields are name, display_name and uid. schema: type: string title: filter required: false - name: orderBy in: query description: |- order_by is a single order field with optional direction; the portable fields are created_at and name. schema: type: string title: order_by required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListSnapshotsResponse" default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - snapshotsRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/snapshots/{snapshot}: get: tags: - Snapshots summary: GetSnapshot reads one snapshot by its resource name. description: GetSnapshot reads one snapshot by its resource name. operationId: getSnapshot parameters: - name: snapshot in: path description: The snapshot id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Snapshot" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - snapshotsRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Snapshots summary: DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds. description: DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds. operationId: deleteSnapshot parameters: - name: snapshot in: path description: The snapshot id. required: true schema: type: string - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. responses: "204": description: Success. The response carries no body. "409": description: |- The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. content: application/json: schema: $ref: "#/components/schemas/Error" examples: deletion_preparation_incomplete: summary: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. value: code: failedPrecondition message: "deletion_preparation_incomplete: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state." deletion_content_lease_held: summary: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. value: code: failedPrecondition message: "deletion_content_lease_held: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held." "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The target's preparation, capture, or import has not finished; deletion is refused until it settles to a terminal state. reason: deletion_preparation_incomplete - code: FAILED_PRECONDITION description: An admitted consumer or live resource holds a content lease on the target; deletion is refused while any lease remains held. reason: deletion_content_lease_held security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - snapshotsWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false /v1/snapshots/{snapshot}/restore: post: tags: - Snapshots summary: RestoreSnapshot forks a new sandbox from a snapshot. description: |- RestoreSnapshot forks a new sandbox from a snapshot. Action: a restore creates a sandbox, so the snapshot in the path is the source and not the created resource. operationId: restoreSnapshot parameters: - name: snapshot in: path description: The snapshot id. required: true schema: type: string - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. requestBody: content: application/json: schema: type: object properties: displayName: type: string maxLength: 64 pattern: ^[a-zA-Z0-9_-]*$ description: (OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID. title: RestoreSnapshotRequest additionalProperties: false description: RestoreSnapshotRequest creates a new sandbox from one snapshot. required: true responses: "201": description: Success content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - not: properties: core: properties: status: enum: - creating - starting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "202": description: Accepted. The resource is still progressing; read it or follow its events until completion. content: application/json: schema: allOf: - $ref: "#/components/schemas/Sandbox" - properties: core: properties: status: enum: - creating - starting required: - status required: - core headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - snapshotsRead - sandboxesCreate x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false x-sbx-resource-response: $ref: "#/components/schemas/Sandbox" /v1/volumes: get: tags: - Volumes summary: ListVolumes lists volumes in the caller's owner scope. description: |- ListVolumes lists volumes in the caller's owner scope. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: listVolumes parameters: - name: pageSize in: query description: |- page_size is an optional page size. Omitted or zero uses the backend default. Unless the operation states otherwise, page-size limits and handling of larger requests are backend-specific; use the backend support guide. Continue with nextPageToken until it is empty. schema: type: integer title: page_size required: false - name: pageToken in: query description: page_token is an opaque continuation token. schema: type: string title: page_token required: false - name: filter in: query description: |- filter is comma-separated exact-match field=value terms; the portable fields are name, display_name and uid. schema: type: string title: filter required: false - name: orderBy in: query description: |- order_by is a single order field with optional direction; the portable fields are created_at and name. schema: type: string title: order_by required: false responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/ListVolumesResponse" "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - volumesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false post: tags: - Volumes summary: CreateVolume creates a persistent volume. description: |- CreateVolume creates a persistent volume. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: createVolume requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateVolumeRequest" required: true responses: "201": description: Success content: application/json: schema: $ref: "#/components/schemas/Volume" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "409": description: |- Creation conflicts with an existing resource (ALREADY_EXISTS). The Idempotency-Key was already used with a different payload. content: application/json: schema: $ref: "#/components/schemas/Error" examples: failedPrecondition: summary: The Idempotency-Key was already used with a different payload. value: code: failedPrecondition message: The Idempotency-Key was already used with a different payload. "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. - code: FAILED_PRECONDITION description: The Idempotency-Key was already used with a different payload. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - volumesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false parameters: - name: Idempotency-Key in: header description: Replay key. Reusing it with a different payload fails with failedPrecondition; accepted keys are retained for at least 24 hours. schema: type: string title: Idempotency-Key description: Idempotency key. A replay returns the first result; the same key with a different payload fails with FAILED_PRECONDITION; retained at least 24 hours. /v1/volumes/{volume}: get: tags: - Volumes summary: GetVolume reads one volume by its resource name. description: |- GetVolume reads one volume by its resource name. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: getVolume parameters: - name: volume in: path description: The volume id. required: true schema: type: string - name: If-None-Match in: header description: A quoted entity-tag or comma-separated list, compared weakly with the current resource etag. A match, including a weak form or wildcard *, answers 304 without a body after authorization. Malformed input is treated as no match. schema: type: string responses: "200": description: Success content: application/json: schema: $ref: "#/components/schemas/Volume" headers: ETag: description: The etag of the resource this response carries, which the next mutation of it sends as If-Match. schema: type: string "304": description: The resource's etag equals the If-None-Match value, so this response carries no body. "404": description: The target is absent or not visible within the caller's scope. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: The target is absent or not visible within the caller's scope. value: code: notFound message: The target is absent or not visible within the caller's scope. "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: NOT_FOUND description: The target is absent or not visible within the caller's scope. - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - volumesRead x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false delete: tags: - Volumes summary: DeleteVolume deletes a volume; deleting an already absent volume succeeds. description: |- DeleteVolume deletes a volume; deleting an already absent volume succeeds. Returns unimplemented when this operation is unavailable. Support does not grant permission. operationId: deleteVolume parameters: - name: volume in: path description: The volume id. required: true schema: type: string - name: If-Match in: header description: "The complete quoted strong entity-tag observed on the resource, including its quotes. Every mutation of an existing resource requires it: an absent value answers 428 and a stale one 412, each carrying failedPrecondition in the body." required: true schema: type: string title: If-Match description: |- etag is the required precondition, the value the target's last read returned. An absent one refuses etag_required and a stale one etag_mismatch. responses: "204": description: Success. The response carries no body. "412": description: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_mismatch: summary: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value. value: code: failedPrecondition message: "etag_mismatch: The precondition is not the resource's current etag. The body carries failedPrecondition naming etag_mismatch and an EtagMismatch detail with the current value." details: - "@type": type.googleapis.com/docker.sandboxes.v1.EtagMismatch currentEtag: v2 "428": description: No precondition was sent. The body carries failedPrecondition naming etag_required. content: application/json: schema: $ref: "#/components/schemas/Error" examples: etag_required: summary: No precondition was sent. The body carries failedPrecondition naming etag_required. value: code: failedPrecondition message: "etag_required: No precondition was sent. The body carries failedPrecondition naming etag_required." "501": description: This operation is not available on this service. content: application/json: schema: $ref: "#/components/schemas/Error" examples: unimplemented: summary: This operation is not available on this service. value: code: unimplemented message: This operation is not available on this service. default: description: The structured Error body identifies the failure with a stable code and optional typed details. content: application/json: schema: $ref: "#/components/schemas/Error" x-sbx-error-responses: - code: UNIMPLEMENTED description: This operation is not available on this service. security: - bearer: [] x-sbx-serving-surface: management x-sbx-plane: control x-sbx-required-permissions: - volumesWrite x-sbx-conditional-permissions: [] x-sbx-authenticated-only: false components: schemas: Error: type: object title: Error required: - code description: An HTTP refusal, resource failure, or terminal stream error. Clients preserve unknown codes and structured details. properties: code: anyOf: - $ref: "#/components/schemas/ErrorCode" - type: string message: type: string details: type: array items: $ref: "#/components/schemas/ErrorDetail" examples: - code: notFound details: [] message: sandbox not found ErrorCode: type: string enum: - canceled - unknown - invalidArgument - deadlineExceeded - notFound - alreadyExists - permissionDenied - resourceExhausted - failedPrecondition - aborted - outOfRange - unimplemented - internal - unavailable - dataLoss - unauthenticated description: Known public failure categories. Error.code also accepts future strings. ErrorDetail: oneOf: - $ref: "#/components/schemas/BadRequestErrorDetail" - $ref: "#/components/schemas/DebugInfoErrorDetail" - $ref: "#/components/schemas/ErrorInfoErrorDetail" - $ref: "#/components/schemas/HelpErrorDetail" - $ref: "#/components/schemas/LocalizedMessageErrorDetail" - $ref: "#/components/schemas/PreconditionFailureErrorDetail" - $ref: "#/components/schemas/QuotaFailureErrorDetail" - $ref: "#/components/schemas/RequestInfoErrorDetail" - $ref: "#/components/schemas/ResourceInfoErrorDetail" - $ref: "#/components/schemas/RetryInfoErrorDetail" - $ref: "#/components/schemas/ValidationViolationsErrorDetail" - $ref: "#/components/schemas/EtagMismatchErrorDetail" - $ref: "#/components/schemas/KitFieldOutcomeReportErrorDetail" - $ref: "#/components/schemas/McpConfigurationReportErrorDetail" - $ref: "#/components/schemas/UnknownErrorDetail" discriminator: propertyName: "@type" mapping: type.googleapis.com/google.rpc.BadRequest: "#/components/schemas/BadRequestErrorDetail" type.googleapis.com/google.rpc.DebugInfo: "#/components/schemas/DebugInfoErrorDetail" type.googleapis.com/google.rpc.ErrorInfo: "#/components/schemas/ErrorInfoErrorDetail" type.googleapis.com/google.rpc.Help: "#/components/schemas/HelpErrorDetail" type.googleapis.com/google.rpc.LocalizedMessage: "#/components/schemas/LocalizedMessageErrorDetail" type.googleapis.com/google.rpc.PreconditionFailure: "#/components/schemas/PreconditionFailureErrorDetail" type.googleapis.com/google.rpc.QuotaFailure: "#/components/schemas/QuotaFailureErrorDetail" type.googleapis.com/google.rpc.RequestInfo: "#/components/schemas/RequestInfoErrorDetail" type.googleapis.com/google.rpc.ResourceInfo: "#/components/schemas/ResourceInfoErrorDetail" type.googleapis.com/google.rpc.RetryInfo: "#/components/schemas/RetryInfoErrorDetail" type.googleapis.com/buf.validate.Violations: "#/components/schemas/ValidationViolationsErrorDetail" type.googleapis.com/docker.sandboxes.v1.EtagMismatch: "#/components/schemas/EtagMismatchErrorDetail" type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport: "#/components/schemas/KitFieldOutcomeReportErrorDetail" type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport: "#/components/schemas/McpConfigurationReportErrorDetail" UnknownErrorDetail: type: object required: - "@type" additionalProperties: true description: A structured error detail identified by @type. Its decoded JSON fields appear beside the type URL. properties: "@type": type: string not: enum: - type.googleapis.com/google.rpc.BadRequest - type.googleapis.com/google.rpc.DebugInfo - type.googleapis.com/google.rpc.ErrorInfo - type.googleapis.com/google.rpc.Help - type.googleapis.com/google.rpc.LocalizedMessage - type.googleapis.com/google.rpc.PreconditionFailure - type.googleapis.com/google.rpc.QuotaFailure - type.googleapis.com/google.rpc.RequestInfo - type.googleapis.com/google.rpc.ResourceInfo - type.googleapis.com/google.rpc.RetryInfo - type.googleapis.com/buf.validate.Violations - type.googleapis.com/docker.sandboxes.v1.EtagMismatch - type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport - type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport ValidationFieldPath: type: object properties: elements: type: array items: $ref: "#/components/schemas/ValidationFieldPathElement" description: "`elements` contains each element of the path, starting from the root and recursing downward." title: FieldPath description: A path to a field, including any parent fields. ValidationFieldPathElement: type: object allOf: - properties: fieldNumber: type: - integer - "null" format: int32 description: "`field_number` is the field number this path element refers to." fieldName: type: - string - "null" description: |- `field_name` contains the field name this path element refers to. This can be used to display a human-readable path even if the field number is unknown. fieldType: oneOf: - $ref: "#/components/schemas/ValidationFieldType" - type: "null" description: The type of the field that failed validation. keyType: oneOf: - $ref: "#/components/schemas/ValidationFieldType" - type: "null" description: |- `key_type` specifies the map key type of this field. This value is useful when traversing unknown fields through wire data: specifically, it allows handling the differences between different integer encodings. valueType: oneOf: - $ref: "#/components/schemas/ValidationFieldType" - type: "null" description: |- `value_type` specifies map value type of this field. This is useful if you want to display a value inside unknown fields through wire data. - oneOf: - type: object properties: boolKey: type: boolean description: "`bool_key` specifies a map key of type bool." title: bool_key required: - boolKey - type: object properties: index: type: - integer - string format: int64 description: "`index` specifies a 0-based index into a repeated field." title: index required: - index - type: object properties: intKey: type: - integer - string format: int64 description: "`int_key` specifies a map key of type int32, int64, sint32, sint64, sfixed32 or sfixed64." title: int_key required: - intKey - type: object properties: stringKey: type: string description: "`string_key` specifies a map key of type string." title: string_key required: - stringKey - type: object properties: uintKey: type: - integer - string format: int64 description: "`uint_key` specifies a map key of type uint32, uint64, fixed32 or fixed64." title: uint_key required: - uintKey title: FieldPathElement description: One field in a validation path. For a map or list, the subscript identifies the selected element. ValidationViolation: type: object properties: field: oneOf: - $ref: "#/components/schemas/ValidationFieldPath" - type: "null" description: The field that failed validation, including its parent fields. rule: oneOf: - $ref: "#/components/schemas/ValidationFieldPath" - type: "null" description: The validation rule that failed. ruleId: type: - string - "null" description: |- `rule_id` is the unique identifier of the `Rule` that was not fulfilled. This is the same `id` that was specified in the `Rule` message, allowing easy tracing of which rule was violated. message: type: - string - "null" description: |- `message` is a human-readable error message that describes the nature of the violation. This can be the default error message from the violated `Rule`, or it can be a custom message that gives more context about the violation. forKey: type: - boolean - "null" description: "`for_key` indicates whether the violation was caused by a map key, rather than a value." title: Violation description: A validation failure, with the affected field, rule, and a human-readable message. ValidationViolations: type: object properties: violations: type: array items: $ref: "#/components/schemas/ValidationViolation" description: "`violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected." title: Violations description: The validation failures returned for a request. ValidationViolationsErrorDetail: type: object properties: violations: type: array items: $ref: "#/components/schemas/ValidationViolation" description: "`violations` is a repeated field that contains all the `Violation` messages corresponding to the violations detected." "@type": type: string const: type.googleapis.com/buf.validate.Violations title: ViolationsErrorDetail description: The validation failures returned for a request. required: - "@type" AppliedKit: type: object properties: ref: type: string description: ref is the kit reference supplied or resolved by the backend. kind: type: string enum: - sandbox - mixin description: kind is normalized to "sandbox" or "mixin". appliedAt: description: applied_at is when the kit became active. $ref: "#/components/schemas/Timestamp" digest: type: string description: digest identifies the exact applied content. title: AppliedKit required: - kind description: AppliedKit records kit content that was applied to a sandbox. EndpointAuthentication: type: object properties: scheme: not: enum: - unspecified $ref: "#/components/schemas/EndpointAuthenticationScheme" defaultTtl: description: default_ttl and max_ttl describe CreateEndpointCredential's provider policy. $ref: "#/components/schemas/Duration" maxTtl: $ref: "#/components/schemas/Duration" credentialTransports: type: array items: $ref: "#/components/schemas/EndpointCredentialTransport" uniqueItems: true description: Omission retains Authorization-header clients; browsers require an explicit subprotocol offer. title: EndpointAuthentication required: - scheme description: |- EndpointAuthentication describes credential issuance without publishing a token. local sockets cannot advertise bearer credential transports scoped bearer discovery states the five-minute credential lifetime; local sockets carry no token lifetime dependentSchemas: scheme: allOf: - oneOf: - required: - defaultTtl - maxTtl properties: scheme: const: scopedBearer defaultTtl: pattern: ^300([.]0{1,9})?s$ maxTtl: pattern: ^300([.]0{1,9})?s$ - properties: scheme: const: localSocket not: anyOf: - required: - defaultTtl - required: - maxTtl credentialTransports: allOf: - if: properties: scheme: const: localSocket then: properties: credentialTransports: maxItems: 0 EndpointAuthenticationScheme: type: string title: EndpointAuthenticationScheme enum: - unspecified - scopedBearer - localSocket description: |- Values: unspecified scopedBearer localSocket EndpointCredentialTransport: type: string title: EndpointCredentialTransport enum: - unspecified - authorizationHeader - webSocketSubprotocol description: |- Values: unspecified authorizationHeader webSocketSubprotocol KitRef: type: object properties: ref: type: string minLength: 1 description: ref names the kit source. kind: type: string enum: - "" - sandbox - mixin description: kind is "sandbox", "mixin", or empty to defer to the kit's own manifest. title: KitRef required: - ref additionalProperties: false description: KitRef names a kit to apply. Permission: type: string title: Permission enum: - unspecified - sandboxesRead - sandboxesCreate - sandboxesExec - sandboxesFilesRead - sandboxesFilesWrite - imagesPull - secretsWrite - sandboxesDelete - sandboxesLifecycle - sandboxesKits - sandboxesPorts - sandboxesCredential - sandboxesSsh - imagesRead - imagesWrite - secretsRead - networkPoliciesRead - volumesRead - volumesWrite - snapshotsRead - snapshotsWrite - mcpRead - mcpWrite - credentialsExchange - sandboxesRename - secretsResolve - operator description: The actions a credential is allowed to perform. Each operation declares its required permissions; service support does not grant permission. Platform: type: object properties: os: type: string description: os is the operating system, for example "linux". architecture: type: string description: architecture is the CPU architecture, for example "amd64" or "arm64". title: Platform additionalProperties: false description: Platform is the OCI platform tuple. Protocol: type: string title: Protocol enum: - unspecified - tcp - udp - tcp4 - tcp6 - udp4 - udp6 description: |- Protocol names the transport protocol for a published port. Values: unspecified: unspecified means the backend default, TCP. tcp: tcp publishes TCP traffic. udp: udp publishes UDP traffic. tcp4: tcp4 publishes IPv4 TCP traffic. tcp6: tcp6 publishes IPv6 TCP traffic. udp4: udp4 publishes IPv4 UDP traffic. udp6: udp6 publishes IPv6 UDP traffic. PublishedPort: type: object properties: hostIp: type: string description: host_ip is the local host bind address when relevant. hostPort: type: integer description: host_port is the local host port when relevant. sandboxPort: type: integer description: sandbox_port is the port inside the sandbox. protocol: description: protocol is the published protocol. $ref: "#/components/schemas/Protocol" url: type: string description: url is the required externally reachable address, including host-local addresses. title: PublishedPort description: PublishedPort reports external reachability for one sandbox port. Resources: type: object properties: cpus: type: - integer - "null" description: cpus is present only when the caller or backend chooses a CPU count. memoryMib: type: - integer - string - "null" format: int64 description: memory_mib is present only when the caller or backend chooses memory. title: Resources additionalProperties: false description: Resources describes sandbox CPU and memory allocation. SandboxCore: type: object allOf: - properties: agent: type: string description: agent is the named agent profile, empty for raw image/start-command sandboxes. status: not: enum: - unspecified description: status is the coarse lifecycle state. readOnly: true $ref: "#/components/schemas/SandboxStatus" resources: description: resources are the sandbox resources. $ref: "#/components/schemas/Resources" platform: description: platform is the canonical placed platform. $ref: "#/components/schemas/Platform" environment: type: object additionalProperties: type: string title: value description: environment is non-secret environment metadata. ports: type: array items: $ref: "#/components/schemas/PublishedPort" description: ports are the currently published ports. appliedKits: type: array items: $ref: "#/components/schemas/AppliedKit" description: applied_kits records kits active in the sandbox. createdAt: description: created_at is the creation time. $ref: "#/components/schemas/Timestamp" endpoint: description: endpoint is where process and file services are served for this sandbox. $ref: "#/components/schemas/SandboxEndpoint" origin: type: string description: origin is set by merged views to identify the backend that owns this sandbox. labels: type: object additionalProperties: type: string title: value description: labels are non-secret caller-assigned key/value metadata. etag: type: string minLength: 1 pattern: ^"[^"\x00-\x20\x7f]*"$ description: |- etag identifies the observed version of this resource. It is opaque and strong, changes on every visible change, and is what a mutation sends as its precondition. readOnly: true - properties: image: type: string pattern: ^images/[^/]+$ description: image is the managed Image resource name. imageRef: type: string description: image_ref is an external OCI reference, with the existing backend validation. dependentSchemas: image: not: anyOf: - required: - imageRef imageRef: not: anyOf: - required: - image title: SandboxCore required: - status - createdAt - etag description: SandboxCore is the backend-neutral sandbox view. At most one of image, imageRef is set. SandboxEndpoint: type: object properties: uri: type: string description: uri is the endpoint API base; preserve its path prefix when appending /v1 routes. protocol: description: protocol identifies the endpoint transport. $ref: "#/components/schemas/SandboxEndpointProtocol" credentialAudience: type: string description: credential_audience is server-controlled and required for network endpoints. sandbox: type: string pattern: ^sandboxes/[^/]+$ description: sandbox names the immutable sandbox incarnation served by this endpoint. sandboxUid: type: - string minLength: 1 readOnly: true apiVersion: type: string description: api_version identifies the /v1 endpoint contract before the client connects. const: v1 capabilities: type: array items: type: string pattern: ^[a-z][A-Za-z0-9]*$ minItems: 1 uniqueItems: true description: capabilities lists supported public operation IDs, independently of caller grants. authentication: $ref: "#/components/schemas/EndpointAuthentication" title: SandboxEndpoint required: - sandbox - sandboxUid - apiVersion - capabilities - authentication description: |- SandboxEndpoint tells a client where sandbox endpoint services are served. network endpoints require scoped credentials; Unix sockets use actual socket access controls sandbox must contain the endpoint's immutable sandbox UID dependentSchemas: authentication: allOf: - required: - protocol oneOf: - required: - credentialAudience properties: protocol: const: http credentialAudience: minLength: 1 authentication: properties: scheme: const: scopedBearer - properties: protocol: const: unixSocket credentialAudience: const: "" authentication: properties: scheme: const: localSocket SandboxEndpointProtocol: type: string title: SandboxEndpointProtocol enum: - unspecified - http - unixSocket description: |- SandboxEndpointProtocol identifies the transport used by a sandbox endpoint. Values: unspecified: unspecified is not a concrete endpoint protocol. http: http is the REST API over HTTP. unixSocket: unixSocket is a local unix socket. SandboxStatus: type: string title: SandboxStatus enum: - unspecified - creating - starting - running - stopping - stopped - failed - deleting - degraded description: |- SandboxStatus is the backend-neutral lifecycle state. Values: unspecified: unspecified is never a concrete known state. creating: creating means provisioning has not completed. starting: starting means a stopped sandbox is starting or resuming. running: running means the sandbox is running. stopping: stopping means the sandbox is stopping or hibernating. stopped: stopped means the sandbox is not running and may be started. failed: failed means the sandbox reached an unrecoverable failure. deleting: deleting means deletion is accepted; reads continue until removal. degraded: degraded means runtime contact is lost; recovery or failure may follow. EffectiveCoreLifecycle: type: object properties: stopMemoryOutcome: not: enum: - unspecified description: stop_memory_outcome is the selected stop/start guarantee for this sandbox. $ref: "#/components/schemas/StopMemoryOutcome" canCaptureMemory: type: boolean description: can_capture_memory is this sandbox's ALL snapshot support, independently set. autoResume: type: - boolean - "null" description: |- auto_resume is the configured authenticated auto-resume setting; absent means unknown. Snapshot readback preserves the capture-time value, not current support or a resume guarantee. title: EffectiveCoreLifecycle required: - stopMemoryOutcome description: EffectiveCoreLifecycle is persisted at admission and cannot silently degrade. EffectiveFeatures: type: object properties: lifecycle: description: lifecycle is required even when no optional feature is selected. $ref: "#/components/schemas/EffectiveCoreLifecycle" outputRetention: description: output_retention is the persisted per-process reconnect guarantee. $ref: "#/components/schemas/OutputRetention" managedVolumes: description: managed_volumes records stable volume identities and concrete attachment modes. $ref: "#/components/schemas/EffectiveManagedVolumes" timeouts: description: timeouts records frozen defaults and the currently armed deadline, if any. $ref: "#/components/schemas/EffectiveTimeouts" title: EffectiveFeatures required: - lifecycle - outputRetention description: EffectiveFeatures is emitted only through the composition representation. FeatureOptions: type: object properties: managedVolumes: description: managed_volumes selects persistent resources and guest targets. $ref: "#/components/schemas/ManagedVolumeOptions" timeouts: description: timeouts enables an explicit deadline; omission enables none. $ref: "#/components/schemas/TimeoutOptions" storedSecrets: description: stored_secrets selects authorized stored references, never raw material. $ref: "#/components/schemas/StoredSecretOptions" title: FeatureOptions additionalProperties: false description: FeatureOptions carries typed admission intent; unknown fields are refused. OutputRetention: type: object properties: minDuration: description: min_duration retains each process's output for at least this age when set. $ref: "#/components/schemas/Duration" minBytes: type: - integer - string format: int64 description: |- min_bytes retains at least this many recent bytes per process when nonzero. a byte retention floor must be zero or at least 64 KiB title: OutputRetention description: |- OutputRetention records minimum reconnect coverage independently of location. output retention requires a duration or byte floor StopMemoryOutcome: type: string title: StopMemoryOutcome enum: - unspecified - discard - preserve description: |- StopMemoryOutcome records the stop/start guarantee independently of location. Values: unspecified: unspecified is not an advertised or accepted guarantee. discard: discard retains disk and starts a fresh process tree. preserve: preserve restores the stopped process tree on start. FilesDownloadRequest: type: object properties: paths: type: array items: type: string minItems: 1 description: |- paths naming stable regular files or absent entries at canonical absolute paths yield contiguous results in request order, including duplicates. title: DownloadRequest required: - paths additionalProperties: false description: DownloadRequest asks for one or more paths. FilesDownloadResponse: type: object title: DownloadResponse unevaluatedProperties: false description: DownloadResponse is one frame in a download stream. At most one of data, error, header is set. properties: data: type: string format: byte description: data carries bytes for the current file. error: description: error reports a path-level failure without aborting the whole stream. $ref: "#/components/schemas/FileError" header: description: header starts a downloaded file. $ref: "#/components/schemas/FileHeader" dependentSchemas: data: not: anyOf: - required: - error - required: - header error: not: anyOf: - required: - data - required: - header header: not: anyOf: - required: - data - required: - error FileError: type: object properties: path: type: string description: path is the path that failed. failure: description: failure retains the shared typed code and details for this path. $ref: "#/components/schemas/Error" title: FileError required: - failure description: FileError reports a path-level file error. FileHeader: type: object properties: path: type: string minLength: 1 description: path is the sandbox path. mode: type: integer description: |- mode carries Unix permission bits. Upload applies mode & 0777, or 0644 when that value is zero, without subtracting umask; Download reports stored bits. title: FileHeader required: - path additionalProperties: false description: FileHeader starts a file in an upload or download stream. FileInfo: type: object properties: path: type: string description: path is the sandbox path. size: type: - integer - string format: int64 description: size is the file size in bytes. mode: type: integer description: mode is the stored Unix permission bits (0777), without type or special bits. isDir: type: boolean description: |- is_dir reports whether the path is a directory and stays populated on every backend and every caller. type is the richer authority, and type == directory iff is_dir. type: description: |- type classifies the object, and Stat and List populate it for every caller. Stat and List resolve an in-jail symlink and report the resolved target's type; a link that cannot be resolved in-jail (dangling, looping, or escaping) reports symlink for itself rather than disclosing an out-of-jail target. $ref: "#/components/schemas/FileType" linkTarget: type: string description: |- link_target is the literal readlink() text when type is symlink, since that is the only case where nothing else lets the caller learn what the link names; empty otherwise. title: FileInfo description: FileInfo is file metadata. FileType: type: string title: FileType enum: - unspecified - regular - directory - symlink - other description: |- FileType classifies the object at a path. Values: unspecified: unspecified means the backend has not classified the object. Stat and List always classify it. regular: regular is a regular file. directory: directory is a directory. symlink: symlink is a symbolic link that could not be resolved to a target inside the jail. other: other is a socket, FIFO, device, or other non-regular, non-directory, non-symlink object. FilesListResponse: type: object properties: entries: type: array items: $ref: "#/components/schemas/FileInfo" description: entries is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListResponse description: ListResponse returns directory entries and a next-page token. FilesMkdirRequest: type: object properties: path: type: string minLength: 1 description: path is the directory path. mode: type: integer description: |- mode supplies the new leaf's Unix permission bits: mode & 0777, or 0755 when that value is zero, without subtracting umask. parents: type: boolean description: parents creates missing parents when true. title: MkdirRequest required: - path additionalProperties: false description: MkdirRequest creates a directory. FilesMkdirResponse: type: object title: MkdirResponse description: MkdirResponse has no fields. FilesMoveRequest: type: object properties: from: type: string minLength: 1 description: from is the source path. to: type: string minLength: 1 description: to is the exact destination path. title: MoveRequest required: - from - to additionalProperties: false description: MoveRequest moves or renames a path. FilesMoveResponse: type: object title: MoveResponse description: MoveResponse has no fields. FilesReadFileRequest: type: object properties: path: type: string minLength: 1 description: path is the sandbox path of a regular file. title: ReadFileRequest required: - path additionalProperties: false description: ReadFileRequest names one regular file. FilesReadFileResponse: type: object properties: info: description: info remains available to the internal adapter; HTTP clients use Stat for metadata. $ref: "#/components/schemas/FileInfo" data: type: string format: byte description: data is the complete content; a file above the message cap is refused. title: ReadFileResponse required: - info additionalProperties: false description: ReadFileResponse carries the whole file; HTTP selects data as its raw response body. FilesRemoveResponse: type: object properties: completedPaths: type: array items: type: string description: |- completed_paths lists removed paths in traversal order, bounded to the first 1000; completed_count carries the true total when it exceeds that bound. completedCount: type: integer description: |- completed_count is the total number of paths removed, which may exceed len(completed_paths). failedPath: type: string description: |- failed_path is the path where a recursive removal stopped; empty on full success. Every path in completed_paths was removed before this one. title: RemoveResponse description: |- RemoveResponse reports partial recursive progress to every caller: check failed_path, not the operation status, when Remove stops partway. Effects are never rolled back. FilesStatResponse: type: object properties: info: description: info is metadata for the path. $ref: "#/components/schemas/FileInfo" title: StatResponse description: StatResponse returns file metadata. FilesUploadRequest: type: object oneOf: - type: object properties: data: type: string format: byte description: data appends bytes to the current file. title: data required: - data - type: object properties: header: description: |- header starts a new file. The first frame, and the first frame after each completed file, must be this arm. $ref: "#/components/schemas/FileHeader" title: header required: - header title: UploadRequest unevaluatedProperties: false description: UploadRequest is one frame in an upload stream. FilesUploadResponse: type: object properties: filesWritten: type: integer description: files_written is the number of files successfully written. title: UploadResponse description: UploadResponse reports completed file writes. FilesWriteFileRequest: type: object properties: header: description: header names the path and mode, as an Upload header does. $ref: "#/components/schemas/FileHeader" data: type: string format: byte description: data is the complete new content; empty writes an empty file. title: WriteFileRequest required: - header additionalProperties: false description: WriteFileRequest replaces one file. FilesWriteFileResponse: type: object properties: info: description: info is the file's metadata after the write. $ref: "#/components/schemas/FileInfo" title: WriteFileResponse required: - info description: WriteFileResponse reports the written file. AttachmentMode: type: string title: AttachmentMode enum: - unspecified - exclusive description: |- AttachmentMode fixes attachment ownership independently of backend placement. Values: unspecified: unspecified selects exclusive read-write attachment. exclusive: exclusive permits one sandbox to attach the volume read-write. EffectiveManagedVolumes: type: object properties: attachments: type: array items: $ref: "#/components/schemas/EffectiveVolumeAttachment" minItems: 1 description: attachments retains admission order and stable volume identities. title: EffectiveManagedVolumes required: - attachments description: EffectiveManagedVolumes records storage that is not deleted with the sandbox. EffectiveVolumeAttachment: type: object properties: volume: type: string description: volume is the resource name recorded for this reference. volumeUid: type: - string - "null" description: volume_uid retains the observed backing incarnation when the backend provides one. readOnly: true target: type: string minLength: 1 description: target is the accepted normalized absolute guest path. mode: not: enum: - unspecified description: mode is explicit and survives sandbox stop/start and backend restart. $ref: "#/components/schemas/AttachmentMode" title: EffectiveVolumeAttachment required: - target - mode description: EffectiveVolumeAttachment retains the identity, not a reusable name lookup. ManagedVolumeOptions: type: object properties: attachments: type: array items: $ref: "#/components/schemas/VolumeAttachment" minItems: 1 description: attachments cannot repeat a volume identity or overlap another mount target. title: ManagedVolumeOptions required: - attachments additionalProperties: false description: ManagedVolumeOptions selects existing volumes; it does not create storage. VolumeAttachment: type: object properties: volume: type: string pattern: ^volumes/[^/]+$ description: volume is the complete resource name, in the form volumes/{volume}. target: type: string minLength: 1 description: target is an absolute guest path and cannot overlap another mount target. mode: description: mode defaults to exclusive; it never silently enables shared writers. $ref: "#/components/schemas/AttachmentMode" title: VolumeAttachment required: - volume - target additionalProperties: false description: VolumeAttachment binds an existing owner-scoped volume before guest execution. StoredSecretOptions: type: object properties: secrets: type: array items: type: string pattern: ^secrets/[^/]+$ minItems: 1 description: secrets are complete Secret resource names resolved once at admission. title: StoredSecretOptions required: - secrets additionalProperties: false description: StoredSecretOptions resolves owner-scoped references before the workload can run. EffectiveTimeouts: type: object properties: onTimeout: not: enum: - unspecified description: on_timeout remains the accepted disposition through renewal and restart. $ref: "#/components/schemas/TimeoutAction" autoResume: type: boolean description: auto_resume is explicit; endpoint authorization still precedes any wake-up. initialTimeout: description: Records the accepted initial TTL, not the recurring interval for RESTART or KEEP. $ref: "#/components/schemas/Duration" expiresAt: description: expires_at is present only while a deadline is armed, not before first readiness or while stopped. $ref: "#/components/schemas/Timestamp" resumeTimeout: description: Freezes the action's default for later starts; RESTART and KEEP manage their own interval. $ref: "#/components/schemas/Duration" title: EffectiveTimeouts required: - onTimeout - initialTimeout description: |- EffectiveTimeouts retains the selected behavior and current action deadline. DELETE and STOP retain a resume timeout; RESTART (and its deprecated alias KEEP) does not use one TimeoutAction: type: string title: TimeoutAction enum: - unspecified - delete - stop - keep - restart description: |- TimeoutAction selects the lifecycle action taken at the reported deadline. Values: unspecified: unspecified is invalid when explicitly supplied. delete: delete deletes the sandbox at expiry. stop: stop applies the sandbox's persisted stop guarantee at expiry. keep: Deprecated alias for the restart action, still accepted on input and output. New clients should use the canonical restart action. restart: Preserves memory through backend-managed stop/resume cycles at expiry. Requires memory preservation and the always-on entitlement. TimeoutOptions: type: object properties: timeout: description: timeout is the initial TTL; omission selects the advertised action default. $ref: "#/components/schemas/Duration" onTimeout: oneOf: - $ref: "#/components/schemas/TimeoutAction" - type: "null" not: enum: - unspecified description: on_timeout defaults to DELETE; an explicit UNSPECIFIED is invalid. autoResume: type: - boolean - "null" description: Omission selects the advertised default; false does not disable RESTART or KEEP cycles. title: TimeoutOptions additionalProperties: false description: |- TimeoutOptions selects deadline behavior; presence enables this feature for the sandbox. an explicit RESTART (or its deprecated alias KEEP) initial timeout must be at least one hour ProcessAttach: type: object properties: name: type: string pattern: ^processes/[^/]+$ description: name is the complete resource name, in the form processes/{process}. resumeFrom: type: - integer - string format: int64 description: resume_from resumes after a received or published stream_sequence; 0 means from the start. Missing output after this point fails with FAILED_PRECONDITION. title: Attach required: - name additionalProperties: false description: Attach selects the process and output resume point. ProcessChunk: type: object properties: stream: description: stream identifies stdout, stderr, or PTY output. $ref: "#/components/schemas/StreamType" data: type: string format: byte description: data is output bytes. streamSequence: type: - integer - string format: int64 description: stream_sequence is one-based and strictly increases per process output stream. title: Chunk description: Chunk carries process output. CreateProcessRequest: type: object properties: cmd: type: array items: type: string minItems: 1 description: cmd is the argv vector. env: type: object additionalProperties: type: string title: value description: env adds environment variables. workingDir: type: string description: working_dir is the process working directory. user: type: string description: user is the user to run as. pty: description: pty requests a pseudo-terminal; absence uses separate stdin/stdout/stderr pipes. $ref: "#/components/schemas/PtyConfig" session: type: string description: session is an optional opaque session tag stored verbatim; empty means untagged. label: type: - string - "null" minLength: 1 description: (OPTIONAL) label is unique within the sandbox; omission retains the server-generated default. title: CreateProcessRequest required: - cmd additionalProperties: false description: CreateProcessRequest starts an interactive process. ExecRequest: type: object properties: cmd: type: array items: type: string minItems: 1 description: cmd is the argv vector. env: type: object additionalProperties: type: string title: value description: env adds environment variables. workingDir: type: string description: working_dir is the process working directory. user: type: string description: user is the user to run as. title: ExecRequest required: - cmd additionalProperties: false description: ExecRequest runs a command to completion. ExecResponse: type: object properties: exitCode: type: integer format: int32 description: exit_code is the process exit code. stdout: type: string format: byte description: stdout is captured stdout, up to the capture limit when incomplete. stderr: type: string format: byte description: stderr is captured stderr, up to the capture limit when incomplete. incomplete: type: boolean description: |- incomplete is true when the combined capture limit forced stdout and/or stderr to discard some of the command's real output; false whenever every byte the command produced was retained, even if that total lands exactly at the limit. exit_code is still the real, final exit code: the command ran to completion, only its captured output was capped. A retry would rerun the command, so this stays a normal successful response rather than an error a client might retry. title: ExecResponse description: ExecResponse returns process output after the command exits. ProcessExited: type: object properties: exitCode: type: integer format: int32 description: exit_code is the process exit code. reason: type: string description: reason is backend-readable exit context. title: Exited description: Exited reports process completion. ProcessHeartbeat: type: object title: Heartbeat additionalProperties: false description: Heartbeat is an idle keepalive frame. InteractRequest: type: object oneOf: - type: object properties: attach: description: attach opens or resumes the interaction. $ref: "#/components/schemas/ProcessAttach" title: attach required: - attach - type: object properties: closeStdin: type: boolean description: |- close_stdin closes standard input when true; false has no effect, including on a PTY. On a PTY, true delivers the terminal's VEOF input through the line discipline and does not close the PTY master; subsequent stdin frames remain valid. Terminal mode owns interpretation: canonical mode treats VEOF as marking the end of input, while raw mode delivers it as an ordinary input byte, so this promises delivery, never interpretation. Each true frame on a PTY delivers exactly one VEOF input; unlike the pipe path, repeated frames are not a no-op. title: close_stdin required: - closeStdin - type: object properties: resize: description: resize changes terminal size; portable-range dimensions on a running process without a PTY return FAILED_PRECONDITION. $ref: "#/components/schemas/TerminalSize" title: resize required: - resize - type: object properties: stdin: type: string format: byte description: stdin writes process standard input. title: stdin required: - stdin title: InteractRequest unevaluatedProperties: false description: InteractRequest is one frame on the bidirectional interaction stream. ListProcessesResponse: type: object properties: processes: type: array items: $ref: "#/components/schemas/Process" description: processes is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListProcessesResponse description: ListProcessesResponse returns processes and a next-page token. ProcessOutput: type: object title: Output unevaluatedProperties: false description: Output is one server frame on an interaction stream. At most one of chunk, exited, heartbeat is set. properties: chunk: description: chunk carries ordered process output. $ref: "#/components/schemas/ProcessChunk" exited: description: exited reports process completion. $ref: "#/components/schemas/ProcessExited" heartbeat: description: heartbeat keeps an idle stream alive and carries no resume position. $ref: "#/components/schemas/ProcessHeartbeat" dependentSchemas: chunk: not: anyOf: - required: - exited - required: - heartbeat exited: not: anyOf: - required: - chunk - required: - heartbeat heartbeat: not: anyOf: - required: - chunk - required: - exited Process: type: object properties: uid: type: - string - "null" description: (IMMUTABLE) uid is the existing process incarnation, also used as the resource name terminal. readOnly: true pid: type: integer format: int32 description: pid is the process id inside the sandbox when available. session: type: string description: session is the session tag from the create, empty when untagged. state: description: state is the process state, concrete in conforming responses. $ref: "#/components/schemas/ProcessState" lastStreamSequence: type: - integer - string format: int64 description: last_stream_sequence is the highest stream_sequence emitted for the process when this report was assembled; 0 before any output. receiptKind: description: |- receipt_kind classifies this response on CreateProcess; every other operation returning a Process, including ListProcesses, always reports unspecified. $ref: "#/components/schemas/ReceiptKind" exitCode: type: - integer - "null" format: int32 description: exit_code is the process exit code, set only when state is exited and absent otherwise. label: type: string minLength: 1 description: (IMMUTABLE) label retains the unique, immutable process label and its generated default. name: type: string description: (IDENTIFIER) name is scoped to the discovered sandbox endpoint API base. title: Process required: - label description: Process is the handle returned before interaction begins. ProcessState: type: string title: ProcessState enum: - unspecified - running - exited description: |- ProcessState is the coarse process lifecycle a process report carries. Values: unspecified: unspecified is not a concrete state; conforming responses never use it. running: running means the process has not exited. exited: exited means the process has exited. PtyConfig: type: object properties: initialSize: description: initial_size requests an initial terminal size; absence selects a backend-defined size. $ref: "#/components/schemas/TerminalSize" title: PtyConfig additionalProperties: false description: PtyConfig configures pseudo-terminal creation. ReadOutputResponse: type: object properties: chunks: type: array items: $ref: "#/components/schemas/ProcessChunk" description: chunks is retained output in stream_sequence order, possibly empty. nextResumeFrom: type: - integer - string format: int64 description: |- next_resume_from is the stream_sequence to pass next; equal to resume_from when nothing new was retained. exited: description: exited is set once the process has exited and no retained bytes follow next_resume_from. $ref: "#/components/schemas/ProcessExited" title: ReadOutputResponse description: ReadOutputResponse is one page of ordered output. ReceiptKind: type: string title: ReceiptKind enum: - unspecified - fresh - replay description: |- ReceiptKind classifies whether a CreateProcess response was freshly assembled or is the retained receipt of an earlier accepted request. Values: unspecified: unspecified is not a concrete classification; a backend or a client generated before this field existed reports or reads this. It asserts neither freshness nor replay. fresh: fresh means this Process was assembled for this specific accepted request; last_stream_sequence reflects live state as of that acceptance. replay: replay means the backend returned the retained result of an earlier accepted request under the synchronous mutation replay rule; last_stream_sequence is frozen at the value observed during that original acceptance. ProcessSignal: type: string title: Signal enum: - unspecified - term - kill - int - hup - quit - usr1 - usr2 description: |- Signal is a process signal. Values: unspecified: unspecified is invalid. term: term requests graceful termination. kill: kill requests immediate termination. int: int requests interrupt. hup: hup requests hangup. quit: quit requests quit. usr1: usr1 requests user signal 1. usr2: usr2 requests user signal 2. SignalResponse: type: object title: SignalResponse description: SignalResponse has no fields. StreamType: type: string title: StreamType enum: - unspecified - stdout - stderr - pty description: |- StreamType identifies the source of an output chunk. Values: unspecified: unspecified is not a concrete output stream. stdout: stdout is stdout. stderr: stderr is stderr. pty: pty is merged PTY output. TerminalSize: type: object properties: rows: type: integer description: rows is the terminal row count. cols: type: integer description: cols is the terminal column count. bounded: type: boolean description: |- bounded requests the portable range enforced on this size, with no opt in to perform first. Unset or false keeps the unenforced behavior. title: TerminalSize additionalProperties: false description: |- TerminalSize is a terminal rows/columns pair; 1 through 65535 is the portable range. bounded requires rows and cols in 1..65535 AddMcpGatewayServerResponse: type: object properties: server: description: server is the gateway server. $ref: "#/components/schemas/McpServer" title: AddMcpGatewayServerResponse description: AddMcpGatewayServerResponse returns the added or already-present server. AttributedRule: type: object properties: network: type: string description: network is the network name or CIDR. layer: description: layer identifies where the rule came from. $ref: "#/components/schemas/PolicyLayer" title: AttributedRule description: AttributedRule reports a rule and the layer that supplied it. CaptureMode: type: string title: CaptureMode enum: - unspecified - all - disk description: |- CaptureMode selects whether captured images include memory. Values: unspecified: unspecified means disk-only capture. all: all captures memory and disk and requires memory-capture support. disk: disk captures disk only. CreateImageRequest: type: object allOf: - properties: displayName: type: string not: type: string enum: - . - .. minLength: 1 pattern: ^[^/]+$ description: display_name is a scoped label; the backend assigns the immutable resource ID. description: type: string description: description is caller-supplied text. startCmd: type: array items: type: string description: start_cmd is used when the image is launched as a raw image sandbox. readyCmd: type: array items: type: string description: ready_cmd is used to determine readiness for raw image sandboxes. - oneOf: - type: object properties: fromImage: description: from_image registers an entry that will receive pushed OCI content. $ref: "#/components/schemas/ImageFromImage" title: from_image required: - fromImage title: CreateImageRequest required: - displayName unevaluatedProperties: false description: CreateImageRequest creates a managed image. CreatePortRequestPortInput: type: object properties: number: type: integer maximum: 65535 minimum: 1 format: int32 description: (IMMUTABLE) number is immutable and unique within the sandbox; duplicates refuse ALREADY_EXISTS. protocol: type: string title: PortInputProtocol enum: - unspecified - tcp description: (IMMUTABLE) protocol defaults to TCP when unspecified. title: PortInput required: - number additionalProperties: false CreateSandboxRequest: type: object allOf: - properties: agent: type: string description: agent names an optional agent profile; unsupported profiles fail explicitly. displayName: type: string maxLength: 64 pattern: ^[a-zA-Z0-9_-]*$ description: (OPTIONAL) display_name is a scoped label; the backend assigns the immutable resource ID. displayNamePrefix: type: string description: (OPTIONAL) display_name_prefix requests a generated label and excludes display_name. environment: type: object additionalProperties: type: string title: value description: environment is non-secret environment metadata. resources: description: resources requests CPU and memory within the selected placement's limits. $ref: "#/components/schemas/Resources" pullPolicy: type: string title: CreateSandboxRequestPullPolicy enum: - unspecified - always description: pull_policy retains shared image-pull semantics and explicit support errors. kits: type: array items: $ref: "#/components/schemas/KitInput" description: kits are the kit inputs to apply before readiness, in composition order. mcp: description: mcp requests an MCP gateway wired before the workload starts. $ref: "#/components/schemas/McpCreateSpec" networkPolicies: type: array items: $ref: "#/components/schemas/NetworkPolicy" description: |- network_policies are inline policies materialized in governance and enforced before the first guest process. Omission or an empty list requests no inline policies; unsupported policies fail before create effects. policyIds: type: array items: type: string minLength: 1 description: policy_ids names existing governance policies, never raw policy content. platform: description: |- platform selects an exact supported, image-compatible tuple when present. explicit platform requires OS and architecture $ref: "#/components/schemas/Platform" startupExecution: description: |- startup_execution is ordinary create input and persists for the sandbox lifetime. $ref: "#/components/schemas/StartupExecution" labels: type: object maxProperties: 64 additionalProperties: type: string title: value description: "" description: |- labels are non-secret caller-assigned key/value metadata recorded at admission. This contract has no verb that changes labels afterwards. features: description: features carries typed inputs validated before admission can have effects. $ref: "#/components/schemas/FeatureOptions" - properties: image: type: string pattern: ^images/[^/]+$ description: image is the managed Image resource name. imageRef: type: string description: image_ref is an external OCI reference, with the existing backend validation. dependentSchemas: image: not: anyOf: - required: - imageRef imageRef: not: anyOf: - required: - image title: CreateSandboxRequest unevaluatedProperties: false description: |- CreateSandboxRequest validates typed composition intent before replay and persists accepted guarantees, distinct enough from legacy create that old servers cannot silently drop it. display_name and display_name_prefix are mutually exclusive At most one of image, imageRef is set. CreateSecretRequest: type: object allOf: - properties: displayName: type: string not: type: string enum: - . - .. minLength: 1 pattern: ^[^/]+$ description: display_name is a scoped label; the backend assigns the immutable resource ID. serviceType: type: string description: service_type identifies the consuming service. - oneOf: - type: object properties: custom: description: |- custom stores an opaque value with caller-authored injection metadata. CreateSecretRequest.service_type is server-assigned for custom material; leave it empty. $ref: "#/components/schemas/CustomSecretMaterial" title: custom required: - custom - type: object properties: oauth: description: oauth stores OAuth refresh material. $ref: "#/components/schemas/OAuthRefreshMaterial" title: oauth required: - oauth - type: object properties: token: description: token stores opaque token material. $ref: "#/components/schemas/TokenSecretMaterial" title: token required: - token title: CreateSecretRequest required: - displayName unevaluatedProperties: false description: |- CreateSecretRequest stores new secret material. service_type must be empty for custom material (server-assigned) CreateVolumeRequest: type: object properties: displayName: type: string not: type: string enum: - . - .. minLength: 1 pattern: ^[^/]+$ description: display_name is a scoped label; the backend assigns the immutable resource ID. title: CreateVolumeRequest required: - displayName additionalProperties: false description: CreateVolumeRequest creates one volume. CredentialFenceReceipt: type: object properties: target: type: string pattern: ^(sandboxes|secrets)/[^/]+$ description: target is the complete Sandbox or Secret resource name bound to this receipt. generation: exclusiveMinimum: 0 type: - integer - string format: int64 description: generation increases for each accepted material/rule replacement on that target. title: CredentialFenceReceipt required: - target - generation description: CredentialFenceReceipt acknowledges one completed generation without granting current use. CustomInjection: type: object properties: hosts: type: array items: type: string minLength: 1 maxItems: 10 minItems: 1 description: |- hosts are exact lowercase DNS names. Wildcards, IP literals, ports, schemes, paths, and hosts a managed integration already serves are rejected. header: type: string minLength: 1 description: |- header is the HTTP header the value is written to. Routing, framing, and cookie headers are rejected. format: type: string description: |- format renders the value with exactly one %s; %% escapes a literal percent, and any other % sequence is rejected. Empty means "%s". envVar: type: string description: |- env_var optionally names a sandbox environment variable that carries the secret's placeholder (never the value) as a delivery convenience. placeholderTemplate: type: string description: |- placeholder_template optionally shapes the placeholder for clients that validate credential shape before sending (e.g. "sk-corp-{rand}"). Each {rand} token is expanded server-side; {rand} is the only token. Empty uses the backend default ("sbx-cs-{rand}"). title: CustomInjection required: - hosts - header additionalProperties: false description: |- CustomInjection is caller-authored, non-secret metadata for a custom secret: which exact hosts receive the value, in which header and format, and how the placeholder is shaped and delivered. Unlike secret material, reads return it. CustomSecretMaterial: type: object properties: value: type: string minLength: 1 description: value is the secret value. writeOnly: true injection: description: injection is the caller-authored routing. $ref: "#/components/schemas/CustomInjection" title: CustomSecretMaterial required: - value - injection additionalProperties: false description: CustomSecretMaterial is an opaque secret value plus its injection routing. DeleteSecretResponse: type: object properties: credentialFence: description: credential_fence remains the original historical receipt after deletion or name reuse. $ref: "#/components/schemas/CredentialFenceReceipt" title: DeleteSecretResponse description: DeleteSecretResponse acknowledges deletion and optional consumer fencing. EffectiveNetworkPolicy: type: object properties: mode: not: enum: - unspecified description: mode is the effective mode and is always concrete in conforming responses. $ref: "#/components/schemas/NetworkPolicyMode" allowNetworks: type: array items: $ref: "#/components/schemas/AttributedRule" description: allow_networks are effective allowed rules with attribution. denyNetworks: type: array items: $ref: "#/components/schemas/AttributedRule" description: deny_networks are effective denied rules with attribution. title: EffectiveNetworkPolicy required: - mode description: EffectiveNetworkPolicy is the policy after layering and fail-closed defaults. EndpointCredential: type: object properties: token: type: string minLength: 1 expireTime: $ref: "#/components/schemas/Timestamp" permissions: type: array items: $ref: "#/components/schemas/Permission" enum: - sandboxesExec - sandboxesFilesRead - sandboxesFilesWrite minItems: 1 uniqueItems: true description: "Allowed values: sandboxesExec, sandboxesFilesRead, sandboxesFilesWrite." sandbox: type: string pattern: ^sandboxes/[^/]+$ audience: type: string minLength: 1 title: EndpointCredential required: - token - expireTime - permissions - sandbox - audience description: "EndpointCredential is returned once with Cache-Control: no-store; never log its token." EtagMismatch: type: object properties: currentEtag: type: string minLength: 1 description: current_etag is informational; clients must not silently retry with it. title: EtagMismatch required: - currentEtag description: |- EtagMismatch is the status detail a stale precondition carries, so a client learns the current version for an explicit conflict-resolution decision. EtagMismatchErrorDetail: type: object properties: currentEtag: type: string minLength: 1 description: current_etag is informational; clients must not silently retry with it. "@type": type: string const: type.googleapis.com/docker.sandboxes.v1.EtagMismatch title: EtagMismatchErrorDetail required: - currentEtag - "@type" description: |- EtagMismatch is the status detail a stale precondition carries, so a client learns the current version for an explicit conflict-resolution decision. ExactDestination: type: object properties: kind: not: enum: - unspecified description: kind selects a matching rule; dnsLabelPrefix requires destination.v2. $ref: "#/components/schemas/ExactDestinationKind" value: type: string minLength: 1 description: |- For dnsLabelPrefix, crl.digicert.com matches a first label starting with crl and remaining labels exactly digicert.com; every value label is canonical ASCII DNS. port: type: - integer - "null" maximum: 65535 minimum: 1 description: An absent port matches all numeric ports; zero is invalid when present. title: ExactDestination required: - kind - value description: |- ExactDestination uses canonical selector values, never legacy glob syntax. dnsLabelPrefix requires a canonical DNS label prefix and suffix ExactDestinationKind: type: string title: ExactDestinationKind enum: - unspecified - dns - dnsLabel - dnsSubtree - ip - cidr - dnsLabelPrefix description: |- ExactDestinationKind keeps DNS and IP-literal decisions distinct. Values: unspecified dns dnsLabel dnsSubtree ip cidr dnsLabelPrefix ExactNetworkPolicy: type: object properties: revision: type: string minLength: 1 description: revision binds authority, configuration and resolved conditions to the installed generation. selectorVersion: type: string enum: - destination.v1 - destination.v2 description: selector_version fixes matching semantics across implementations. nodes: type: array items: $ref: "#/components/schemas/ExactPolicyNode" maxItems: 256 minItems: 1 description: nodes are complete and topologically ordered; the final node is the root. title: ExactNetworkPolicy required: - revision - selectorVersion - nodes description: |- ExactNetworkPolicy is a complete consumer-installed generation; its last node is the root. dnsLabelPrefix requires destination.v2 ExactPolicyConstant: type: string title: ExactPolicyConstant enum: - unspecified - "true" - "false" description: |- ExactPolicyConstant makes both Boolean identities explicit. Values: unspecified true false ExactPolicyNode: type: object allOf: - properties: source: description: source is required on constants and destinations and absent on Boolean operators. $ref: "#/components/schemas/ExactPolicySource" - oneOf: - type: object properties: all: description: all intersects every operand. $ref: "#/components/schemas/ExactPolicyOperands" title: all required: - all - type: object properties: any: description: any unions its operands without discarding enclosing ceilings. $ref: "#/components/schemas/ExactPolicyOperands" title: any required: - any - type: object properties: constant: not: enum: - unspecified description: constant explicitly allows or denies independently of the destination. $ref: "#/components/schemas/ExactPolicyConstant" title: constant required: - constant - type: object properties: destination: description: destination matches only its declared DNS or IP kind. $ref: "#/components/schemas/ExactDestination" title: destination required: - destination - type: object properties: not: type: integer description: not negates one earlier node. title: not required: - not title: ExactPolicyNode description: ExactPolicyNode is topologically ordered; references must precede this node. ExactPolicyOperands: type: object properties: nodes: type: array items: type: integer maxItems: 64 minItems: 1 description: nodes must all precede the enclosing operator. title: ExactPolicyOperands required: - nodes description: ExactPolicyOperands contains earlier node indexes; empty Boolean groups are invalid. ExactPolicyOrigin: type: string title: ExactPolicyOrigin enum: - unspecified - organization - owner - attached - kit - gateway - default description: |- ExactPolicyOrigin separates governance from attached and runtime-owned permissions. Values: unspecified organization owner attached kit gateway default ExactPolicySource: type: object properties: origin: not: enum: - unspecified description: origin distinguishes the authority that supplied this leaf. $ref: "#/components/schemas/ExactPolicyOrigin" id: type: string minLength: 1 description: id identifies that source without exposing credentials or policy content. title: ExactPolicySource required: - origin - id description: ExactPolicySource identifies the nonsecret authority of a leaf expression. ExchangeCompositionCredentialResponse: type: object title: ExchangeCompositionCredentialResponse GetNetworkPoliciesResponse: type: object properties: effective: $ref: "#/components/schemas/EffectiveNetworkPolicy" exact: $ref: "#/components/schemas/ExactNetworkPolicy" title: GetNetworkPoliciesResponse required: - effective - exact description: GetNetworkPoliciesResponse binds both views to exact.revision; a partial read fails. IdentityExchangeServiceExchangeDockerCredentialRequest: type: object properties: idToken: type: string minLength: 1 description: id_token is single-use identity material, never an owner selector. writeOnly: true title: IdentityExchangeServiceExchangeDockerCredentialRequest required: - idToken additionalProperties: false Image: type: object properties: uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true name: type: string pattern: ^images/[^/]+$ description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. description: type: string description: description is caller-supplied text. status: not: enum: - unspecified description: status is the image readiness state. readOnly: true $ref: "#/components/schemas/ImageStatus" imageRef: type: string description: image_ref is the registry or backend image reference when available. imageDigest: type: string description: image_digest is the content digest when known. resources: description: resources describes the image's preferred runtime resources. $ref: "#/components/schemas/Resources" startCmd: type: array items: type: string description: start_cmd is the command used by raw image sandboxes. readyCmd: type: array items: type: string description: ready_cmd is the readiness command used by raw image sandboxes. platform: description: platform is the image platform. $ref: "#/components/schemas/Platform" totalSizeBytes: type: - integer - string format: int64 description: total_size_bytes is the approximate stored image size. createdAt: description: created_at is the creation timestamp. $ref: "#/components/schemas/Timestamp" updatedAt: description: updated_at is the last update timestamp. $ref: "#/components/schemas/Timestamp" failure: description: failure is set when status is FAILED. $ref: "#/components/schemas/Error" source: description: source records how the image was created. $ref: "#/components/schemas/ImageSource" captureMode: description: capture_mode records whether captured content includes memory. $ref: "#/components/schemas/CaptureMode" etag: type: string minLength: 1 pattern: ^"[^"\x00-\x20\x7f]*"$ description: |- etag identifies the observed version of this resource. It is opaque and strong, changes on every visible change, and is what a mutation sends as its precondition. readOnly: true pushTarget: description: push_target appears only in from_image create responses awaiting upload, never reads. readOnly: true $ref: "#/components/schemas/ImagePushTarget" displayName: type: string description: display_name is a scoped label and never selects the resource. title: Image required: - uid - name - status - createdAt - updatedAt - etag description: |- Image is the detailed managed image view. uid must equal the immutable resource ID in name ImageBlobRef: type: object properties: digest: type: string description: digest is the content digest. mediaType: type: string description: media_type is the OCI media type. size: type: - integer - string format: int64 description: size is the blob size in bytes. url: type: string description: url is a short-lived pull URL. title: ImageBlobRef description: ImageBlobRef describes one pullable blob. ImageFromImage: type: object properties: resources: description: resources describes preferred runtime resources for the resulting image. $ref: "#/components/schemas/Resources" platform: description: platform is the platform for the pushed content. $ref: "#/components/schemas/Platform" captureMode: type: string title: ImageFromImageCaptureMode enum: - unspecified - disk description: capture_mode must be unspecified or disk; pushed OCI content cannot include memory. not: enum: - all platformHint: description: |- platform_hint picks among a multi-platform push when platform is absent. A hint the backend cannot honor is ignored, never an error. $ref: "#/components/schemas/Platform" kitStartup: description: Startup commands copied from the source sandbox. Services with startup replay run these commands when a sandbox created from the image boots. Services without startup replay accept valid commands without running them. $ref: "#/components/schemas/KitStartup" title: ImageFromImage additionalProperties: false description: ImageFromImage registers a target for pushed OCI content. ImagePullSpec: type: object properties: manifestDigest: type: string description: manifest_digest is the manifest digest. manifestMediaType: type: string description: manifest_media_type is the manifest media type. config: description: config is the image config blob. $ref: "#/components/schemas/ImageBlobRef" layers: type: array items: $ref: "#/components/schemas/ImageBlobRef" description: layers are the image layer blobs. expiresAt: description: expires_at is when the pull material expires. $ref: "#/components/schemas/Timestamp" title: ImagePullSpec description: ImagePullSpec describes short-lived pull material for placement. ImagePushTarget: type: object properties: imageRef: type: string description: image_ref is the registry reference to push. accessToken: type: string description: access_token is the short-lived push credential. accessTokenExpiresAt: description: access_token_expires_at is the token expiry. $ref: "#/components/schemas/Timestamp" title: ImagePushTarget description: ImagePushTarget carries short-lived upload credentials. ImageSource: type: string title: ImageSource enum: - unspecified - image - sandbox description: |- ImageSource records how the image was created. Values: unspecified: unspecified means the source is unknown or not reported. image: image means the image came from pushed or imported image bytes. sandbox: sandbox means the image came from a sandbox capture. ImageStatus: type: string title: ImageStatus enum: - unspecified - pending - waitingForPush - preparing - completed - failed - deleted description: |- ImageStatus is the image readiness state. Values: unspecified: unspecified is never a concrete known state. pending: pending means an asynchronous build has not started or reported progress. waitingForPush: waitingForPush means the backend is waiting for OCI content upload. preparing: preparing means the backend is preparing pushed or captured content. completed: completed means the image is ready to use. failed: failed means image preparation reached a terminal failure. deleted: deleted means the backend exposes a retained delete tombstone. ImageSummary: type: object properties: uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true name: type: string pattern: ^images/[^/]+$ description: name ends in the immutable backing ID and never changes with display_name. status: not: enum: - unspecified description: status is the image readiness state. $ref: "#/components/schemas/ImageStatus" source: description: source records how the image was created. $ref: "#/components/schemas/ImageSource" totalSizeBytes: type: - integer - string format: int64 description: total_size_bytes is the approximate stored image size. createdAt: description: created_at is the creation timestamp. $ref: "#/components/schemas/Timestamp" updatedAt: description: updated_at is the last update timestamp. $ref: "#/components/schemas/Timestamp" imageRef: type: string description: image_ref is the registry or backend image reference when available. imageDigest: type: string description: image_digest is the content digest when known. captureMode: description: capture_mode records whether captured content includes memory. $ref: "#/components/schemas/CaptureMode" platform: description: platform is the image platform. $ref: "#/components/schemas/Platform" displayName: type: string description: display_name is a scoped label and never selects the resource. title: ImageSummary required: - uid - name - status - createdAt - updatedAt description: |- ImageSummary is the list view of an image. uid must equal the immutable resource ID in name IssueSSHCertResponse: type: object properties: certificate: type: string description: certificate is the signed SSH certificate. sshConfig: type: string description: |- ssh_config optionally renders the connection fields as OpenSSH client configuration; the structured fields are canonical. knownHosts: type: string description: known_hosts is host key material that authenticates the SSH endpoint. expiresAt: description: expires_at is the instant after which the certificate is invalid. $ref: "#/components/schemas/Timestamp" host: type: string description: host is the SSH endpoint host to connect to. port: type: integer description: port is the SSH endpoint port to connect to. username: type: string description: username is the SSH username to present; it carries no authorization. title: IssueSSHCertResponse description: IssueSSHCertResponse returns signed SSH client material, never a private key. KitArtifactInput: type: object allOf: - properties: ref: $ref: "#/components/schemas/KitRef" - oneOf: - type: object properties: inline: type: string format: byte description: inline is the artifact in the pinned JSON encoding. title: inline required: - inline title: KitArtifactInput required: - ref unevaluatedProperties: false description: KitArtifactInput carries a v2 artifact inline or by staged digest. KitFieldDisposition: type: string title: KitFieldDisposition enum: - unspecified - skipped - refused description: |- KitFieldDisposition describes a declaration that was not applied. Values: unspecified: unspecified is invalid in a report. skipped: skipped identifies a contract-permitted optional skip. refused: refused prevents guest or kit effects. KitFieldOutcome: type: object properties: kitIndex: exclusiveMaximum: 64 type: integer description: kit_index is the zero-based position in the originating request's kits. ref: type: string description: ref preserves the exact requested kit reference. digest: type: string description: digest is the resolved content identity when resolution succeeded. fieldPath: type: string description: field_path is an RFC 6901 pointer into the pinned JSON artifact. disposition: not: enum: - unspecified description: disposition never claims that an accepted declaration has executed. $ref: "#/components/schemas/KitFieldDisposition" reason: not: enum: - unspecified description: reason is a bounded category, not caller-controlled diagnostic content. $ref: "#/components/schemas/KitFieldReason" reasonText: type: string description: reason_text contains nonsecret explanatory text, never values or command content. title: KitFieldOutcome required: - ref - fieldPath - disposition - reason description: KitFieldOutcome identifies one non-applied declaration without exposing its value. KitFieldOutcomeReport: type: object properties: complete: type: boolean description: complete means every refused or skipped declaration is accounted for; absence proves nothing. outcomes: type: array items: $ref: "#/components/schemas/KitFieldOutcome" maxItems: 256 description: outcomes follow request index then UTF-8 field-path order and are never truncated. title: KitFieldOutcomeReport description: KitFieldOutcomeReport records settled diagnostics on a sandbox or an admission refusal. KitFieldOutcomeReportErrorDetail: type: object properties: complete: type: boolean description: complete means every refused or skipped declaration is accounted for; absence proves nothing. outcomes: type: array items: $ref: "#/components/schemas/KitFieldOutcome" maxItems: 256 description: outcomes follow request index then UTF-8 field-path order and are never truncated. "@type": type: string const: type.googleapis.com/docker.sandboxes.v1.KitFieldOutcomeReport title: KitFieldOutcomeReportErrorDetail description: KitFieldOutcomeReport records settled diagnostics on a sandbox or an admission refusal. required: - "@type" KitFieldReason: type: string title: KitFieldReason enum: - unspecified - unsupported - unknownField - credentialUnavailable description: |- KitFieldReason provides stable, nonsecret diagnostic categories. Values: unspecified: unspecified is invalid in a report. unsupported: unsupported means the backend cannot honor the declaration. unknownField: unknownField means the pinned schema does not recognize the declaration. credentialUnavailable: credentialUnavailable means the declared credential cannot be injected. KitInput: type: object oneOf: - type: object properties: artifact: $ref: "#/components/schemas/KitArtifactInput" title: artifact required: - artifact title: KitInput unevaluatedProperties: false description: KitInput is one kit in either shape. KitStartup: type: object properties: kits: type: array items: type: string minLength: 1 minItems: 1 description: |- kits names the kit identities the commands derive from, in composition order. Required. commands: type: array items: $ref: "#/components/schemas/KitStartupCommand" minItems: 1 description: commands run in order at sandbox boot, on a backend that replays them. title: KitStartup required: - kits - commands additionalProperties: false description: Startup commands retained when creating an image. Services with startup replay run them at each boot; services without it accept valid commands without running them. KitStartupCommand: type: object properties: argv: type: array items: type: string minItems: 1 description: |- argv is the command and its arguments, exec-style. An argument other than the executable itself may be empty (an intentional empty string, as in `printf %s ""`); only the vector itself is required non-empty. user: type: string description: user runs the command as this user; empty means the backend default. background: type: boolean description: background launches the command detached instead of waiting for it. title: KitStartupCommand required: - argv additionalProperties: false description: |- KitStartupCommand is one startup command in a KitStartup set, run in order by a backend that replays it at sandbox boot. ListImagesResponse: type: object properties: images: type: array items: $ref: "#/components/schemas/ImageSummary" description: images is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListImagesResponse description: ListImagesResponse returns image results and a next-page token. ListPolicyLogEntriesResponse: type: object properties: entries: type: array items: $ref: "#/components/schemas/PolicyLogEntry" description: entries is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListPolicyLogEntriesResponse description: ListPolicyLogEntriesResponse returns policy log entries and a next-page token. ListPortsResponse: type: object properties: published: type: array items: $ref: "#/components/schemas/Port" description: published is ordered by number ascending. title: ListPortsResponse description: ListPortsResponse returns currently published ports. ListSandboxesResponse: type: object properties: sandboxes: type: array items: $ref: "#/components/schemas/Sandbox" description: sandboxes is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListSandboxesResponse description: ListSandboxesResponse returns sandbox results and a next-page token. ListSecretsResponse: type: object properties: secrets: type: array items: $ref: "#/components/schemas/Secret" description: secrets is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListSecretsResponse description: ListSecretsResponse returns secrets and a next-page token. ListSnapshotsResponse: type: object properties: snapshots: type: array items: $ref: "#/components/schemas/SnapshotSummary" description: snapshots is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListSnapshotsResponse description: ListSnapshotsResponse returns snapshot results and a next-page token. ListVolumesResponse: type: object properties: volumes: type: array items: $ref: "#/components/schemas/Volume" description: volumes is the current page. nextPageToken: type: string description: next_page_token is empty when there are no more pages. title: ListVolumesResponse description: ListVolumesResponse returns volumes and a next-page token. McpAuthorization: type: object properties: server: type: string pattern: ^(?:mcp-servers/[^/]+)?$ description: (OPTIONAL) server is the complete resource name, in the form mcp-servers/{server}. uid: type: - string - "null" description: (IMMUTABLE) uid is the existing immutable backing identity, omitted when none is available. readOnly: true status: readOnly: true $ref: "#/components/schemas/McpAuthorizationStatus" authorizationUrl: type: string description: authorization_url is present only while interaction is pending. readOnly: true createdAt: readOnly: true $ref: "#/components/schemas/Timestamp" updatedAt: readOnly: true $ref: "#/components/schemas/Timestamp" expiresAt: description: expires_at bounds the pending flow; expiry records FAILED on this incarnation. readOnly: true $ref: "#/components/schemas/Timestamp" failure: readOnly: true $ref: "#/components/schemas/Error" etag: type: string description: etag identifies this incarnation and changes with every visible authorization update. readOnly: true name: type: string description: (IDENTIFIER) name is the complete singleton resource name. title: McpAuthorization description: McpAuthorization is the current authorization incarnation for one named upstream. McpAuthorizationStatus: type: string title: McpAuthorizationStatus enum: - unspecified - pending - authorized - failed description: |- McpAuthorizationStatus reports the current upstream authorization outcome. Values: unspecified pending authorized failed McpConfigurationMode: type: string title: McpConfigurationMode enum: - unspecified - dynamic - static - attached description: |- McpConfigurationMode identifies desired hosting ownership and discovery behavior. Values: unspecified: unspecified is not a concrete report mode. dynamic: dynamic uses a backend-minted gateway with discovery. static: static uses a backend-minted gateway without discovery. attached: attached retains a read-only external binding. McpConfigurationOutcome: type: string title: McpConfigurationOutcome enum: - unspecified - pending - applied - skipped - failed description: |- McpConfigurationOutcome describes one requested server in the reported generation. Values: unspecified: unspecified is not a concrete outcome. pending: pending has not settled and cannot establish completeness. applied: applied is confirmed membership, not upstream authorization. skipped: skipped requires an explicitly applicable compatibility rule. failed: failed retains intent that could not be provisioned. McpConfigurationReport: type: object properties: generation: type: string description: generation is an opaque durable fence, never ordered or synthesized by callers. mode: not: enum: - unspecified description: mode separates minted discovery behavior from read-only attachment. $ref: "#/components/schemas/McpConfigurationMode" complete: type: boolean description: complete means every active requested server is applied or explicitly permitted to skip. servers: type: array items: $ref: "#/components/schemas/McpConfiguredServer" maxItems: 256 description: servers is the complete active requested set; together with dormant_servers it matches McpGateway.servers. dormantServers: type: array items: $ref: "#/components/schemas/McpServer" maxItems: 256 description: dormant_servers retains earlier minted intent while attached; it is empty in minted modes. title: McpConfigurationReport required: - generation - mode description: McpConfigurationReport is also returned in Error.details on accepted provisioning failure. McpConfigurationReportErrorDetail: type: object properties: generation: type: string description: generation is an opaque durable fence, never ordered or synthesized by callers. mode: not: enum: - unspecified description: mode separates minted discovery behavior from read-only attachment. $ref: "#/components/schemas/McpConfigurationMode" complete: type: boolean description: complete means every active requested server is applied or explicitly permitted to skip. servers: type: array items: $ref: "#/components/schemas/McpConfiguredServer" maxItems: 256 description: servers is the complete active requested set; together with dormant_servers it matches McpGateway.servers. dormantServers: type: array items: $ref: "#/components/schemas/McpServer" maxItems: 256 description: dormant_servers retains earlier minted intent while attached; it is empty in minted modes. "@type": type: string const: type.googleapis.com/docker.sandboxes.v1.McpConfigurationReport title: McpConfigurationReportErrorDetail required: - generation - mode - "@type" description: McpConfigurationReport is also returned in Error.details on accepted provisioning failure. McpConfiguredServer: type: object properties: server: description: server is the resolved requested server; its type cannot silently change within retained intent. $ref: "#/components/schemas/McpServer" outcome: not: enum: - unspecified description: outcome is concrete even when the gateway remains ready after a failed add. $ref: "#/components/schemas/McpConfigurationOutcome" reason: type: string description: reason is nonsecret context and never carries credentials or credential-bearing URLs. title: McpConfiguredServer required: - server - outcome description: McpConfiguredServer preserves one canonical requested identity and its provisioning outcome. McpCreateSpec: type: object properties: servers: type: array items: type: string minLength: 1 description: servers are initial server names for a backend-minted gateway. static: type: boolean description: static pins the requested server set and closes gateway-side discovery. gatewayUrl: type: - string - "null" format: uri description: gateway_url attaches read-only to a pre-existing shareable gateway when supported. title: McpCreateSpec additionalProperties: false description: |- McpCreateSpec configures the sandbox's MCP gateway before the workload starts. servers must be empty when gateway_url is set McpGateway: type: object properties: url: type: string description: url is the gateway endpoint. state: description: state is the gateway readiness state. $ref: "#/components/schemas/McpGatewayState" servers: type: array items: $ref: "#/components/schemas/McpServer" description: servers is the accumulated requested set, not live gateway truth. reused: type: boolean description: reused is true when the response reused an existing gateway. uid: type: - string - "null" description: (IMMUTABLE) uid is the existing immutable backing identity, omitted when none is available. readOnly: true name: type: string description: (IDENTIFIER) name is the complete singleton resource name. title: McpGateway description: McpGateway is gateway state for one sandbox. McpGatewayState: type: string title: McpGatewayState enum: - unspecified - provisioning - ready - failed description: |- McpGatewayState reports gateway readiness. Values: unspecified: unspecified is never a concrete known state. provisioning: provisioning means the gateway is starting. ready: ready means the gateway can accept server operations. failed: failed means gateway setup failed. McpServer: type: object properties: name: type: string description: name is the external configured server key, not an API resource name. type: description: type is the configured server type. $ref: "#/components/schemas/McpServerType" title: McpServer description: McpServer projects one external server key configured on a gateway. McpServerType: type: string title: McpServerType enum: - unspecified - remote - container - stdio description: |- McpServerType identifies a gateway server integration style. Values: unspecified: unspecified is not a concrete server type. remote: remote is an HTTP remote MCP server. container: container is a container-backed MCP server. stdio: stdio is a stdio-backed MCP server. NetworkPolicy: type: object properties: mode: type: string title: NetworkPolicyMode enum: - denyAll description: mode is required and cannot be UNSPECIFIED. not: enum: - unspecified allowNetworks: type: array items: type: string description: allow_networks are exact network names or CIDRs allowed by this document. denyNetworks: type: array items: type: string description: deny_networks are exact network names or CIDRs denied by this document. title: NetworkPolicy required: - mode additionalProperties: false description: NetworkPolicy is an inline policy request materialized in the governance plane. NetworkPolicyMode: type: string title: NetworkPolicyMode enum: - unspecified - allowAll - denyAll description: |- NetworkPolicyMode is the top-level egress disposition. Values: unspecified: unspecified is invalid in policy documents and in conforming responses. allowAll: allowAll allows egress unless denied by a narrower rule. denyAll: denyAll denies egress unless allowed by a narrower rule. OAuthConfig: type: object properties: tokenEndpoint: type: string description: token_endpoint is the OAuth token endpoint. clientId: type: string description: client_id is the OAuth client id. title: OAuthConfig description: OAuthConfig is non-secret OAuth metadata returned on reads. OAuthRefreshMaterial: type: object properties: refreshToken: type: string minLength: 1 description: refresh_token is the OAuth refresh token. writeOnly: true initialAccessToken: type: string description: initial_access_token is an optional bootstrap access token. writeOnly: true expiresAt: description: expires_at is the access token expiry when supplied. $ref: "#/components/schemas/Timestamp" scopes: type: array items: type: string description: scopes are requested OAuth scopes. providerAccountId: type: string description: provider_account_id identifies the provider account. idToken: type: string description: id_token is an optional OpenID Connect id token. writeOnly: true clientId: type: string description: client_id is the OAuth client id. title: OAuthRefreshMaterial required: - refreshToken additionalProperties: false description: |- OAuthRefreshMaterial is OAuth secret material. Unlike OAuthRefreshMaterialV2 it pairs no bootstrap token with an expiry and stores client_id as the caller supplied it. PolicyDecision: type: string title: PolicyDecision enum: - unspecified - allowed - blocked description: |- PolicyDecision is the outcome of an evaluated access attempt. Values: unspecified: unspecified means the decision is unknown or not reported. allowed: allowed means the attempt was allowed. blocked: blocked means the attempt was blocked. PolicyDomain: type: string title: PolicyDomain enum: - unspecified - network description: |- PolicyDomain identifies a policy subsystem. Values: unspecified: unspecified is not a concrete policy domain. network: network is network egress policy. PolicyLayer: type: string title: PolicyLayer enum: - unspecified - org - owner - kit - attached - gateway - default description: |- PolicyLayer identifies where an effective rule came from. ORG and OWNER are the two governance scopes; exactly one governs a caller, so a conforming effective view never mixes them. Values: unspecified: unspecified means the layer is unknown or not reported. org: org is org-level governance policy. owner: owner is owner-level governance policy. kit: kit is the sandbox-scoped policy a kit contributes. attached: attached is a governance policy bound to the sandbox: an inline document or a referenced policy id, materialized and bound by the governance plane at create. gateway: gateway is an enforced runtime-owned gateway policy contribution, not a backend service-route exemption. default: default is an explicit installed default-policy contribution, not a substitute for unknown provenance or an owner-level policy. PolicyLogEntry: type: object properties: resource: type: string description: resource is the requested destination or resource. decision: description: decision is the observed allow or block outcome. $ref: "#/components/schemas/PolicyDecision" proxyType: type: string description: proxy_type is the proxy or enforcement path that observed the decision. rule: type: string description: rule is the matching rule when available. reason: type: string description: reason is backend-readable context. count: type: - integer - string format: int64 description: count is the number of coalesced observations. firstSeen: description: first_seen is the first observation timestamp. $ref: "#/components/schemas/Timestamp" lastSeen: description: last_seen is the most recent observation timestamp. $ref: "#/components/schemas/Timestamp" sandbox: type: string description: sandbox is the resource name recorded for this reference. sandboxUid: type: - string - "null" description: sandbox_uid retains the observed backing incarnation when the backend provides one. readOnly: true domain: description: domain is the policy domain that emitted the entry. $ref: "#/components/schemas/PolicyDomain" title: PolicyLogEntry description: PolicyLogEntry is an aggregated observed policy decision. Port: type: object properties: number: type: integer maximum: 65535 minimum: 1 format: int32 description: (IMMUTABLE) number is immutable and unique within the sandbox; duplicates refuse ALREADY_EXISTS. protocol: description: (IMMUTABLE) protocol defaults to TCP when unspecified. $ref: "#/components/schemas/Protocol" url: type: string description: url is the required externally reachable address, including host-local addresses. readOnly: true etag: type: string description: etag identifies the observed version of this port. readOnly: true uid: type: - string - "null" description: (IMMUTABLE) uid is the durable publication incarnation when the backend provides one. readOnly: true name: type: string description: (IDENTIFIER) name identifies the published port number under its sandbox resource name. title: Port required: - number description: |- Port is one sandbox port made reachable from outside the sandbox. The same facts appear inline on SandboxCore.ports for a caller reading the sandbox. RawImageStartup: type: object properties: start: description: start replaces the complete launch argv; omission uses the image command. $ref: "#/components/schemas/StartupArgv" title: RawImageStartup additionalProperties: false description: RawImageStartup resolves identity and working directory from the pinned image. Sandbox: type: object properties: core: description: core is the backend-neutral sandbox view. $ref: "#/components/schemas/SandboxCore" effectiveFeatures: description: effective_features is emitted only by the composition contract projection. $ref: "#/components/schemas/EffectiveFeatures" failure: description: failure is present only while status is FAILED and clears on recovery. readOnly: true $ref: "#/components/schemas/Error" name: type: string pattern: ^sandboxes/[^/]+$ description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true displayName: type: string description: display_name is the scoped label; UpdateSandbox changes it without changing identity. title: Sandbox required: - core - name - uid description: |- Sandbox carries shared core state and the effective state of its selected features. uid must equal the immutable resource ID in name Secret: type: object properties: uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true name: type: string pattern: ^secrets/[^/]+$ description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. serviceType: type: string description: service_type identifies the consuming service. type: description: type identifies the stored material shape. $ref: "#/components/schemas/SecretType" oauthConfig: description: oauth_config is returned only for OAuth-shaped secrets. $ref: "#/components/schemas/OAuthConfig" scopes: type: array items: type: string description: scopes are non-secret OAuth scopes. createdAt: description: created_at is the creation timestamp. $ref: "#/components/schemas/Timestamp" updatedAt: description: updated_at is the last update timestamp. $ref: "#/components/schemas/Timestamp" injection: description: injection is returned only for custom-shaped secrets. $ref: "#/components/schemas/CustomInjection" placeholder: type: string description: |- placeholder is server-generated per custom secret and stable across value rotation; it is not secret material. A client presents it where the credential would go; for the configured hosts the backend replaces the configured header's value at egress regardless of what was sent. etag: type: string minLength: 1 pattern: ^"[^"\x00-\x20\x7f]*"$ description: |- etag identifies the observed version of this resource. It is opaque and strong, changes on every visible change, and is what a mutation sends as its precondition. readOnly: true displayName: type: string description: display_name is a scoped label and never selects the resource. title: Secret required: - uid - name - createdAt - updatedAt - etag description: |- Secret is returned metadata and never includes secret material. uid must equal the immutable resource ID in name SecretType: type: string title: SecretType enum: - unspecified - token - oauthRefresh - custom - registryV2 - hostResolved description: "The stored credential shape: token, OAuth refresh material, custom injection, registry credentials, or a credential resolved from an approved host-owned source. Secret material is never returned." Snapshot: type: object properties: uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true name: type: string pattern: ^snapshots/[^/]+$ description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. description: type: string description: description is caller-supplied text. sandbox: type: string description: sandbox is the resource name recorded for this reference. sandboxUid: type: - string - "null" description: sandbox_uid retains the observed backing incarnation when the backend provides one. readOnly: true status: not: enum: - unspecified description: status is the snapshot readiness state. readOnly: true $ref: "#/components/schemas/SnapshotStatus" totalSizeBytes: type: - integer - string format: int64 description: total_size_bytes is the approximate stored snapshot size. resources: description: resources describes the captured sandbox resources. $ref: "#/components/schemas/Resources" platform: description: platform is the captured sandbox platform. $ref: "#/components/schemas/Platform" createdAt: description: created_at is the creation timestamp. $ref: "#/components/schemas/Timestamp" failure: description: failure is set when status is FAILED. $ref: "#/components/schemas/Error" captureMode: description: capture_mode is the mode the snapshot was captured with. $ref: "#/components/schemas/CaptureMode" etag: type: string minLength: 1 pattern: ^"[^"\x00-\x20\x7f]*"$ description: |- etag identifies the observed version of this resource. It is opaque and strong, changes on every visible change, and is what a mutation sends as its precondition. readOnly: true displayName: type: string description: display_name is a scoped label and never selects the resource. title: Snapshot required: - uid - name - status - createdAt - etag description: |- Snapshot is the detailed snapshot view. uid must equal the immutable resource ID in name SnapshotStatus: type: string title: SnapshotStatus enum: - unspecified - creating - ready - failed - deleted description: |- SnapshotStatus is snapshot readiness state. Values: unspecified: unspecified is never a concrete known state. creating: creating means capture has not completed. ready: ready means the snapshot can be restored. failed: failed means capture reached a terminal failure. deleted: deleted means the backend exposes a retained delete tombstone. SnapshotSummary: type: object properties: uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true name: type: string pattern: ^snapshots/[^/]+$ description: name ends in the immutable backing ID and never changes with display_name. sandbox: type: string description: sandbox is the resource name recorded for this reference. sandboxUid: type: - string - "null" description: sandbox_uid retains the observed backing incarnation when the backend provides one. readOnly: true status: not: enum: - unspecified description: status is the snapshot readiness state. $ref: "#/components/schemas/SnapshotStatus" totalSizeBytes: type: - integer - string format: int64 description: total_size_bytes is the approximate stored snapshot size. createdAt: description: created_at is the creation timestamp. $ref: "#/components/schemas/Timestamp" captureMode: description: capture_mode is the mode the snapshot was captured with. $ref: "#/components/schemas/CaptureMode" displayName: type: string description: display_name is a scoped label and never selects the resource. title: SnapshotSummary required: - uid - name - status - createdAt description: |- SnapshotSummary is the list view of a snapshot. uid must equal the immutable resource ID in name StartupArgv: type: object properties: argv: type: array items: type: string minItems: 1 description: |- argv is executed without shell expansion. It carries at least one element, and that first element is the executable and must not be empty. title: StartupArgv required: - argv additionalProperties: false description: |- StartupArgv preserves literal arguments, including empty positional arguments. startup argv requires a nonempty executable StartupExecution: type: object oneOf: - type: object properties: rawImage: description: raw_image executes image commands using OCI identity and directory defaults. $ref: "#/components/schemas/RawImageStartup" title: raw_image required: - rawImage title: StartupExecution unevaluatedProperties: false description: |- StartupExecution retains the accepted execution promise across fresh boots. It is ordinary create input. TokenSecretMaterial: type: object properties: value: type: string minLength: 1 description: value is the secret token. writeOnly: true title: TokenSecretMaterial required: - value additionalProperties: false description: TokenSecretMaterial is opaque token material. Volume: type: object properties: uid: type: - string minLength: 1 description: (IMMUTABLE) uid is the existing backing ID, equal to the resource name's terminal segment. readOnly: true name: type: string pattern: ^volumes/[^/]+$ description: (IDENTIFIER) name ends in the immutable backing ID and never changes with display_name. createdAt: description: created_at is the creation timestamp. $ref: "#/components/schemas/Timestamp" etag: type: string minLength: 1 pattern: ^"[^"\x00-\x20\x7f]*"$ description: |- etag identifies the observed version of this resource. It is opaque and strong, changes on every visible change, and is what a mutation sends as its precondition. readOnly: true displayName: type: string description: display_name is a scoped label and never selects the resource. title: Volume required: - uid - name - createdAt - etag description: |- Volume is persistent storage metadata within its owner and contract scope. uid must equal the immutable resource ID in name Duration: type: string pattern: ^-?\d+(\.\d{1,9})?s$ description: Seconds with a trailing s, for example 30s or 1.5s. examples: - 30s - 1.5s ValidationFieldType: type: string title: Type enum: - TYPE_DOUBLE - TYPE_FLOAT - TYPE_INT64 - TYPE_UINT64 - TYPE_INT32 - TYPE_FIXED64 - TYPE_FIXED32 - TYPE_BOOL - TYPE_STRING - TYPE_GROUP - TYPE_MESSAGE - TYPE_BYTES - TYPE_UINT32 - TYPE_ENUM - TYPE_SFIXED32 - TYPE_SFIXED64 - TYPE_SINT32 - TYPE_SINT64 Timestamp: type: string examples: - 2023-01-15T01:30:15.01Z - 2024-12-25T12:00:00Z format: date-time description: An RFC 3339 timestamp in UTC, for example 2026-01-02T03:04:05Z. BadRequest: type: object properties: fieldViolations: type: array items: $ref: "#/components/schemas/BadRequestFieldViolation" description: Describes all violations in a client request. title: BadRequest description: |- Describes violations in a client request. This error type focuses on the syntactic aspects of the request. BadRequestFieldViolation: type: object properties: field: type: string description: |- A path that leads to a field in the request body. The value will be a sequence of dot-separated identifiers that identify a protocol buffer field. Consider the following: message CreateContactRequest { message EmailAddress { enum Type { TYPE_UNSPECIFIED = 0; HOME = 1; WORK = 2; } optional string email = 1; repeated EmailType type = 2; } string full_name = 1; repeated EmailAddress email_addresses = 2; } In this example, in proto `field` could take one of the following values: * `full_name` for a violation in the `full_name` value * `email_addresses[0].email` for a violation in the `email` field of the first `email_addresses` message * `email_addresses[2].type[1]` for a violation in the second `type` value in the third `email_addresses` message. In JSON, the same values are represented as: * `fullName` for a violation in the `fullName` value * `emailAddresses[0].email` for a violation in the `email` field of the first `emailAddresses` message * `emailAddresses[2].type[1]` for a violation in the second `type` value in the third `emailAddresses` message. description: type: string description: A description of why the request element is bad. reason: type: string description: |- The reason of the field-level error. This is a constant value that identifies the proximate cause of the field-level error. It should uniquely identify the type of the FieldViolation within the scope of the ErrorInfo.domain. This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents UPPER_SNAKE_CASE. localizedMessage: description: |- Provides a localized error message for field-level errors that is safe to return to the API consumer. $ref: "#/components/schemas/LocalizedMessage" title: FieldViolation description: A message type used to describe a single bad request field. BadRequestErrorDetail: type: object properties: fieldViolations: type: array items: $ref: "#/components/schemas/BadRequestFieldViolation" description: Describes all violations in a client request. "@type": type: string const: type.googleapis.com/google.rpc.BadRequest title: BadRequestErrorDetail description: |- Describes violations in a client request. This error type focuses on the syntactic aspects of the request. required: - "@type" DebugInfo: type: object properties: stackEntries: type: array items: type: string description: The stack trace entries indicating where the error occurred. detail: type: string description: Additional debugging information provided by the server. title: DebugInfo description: Describes additional debugging info. DebugInfoErrorDetail: type: object properties: stackEntries: type: array items: type: string description: The stack trace entries indicating where the error occurred. detail: type: string description: Additional debugging information provided by the server. "@type": type: string const: type.googleapis.com/google.rpc.DebugInfo title: DebugInfoErrorDetail description: Describes additional debugging info. required: - "@type" ErrorInfo: type: object properties: reason: type: string description: |- The reason of the error. This is a constant value that identifies the proximate cause of the error. Error reasons are unique within a particular domain of errors. This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents UPPER_SNAKE_CASE. domain: type: string description: |- The logical grouping to which the "reason" belongs. The error domain is typically the registered service name of the tool or product that generates the error. Example: "pubsub.googleapis.com". If the error is generated by some common infrastructure, the error domain must be a globally unique value that identifies the infrastructure. For Google API infrastructure, the error domain is "googleapis.com". metadata: type: object additionalProperties: type: string title: value description: |- Additional structured details about this error. Keys must match a regular expression of `[a-z][a-zA-Z0-9-_]+` but should ideally be lowerCamelCase. Also, they must be limited to 64 characters in length. When identifying the current value of an exceeded limit, the units should be contained in the key, not the value. For example, rather than `{"instanceLimit": "100/request"}`, should be returned as, `{"instanceLimitPerRequest": "100"}`, if the client exceeds the number of instances that can be created in a single (batch) request. title: ErrorInfo description: |- Describes the cause of the error with structured details. Example of an error when contacting the "pubsub.googleapis.com" API when it is not enabled: { "reason": "API_DISABLED" "domain": "googleapis.com" "metadata": { "resource": "projects/123", "service": "pubsub.googleapis.com" } } This response indicates that the pubsub.googleapis.com API is not enabled. Example of an error that is returned when attempting to create a Spanner instance in a region that is out of stock: { "reason": "STOCKOUT" "domain": "spanner.googleapis.com", "metadata": { "availableRegions": "us-central1,us-east2" } } ErrorInfoErrorDetail: type: object properties: reason: type: string description: |- The reason of the error. This is a constant value that identifies the proximate cause of the error. Error reasons are unique within a particular domain of errors. This should be at most 63 characters and match a regular expression of `[A-Z][A-Z0-9_]+[A-Z0-9]`, which represents UPPER_SNAKE_CASE. domain: type: string description: |- The logical grouping to which the "reason" belongs. The error domain is typically the registered service name of the tool or product that generates the error. Example: "pubsub.googleapis.com". If the error is generated by some common infrastructure, the error domain must be a globally unique value that identifies the infrastructure. For Google API infrastructure, the error domain is "googleapis.com". metadata: type: object additionalProperties: type: string title: value description: |- Additional structured details about this error. Keys must match a regular expression of `[a-z][a-zA-Z0-9-_]+` but should ideally be lowerCamelCase. Also, they must be limited to 64 characters in length. When identifying the current value of an exceeded limit, the units should be contained in the key, not the value. For example, rather than `{"instanceLimit": "100/request"}`, should be returned as, `{"instanceLimitPerRequest": "100"}`, if the client exceeds the number of instances that can be created in a single (batch) request. "@type": type: string const: type.googleapis.com/google.rpc.ErrorInfo title: ErrorInfoErrorDetail description: |- Describes the cause of the error with structured details. Example of an error when contacting the "pubsub.googleapis.com" API when it is not enabled: { "reason": "API_DISABLED" "domain": "googleapis.com" "metadata": { "resource": "projects/123", "service": "pubsub.googleapis.com" } } This response indicates that the pubsub.googleapis.com API is not enabled. Example of an error that is returned when attempting to create a Spanner instance in a region that is out of stock: { "reason": "STOCKOUT" "domain": "spanner.googleapis.com", "metadata": { "availableRegions": "us-central1,us-east2" } } required: - "@type" Help: type: object properties: links: type: array items: $ref: "#/components/schemas/HelpLink" description: URL(s) pointing to additional information on handling the current error. title: Help description: |- Provides links to documentation or for performing an out of band action. For example, if a quota check failed with an error indicating the calling project hasn't enabled the accessed service, this can contain a URL pointing directly to the right place in the developer console to flip the bit. HelpLink: type: object properties: description: type: string description: Describes what the link offers. url: type: string description: The URL of the link. title: Link description: Describes a URL link. HelpErrorDetail: type: object properties: links: type: array items: $ref: "#/components/schemas/HelpLink" description: URL(s) pointing to additional information on handling the current error. "@type": type: string const: type.googleapis.com/google.rpc.Help title: HelpErrorDetail description: |- Provides links to documentation or for performing an out of band action. For example, if a quota check failed with an error indicating the calling project hasn't enabled the accessed service, this can contain a URL pointing directly to the right place in the developer console to flip the bit. required: - "@type" LocalizedMessage: type: object properties: locale: type: string description: |- The locale used following the specification defined at https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Examples are: "en-US", "fr-CH", "es-MX" message: type: string description: The localized error message in the above locale. title: LocalizedMessage description: |- Provides a localized error message that is safe to return to the user which can be attached to an operation error. LocalizedMessageErrorDetail: type: object properties: locale: type: string description: |- The locale used following the specification defined at https://www.rfc-editor.org/rfc/bcp/bcp47.txt. Examples are: "en-US", "fr-CH", "es-MX" message: type: string description: The localized error message in the above locale. "@type": type: string const: type.googleapis.com/google.rpc.LocalizedMessage title: LocalizedMessageErrorDetail description: |- Provides a localized error message that is safe to return to the user which can be attached to an operation error. required: - "@type" PreconditionFailure: type: object properties: violations: type: array items: $ref: "#/components/schemas/PreconditionFailureViolation" description: Describes all precondition violations. title: PreconditionFailure description: |- Describes what preconditions have failed. For example, if an operation failed because it required the Terms of Service to be acknowledged, it could list the terms of service violation in the PreconditionFailure message. PreconditionFailureViolation: type: object properties: type: type: string description: |- The type of PreconditionFailure. We recommend using a service-specific enum type to define the supported precondition violation subjects. For example, "TOS" for "Terms of Service violation". subject: type: string description: |- The subject, relative to the type, that failed. For example, "google.com/cloud" relative to the "TOS" type would indicate which terms of service is being referenced. description: type: string description: |- A description of how the precondition failed. Developers can use this description to understand how to fix the failure. For example: "Terms of service not accepted". title: Violation description: A message type used to describe a single precondition failure. PreconditionFailureErrorDetail: type: object properties: violations: type: array items: $ref: "#/components/schemas/PreconditionFailureViolation" description: Describes all precondition violations. "@type": type: string const: type.googleapis.com/google.rpc.PreconditionFailure title: PreconditionFailureErrorDetail description: |- Describes what preconditions have failed. For example, if an operation failed because it required the Terms of Service to be acknowledged, it could list the terms of service violation in the PreconditionFailure message. required: - "@type" QuotaFailure: type: object properties: violations: type: array items: $ref: "#/components/schemas/QuotaFailureViolation" description: Describes all quota violations. title: QuotaFailure description: |- Describes how a quota check failed. For example if a daily limit was exceeded for the calling project, a service could respond with a QuotaFailure detail containing the project id and the description of the quota limit that was exceeded. If the calling project hasn't enabled the service in the developer console, then a service could respond with the project id and set `service_disabled` to true. Also see RetryInfo and Help types for other details about handling a quota failure. QuotaFailureViolation: type: object properties: subject: type: string description: |- The subject on which the quota check failed. For example, "clientip:" or "project:". description: type: string description: |- A description of how the quota check failed. Clients can use this description to find more about the quota configuration in the service's public documentation, or find the relevant quota limit to adjust through developer console. For example: "Service disabled" or "Daily Limit for read operations exceeded". apiService: type: string description: |- The API Service from which the `QuotaFailure.Violation` orginates. In some cases, Quota issues originate from an API Service other than the one that was called. In other words, a dependency of the called API Service could be the cause of the `QuotaFailure`, and this field would have the dependency API service name. For example, if the called API is Kubernetes Engine API (container.googleapis.com), and a quota violation occurs in the Kubernetes Engine API itself, this field would be "container.googleapis.com". On the other hand, if the quota violation occurs when the Kubernetes Engine API creates VMs in the Compute Engine API (compute.googleapis.com), this field would be "compute.googleapis.com". quotaMetric: type: string description: |- The metric of the violated quota. A quota metric is a named counter to measure usage, such as API requests or CPUs. When an activity occurs in a service, such as Virtual Machine allocation, one or more quota metrics may be affected. For example, "compute.googleapis.com/cpus_per_vm_family", "storage.googleapis.com/internet_egress_bandwidth". quotaId: type: string description: |- The id of the violated quota. Also know as "limit name", this is the unique identifier of a quota in the context of an API service. For example, "CPUS-PER-VM-FAMILY-per-project-region". quotaDimensions: type: object additionalProperties: type: string title: value description: |- The dimensions of the violated quota. Every non-global quota is enforced on a set of dimensions. While quota metric defines what to count, the dimensions specify for what aspects the counter should be increased. For example, the quota "CPUs per region per VM family" enforces a limit on the metric "compute.googleapis.com/cpus_per_vm_family" on dimensions "region" and "vm_family". And if the violation occurred in region "us-central1" and for VM family "n1", the quota_dimensions would be, { "region": "us-central1", "vm_family": "n1", } When a quota is enforced globally, the quota_dimensions would always be empty. quotaValue: type: - integer - string format: int64 description: |- The enforced quota value at the time of the `QuotaFailure`. For example, if the enforced quota value at the time of the `QuotaFailure` on the number of CPUs is "10", then the value of this field would reflect this quantity. futureQuotaValue: type: - integer - string - "null" format: int64 description: |- The new quota value being rolled out at the time of the violation. At the completion of the rollout, this value will be enforced in place of quota_value. If no rollout is in progress at the time of the violation, this field is not set. For example, if at the time of the violation a rollout is in progress changing the number of CPUs quota from 10 to 20, 20 would be the value of this field. title: Violation description: |- A message type used to describe a single quota violation. For example, a daily quota or a custom quota that was exceeded. QuotaFailureErrorDetail: type: object properties: violations: type: array items: $ref: "#/components/schemas/QuotaFailureViolation" description: Describes all quota violations. "@type": type: string const: type.googleapis.com/google.rpc.QuotaFailure title: QuotaFailureErrorDetail description: |- Describes how a quota check failed. For example if a daily limit was exceeded for the calling project, a service could respond with a QuotaFailure detail containing the project id and the description of the quota limit that was exceeded. If the calling project hasn't enabled the service in the developer console, then a service could respond with the project id and set `service_disabled` to true. Also see RetryInfo and Help types for other details about handling a quota failure. required: - "@type" RequestInfo: type: object properties: requestId: type: string description: |- An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. servingData: type: string description: |- Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. title: RequestInfo description: |- Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. RequestInfoErrorDetail: type: object properties: requestId: type: string description: |- An opaque string that should only be interpreted by the service generating it. For example, it can be used to identify requests in the service's logs. servingData: type: string description: |- Any data that was used to serve this request. For example, an encrypted stack trace that can be sent back to the service provider for debugging. "@type": type: string const: type.googleapis.com/google.rpc.RequestInfo title: RequestInfoErrorDetail description: |- Contains metadata about the request that clients can attach when filing a bug or providing other forms of feedback. required: - "@type" ResourceInfo: type: object properties: resourceType: type: string description: |- A name for the type of resource being accessed, e.g. "sql table", "cloud storage bucket", "file", "Google calendar"; or the type URL of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". resourceName: type: string description: |- The name of the resource being accessed. For example, a shared calendar name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current error is [CodePERMISSION_DENIED][CodePERMISSION_DENIED]. owner: type: string description: |- The owner of the resource (optional). For example, "user:" or "project:". description: type: string description: |- Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the `writer` permission on the developer console project. title: ResourceInfo description: Describes the resource that is being accessed. ResourceInfoErrorDetail: type: object properties: resourceType: type: string description: |- A name for the type of resource being accessed, e.g. "sql table", "cloud storage bucket", "file", "Google calendar"; or the type URL of the resource: e.g. "type.googleapis.com/google.pubsub.v1.Topic". resourceName: type: string description: |- The name of the resource being accessed. For example, a shared calendar name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current error is [CodePERMISSION_DENIED][CodePERMISSION_DENIED]. owner: type: string description: |- The owner of the resource (optional). For example, "user:" or "project:". description: type: string description: |- Describes what error is encountered when accessing this resource. For example, updating a cloud project may require the `writer` permission on the developer console project. "@type": type: string const: type.googleapis.com/google.rpc.ResourceInfo title: ResourceInfoErrorDetail description: Describes the resource that is being accessed. required: - "@type" RetryInfo: type: object properties: retryDelay: description: Clients should wait at least this long between retrying the same request. $ref: "#/components/schemas/Duration" title: RetryInfo description: |- Describes when the clients can retry a failed request. Clients could ignore the recommendation here or retry when this information is missing from error responses. It's always recommended that clients should use exponential backoff when retrying. Clients should wait until `retry_delay` amount of time has passed since receiving the error response before retrying. If retrying requests also fail, clients should use an exponential backoff scheme to gradually increase the delay between retries based on `retry_delay`, until either a maximum number of retries have been reached or a maximum retry delay cap has been reached. RetryInfoErrorDetail: type: object properties: retryDelay: description: Clients should wait at least this long between retrying the same request. $ref: "#/components/schemas/Duration" "@type": type: string const: type.googleapis.com/google.rpc.RetryInfo title: RetryInfoErrorDetail description: |- Describes when the clients can retry a failed request. Clients could ignore the recommendation here or retry when this information is missing from error responses. It's always recommended that clients should use exponential backoff when retrying. Clients should wait until `retry_delay` amount of time has passed since receiving the error response before retrying. If retrying requests also fail, clients should use an exponential backoff scheme to gradually increase the delay between retries based on `retry_delay`, until either a maximum number of retries have been reached or a maximum retry delay cap has been reached. required: - "@type" UpdateSecretBody: type: object allOf: - properties: serviceType: type: string description: service_type identifies the consuming service. - oneOf: - type: object properties: custom: description: |- custom stores an opaque value with caller-authored injection metadata. UpdateSecretRequest.service_type is server-assigned for custom material; leave it empty. $ref: "#/components/schemas/CustomSecretMaterial" title: custom required: - custom - type: object properties: oauth: description: oauth stores OAuth refresh material. $ref: "#/components/schemas/OAuthRefreshMaterial" title: oauth required: - oauth - type: object properties: token: description: token stores opaque token material. $ref: "#/components/schemas/TokenSecretMaterial" title: token required: - token title: UpdateSecretRequest unevaluatedProperties: false description: |- UpdateSecretRequest replaces secret material. service_type must be empty for custom material (server-assigned) securitySchemes: bearer: type: http scheme: bearer description: A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions. sandboxBearer: type: http scheme: bearer description: A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted. sandboxWebSocketBearer: type: apiKey in: header name: Sec-WebSocket-Protocol description: Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization. security: - bearer: [] tags: - name: Files description: Read, write, copy, and manage files inside a sandbox. x-displayName: Files kind: nav summary: Files - name: Processes description: Run commands and interact with processes inside a sandbox. x-displayName: Processes kind: nav summary: Processes - name: Credentials description: Exchange credentials for the authenticated owner. x-displayName: Credentials kind: nav summary: Credentials - name: Images description: Manage images used to create sandboxes. x-displayName: Images kind: nav summary: Images - name: MCP gateways description: Configure MCP gateways and authorize upstream servers. x-displayName: MCP gateways kind: nav summary: MCP gateways - name: Network policies description: Read enforced outbound network policies and their decision logs. x-displayName: Network policies kind: nav summary: Network policies - name: Sandboxes description: Create sandboxes and manage their lifecycle, ports, and SSH access. x-displayName: Sandboxes kind: nav summary: Sandboxes - name: Secrets description: Store credentials and read their metadata without returning secret material. x-displayName: Secrets kind: nav summary: Secrets - name: Snapshots description: Capture sandbox state and restore it into a new sandbox. x-displayName: Snapshots kind: nav summary: Snapshots - name: Volumes description: Manage persistent storage and attach it to sandboxes. x-displayName: Volumes kind: nav summary: Volumes jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base