Secure, Fast, and Extensible Sandbox runtime for AI agents.
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/**
* This file was auto-generated by openapi-typescript.
* Do not make direct changes to the file.
*/
export interface paths {
"/sandboxes/{sandboxId}/networkpolicy": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
/**
* Read sandbox network policy
* @description Fsb reads the egress-held policy record — the response reflects
* exactly what the egress enforces, not the create-time binding input.
* Other backends proxy the sandbox-side egress service. Requires
* lifecycle API authentication.
*/
get: operations["getSandboxNetworkPolicy"];
/**
* Replace the complete sandbox network policy
* @description Replaces defaultAction and all rules, rather than merging them. Fsb
* relays the replacement to the egress-held policy record through the
* FastPath handler relay — the ack means the egress applied it (and, with
* policy persistence, that it is durable). The create-time binding input
* is the bootstrap only; runtime changes never rewrite it, and a paused
* (sealed) sandbox rejects mutations until resume. Other backends proxy
* the sandbox-side egress service.
*/
put: operations["replaceSandboxNetworkPolicy"];
post?: never;
/**
* Delete sandbox network policy rules by target
* @description Removes egress rules whose target matches one of the provided
* entries. Matching is by exact target string; unknown targets are
* silently ignored (idempotent). The current defaultAction is
* preserved. Other backends proxy the sandbox-side egress service.
*/
delete: operations["deleteSandboxNetworkPolicyRules"];
options?: never;
head?: never;
/**
* Patch sandbox network policy rules
* @description Merges egress rules into the current policy using the same semantics
* as the sandbox-side egress service PATCH endpoint: incoming rules
* take priority over existing rules with the same target and replace
* them in place; within one patch payload, the first rule for a target
* wins; existing rules for other targets and the current defaultAction
* are preserved. Fsb composes the merge server-side (relay GET → merge
* → relay PUT carrying the read revision) — a concurrent writer wins
* and the stale merge is a 409. Other backends proxy the sandbox-side
* egress service.
*/
patch: operations["patchSandboxNetworkPolicy"];
trace?: never;
};
"/sandboxes/{sandboxId}/credential-vault": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
/**
* Read sanitized sandbox Credential Vault state
* @description Returns the sanitized Credential Vault state: credential names,
* source types, binding metadata and the current revision. Credential
* values are never returned on any read surface. Readback after a lost
* mutation ack resolves the current revision (retry anchor for 412).
* Other backends proxy the sandbox-side egress service.
*/
get: operations["getSandboxCredentialVault"];
put?: never;
/**
* Create the sandbox Credential Vault
* @description Creates the initial Credential Vault revision and activates it for
* credential injection. Inline credential values are write-only and are
* never returned by any read. Credential Vault requires a network
* policy; `defaultAction: deny` is strongly recommended.
*
* For Fsb the server relays the revision to the egress-held vault over
* the FastPath handler relay; the relay response is the synchronous
* egress-validated ack, so success means the sandbox has loaded the
* revision (create-only: 409 when a vault already exists, atomic across
* server replicas). Other backends proxy the sandbox-side egress
* service with sidecar semantics.
*/
post: operations["createSandboxCredentialVault"];
/**
* Delete the sandbox Credential Vault
* @description Removes all credentials and bindings; the network policy is kept.
* Other backends proxy the sandbox-side egress service.
*/
delete: operations["deleteSandboxCredentialVault"];
options?: never;
head?: never;
/**
* Atomically mutate sandbox credentials and bindings
* @description Applies one atomic mutation set: `delete` first, then `replace`, then
* `add` (per set). Every mentioned name must resolve exactly once —
* `add` requires the name to be absent; `replace` and `delete` require
* it to exist. `expectedRevision`, when provided, must match the
* current revision (412 otherwise).
*
* For Fsb the merge is composed server-side (relay read → in-memory
* merge → relay replace) and validated by the egress vault; a rejected
* mutation never leaves a partially applied revision (last-good kept).
* Other backends proxy the sandbox-side egress service. On 412, re-read
* the state and retry with the fresh revision.
*/
patch: operations["patchSandboxCredentialVault"];
trace?: never;
};
"/sandboxes/{sandboxId}/credential-vault/credentials": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
/**
* List sanitized credential metadata
* @description Returns sanitized credential metadata (names, source types,
* per-record revisions); values are never returned. Other backends
* proxy the sandbox-side egress service.
*/
get: operations["listSandboxCredentialVaultCredentials"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/credential-vault/credentials/{credentialName}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
/** @description Credential name */
credentialName: string;
};
cookie?: never;
};
/**
* Get sanitized metadata for one credential
* @description Returns sanitized metadata for a single credential; values are never
* returned. Other backends proxy the sandbox-side egress service.
*/
get: operations["getSandboxCredentialVaultCredential"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/credential-vault/bindings": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
/**
* List sanitized credential binding metadata
* @description Returns sanitized credential binding metadata (matchers and auth
* shapes without credential values). Other backends proxy the
* sandbox-side egress service.
*/
get: operations["listSandboxCredentialVaultBindings"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/credential-vault/bindings/{bindingName}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
/** @description Credential binding name */
bindingName: string;
};
cookie?: never;
};
/**
* Get sanitized metadata for one binding
* @description Returns sanitized metadata for a single credential binding; values
* are never returned. Other backends proxy the sandbox-side egress
* service.
*/
get: operations["getSandboxCredentialVaultBinding"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/metrics/events": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Report an SDK metrics event
* @description Accepts best-effort telemetry from SDKs (Phase 1: sandbox creation latency).
*
* SDKs SHOULD fire-and-forget this call after `create` + readiness complete
* (or after a failed creation attempt). Failures to report MUST NOT affect
* sandbox usability. The server accepts events even when OpenTelemetry
* export is disabled (noop recording).
*
* SDK language and version are taken from the HTTP `User-Agent` header
* (for example `OpenSandbox-Python-SDK/0.1.14`), not from the JSON body.
*/
post: operations["reportMetricsEvent"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* List sandboxes
* @description List all sandboxes with optional filtering and pagination using query parameters.
* All filter conditions use AND logic. Multiple `state` parameters use OR logic within states.
*/
get: {
parameters: {
query?: {
/**
* @description Filter by lifecycle state. Pass multiple times for OR logic.
* Example: `?state=Running&state=Paused`
*/
state?: string[];
/**
* @description Arbitrary metadata key-value pairs for filtering,keys and values must be url encoded
* Example: To filter by `project=Apollo` and `note=Demo Test`: `?metadata=project%3DApollo%26note%3DDemo%252520Test`
*/
metadata?: string;
/** @description Page number for pagination */
page?: number;
/** @description Number of items per page */
pageSize?: number;
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Paginated collection of sandboxes */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ListSandboxesResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
500: components["responses"]["InternalServerError"];
};
};
put?: never;
/**
* Create a sandbox
* @description Creates a new sandbox from a container image, restores one from a
* persistent sandbox snapshot, or allocates one from a pre-configured
* Pool, with optional resource limits, environment variables, and metadata.
*
* Standard mode requires exactly one startup source:
* - `image` to provision directly from a container image.
* - `snapshotId` to restore from a previously created snapshot.
*
* Pool mode uses `extensions.poolRef` to select the pre-created Pod and
* schedules a per-allocation task; `image` and `snapshotId` are not
* required.
*
* When `image` is provided, `entrypoint` is required. When `snapshotId` is
* provided, `entrypoint` is optional. If omitted, the server defaults the
* sandbox entrypoint to `["tail", "-f", "/dev/null"]`.
*
* ## Authentication
*
* API Key authentication is required via:
* - `OPEN-SANDBOX-API-KEY: <api-key>` header
*/
post: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["CreateSandboxRequest"];
};
};
responses: {
/**
* @description Sandbox created and provisioned successfully.
*
* The returned sandbox includes:
* - `id`: Unique sandbox identifier
* - `status.state: "Running"` (provisioning completed synchronously)
* - `status.reason` and `status.message` indicating current state
* - `metadata`, `expiresAt`, `createdAt`: Core sandbox information
*
* Note: startup source details and `updatedAt` are not included in the create response.
* Use GET /sandboxes/{sandboxId} to retrieve the complete sandbox information.
*/
202: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
Location: components["headers"]["Location"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CreateSandboxResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
/**
* @description Namespace ResourceQuota exhausted — the sandbox was not admitted.
*
* The returned `ErrorResponse.code` is `KUBERNETES::QUOTA_EXCEEDED` and
* `message` carries the Kubernetes admission rejection details.
*
* This fail-fast behavior applies when the `agent-sandbox` workload
* provider is used. With the default `batchsandbox` provider, quota
* exhaustion currently waits for the sandbox creation timeout.
*/
403: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
409: components["responses"]["Conflict"];
/** @description Pool capacity remained unavailable before the acquisition timeout */
429: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
"Retry-After": components["headers"]["RetryAfter"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
500: components["responses"]["InternalServerError"];
};
};
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/snapshots": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* List snapshots
* @description List all snapshots with optional filtering and pagination using query parameters.
* Snapshots are persistent captures of sandbox state and may outlive the source sandbox.
*/
get: {
parameters: {
query?: {
/** @description Filter snapshots by source sandbox identifier */
sandboxId?: string;
/** @description Filter snapshots by exact snapshot name */
name?: string;
/**
* @description Filter by snapshot lifecycle state. Pass multiple times for OR logic.
* Example: `?state=Ready&state=Failed`
*/
state?: components["schemas"]["SnapshotState"][];
/** @description Page number for pagination */
page?: number;
/** @description Number of items per page */
pageSize?: number;
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Paginated collection of snapshots */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ListSnapshotsResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
500: components["responses"]["InternalServerError"];
};
};
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/snapshots/{snapshotId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique snapshot identifier */
snapshotId: components["parameters"]["SnapshotId"];
};
cookie?: never;
};
/**
* Fetch a snapshot by id
* @description Returns snapshot state and metadata.
*/
get: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique snapshot identifier */
snapshotId: components["parameters"]["SnapshotId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Snapshot current state and metadata */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Snapshot"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
put?: never;
post?: never;
/**
* Delete a snapshot
* @description Delete a persistent sandbox snapshot by id. Snapshots that are still
* being created cannot be deleted.
*
* For Kubernetes-backed snapshots, deletion removes OpenSandbox metadata
* and Kubernetes coordination resources, but does not guarantee removal
* of pushed OCI images from the configured registry. Use registry
* retention or garbage collection policies for image lifecycle cleanup.
*/
delete: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique snapshot identifier */
snapshotId: components["parameters"]["SnapshotId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Snapshot successfully deleted */
204: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content?: never;
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
/**
* Fetch a sandbox by id
* @description Returns the complete sandbox information including:
* - `id`, `status`, `metadata`, `expiresAt`, `createdAt`: Core information
* - `image` or `snapshotId`: Startup source information (not included in create response)
* - `entrypoint`: Entry process specification
*
* This is the complete representation of the sandbox resource.
*/
get: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sandbox current state and metadata */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Sandbox"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
};
};
put?: never;
post?: never;
/**
* Delete a sandbox
* @description Request sandbox deletion. Runtime cleanup may continue after the response.
* For Kubernetes BatchSandbox workloads, queries report Stopping during cleanup
* and return 404 once the resource is removed.
*/
delete: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sandbox deletion accepted. Runtime cleanup may still be in progress. */
204: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content?: never;
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/metadata": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
get?: never;
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
/**
* Patch sandbox metadata
* @description Update sandbox metadata using JSON Merge Patch semantics (RFC 7396).
*
* **Merge Patch rules:**
* | Request body key/value | Behavior |
* |---|---|
* | `"key": "value"` | Add or replace the key |
* | `"key": null` | Delete the key (silently ignored if key does not exist) |
* | key absent | Keep current value (no change) |
* | Empty `{}` | No-op, returns current metadata |
*
* Metadata keys and values must comply with Kubernetes label rules:
* - Keys must be valid DNS label names or prefixed DNS subdomains
* - Keys with the `opensandbox.io/` prefix are reserved and rejected
* - Values must be 63 characters or less, matching `[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?`
*
* This operation does not restart or recreate the sandbox container/pod.
*
* **Concurrency:** On the Docker runtime concurrent PATCH requests apply
* one after another, last write wins per key. On Kubernetes a PATCH
* writes back the whole label set it read, with no `resourceVersion`
* check, so a concurrent PATCH may revert a value another PATCH changed
* or resurrect a key it deleted. A PATCH on an fsb sandbox sends only its
* own keys, fenced by the sandbox UID and generation. Use a single writer
* or coordinate out-of-band when concurrent modifications to the same
* key are expected.
*/
patch: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["PatchSandboxMetadataRequest"];
};
};
responses: {
/**
* @description Metadata patched successfully. Returns the complete sandbox resource
* with updated metadata.
*/
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Sandbox"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
trace?: never;
};
"/sandboxes/{sandboxId}/snapshots": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Create a snapshot from a sandbox
* @description Create a persistent point-in-time snapshot from the sandbox's current state.
* The source sandbox must be `Running`. The returned snapshot id identifies
* the created artifact. Snapshot creation may temporarily pause the sandbox
* while the runtime captures provider-supported state, then the source
* sandbox continues running.
*/
post: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: {
content: {
"application/json": components["schemas"]["CreateSnapshotRequest"];
};
};
responses: {
/**
* @description Snapshot creation accepted.
*
* The returned snapshot includes `status.state: "Creating"`.
* Poll GET /snapshots/{snapshotId} to track progress until the snapshot
* transitions to `Ready` or `Failed`.
*/
202: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
Location: components["headers"]["Location"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Snapshot"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/pause": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Pause execution while retaining state
* @description Pause a running sandbox while preserving its state. Poll GET /sandboxes/{sandboxId} to track state transition through Pausing and eventually Paused.
*/
post: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/**
* @description Pause operation accepted.
*
* Sandbox will transition to Pausing state and eventually Paused.
* Poll GET /sandboxes/{sandboxId} to track progress.
*/
202: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content?: never;
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/resume": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Resume a paused sandbox
* @description Resume execution of a paused sandbox. Poll GET /sandboxes/{sandboxId} to track state transition through Resuming and eventually Running.
*/
post: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/**
* @description Resume operation accepted.
*
* Sandbox will transition from Paused → Resuming → Running.
* Poll GET /sandboxes/{sandboxId} to track progress.
*/
202: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content?: never;
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/renew-expiration": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
get?: never;
put?: never;
/**
* Renew sandbox expiration
* @description Set the absolute expiration time of a sandbox to the supplied future timestamp.
* This may shorten, preserve, or extend the current expiration.
* The server configuration `server.max_sandbox_timeout_seconds` applies only
* to `timeout` on creation and does not limit this operation.
*/
post: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["RenewSandboxExpirationRequest"];
};
};
responses: {
/**
* @description Sandbox expiration updated successfully.
*
* Returns only the updated expiresAt field.
*/
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["RenewSandboxExpirationResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
};
};
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/sandboxes/{sandboxId}/endpoints/{port}": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* Get sandbox access endpoint
* @description Get the public access endpoint URL for accessing a service running on a specific port
* within the sandbox. The service must be listening on the specified port inside
* the sandbox for the endpoint to be available.
*/
get: {
parameters: {
query?: {
/** @description Whether to return a server-proxied URL. Cannot be combined with `expires`. */
use_server_proxy?: boolean;
/**
* @description Optional. When set, the server **issues a signed** access route (OSEP-0011). The value
* is **Linux / Unix epoch seconds** — a decimal `uint64` count of **whole seconds** since
* the Unix epoch (`1970-01-01 00:00:00` UTC, same as POSIX / `time(2)`), not
* milliseconds. Normalized to `expires_b36` for the four-segment route token. Omit to
* get the unsigned/legacy response shape. Cannot be combined with `use_server_proxy=true`.
*/
expires?: string;
};
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
/** @description Port number where the service is listening inside the sandbox */
port: number;
};
cookie?: never;
};
requestBody?: never;
responses: {
/**
* @description Endpoint retrieved successfully.
*
* Returns the public URL for accessing the service on the specified port.
*/
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
OpenSandboxOrigin: components["headers"]["SandboxOrigin"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Endpoint"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
};
};
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/templates": {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
/**
* List fsb templates
* @description Lists the current tenant's templates with optional metadata filtering
* (AND logic) and pagination. Results never include other tenants'
* templates.
*/
get: operations["listTemplates"];
put?: never;
/**
* Create a fsb template
* @description Declares a golden-image build executed by fast-sandbox.
* Available on Kubernetes-backed runtimes (`kubernetes` and `fsb`);
* 501 otherwise (e.g. the Docker runtime).
*
* The build is asynchronous: the response carries `status.phase: Pending`;
* poll `GET /templates/{templateId}` until `Succeeded` (or `Failed` with
* `status.message`). Only `Succeeded` templates can back template-based
* sandbox creation. Kernel, execd and guest init are server-side build
* inputs supplied from the `[fsb]` configuration, not client fields.
*
* Templates are tenant-private: every template is scoped to the
* requester's fast-sandbox namespace.
*/
post: operations["createTemplate"];
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/templates/{templateId}": {
parameters: {
query?: never;
header?: never;
path: {
/** @description Template identifier (`tpl_<uuid>`) */
templateId: string;
};
cookie?: never;
};
/**
* Get a fsb template
* @description Returns one template with its build status. The status is lazily
* synced from the fast-sandbox SandboxTemplate CRD, so the response
* reflects the latest build phase.
*/
get: operations["getTemplate"];
put?: never;
post?: never;
/**
* Delete a fsb template
* @description Deletes the catalog row and the backing SandboxTemplate CRD.
* Sandboxes already created from the template are unaffected: their
* Sandbox CRs hold their own artifact references.
*/
delete: operations["deleteTemplate"];
options?: never;
head?: never;
patch?: never;
trace?: never;
};
}
export type webhooks = Record<string, never>;
export interface components {
schemas: {
/**
* @description SDK-reported metrics event. Phase 1 covers sandbox creation latency from
* the start of create until readiness succeeds or creation fails.
*
* SDK language and package version are identified via the request
* `User-Agent` header (for example `OpenSandbox-Go-SDK/0.1.0`), not body fields.
*/
MetricsEvent: {
/**
* @description Metric event type
* @enum {string}
*/
eventType: "sandbox.create";
/** @description Sandbox identifier when available (may be omitted if create failed before an ID was assigned) */
sandboxId?: string;
/** @description Container image URI or snapshot startup source label */
image?: string;
/** @description Wall-clock duration in milliseconds from create start to ready or failure */
createDurationMs: number;
/** @description Whether create + readiness completed successfully */
success: boolean;
};
ListSandboxesResponse: {
items: components["schemas"]["Sandbox"][];
pagination: components["schemas"]["PaginationInfo"];
};
ListSnapshotsResponse: {
items: components["schemas"]["Snapshot"][];
pagination: components["schemas"]["PaginationInfo"];
};
/** @description Pagination metadata for list responses */
PaginationInfo: {
/** @description Current page number */
page: number;
/** @description Number of items per page */
pageSize: number;
/** @description Total number of items matching the filter */
totalItems: number;
/** @description Total number of pages */
totalPages: number;
/** @description Whether there are more pages after the current one */
hasNextPage: boolean;
};
/** @description Response from creating a new sandbox. Contains essential information without startup source details and updatedAt. */
CreateSandboxResponse: {
/** @description Unique sandbox identifier */
id: string;
/** @description Current lifecycle status and detailed state information */
status: components["schemas"]["SandboxStatus"];
/** @description Custom metadata from creation request */
metadata?: {
[key: string]: string;
};
/** @description Opaque extension data restored from provider-specific storage */
extensions?: {
[key: string]: string;
};
/**
* @description Platform constraint echoed from request or workload template.
* Null when no scheduling constraint is provided.
*/
platform?: components["schemas"]["PlatformSpec"];
/**
* Format: date-time
* @description Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
*/
expiresAt?: string;
/**
* Format: date-time
* @description Sandbox creation timestamp
*/
createdAt: string;
/**
* @description Entry process specification for the sandbox. For image-created sandboxes,
* this is copied from the creation request. For snapshot-created sandboxes,
* this is restored from the snapshot.
*/
entrypoint: string[];
};
/** @description Optional settings for creating a sandbox snapshot. */
CreateSnapshotRequest: {
/** @description Optional human-readable snapshot name. */
name?: string;
};
/** @description Persistent point-in-time capture of a sandbox. */
Snapshot: {
/** @description Unique snapshot identifier */
id: string;
/** @description Source sandbox identifier used to create this snapshot */
sandboxId: string;
/** @description Optional human-readable snapshot name */
name?: string;
/** @description Current snapshot lifecycle status and detailed state information */
status: components["schemas"]["SnapshotStatus"];
/**
* Format: date-time
* @description Snapshot creation timestamp
*/
createdAt: string;
};
/**
* @description Snapshot lifecycle state.
*
* Common state values:
* - Creating: Snapshot creation has been accepted and runtime capture is in progress.
* - Deleting: Snapshot deletion has been requested and cleanup is in progress.
* - Ready: Snapshot is available for restoring sandboxes.
* - Failed: Snapshot creation failed.
*
* Note: New state values may be added in future versions.
* Clients should handle unknown state values gracefully.
*/
SnapshotState: string;
/** @description Detailed snapshot status information with lifecycle state and transition details. */
SnapshotStatus: {
/** @description Current lifecycle state of the snapshot */
state: components["schemas"]["SnapshotState"];
/**
* @description Short machine-readable reason code for the current state.
* Examples: "snapshot_accepted", "snapshot_ready", "snapshot_capture_failed"
*/
reason?: string;
/** @description Human-readable message describing the current state or failure reason */
message?: string;
/**
* Format: date-time
* @description Timestamp of the last state transition
*/
lastTransitionAt?: string;
};
/** @description Runtime execution environment provisioned from a container image or restored from a snapshot */
Sandbox: {
/** @description Unique sandbox identifier */
id: string;
/**
* @description Container image specification used to provision this sandbox.
* Present when the sandbox was created directly from a container image.
* Not returned in createSandbox response.
*/
image?: components["schemas"]["ImageSpec"];
/**
* @description Snapshot identifier used to restore this sandbox.
* Present when the sandbox was restored from a snapshot.
* Not returned in createSandbox response.
*/
snapshotId?: string;
/**
* @description Platform constraint echoed from request or workload template.
* Null when no scheduling constraint is provided.
*/
platform?: components["schemas"]["PlatformSpec"];
/** @description Current lifecycle status and detailed state information */
status: components["schemas"]["SandboxStatus"];
/** @description Custom metadata from creation request */
metadata?: {
[key: string]: string;
};
/** @description Opaque extension data restored from provider-specific storage */
extensions?: {
[key: string]: string;
};
/**
* @description Current runtime-confirmed pool allocation. Omitted unless an active pool
* allocation is confirmed; this is not a request echo, allocation history,
* readiness signal, or Kubernetes introspection result.
*/
allocation?: components["schemas"]["AllocationSummary"];
/**
* @description The command to execute as the sandbox's entry process.
* Always present in responses. For image-created sandboxes, this is copied
* from the creation request. For snapshot-created sandboxes, this is restored
* from the snapshot.
*/
entrypoint: string[];
/**
* Format: date-time
* @description Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
*/
expiresAt?: string;
/**
* Format: date-time
* @description Sandbox creation timestamp
*/
createdAt: string;
};
/** @description Public summary of a confirmed active pool allocation. */
AllocationSummary: {
/**
* @description Allocation mode.
* @enum {string}
*/
mode: "pool";
/** @description Concrete pool reference currently allocated. */
poolRef: string;
/**
* @description Current confirmed allocation state.
* @enum {string}
*/
state: "allocated";
};
/**
* @description High-level lifecycle state of the sandbox.
*
* Common state values:
* - Pending: Sandbox is being provisioned
* - Running: Sandbox is running and ready to accept requests
* - Pausing: Sandbox is in the process of pausing
* - Paused: Sandbox has been paused while retaining its state
* - Resuming: Sandbox is being restored after a pause
* - Stopping: Sandbox is being terminated
* - Terminated: Sandbox has been successfully terminated
* - Failed: Sandbox encountered a critical error
*
* State transitions:
* - Pending → Running (after creation completes)
* - Running → Pausing (when pause is requested)
* - Pausing → Paused (pause operation completes)
* - Paused → Resuming (when resume is requested)
* - Resuming → Running (when resume operation completes)
* - Running/Paused → Stopping (when kill is requested or TTL expires)
* - Stopping → Terminated (kill/timeout operation completes)
* - Pending/Running/Paused/Resuming → Failed (on error)
*
* Note: New state values may be added in future versions.
* Clients should handle unknown state values gracefully.
*/
SandboxState: string;
/** @description Detailed status information with lifecycle state and transition details */
SandboxStatus: {
/** @description Current lifecycle state of the sandbox */
state: components["schemas"]["SandboxState"];
/**
* @description Short machine-readable reason code for the current state.
* Examples: "user_delete", "ttl_expiry", "provision_timeout", "runtime_error"
*/
reason?: string;
/** @description Human-readable message describing the current state or reason for state transition */
message?: string;
/**
* Format: date-time
* @description Timestamp of the last state transition
*/
lastTransitionAt?: string;
};
/**
* @description Container image specification for sandbox provisioning.
*
* Supports public registry images and private registry images with authentication.
*/
ImageSpec: {
/**
* @description Container image URI in standard format.
*
* Examples:
* - "python:3.11" (Docker Hub)
* - "ubuntu:22.04"
* - "gcr.io/my-project/model-server:v1.0"
* - "private-registry.company.com:5000/app:latest"
*/
uri: string;
/** @description Registry authentication credentials (required for private registries) */
auth?: {
/** @description Registry username or service account */
username?: string;
/** @description Registry password or authentication token */
password?: string;
};
};
/**
* @description Runtime platform constraint used for scheduling/provisioning.
*
* This field is independent from `image` and expresses the expected target
* OS and CPU architecture for sandbox execution.
*
* Behavioral notes:
* - If omitted, the runtime applies its own default platform selection behavior.
* For Docker, requests are created without an explicit platform override.
* For Kubernetes, no `kubernetes.io/os` or `kubernetes.io/arch` constraint
* is injected unless provided by request or workload template.
* - If provided and cannot be satisfied by runtime/template/pool constraints,
* request must fail explicitly.
*/
PlatformSpec: {
/**
* @description Target operating system (for example `linux` or `windows`).
* @example linux
* @enum {string}
*/
os: "linux" | "windows";
/**
* @description Target CPU architecture (for example `amd64` or `arm64`).
* @example arm64
* @enum {string}
*/
arch: "amd64" | "arm64";
};
/**
* @description A lifecycle command executed directly as an argv array. No implicit shell
* expansion is performed. Use an explicit shell command such as
* `["sh", "-c", "..."]` when shell syntax is required.
*/
LifecycleHook: {
/** @description Command and arguments to execute. */
command: string[];
/** @description Maximum execution time in seconds, up to 3 hours (10800 seconds) for `preStart`. The server defaults to 60 when omitted. */
timeoutSeconds?: number;
};
/** @description A named lifecycle command scheduled inside the sandbox by execd. */
PeriodicLifecycleHook: {
/** @description Name unique among periodic hooks in this sandbox. */
name: string;
/**
* @description Five-field cron expression or descriptor such as `@hourly` or
* `@every 30s`. An `@every` interval must be a whole number of
* seconds with a minimum of one second.
*/
schedule: string;
/** @description Command and arguments to execute without implicit shell expansion. */
command: string[];
/** @description Maximum execution time in seconds, up to 300. The server defaults to 60 when omitted. */
timeoutSeconds?: number;
};
/**
* @description Extensible container for sandbox lifecycle configuration. All fields
* are optional. Future lifecycle events are added as new optional
* fields without changing the semantics of existing fields.
*
* `preStart` and `periodic` are hooks executed inside the sandbox by
* execd. `idlePolicy` (OSEP-0024) and `renewalPolicy` (OSEP-0009) are
* control-plane policies: they tell the server how to treat the
* sandbox's state machine and never reach the guest.
*/
SandboxLifecycle: {
/**
* @description Runs in execd after its HTTP server is ready and before the user
* entrypoint on every sandbox container start. A failed or timed-out
* hook prevents the user entrypoint from starting.
*/
preStart?: components["schemas"]["LifecycleHook"];
/**
* @description Scheduled hooks run by execd while the sandbox is running. Runs of
* the same named hook never overlap; a scheduled run is skipped when
* its previous run is still active.
*/
periodic?: components["schemas"]["PeriodicLifecycleHook"][];
/**
* @description Auto-pause and wake-on-access behavior (OSEP-0024). Supported only
* by the fast-sandbox backend; other backends reject the field.
* Omitting `idlePolicy` preserves non-automated behavior exactly:
* the sandbox is never auto-paused and never auto-woken.
*/
idlePolicy?: components["schemas"]["IdlePolicy"];
/**
* @description Renew-on-access behavior (OSEP-0009): each ingress-observed or
* proxied access extends the sandbox expiration. Control-plane
* state and never reaches the guest. Supported by the docker and
* Kubernetes (pod) backends; the fast-sandbox backend rejects the
* field. Supersedes the deprecated
* `extensions["access.renew.extend.seconds"]` creation key, which
* remains supported throughout 1.x and is removed in 2.0.
*/
renewalPolicy?: components["schemas"]["RenewalPolicy"];
};
/**
* @description Renew-on-access behavior declared by the sandbox (OSEP-0009). The
* policy is desired control-plane state: when the ingress gateway or
* the server proxy observes traffic for the sandbox, the server extends
* the sandbox expiration without client involvement. The policy never
* reaches the guest.
*
* Setting the policy has no effect unless the server operator enabled
* the renew-intent integration (`[renew_intent]`). A missing policy
* means the sandbox never auto-renews.
*/
RenewalPolicy: {
/**
* @description Extension window X in seconds for each access-driven renewal:
* the expiration is moved to `max(now + X, current expiresAt)`.
* Must be between 300 (5 minutes) and 86400 (24 hours) inclusive.
*/
extendSeconds: number;
};
/**
* @description Idle behavior declared by the sandbox (OSEP-0024). The policy is
* desired state: the server validates it and persists it as the
* reserved `sandbox.opensandbox.io/idle-policy` Sandbox CR annotation.
*
* With `idleTimeoutSeconds`, the sandbox is auto-paused after that many
* seconds without ingress-observed activity. Without it, the policy is
* wake-only: the sandbox is never auto-paused, but a (manually) paused
* sandbox wakes on access. A missing, malformed, or invalid policy is
* treated exactly as absent — never as an implicit opt-in.
*
* Constraints: `idleTimeoutSeconds` must not exceed the server's
* configured activity TTL (default 1800), so a present-but-stale
* activity key always implies idle-by-value. Enabling deployment flags
* never changes the behavior of sandboxes that do not declare a policy.
*/
IdlePolicy: {
/**
* @description Idle threshold X in seconds: the sandbox is auto-paused after X
* continuously idle seconds. Absent together with `onIdle` means a
* wake-only policy.
*/
idleTimeoutSeconds?: number;
/**
* @description Action taken at the idle threshold. Required with, and only
* valid with, `idleTimeoutSeconds`. Only `pause` exists today; the
* enum exists so future actions are additive.
* @enum {string}
*/
onIdle?: "pause";
/**
* @description Whether incoming traffic may wake the sandbox from `Paused`.
* Defaults to `true` when omitted.
* `false` keeps today's paused behavior (permanent 503 through the
* gateway) and only `POST /sandboxes/{sandboxId}/resume` restores
* the sandbox.
*/
wakeOnAccess?: boolean;
/**
* @description Application-declared activity probe. When the sandbox is
* otherwise idle, the server issues `GET {path}` on `{port}`;
* `200 {"active": true}` counts as activity and resets the idle
* clock, while `{"active": false}`, any failure, or a timeout
* records nothing. Relevant only with auto-pause.
*/
activeProbe?: components["schemas"]["ActivityProbe"];
};
/**
* @description Endpoint inside the sandbox that answers `{"active": bool,
* "message"?: string}` with 200 while work is in progress.
*/
ActivityProbe: {
/** @description Sandbox port serving the probe endpoint. */
port: number;
/**
* @description Absolute HTTP path of the probe endpoint. Must not contain
* whitespace or control characters.
*/
path: string;
/** @description Probe request budget in seconds. The server defaults to 2 when omitted. */
timeoutSeconds?: number;
};
/**
* @description JSON Merge Patch (RFC 7396) request body for updating sandbox metadata.
*
* The request body is the metadata object itself:
* - Present keys with non-null values add or replace
* - Keys with `null` values are deleted
* - Absent keys are left unchanged
*
* Keys with the `opensandbox.io/` prefix are reserved and rejected.
* @example {
* "project": "new-project",
* "team": null,
* "environment": "production"
* }
*/
PatchSandboxMetadataRequest: {
[key: string]: string | null;
};
/**
* @description Request to create a new sandbox from either a container image, a snapshot,
* or a pre-configured pool (via `extensions.poolRef`).
*
* **Standard mode**: Exactly one of `image` or `snapshotId` must be provided,
* and `resourceLimits` is required.
*
* When `image` is provided, `entrypoint` is required. When `snapshotId` is
* provided, `entrypoint` is optional. If omitted, the server defaults the
* sandbox entrypoint to `["tail", "-f", "/dev/null"]`.
*
* **Pool mode**: When `extensions.poolRef` is set, the sandbox is created from
* a pre-configured on-demand Pool. In this case `image` and `resourceLimits`
* are optional and defined by the Pool CRD template. `entrypoint` is also
* optional; when omitted, the server creates a per-allocation task using
* `['tail', '-f', '/dev/null']`. The Pool must run task-executor and provide
* bootstrap plus execd.
* `snapshotId`, `networkPolicy`, `platform`, `volumes`, and
* `credentialProxy.enabled` must not be provided together with `poolRef`.
*
* **Note**: API Key authentication is required via the `OPEN-SANDBOX-API-KEY` header.
*/
CreateSandboxRequest: {
/**
* @description Container image specification for the sandbox.
* Mutually exclusive with `snapshotId`.
*/
image?: components["schemas"]["ImageSpec"];
/**
* @description Snapshot identifier to restore from.
* Mutually exclusive with `image`.
*/
snapshotId?: string;
/**
* @description Fsb (fast-sandbox microVM) template to create the sandbox from; on the
* `kubernetes` runtime this routes the create to the fsb catalog.
* Mutually exclusive with `image` and `snapshotId`; in template mode
* the workload shape is fixed by the template's golden image, so
* `entrypoint`, `env`, `resourceLimits`, `resourceRequests`,
* `volumes`, `platform`, `secureAccess` and
* lifecycle hooks are rejected (400), and `timeout` is required.
* `credentialProxy` is accepted and ignored: the vault is not
* carried at create time — it is configured after creation through
* the server-routed Credential Vault API
* (`/sandboxes/{sandboxId}/credential-vault`).
* `lifecycle.idlePolicy` is allowed: it is control-plane state,
* not workload shape.
* The template must belong to the requester's tenant and be
* `Succeeded`; anything else yields 404 (no existence leak).
*/
templateId?: string;
/**
* @description Optional platform constraint for sandbox scheduling/runtime selection.
*
* If omitted, runtime default behavior applies (runtime-specific and not
* a fixed architecture guarantee). If specified, the runtime must satisfy
* this constraint or fail explicitly.
* This field is only meaningful when scheduling constraints are set.
*/
platform?: components["schemas"]["PlatformSpec"];
/**
* @description Sandbox timeout in seconds. The sandbox will automatically terminate after this duration.
* The maximum is controlled by the server configuration (`server.max_sandbox_timeout_seconds`).
* Omit this field or set it to null to disable automatic expiration and require explicit cleanup.
* Note: manual cleanup support is runtime-dependent; Kubernetes providers may reject
* omitted or null timeout when the underlying workload provider does not support non-expiring sandboxes.
*/
timeout?: number | null;
/**
* @description Runtime resource constraints (hard caps) for the sandbox instance.
* Required when `extensions.poolRef` is not set.
* Optional when using pool mode (resource limits are defined by the Pool CRD template).
* SDK clients should provide sensible defaults (e.g., cpu: "500m", memory: "512Mi").
*/
resourceLimits?: components["schemas"]["ResourceLimits"];
/**
* @description Resource reservations (guaranteed minimums) for the sandbox instance.
* When provided, these values are used as Kubernetes resource `requests`,
* enabling Burstable QoS class (where `requests < limits`).
* When omitted, `resourceLimits` values are used for both limits and requests,
* resulting in Guaranteed QoS class.
* Only meaningful for Kubernetes-based runtimes; ignored by Docker runtime.
*/
resourceRequests?: components["schemas"]["ResourceLimits"];
/**
* @description Environment variables to inject into the sandbox runtime.
* @example {
* "API_KEY": "secret-key",
* "DEBUG": "true",
* "LOG_LEVEL": "info"
* }
*/
env?: {
[key: string]: string;
};
/**
* @description Custom key-value metadata for management, filtering, and tagging.
* Use "name" key for a human-readable identifier.
* @example {
* "name": "Data Processing Sandbox",
* "project": "data-processing",
* "team": "ml",
* "environment": "staging"
* }
*/
metadata?: {
[key: string]: string;
};
/**
* @description Optional declarative sandbox lifecycle configuration. `preStart`
* and `periodic` are hooks; the server transports them to execd and
* callers must not depend on the internal transport mechanism. The
* configuration is not included in Sandbox responses.
*
* Lifecycle hooks are not supported together with
* `extensions.poolRef`, because Pool Pods are pre-created before
* request-specific hooks are known. Runtimes that do not implement
* lifecycle hook transport reject hooks. `lifecycle.idlePolicy` is
* not a hook and may accompany `extensions.poolRef`; it is honored
* only by the fast-sandbox backend and rejected by others.
* `lifecycle.renewalPolicy` is likewise not a hook: it may
* accompany `extensions.poolRef` and is honored by the docker and
* Kubernetes (pod) backends, while the fast-sandbox backend rejects
* it. Setting both `lifecycle.renewalPolicy` and the deprecated
* `extensions["access.renew.extend.seconds"]` is accepted only when
* their parsed values match; conflicting values are rejected with
* HTTP 400.
*/
lifecycle?: components["schemas"]["SandboxLifecycle"];
/**
* @description The command to execute as the sandbox's entry process.
*
* Required when `image` is provided.
*
* Optional when `snapshotId` is provided. If omitted for snapshot
* restore, the server defaults to `["tail", "-f", "/dev/null"]`.
*
* Optional when `extensions.poolRef` is provided. If omitted for Pool
* mode, the server uses the same default in a per-allocation task.
*
* Explicitly specifies the user's expected main process, allowing the sandbox management
* service to reliably inject control processes before executing this command.
*
* Format: [executable, arg1, arg2, ...]
*
* Examples:
* - ["python", "/app/main.py"]
* - ["/bin/bash"]
* - ["java", "-jar", "/app/app.jar"]
* - ["node", "server.js"]
* @example [
* "python",
* "/app/main.py"
* ]
*/
entrypoint?: string[];
/**
* @description Optional outbound network policy for the sandbox.
* Shape matches the sidecar `/policy` endpoint. If omitted or empty,
* the sidecar starts in allow-all mode until updated.
* For Fsb, an omitted policy still registers an egress binding,
* seeded with a no-op default-allow record (the sandbox behaves
* like a policy-less one until changed): runtime changes go
* through the networkpolicy endpoints (handler relay), which
* require that registration.
* Not supported together with `extensions.poolRef`; pooled pods are
* pre-created, so the server rejects this combination instead of
* silently ignoring the requested policy.
*/
networkPolicy?: components["schemas"]["NetworkPolicy"];
/**
* @description Optional Credential Vault proxy startup settings. Set `enabled: true`
* to enable transparent MITM support for credential injection. Plain
* `networkPolicy` does not enable transparent MITM unless this option
* is set. On fsb template-backed sandboxes the field is accepted and
* ignored at create time: the shared-Fastlet egress has no per-sandbox
* sidecar, and the vault is configured after creation through the
* server-routed Credential Vault API.
*/
credentialProxy?: components["schemas"]["CredentialProxyConfig"];
/**
* @description Opts the sandbox into secured access for endpoint access.
* This is currently supported only for Kubernetes sandboxes exposed
* through ingress gateway mode. When enabled, the server provisions
* access credentials and returns the required request headers with
* endpoint responses. Clients must include those endpoint headers when
* calling the sandbox. When omitted or false, endpoints remain
* accessible without the additional access token for backward
* compatibility.
* @default false
*/
secureAccess: boolean;
/**
* @description Storage mounts for the sandbox. Each volume entry specifies a named backend-specific
* storage source and common mount settings. Exactly one backend type must be specified
* per volume entry.
*/
volumes?: components["schemas"]["Volume"][];
/**
* @description Opaque container for provider-specific or transient parameters not supported by the core API.
*
* **Note**: This field is reserved for internal features, experimental flags, or temporary behaviors. Standard parameters should be proposed as core API fields.
*
* **Best Practices**:
* - **Namespacing**: Use prefixed keys (e.g., `storage.id`) to prevent collisions.
* - **Pass-through**: SDKs and middleware must treat this object as opaque and pass it through transparently.
*
* **Well-known keys**:
* - `access.renew.extend.seconds` (**deprecated**): Decimal integer
* string from **300** to **86400** (5 minutes to 24 hours
* inclusive). Opts the sandbox into OSEP-0009 renew-on-access and
* sets per-renewal extension seconds. Omit to disable. Invalid
* values are rejected at creation with HTTP 400 (validated on the
* lifecycle create endpoint via `validate_extensions` in server
* `src/extensions/validation.py`). Superseded by
* `lifecycle.renewalPolicy.extendSeconds`: prefer the structured
* field in new code. The extensions key remains supported
* throughout 1.x and is removed in 2.0; when both are set, their
* parsed values must match or creation fails with HTTP 400.
*/
extensions?: {
[key: string]: string;
};
};
/**
* @description Runtime resource constraints as key-value pairs. Similar to Kubernetes resource specifications,
* allows flexible definition of resource limits. Common resource types include:
* - `cpu`: CPU allocation in millicores (e.g., "250m" for 0.25 CPU cores)
* - `memory`: Memory allocation in bytes or human-readable format (e.g., "512Mi", "1Gi")
* - `gpu`: Number of GPU devices (e.g., "1")
*
* New resource types can be added without API changes.
* @example {
* "cpu": "500m",
* "memory": "512Mi",
* "gpu": "1"
* }
*/
ResourceLimits: {
[key: string]: string;
};
RenewSandboxExpirationRequest: {
/**
* Format: date-time
* @description New absolute expiration time in UTC (RFC 3339 format).
* Must be in the future. May be earlier than, equal to, or later than the current expiresAt.
* The creation-time limit `server.max_sandbox_timeout_seconds` does not apply.
*
* Example: "2025-11-16T14:30:45Z"
*/
expiresAt: string;
};
RenewSandboxExpirationResponse: {
/**
* Format: date-time
* @description The new absolute expiration time in UTC (RFC 3339 format).
*
* Example: "2025-11-16T14:30:45Z"
*/
expiresAt: string;
};
/**
* @description Standard error response for all non-2xx HTTP responses.
* HTTP status code indicates the error category; code and message provide details.
*/
ErrorResponse: {
/**
* @description Machine-readable error code (e.g., INVALID_REQUEST, NOT_FOUND, INTERNAL_ERROR).
* Use this for programmatic error handling.
*/
code: string;
/** @description Human-readable error message describing what went wrong and how to fix it. */
message: string;
};
/**
* @description Endpoint for accessing a service running in the sandbox.
* The service must be listening on the specified port inside the sandbox for the endpoint to be available.
*/
Endpoint: {
/**
* @description Public URL to access the service from outside the sandbox.
* Format: {endpoint-host}/sandboxes/{sandboxId}/port/{port}
* Example: endpoint.opensandbox.io/sandboxes/abc123/port/8080
*/
endpoint: string;
/** @description Requests targeting the sandbox must include the corresponding header(s). */
headers?: {
[key: string]: string;
};
};
/**
* @description Policy intent for Fsb, or the sidecar policy for other backends.
* Fsb does not report live enforcement state or enforcementMode.
*/
PolicyStatusResponse: {
/** @example ok */
status?: string;
/**
* @description Mode derived from the returned policy.
* @example deny_all
*/
mode?: string;
/** @description Optional sidecar enforcement backend; omitted for Fsb. */
enforcementMode?: string;
/** @description Optional context returned by the sidecar. */
reason?: string;
policy?: components["schemas"]["NetworkPolicy"];
};
/**
* @description Egress network policy matching the sidecar `/policy` request body.
* If `defaultAction` is omitted, the sidecar defaults to "deny"; passing an empty
* object or null results in allow-all behavior at startup.
*/
NetworkPolicy: {
/**
* @description Default action when no egress rule matches. Defaults to "deny".
* @enum {string}
*/
defaultAction?: "allow" | "deny";
/** @description List of egress rules evaluated in order. */
egress?: components["schemas"]["NetworkRule"][];
};
/**
* @description Credential Vault proxy startup settings. This is an explicit opt-in for
* transparent MITM support used by credential injection. Credential Vault
* requires `dns+nft` enforcement and a network policy. A deny-default policy
* is strongly recommended; default-allow remains temporarily supported for
* backward compatibility and emits a security warning.
*/
CredentialProxyConfig: {
/**
* @description When true, the server starts the egress sidecar with transparent
* MITM enabled and installs the runtime-managed MITM CA bundle into
* the sandbox container. Requires `networkPolicy` and server
* `[egress].mode = "dns+nft"`. `defaultAction: deny` is strongly
* recommended; default-allow support is deprecated.
* @default false
*/
enabled: boolean;
};
/** @description Egress rule. At least one of `target` or `ports` must be provided; when both are present the rule applies to `ports` on `target` only. Enforced by the server and the egress sidecar. */
NetworkRule: {
/**
* @description Whether to allow or deny matching targets.
* @enum {string}
*/
action: "allow" | "deny";
/**
* @description FQDN, wildcard domain (e.g., "example.com", "*.example.com"), IP
* address, or CIDR. May be omitted when `ports` is set (see below);
* otherwise required.
*/
target?: string;
/**
* @description Restricts this rule to specific TCP destination ports.
*
* - `target` omitted, `ports` set: the rule applies to these ports
* across all IPv4/IPv6 destinations.
* - `target` is an IP or CIDR, `ports` set: the rule applies to that
* destination only on these ports.
* - `target` is a domain: `ports` is rejected with a validation
* error. Domain rules are evaluated at the DNS layer, which has no
* port dimension; combining them is not supported yet.
*
* TCP only for now; UDP port scoping is not supported.
*
* Under `defaultAction: deny`, the DNS proxy still denies hostname
* lookups for targetless allow rules (it matches domain rules
* only), so this shape serves direct-IP clients; hostname access
* requires explicit domain rules or stable IPs.
*/
ports?: number[];
};
/**
* @description Initial Credential Vault revision. Inline credential values are
* write-only. The vault requires a network policy; `defaultAction:
* deny` is strongly recommended.
*/
CredentialVaultCreateRequest: {
credentials: components["schemas"]["Credential"][];
bindings: components["schemas"]["CredentialBinding"][];
};
/**
* @description One atomic mutation set. Applied per set as delete → replace → add;
* every mentioned name must resolve exactly once (add requires the
* name to be absent, replace and delete require it to exist).
*/
CredentialVaultMutationRequest: {
/** @description Optional optimistic concurrency guard; mismatch fails with 412. */
expectedRevision?: number;
credentials?: components["schemas"]["CredentialMutationSet"];
bindings?: components["schemas"]["CredentialBindingMutationSet"];
};
CredentialMutationSet: {
add?: components["schemas"]["Credential"][];
replace?: components["schemas"]["Credential"][];
delete?: string[];
};
CredentialBindingMutationSet: {
add?: components["schemas"]["CredentialBinding"][];
replace?: components["schemas"]["CredentialBinding"][];
delete?: string[];
};
/** @description Sanitized Credential Vault state — credential values never appear. */
CredentialVaultState: {
revision: number;
credentials: components["schemas"]["CredentialMetadata"][];
bindings: components["schemas"]["CredentialBindingMetadata"][];
};
CredentialListResponse: {
revision: number;
credentials: components["schemas"]["CredentialMetadata"][];
};
CredentialBindingListResponse: {
revision: number;
bindings: components["schemas"]["CredentialBindingMetadata"][];
};
CredentialMetadata: {
name: string;
/** @description Credential source kind (`inline` or `exchange`). */
sourceType: string;
/**
* @description Revision that last touched this record. Fsb stamps records with
* the read revision (the relay surface does not carry per-record
* revisions); other backends track per-record revisions.
*/
revision: number;
};
CredentialBindingMetadata: {
name: string;
/** @description See CredentialMetadata.revision for the Fsb caveat. */
revision: number;
match?: components["schemas"]["CredentialMatch"];
auth?: components["schemas"]["CredentialAuthMetadata"];
};
/** @description Sanitized auth shape — `type` (plus `name` for `apiKey`) for static kinds; `credential` only for the typeless exchange form. */
CredentialAuthMetadata: {
type?: string;
name?: string;
credential?: string;
};
Credential: {
name: string;
source: components["schemas"]["CredentialSource"];
};
/**
* @description Where the credential material comes from. Exactly one kind, selected
* by `type`:
*
* - `inline`: the secret value travels in this request via `value`.
* Inline values are write-only and never appear in reads.
* - `exchange`: no local material. Egress resolves header sets per
* request from a header-resolver service addressed by `endpoint`.
* Supported endpoint forms are `unix:///absolute/path` (HTTP over a
* Unix domain socket) and `https://host[:port]` (TLS); anything else
* is rejected with 400.
*
* Fields of the other kind must be absent; for example `value` together
* with `type: exchange` is rejected with 400.
*/
CredentialSource: {
/** @enum {string} */
type: "inline" | "exchange";
/**
* @description Inline secret value. Required when `type` is `inline`; must be
* absent otherwise.
*/
value?: string;
/**
* @description Header-resolver endpoint. Required when `type` is `exchange`; must
* be absent otherwise.
*/
endpoint?: string;
};
CredentialBinding: {
name: string;
match: components["schemas"]["CredentialMatch"];
auth: components["schemas"]["CredentialAuth"];
};
CredentialMatch: {
/**
* @default [
* "https"
* ]
*/
schemes: ("https" | "http")[];
/**
* @deprecated
* @description Deprecated. Port is derived from scheme (https→443, http→80). Values other than 80 or 443 are rejected with a validation error. Standard values (80/443) are accepted but ignored.
*/
ports?: number[];
hosts: string[];
/**
* @default [
* "GET",
* "POST",
* "PUT",
* "PATCH",
* "DELETE"
* ]
*/
methods: string[];
/**
* @default [
* "/*"
* ]
*/
paths: string[];
};
/**
* @description How a binding injects credential material. Exactly one auth kind:
*
* - `bearer`: `type: bearer` plus `credential`.
* - `basic`: `type: basic` plus `credential`.
* - `apiKey`: `type: apiKey` plus `name` and `credential`.
* - `customHeaders`: `type: customHeaders` plus `headers`.
* - `passthrough`: `type: passthrough`, no credential reference.
* - typeless exchange: `type` omitted with only `credential` set. The
* referenced credential must be exchange-sourced; egress resolves the
* header set per request from the credential's endpoint.
*
* Static kinds must reference inline-sourced credentials, and the
* typeless form must reference an exchange-sourced credential and must
* not set `name`, `headers`, or `substitutions`. The five static kinds
* accept optional `substitutions`. Violations are rejected with 400.
*/
CredentialAuth: {
/**
* @description Static auth kind. Omit entirely for the typeless exchange form.
* @enum {string}
*/
type?: "bearer" | "basic" | "apiKey" | "customHeaders" | "passthrough";
/**
* @description Name of the sandbox-local credential whose value is injected. For
* `bearer` the value becomes the bearer token; for `basic` it
* contains pre-encoded base64(username:password). Required for
* `bearer`, `basic`, `apiKey`, and the typeless exchange form; must
* be absent otherwise.
*/
credential?: string;
/** @description Request header name. Required for `apiKey`; must be absent otherwise. */
name?: string;
/** @description Static header set. Required for `customHeaders`; must be absent otherwise. */
headers?: components["schemas"]["CustomHeaderEntry"][];
/**
* @description Optional placeholder replacement set. Accepted for the five static
* kinds; must be absent for the typeless exchange form.
*/
substitutions?: components["schemas"]["CredentialSubstitution"][];
};
CustomHeaderEntry: {
name: string;
/** @description Credential name whose value is injected. */
credential: string;
};
/** @description Literal case-sensitive placeholder replacement for selected request surfaces. Replacement is opt-in and scoped per binding. */
CredentialSubstitution: {
/** @description Name of the sandbox-local credential used as the replacement value. */
credential: string;
/** @description Literal placeholder to replace. */
placeholder: string;
/** @description Request surfaces where the placeholder may be replaced. */
in: ("path" | "query" | "header" | "body")[];
};
/**
* @description Storage mount definition for a sandbox. Each volume entry contains:
* - A unique name identifier
* - Exactly one backend struct (host, pvc, ossfs, etc.) with backend-specific fields
* - Common mount settings (mountPath, readOnly, subPath)
*/
Volume: {
/**
* @description Unique identifier for the volume within the sandbox.
* Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
*/
name: string;
host?: components["schemas"]["Host"];
pvc?: components["schemas"]["PVC"];
ossfs?: components["schemas"]["OSSFS"];
/**
* @description Absolute path inside the container where the volume is mounted.
* Must start with '/'.
*/
mountPath: string;
/**
* @description If true, the volume is mounted as read-only. Defaults to false (read-write).
* @default false
*/
readOnly: boolean;
/**
* @description Optional subdirectory under the backend path to mount.
* For `ossfs` backend, this field is used as the bucket prefix.
* Must be a relative path without '..' components.
*/
subPath?: string;
};
/**
* @description Host path bind mount backend. Maps a directory on the host filesystem
* into the container. Only available when the runtime supports host mounts.
*
* Security note: Host paths are restricted by server-side allowlist.
* Users must specify paths under permitted prefixes.
*/
Host: {
/**
* @description Absolute path on the host filesystem to mount.
* Must start with '/' (Unix) or a drive letter such as 'C:\' or 'D:/'
* (Windows), and be under an allowed prefix.
*/
path: string;
};
/**
* @description Platform-managed named volume backend. A runtime-neutral abstraction
* for referencing a platform-managed named volume. If `createIfNotExists`
* is true (the default) and the volume does not yet exist, it will be
* created automatically using the provisioning hints below.
*
* - Kubernetes: maps to a PersistentVolumeClaim in the same namespace.
* - Docker: maps to a Docker named volume (created via `docker volume create`).
*/
PVC: {
/**
* @description Name of the volume on the target platform.
* In Kubernetes this is the PVC name; in Docker this is the named
* volume name. Must be a valid DNS label.
*/
claimName: string;
/**
* @description When true (the default), the volume is automatically created if
* it does not exist. When false, referencing a non-existent volume
* fails with an error.
* @default true
*/
createIfNotExists: boolean;
/**
* @description When true, the volume is automatically removed when the sandbox
* is deleted. Only applies to volumes that were auto-created by the
* server on this request; pre-existing volumes are never removed.
* For Kubernetes, the resulting PVC delete triggers the bound PV's
* StorageClass reclaim policy (`Retain`/`Delete`).
* @default false
*/
deleteOnSandboxTermination: boolean;
/**
* @description Kubernetes StorageClass name for auto-created PVCs. Null means
* use the cluster default. Ignored for Docker volumes.
*/
storageClass?: string | null;
/**
* @description Storage capacity request for auto-created PVCs (e.g. "1Gi",
* "10Gi"). Defaults to the server-configured `volume_default_size`
* when omitted. Ignored for Docker volumes.
*/
storage?: string | null;
/**
* @description Access modes for auto-created PVCs (e.g. ["ReadWriteOnce"]).
* Defaults to ["ReadWriteOnce"] when omitted. Ignored for Docker
* volumes.
*/
accessModes?: string[] | null;
};
/**
* @description Alibaba Cloud OSS mount backend via ossfs.
*
* The runtime mounts a host-side OSS path under `storage.ossfs_mount_root`
* and bind-mounts the resolved path into the sandbox container.
* Prefix selection is expressed via `Volume.subPath`.
* In Docker runtime, OSSFS backend requires OpenSandbox Server to run on a Linux host with FUSE support.
*/
OSSFS: {
/** @description OSS bucket name. */
bucket: string;
/** @description OSS endpoint (e.g., `oss-cn-hangzhou.aliyuncs.com`). */
endpoint: string;
/**
* @description ossfs major version used by runtime mount integration.
* @default 2.0
* @enum {string}
*/
version: "1.0" | "2.0";
/**
* @description Additional ossfs mount options.
* Runtime encodes options by `version`:
* - `1.0`: mounts with `ossfs ... -o <option>`
* - `2.0`: mounts with `ossfs2 mount ... -c <config-file>` and encodes options as `--<option>` lines in the config file
* Option values must be provided as raw payloads without leading `-`.
*/
options?: string[];
/** @description OSS access key ID for inline credentials mode. */
accessKeyId: string;
/** @description OSS access key secret for inline credentials mode. */
accessKeySecret: string;
};
/** @description Build-side readiness gate for a fsb template. */
FsbTemplateReadiness: {
/**
* @description Readiness probe checked first during the golden-image build;
* e.g. `tcp://127.0.0.1:44772` or `cmd://<command>`.
*/
probe?: string;
/** @description Fallback warmup window in seconds (default 60). */
warmupSeconds?: number;
};
/**
* @description Request to create a Fast Sandbox template: a fast-sandbox golden-image build
* The server persists the build intent, projects it onto a
* SandboxTemplate CRD, and reports the asynchronous build through the
* template status. Kernel, execd and guest init are server-side build
* inputs supplied from the `[fsb]` configuration, not client fields.
*/
CreateFsbTemplateRequest: {
/** @description Source OCI image reference the golden image is built from. */
image: string;
/**
* @description Guest machine sizing: `cpu` -> guest vCPUs, `memory` -> guest memory,
* `disk` -> logical size of the guest rootfs (parallel resource keys).
* The artifact set is stored and P2P-pulled at the `disk` size, so keep
* it just above the expanded source image. Defaults when omitted:
* cpu `1`, memory `512Mi`, disk `2Gi`.
*/
resourceLimits?: components["schemas"]["ResourceLimits"];
/**
* @description Guest business command (argv); empty defaults to
* `["tail", "-f", "/dev/null"]`.
*/
entrypoint?: string[];
/**
* @description Environment variables baked into the golden image (injected as
* `/etc/sandbox-init.env` in the guest; literal values only). The
* source image's own OCI `Config.Env` is inherited like a container
* runtime would; an env with the same name here overrides the
* inherited value. Names must be valid shell variable names
* (`[A-Za-z_][A-Za-z0-9_]*`).
* @example {
* "LOG_LEVEL": "info"
* }
*/
env?: {
[key: string]: string;
};
/** @description Custom key-value metadata for management, filtering, and tagging. */
metadata?: {
[key: string]: string;
};
readiness?: components["schemas"]["FsbTemplateReadiness"];
/**
* @description Publish destination: `s3://bucket/publish` for native artifacts or
* `oci://registry/repository` for overlaybd artifacts. OCI targets
* must not contain a tag or digest; the builder generates unique
* tags per build. Registry credentials are configured on the server.
*/
publish: string;
/**
* @description Storage encoding of the produced snapshot set.
* @default overlaybd
* @enum {string}
*/
format: "native" | "overlaybd";
};
/** @description Status of a fsb template build. */
FsbTemplateStatus: {
/**
* @description Build lifecycle phase.
* @enum {string}
*/
phase: "Pending" | "Building" | "Succeeded" | "Failed";
/**
* @description Published S3 manifest reference or immutable OCI reference
* (`oci://registry/repository@sha256:...`); present when Succeeded.
*/
manifestRef?: string;
/** @description Failure reason when phase is Failed. */
message?: string;
};
/**
* @description A fsb template: a golden image whose build is declared and executed
* by fast-sandbox.
*/
FsbTemplate: {
/** @description Server-generated template ID (`tpl_<uuid>`). */
templateId: string;
/** @description Source OCI image reference. */
image: string;
resourceLimits?: components["schemas"]["ResourceLimits"];
/** @description Guest business command (argv). */
entrypoint?: string[];
/** @description Environment variables baked into the golden image. */
env?: {
[key: string]: string;
};
/** @description Custom metadata from the creation request. */
metadata?: {
[key: string]: string;
};
readiness?: components["schemas"]["FsbTemplateReadiness"];
/** @description S3-compatible or repository-only OCI publish target. */
publish: string;
/**
* @description Snapshot storage encoding.
* @enum {string}
*/
format: "native" | "overlaybd";
status: components["schemas"]["FsbTemplateStatus"];
/**
* Format: date-time
* @description Creation timestamp (RFC 3339 UTC).
*/
createdAt: string;
/**
* Format: date-time
* @description Last update timestamp (RFC 3339 UTC).
*/
updatedAt: string;
};
/** @description Paginated collection of fsb templates. */
ListFsbTemplatesResponse: {
items: components["schemas"]["FsbTemplate"][];
pagination: components["schemas"]["PaginationInfo"];
};
};
responses: {
/** @description Error response envelope */
Error: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description The request was invalid or malformed */
BadRequest: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description Authentication credentials are missing or invalid */
Unauthorized: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description The authenticated user lacks permission for this operation */
Forbidden: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description The requested resource does not exist */
NotFound: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description The operation conflicts with the current state */
Conflict: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description The provided expectedRevision does not match the current revision */
PreconditionFailed: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
/** @description An unexpected server error occurred */
InternalServerError: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
parameters: {
/** @description Unique sandbox identifier */
SandboxId: string;
/** @description Unique snapshot identifier */
SnapshotId: string;
};
requestBodies: never;
headers: {
/**
* @description Origin of the sandbox: `template` when the sandbox runs on a fsb
* golden-image template (no sandbox-side egress sidecar; egress policy
* is managed through the lifecycle control plane). The set of values
* may grow over time; clients must treat a missing or unknown value as
* "not template-backed" and keep using the egress sidecar.
*/
SandboxOrigin: string;
/** @description Unique request identifier for tracing */
XRequestId: string;
/** @description URI of the newly created or related resource */
Location: string;
/** @description Suggested delay in seconds before retrying */
RetryAfter: number;
};
pathItems: never;
}
export type $defs = Record<string, never>;
export interface operations {
getSandboxNetworkPolicy: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Policy intent (Fsb) or sidecar policy (other backends). */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["PolicyStatusResponse"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
/** @description Policy state is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
replaceSandboxNetworkPolicy: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["NetworkPolicy"];
};
};
responses: {
/** @description Committed policy intent; Fsb omits enforcementMode. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["PolicyStatusResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
/** @description FastPath or policy state is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
deleteSandboxNetworkPolicyRules: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": string[];
};
};
responses: {
/** @description Committed policy intent; Fsb omits enforcementMode. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["PolicyStatusResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
/** @description FastPath or policy state is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
patchSandboxNetworkPolicy: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["NetworkRule"][];
};
};
responses: {
/** @description Committed policy intent; Fsb omits enforcementMode. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["PolicyStatusResponse"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
500: components["responses"]["InternalServerError"];
/** @description FastPath or policy state is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
getSandboxCredentialVault: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sanitized Credential Vault state. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialVaultState"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
createSandboxCredentialVault: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["CredentialVaultCreateRequest"];
};
};
responses: {
/** @description Credential Vault created and acknowledged (sanitized state). */
201: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialVaultState"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
412: components["responses"]["PreconditionFailed"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
deleteSandboxCredentialVault: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Credential Vault deleted. */
204: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content?: never;
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
patchSandboxCredentialVault: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["CredentialVaultMutationRequest"];
};
};
responses: {
/** @description Mutation applied and acknowledged (sanitized state). */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialVaultState"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
409: components["responses"]["Conflict"];
412: components["responses"]["PreconditionFailed"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
listSandboxCredentialVaultCredentials: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sanitized credential metadata. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialListResponse"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
getSandboxCredentialVaultCredential: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
/** @description Credential name */
credentialName: string;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sanitized credential metadata. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialMetadata"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
listSandboxCredentialVaultBindings: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sanitized binding metadata. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialBindingListResponse"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
getSandboxCredentialVaultBinding: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Unique sandbox identifier */
sandboxId: components["parameters"]["SandboxId"];
/** @description Credential binding name */
bindingName: string;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Sanitized binding metadata. */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["CredentialBindingMetadata"];
};
};
401: components["responses"]["Unauthorized"];
403: components["responses"]["Forbidden"];
404: components["responses"]["NotFound"];
500: components["responses"]["InternalServerError"];
/** @description The vault backend is temporarily unavailable. */
503: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ErrorResponse"];
};
};
};
};
reportMetricsEvent: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
/**
* @example {
* "eventType": "sandbox.create",
* "sandboxId": "sbx_01HZYEXAMPLE",
* "image": "python:3.12",
* "createDurationMs": 1842,
* "success": true
* }
*/
"application/json": components["schemas"]["MetricsEvent"];
};
};
responses: {
/** @description Event accepted */
204: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content?: never;
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
500: components["responses"]["InternalServerError"];
};
};
listTemplates: {
parameters: {
query?: {
/**
* @description Arbitrary metadata key-value pairs for filtering, keys and values
* must be url encoded. Example: `?metadata=project%3DApollo%26env%3Dprod`
*/
metadata?: string;
/** @description Page number for pagination */
page?: number;
/** @description Number of items per page */
pageSize?: number;
};
header?: never;
path?: never;
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Paginated collection of templates */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["ListFsbTemplatesResponse"];
};
};
401: components["responses"]["Unauthorized"];
501: components["responses"]["InternalServerError"];
};
};
createTemplate: {
parameters: {
query?: never;
header?: never;
path?: never;
cookie?: never;
};
requestBody: {
content: {
"application/json": components["schemas"]["CreateFsbTemplateRequest"];
};
};
responses: {
/** @description Template build accepted; the phase starts at Pending */
201: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["FsbTemplate"];
};
};
400: components["responses"]["BadRequest"];
401: components["responses"]["Unauthorized"];
409: components["responses"]["Conflict"];
501: components["responses"]["InternalServerError"];
503: components["responses"]["InternalServerError"];
};
};
getTemplate: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Template identifier (`tpl_<uuid>`) */
templateId: string;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Template status and artifact references */
200: {
headers: {
"X-Request-ID": components["headers"]["XRequestId"];
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["FsbTemplate"];
};
};
401: components["responses"]["Unauthorized"];
404: components["responses"]["NotFound"];
501: components["responses"]["InternalServerError"];
};
};
deleteTemplate: {
parameters: {
query?: never;
header?: never;
path: {
/** @description Template identifier (`tpl_<uuid>`) */
templateId: string;
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description Template deleted */
204: {
headers: {
[name: string]: unknown;
};
content?: never;
};
401: components["responses"]["Unauthorized"];
404: components["responses"]["NotFound"];
501: components["responses"]["InternalServerError"];
};
};
}