opensandbox-group--opensandbox
wehub-resource-sync
e0e362d700
SDK Tests / changes (push) Successful in 2m29s
Real E2E Tests / changes (push) Successful in 2m29s
Deploy Docs Pages / build (push) Has been cancelled
Deploy Docs Pages / deploy (push) Has been cancelled
Real E2E Tests / JavaScript E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Python E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Java E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / C# E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Go E2E (docker bridge) (push) Has been cancelled
Real E2E Tests / Real E2E CI (push) Has been cancelled
SDK Tests / SDK CI (push) Has been cancelled
SDK Tests / CLI Tests (push) Has been cancelled
SDK Tests / Python SDK Quality (code-interpreter) (push) Has been cancelled
SDK Tests / Python SDK Quality (sandbox) (push) Has been cancelled
SDK Tests / Python SDK Tests (code-interpreter) (push) Has been cancelled
SDK Tests / JavaScript SDK Quality And Tests (code-interpreter) (push) Has been cancelled
SDK Tests / JavaScript SDK Quality And Tests (sandbox) (push) Has been cancelled
SDK Tests / Python SDK Tests (sandbox) (push) Has been cancelled
SDK Tests / CLI Quality (push) Has been cancelled
SDK Tests / Kotlin SDK Quality And Tests (sandbox) (push) Has been cancelled
SDK Tests / Kotlin SDK Quality And Tests (code-interpreter) (push) Has been cancelled
SDK Tests / C# SDK Quality And Tests (code-interpreter) (push) Has been cancelled
SDK Tests / C# SDK Quality And Tests (sandbox) (push) Has been cancelled
SDK Tests / Go SDK Quality And Tests (push) Has been cancelled
1636 行
58 KiB
YAML
1636 行
58 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: OpenSandbox Lifecycle API
|
|
version: 0.1.0
|
|
description: |
|
|
The Sandbox Lifecycle API coordinates how untrusted workloads are created,
|
|
executed, paused, resumed, and finally disposed. This specification focuses on
|
|
the primary lifecycle flows for the `sandbox` domain concept. Sandboxes can
|
|
be provisioned directly from container images or restored from snapshots.
|
|
|
|
## Sandbox Lifecycle
|
|
|
|
A sandbox follows this lifecycle:
|
|
|
|
1. **Creation** → Sandbox is provisioned and enters `Running` state
|
|
2. **Execution** → Sandbox is running and ready to accept requests
|
|
3. **Pause** (optional) → `Pausing` → `Paused` (asynchronous process)
|
|
4. **Resume** (optional) → `Resuming` → `Running` (asynchronous process)
|
|
5. **Termination** → `Stopping` → `Terminated` (can be triggered by kill action, TTL expiry, or error)
|
|
6. **Error** → Any state can transition to `Failed` on critical errors
|
|
|
|
The `status` field provides fine-grained details through `state`, `reason`, and `message`.
|
|
|
|
## Authentication
|
|
|
|
API Key authentication is required for all operations:
|
|
|
|
1. **HTTP Header**
|
|
```
|
|
OPEN-SANDBOX-API-KEY: your-api-key
|
|
```
|
|
|
|
2. **Environment Variable** (for SDK clients)
|
|
```
|
|
OPEN_SANDBOX_API_KEY=your-api-key
|
|
```
|
|
|
|
SDK clients will automatically pick up this environment variable.
|
|
servers:
|
|
- url: http://localhost:8080/v1
|
|
description: Local development
|
|
security:
|
|
- apiKeyAuth: []
|
|
tags:
|
|
- name: Sandboxes
|
|
description: Provision and transition sandboxes through their lifecycle
|
|
- name: Snapshots
|
|
description: Create, list, and delete persistent sandbox snapshots
|
|
paths:
|
|
/sandboxes:
|
|
get:
|
|
tags: [ Sandboxes ]
|
|
summary: 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.
|
|
parameters:
|
|
- name: state
|
|
in: query
|
|
description: |
|
|
Filter by lifecycle state. Pass multiple times for OR logic.
|
|
Example: `?state=Running&state=Paused`
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
style: form
|
|
explode: true
|
|
- name: metadata
|
|
in: query
|
|
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`
|
|
schema:
|
|
type: string
|
|
style: form
|
|
- name: page
|
|
in: query
|
|
description: Page number for pagination
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 1
|
|
- name: pageSize
|
|
in: query
|
|
description: Number of items per page
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 20
|
|
responses:
|
|
'200':
|
|
description: Paginated collection of sandboxes
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListSandboxesResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
post:
|
|
tags: [Sandboxes]
|
|
summary: Create a sandbox
|
|
description: |
|
|
Creates a new sandbox from a container image or restores one from a
|
|
persistent sandbox snapshot with optional resource limits, environment
|
|
variables, and metadata.
|
|
|
|
Exactly one startup source must be provided:
|
|
- `image` to provision directly from a container image.
|
|
- `snapshotId` to restore from a previously created snapshot.
|
|
|
|
When `image` is provided, `entrypoint` is required. When `snapshotId` is
|
|
provided, `entrypoint` is optional. If omitted, the server defaults the
|
|
sandbox entrypoint to `["tail", "-f", "/dev/null"]`.
|
|
|
|
## Authentication
|
|
|
|
API Key authentication is required via:
|
|
- `OPEN-SANDBOX-API-KEY: <api-key>` header
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateSandboxRequest'
|
|
examples:
|
|
deny-with-allowlist:
|
|
summary: Deny by default with allowed domains
|
|
value:
|
|
image:
|
|
uri: python:3.11
|
|
timeout: 3600
|
|
resourceLimits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
entrypoint: ["python", "/app/main.py"]
|
|
networkPolicy:
|
|
defaultAction: deny
|
|
egress:
|
|
- action: allow
|
|
target: "pypi.org"
|
|
allow-with-denylist:
|
|
summary: Allow by default with a deny rule
|
|
value:
|
|
image:
|
|
uri: python:3.11
|
|
timeout: 3600
|
|
resourceLimits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
entrypoint: ["python", "/app/main.py"]
|
|
networkPolicy:
|
|
defaultAction: allow
|
|
egress:
|
|
- action: deny
|
|
target: "bad.example.com"
|
|
manual-cleanup:
|
|
summary: Manual cleanup without automatic expiration
|
|
value:
|
|
image:
|
|
uri: python:3.11
|
|
platform:
|
|
os: linux
|
|
arch: amd64
|
|
resourceLimits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
entrypoint: ["python", "/app/main.py"]
|
|
secure-access:
|
|
summary: Enable secured access for sandbox endpoints in Kubernetes gateway mode
|
|
value:
|
|
image:
|
|
uri: python:3.11
|
|
timeout: 3600
|
|
resourceLimits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
entrypoint: ["python", "/app/main.py"]
|
|
secureAccess: true
|
|
restore-snapshot:
|
|
summary: Restore from a snapshot
|
|
value:
|
|
snapshotId: snap_123
|
|
timeout: 3600
|
|
resourceLimits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
restore-snapshot-with-entrypoint:
|
|
summary: Restore from a snapshot with a custom entrypoint
|
|
value:
|
|
snapshotId: snap_123
|
|
timeout: 3600
|
|
resourceLimits:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
entrypoint: ["python", "/workspace/app.py"]
|
|
responses:
|
|
'202':
|
|
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.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateSandboxResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Location:
|
|
$ref: '#/components/headers/Location'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/snapshots:
|
|
get:
|
|
tags: [Snapshots]
|
|
summary: 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.
|
|
parameters:
|
|
- name: sandboxId
|
|
in: query
|
|
description: Filter snapshots by source sandbox identifier
|
|
schema:
|
|
type: string
|
|
- name: state
|
|
in: query
|
|
description: |
|
|
Filter by snapshot lifecycle state. Pass multiple times for OR logic.
|
|
Example: `?state=Ready&state=Failed`
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SnapshotState'
|
|
style: form
|
|
explode: true
|
|
- name: page
|
|
in: query
|
|
description: Page number for pagination
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 1
|
|
- name: pageSize
|
|
in: query
|
|
description: Number of items per page
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
default: 20
|
|
responses:
|
|
'200':
|
|
description: Paginated collection of snapshots
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListSnapshotsResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/snapshots/{snapshotId}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/SnapshotId'
|
|
get:
|
|
tags: [Snapshots]
|
|
summary: Fetch a snapshot by id
|
|
description: Returns snapshot state and metadata.
|
|
responses:
|
|
'200':
|
|
description: Snapshot current state and metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Snapshot'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
delete:
|
|
tags: [Snapshots]
|
|
summary: 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.
|
|
responses:
|
|
'204':
|
|
description: Snapshot successfully deleted
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}:
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
get:
|
|
tags: [Sandboxes]
|
|
summary: 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.
|
|
responses:
|
|
'200':
|
|
description: Sandbox current state and metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Sandbox'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
delete:
|
|
tags: [Sandboxes]
|
|
summary: Delete a sandbox
|
|
description: Delete a sandbox, terminating its execution. The sandbox will transition through Stopping state to Terminated.
|
|
responses:
|
|
'204':
|
|
description: |
|
|
Sandbox successfully deleted.
|
|
|
|
Sandbox has been scheduled for termination and will transition to Stopping state, then Terminated.
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}/metadata:
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
patch:
|
|
tags: [Sandboxes]
|
|
summary: Patch sandbox metadata
|
|
description: |
|
|
Update sandbox metadata using JSON Merge Patch semantics (RFC 7396).
|
|
|
|
**Merge Patch rules:**
|
|
| Request body key/value | Behavior |
|
|
|---|---|
|
|
| `"key": "value"` | Add or replace the key |
|
|
| `"key": null` | Delete the key (silently ignored if key does not exist) |
|
|
| key absent | Keep current value (no change) |
|
|
| Empty `{}` | No-op, returns current metadata |
|
|
|
|
Metadata keys and values must comply with Kubernetes label rules:
|
|
- Keys must be valid DNS label names or prefixed DNS subdomains
|
|
- Keys with the `opensandbox.io/` prefix are reserved and rejected
|
|
- Values must be 63 characters or less, matching `[A-Za-z0-9]([-A-Za-z0-9_.]*[A-Za-z0-9])?`
|
|
|
|
This operation does not restart or recreate the sandbox container/pod.
|
|
|
|
**Concurrency:** This endpoint uses read-modify-write without optimistic
|
|
locking (no `resourceVersion` check). Concurrent PATCH requests may
|
|
interleave and silently drop updates. Use a single writer or coordinate
|
|
out-of-band when concurrent modifications to the same key are expected.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PatchSandboxMetadataRequest'
|
|
examples:
|
|
add-and-replace:
|
|
summary: Add new keys and replace existing values
|
|
value:
|
|
team: "platform"
|
|
version: "2.0"
|
|
delete-key:
|
|
summary: Delete a metadata key
|
|
value:
|
|
deprecated-key: null
|
|
mixed-operations:
|
|
summary: Add, replace, and delete in a single request
|
|
value:
|
|
project: "new-project"
|
|
team: null
|
|
environment: "production"
|
|
empty-body:
|
|
summary: No-op (returns current metadata)
|
|
value: {}
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Metadata patched successfully. Returns the complete sandbox resource
|
|
with updated metadata.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Sandbox'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}/snapshots:
|
|
post:
|
|
tags: [Snapshots]
|
|
summary: 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.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateSnapshotRequest'
|
|
examples:
|
|
default:
|
|
summary: Create an unnamed snapshot
|
|
value: {}
|
|
named:
|
|
summary: Create a named snapshot
|
|
value:
|
|
name: checkpoint-before-import
|
|
responses:
|
|
'202':
|
|
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`.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Snapshot'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Location:
|
|
$ref: '#/components/headers/Location'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}/pause:
|
|
post:
|
|
tags: [Sandboxes]
|
|
summary: 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.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
responses:
|
|
'202':
|
|
description: |
|
|
Pause operation accepted.
|
|
|
|
Sandbox will transition to Pausing state and eventually Paused.
|
|
Poll GET /sandboxes/{sandboxId} to track progress.
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}/resume:
|
|
post:
|
|
tags: [Sandboxes]
|
|
summary: Resume a paused sandbox
|
|
description: Resume execution of a paused sandbox. Poll GET /sandboxes/{sandboxId} to track state transition through Resuming and eventually Running.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
responses:
|
|
'202':
|
|
description: |
|
|
Resume operation accepted.
|
|
|
|
Sandbox will transition from Paused → Resuming → Running.
|
|
Poll GET /sandboxes/{sandboxId} to track progress.
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}/renew-expiration:
|
|
post:
|
|
tags: [Sandboxes]
|
|
summary: Renew sandbox expiration
|
|
description: Renew the absolute expiration time of a sandbox.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RenewSandboxExpirationRequest'
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Sandbox expiration updated successfully.
|
|
|
|
Returns only the updated expiresAt field.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/RenewSandboxExpirationResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'409':
|
|
$ref: '#/components/responses/Conflict'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
/sandboxes/{sandboxId}/endpoints/{port}:
|
|
get:
|
|
tags: [Sandboxes]
|
|
summary: 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.
|
|
parameters:
|
|
- $ref: '#/components/parameters/SandboxId'
|
|
- name: port
|
|
in: path
|
|
required: true
|
|
description: Port number where the service is listening inside the sandbox
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 65535
|
|
- name: use_server_proxy
|
|
in: query
|
|
description: Whether to return a server-proxied URL. Cannot be combined with `expires`.
|
|
schema:
|
|
type: boolean
|
|
default: false
|
|
- name: expires
|
|
in: query
|
|
required: false
|
|
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`.
|
|
schema:
|
|
type: string
|
|
pattern: '^(0|[1-9][0-9]*)$'
|
|
minLength: 1
|
|
maxLength: 20
|
|
responses:
|
|
'200':
|
|
description: |
|
|
Endpoint retrieved successfully.
|
|
|
|
Returns the public URL for accessing the service on the specified port.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Endpoint'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
'500':
|
|
$ref: '#/components/responses/InternalServerError'
|
|
components:
|
|
securitySchemes:
|
|
apiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: OPEN-SANDBOX-API-KEY
|
|
description: |
|
|
API Key for authentication. Can be provided via:
|
|
1. HTTP Header: OPEN-SANDBOX-API-KEY: your-api-key
|
|
2. Environment variable: OPEN_SANDBOX_API_KEY (for SDK clients)
|
|
parameters:
|
|
SandboxId:
|
|
name: sandboxId
|
|
in: path
|
|
required: true
|
|
description: Unique sandbox identifier
|
|
schema:
|
|
type: string
|
|
SnapshotId:
|
|
name: snapshotId
|
|
in: path
|
|
required: true
|
|
description: Unique snapshot identifier
|
|
schema:
|
|
type: string
|
|
headers:
|
|
XRequestId:
|
|
description: Unique request identifier for tracing
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
Location:
|
|
description: URI of the newly created or related resource
|
|
schema:
|
|
type: string
|
|
format: uri
|
|
RetryAfter:
|
|
description: Suggested delay in seconds before retrying
|
|
schema:
|
|
type: integer
|
|
minimum: 1
|
|
responses:
|
|
Error:
|
|
description: Error response envelope
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
BadRequest:
|
|
description: The request was invalid or malformed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Unauthorized:
|
|
description: Authentication credentials are missing or invalid
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Forbidden:
|
|
description: The authenticated user lacks permission for this operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
NotFound:
|
|
description: The requested resource does not exist
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
Conflict:
|
|
description: The operation conflicts with the current state
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
InternalServerError:
|
|
description: An unexpected server error occurred
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
headers:
|
|
X-Request-ID:
|
|
$ref: '#/components/headers/XRequestId'
|
|
schemas:
|
|
ListSandboxesResponse:
|
|
type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Sandbox'
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
required: [items, pagination]
|
|
ListSnapshotsResponse:
|
|
type: object
|
|
properties:
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Snapshot'
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
required: [items, pagination]
|
|
PaginationInfo:
|
|
type: object
|
|
description: Pagination metadata for list responses
|
|
properties:
|
|
page:
|
|
type: integer
|
|
minimum: 1
|
|
description: Current page number
|
|
pageSize:
|
|
type: integer
|
|
minimum: 1
|
|
description: Number of items per page
|
|
totalItems:
|
|
type: integer
|
|
minimum: 0
|
|
description: Total number of items matching the filter
|
|
totalPages:
|
|
type: integer
|
|
minimum: 0
|
|
description: Total number of pages
|
|
hasNextPage:
|
|
type: boolean
|
|
description: Whether there are more pages after the current one
|
|
required: [page, pageSize, totalItems, totalPages, hasNextPage]
|
|
CreateSandboxResponse:
|
|
type: object
|
|
description: Response from creating a new sandbox. Contains essential information without startup source details and updatedAt.
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique sandbox identifier
|
|
|
|
status:
|
|
$ref: '#/components/schemas/SandboxStatus'
|
|
description: Current lifecycle status and detailed state information
|
|
|
|
metadata:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Custom metadata from creation request
|
|
|
|
extensions:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Opaque extension data restored from provider-specific storage
|
|
|
|
platform:
|
|
$ref: '#/components/schemas/PlatformSpec'
|
|
description: |
|
|
Platform constraint echoed from request or workload template.
|
|
Null when no scheduling constraint is provided.
|
|
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
|
|
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
description: Sandbox creation timestamp
|
|
|
|
entrypoint:
|
|
type: array
|
|
items:
|
|
type: 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.
|
|
|
|
required:
|
|
- id
|
|
- status
|
|
- createdAt
|
|
- entrypoint
|
|
|
|
CreateSnapshotRequest:
|
|
type: object
|
|
description: Optional settings for creating a sandbox snapshot.
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Optional human-readable snapshot name.
|
|
minLength: 1
|
|
additionalProperties: false
|
|
|
|
Snapshot:
|
|
type: object
|
|
description: Persistent point-in-time capture of a sandbox.
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique snapshot identifier
|
|
|
|
sandboxId:
|
|
type: string
|
|
description: Source sandbox identifier used to create this snapshot
|
|
|
|
name:
|
|
type: string
|
|
description: Optional human-readable snapshot name
|
|
|
|
status:
|
|
$ref: '#/components/schemas/SnapshotStatus'
|
|
description: Current snapshot lifecycle status and detailed state information
|
|
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
description: Snapshot creation timestamp
|
|
|
|
required:
|
|
- id
|
|
- sandboxId
|
|
- status
|
|
- createdAt
|
|
additionalProperties: false
|
|
|
|
SnapshotState:
|
|
type: 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.
|
|
|
|
SnapshotStatus:
|
|
type: object
|
|
description: Detailed snapshot status information with lifecycle state and transition details.
|
|
properties:
|
|
state:
|
|
$ref: '#/components/schemas/SnapshotState'
|
|
description: Current lifecycle state of the snapshot
|
|
|
|
reason:
|
|
type: string
|
|
description: |
|
|
Short machine-readable reason code for the current state.
|
|
Examples: "snapshot_accepted", "snapshot_ready", "snapshot_capture_failed"
|
|
|
|
message:
|
|
type: string
|
|
description: Human-readable message describing the current state or failure reason
|
|
|
|
lastTransitionAt:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of the last state transition
|
|
|
|
required: [state]
|
|
additionalProperties: false
|
|
|
|
Sandbox:
|
|
type: object
|
|
description: Runtime execution environment provisioned from a container image or restored from a snapshot
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: Unique sandbox identifier
|
|
|
|
image:
|
|
$ref: '#/components/schemas/ImageSpec'
|
|
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.
|
|
|
|
snapshotId:
|
|
type: string
|
|
description: |
|
|
Snapshot identifier used to restore this sandbox.
|
|
Present when the sandbox was restored from a snapshot.
|
|
Not returned in createSandbox response.
|
|
|
|
platform:
|
|
$ref: '#/components/schemas/PlatformSpec'
|
|
description: |
|
|
Platform constraint echoed from request or workload template.
|
|
Null when no scheduling constraint is provided.
|
|
|
|
status:
|
|
$ref: '#/components/schemas/SandboxStatus'
|
|
description: Current lifecycle status and detailed state information
|
|
|
|
metadata:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Custom metadata from creation request
|
|
|
|
extensions:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Opaque extension data restored from provider-specific storage
|
|
|
|
entrypoint:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: |
|
|
The command to execute as the sandbox's entry process.
|
|
Always present in responses. For image-created sandboxes, this is copied
|
|
from the creation request. For snapshot-created sandboxes, this is restored
|
|
from the snapshot.
|
|
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp when sandbox will auto-terminate. Omitted when manual cleanup is enabled.
|
|
|
|
createdAt:
|
|
type: string
|
|
format: date-time
|
|
description: Sandbox creation timestamp
|
|
|
|
required:
|
|
- id
|
|
- status
|
|
- createdAt
|
|
- entrypoint
|
|
SandboxState:
|
|
type: string
|
|
description: |
|
|
High-level lifecycle state of the sandbox.
|
|
|
|
Common state values:
|
|
- Pending: Sandbox is being provisioned
|
|
- Running: Sandbox is running and ready to accept requests
|
|
- Pausing: Sandbox is in the process of pausing
|
|
- Paused: Sandbox has been paused while retaining its state
|
|
- Resuming: Sandbox is being restored after a pause
|
|
- Stopping: Sandbox is being terminated
|
|
- Terminated: Sandbox has been successfully terminated
|
|
- Failed: Sandbox encountered a critical error
|
|
|
|
State transitions:
|
|
- Pending → Running (after creation completes)
|
|
- Running → Pausing (when pause is requested)
|
|
- Pausing → Paused (pause operation completes)
|
|
- Paused → Resuming (when resume is requested)
|
|
- Resuming → Running (when resume operation completes)
|
|
- Running/Paused → Stopping (when kill is requested or TTL expires)
|
|
- Stopping → Terminated (kill/timeout operation completes)
|
|
- Pending/Running/Paused/Resuming → Failed (on error)
|
|
|
|
Note: New state values may be added in future versions.
|
|
Clients should handle unknown state values gracefully.
|
|
SandboxStatus:
|
|
type: object
|
|
description: Detailed status information with lifecycle state and transition details
|
|
properties:
|
|
state:
|
|
$ref: '#/components/schemas/SandboxState'
|
|
description: Current lifecycle state of the sandbox
|
|
|
|
reason:
|
|
type: string
|
|
description: |
|
|
Short machine-readable reason code for the current state.
|
|
Examples: "user_delete", "ttl_expiry", "provision_timeout", "runtime_error"
|
|
|
|
message:
|
|
type: string
|
|
description: Human-readable message describing the current state or reason for state transition
|
|
|
|
lastTransitionAt:
|
|
type: string
|
|
format: date-time
|
|
description: Timestamp of the last state transition
|
|
|
|
required: [state]
|
|
ImageSpec:
|
|
type: object
|
|
required: [uri]
|
|
description: |
|
|
Container image specification for sandbox provisioning.
|
|
|
|
Supports public registry images and private registry images with authentication.
|
|
properties:
|
|
uri:
|
|
type: string
|
|
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"
|
|
|
|
auth:
|
|
type: object
|
|
description: Registry authentication credentials (required for private registries)
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: Registry username or service account
|
|
password:
|
|
type: string
|
|
description: Registry password or authentication token
|
|
additionalProperties: false
|
|
|
|
additionalProperties: false
|
|
PlatformSpec:
|
|
type: object
|
|
required: [os, arch]
|
|
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.
|
|
properties:
|
|
os:
|
|
type: string
|
|
enum: [linux, windows]
|
|
description: Target operating system (for example `linux` or `windows`).
|
|
example: linux
|
|
arch:
|
|
type: string
|
|
enum: [amd64, arm64]
|
|
description: Target CPU architecture (for example `amd64` or `arm64`).
|
|
example: arm64
|
|
additionalProperties: false
|
|
PatchSandboxMetadataRequest:
|
|
type: object
|
|
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.
|
|
additionalProperties:
|
|
type:
|
|
- string
|
|
- 'null'
|
|
example:
|
|
project: "new-project"
|
|
team: null
|
|
environment: "production"
|
|
|
|
CreateSandboxRequest:
|
|
type: object
|
|
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 pool. In this case `image`, `entrypoint`, and
|
|
`resourceLimits` are all optional (defined by the Pool CRD template).
|
|
`snapshotId` must not be provided together with `poolRef`.
|
|
|
|
**Note**: API Key authentication is required via the `OPEN-SANDBOX-API-KEY` header.
|
|
properties:
|
|
image:
|
|
$ref: '#/components/schemas/ImageSpec'
|
|
description: |
|
|
Container image specification for the sandbox.
|
|
Mutually exclusive with `snapshotId`.
|
|
|
|
snapshotId:
|
|
type: string
|
|
description: |
|
|
Snapshot identifier to restore from.
|
|
Mutually exclusive with `image`.
|
|
|
|
platform:
|
|
$ref: '#/components/schemas/PlatformSpec'
|
|
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.
|
|
|
|
timeout:
|
|
oneOf:
|
|
- type: integer
|
|
minimum: 60
|
|
- type: 'null'
|
|
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.
|
|
|
|
resourceLimits:
|
|
$ref: '#/components/schemas/ResourceLimits'
|
|
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").
|
|
|
|
resourceRequests:
|
|
$ref: '#/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.
|
|
|
|
env:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Environment variables to inject into the sandbox runtime.
|
|
example:
|
|
API_KEY: "secret-key"
|
|
DEBUG: "true"
|
|
LOG_LEVEL: "info"
|
|
|
|
metadata:
|
|
type: object
|
|
additionalProperties:
|
|
type: 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"
|
|
|
|
entrypoint:
|
|
type: array
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
description: |
|
|
The command to execute as the sandbox's entry process.
|
|
|
|
Required when `image` is provided.
|
|
|
|
Optional when `snapshotId` is provided. If omitted for snapshot
|
|
restore, the server defaults to `["tail", "-f", "/dev/null"]`.
|
|
|
|
Explicitly specifies the user's expected main process, allowing the sandbox management
|
|
service to reliably inject control processes before executing this command.
|
|
|
|
Format: [executable, arg1, arg2, ...]
|
|
|
|
Examples:
|
|
- ["python", "/app/main.py"]
|
|
- ["/bin/bash"]
|
|
- ["java", "-jar", "/app/app.jar"]
|
|
- ["node", "server.js"]
|
|
example:
|
|
- "python"
|
|
- "/app/main.py"
|
|
|
|
networkPolicy:
|
|
$ref: '#/components/schemas/NetworkPolicy'
|
|
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.
|
|
|
|
credentialProxy:
|
|
$ref: '#/components/schemas/CredentialProxyConfig'
|
|
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.
|
|
|
|
secureAccess:
|
|
type: boolean
|
|
default: false
|
|
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.
|
|
|
|
volumes:
|
|
type: array
|
|
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.
|
|
items:
|
|
$ref: '#/components/schemas/Volume'
|
|
|
|
extensions:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: |
|
|
Opaque container for provider-specific or transient parameters not supported by the core API.
|
|
|
|
**Note**: This field is reserved for internal features, experimental flags, or temporary behaviors. Standard parameters should be proposed as core API fields.
|
|
|
|
**Best Practices**:
|
|
- **Namespacing**: Use prefixed keys (e.g., `storage.id`) to prevent collisions.
|
|
- **Pass-through**: SDKs and middleware must treat this object as opaque and pass it through transparently.
|
|
|
|
**Well-known keys**:
|
|
- `access.renew.extend.seconds` (optional): Decimal integer string from **300** to **86400** (5 minutes to 24 hours inclusive). Opts the sandbox into OSEP-0009 renew-on-access and sets per-renewal extension seconds. Omit to disable. Invalid values are rejected at creation with HTTP 400 (validated on the lifecycle create endpoint via `validate_extensions` in server `src/extensions/validation.py`).
|
|
ResourceLimits:
|
|
type: object
|
|
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.
|
|
additionalProperties:
|
|
type: string
|
|
example:
|
|
cpu: "500m"
|
|
memory: "512Mi"
|
|
gpu: "1"
|
|
RenewSandboxExpirationRequest:
|
|
type: object
|
|
required: [expiresAt]
|
|
properties:
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
description: |
|
|
New absolute expiration time in UTC (RFC 3339 format).
|
|
Must be in the future and after the current expiresAt time.
|
|
|
|
Example: "2025-11-16T14:30:45Z"
|
|
additionalProperties: false
|
|
RenewSandboxExpirationResponse:
|
|
type: object
|
|
required: [expiresAt]
|
|
properties:
|
|
expiresAt:
|
|
type: string
|
|
format: date-time
|
|
description: |
|
|
The new absolute expiration time in UTC (RFC 3339 format).
|
|
|
|
Example: "2025-11-16T14:30:45Z"
|
|
additionalProperties: false
|
|
ErrorResponse:
|
|
type: object
|
|
description: |
|
|
Standard error response for all non-2xx HTTP responses.
|
|
HTTP status code indicates the error category; code and message provide details.
|
|
properties:
|
|
code:
|
|
type: string
|
|
description: |
|
|
Machine-readable error code (e.g., INVALID_REQUEST, NOT_FOUND, INTERNAL_ERROR).
|
|
Use this for programmatic error handling.
|
|
message:
|
|
type: string
|
|
description: Human-readable error message describing what went wrong and how to fix it.
|
|
required: [code, message]
|
|
additionalProperties: false
|
|
Endpoint:
|
|
type: object
|
|
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.
|
|
properties:
|
|
endpoint:
|
|
type: string
|
|
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
|
|
headers:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: |
|
|
Requests targeting the sandbox must include the corresponding header(s).
|
|
required:
|
|
- endpoint
|
|
additionalProperties: false
|
|
|
|
NetworkPolicy:
|
|
type: object
|
|
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.
|
|
properties:
|
|
defaultAction:
|
|
type: string
|
|
enum: [allow, deny]
|
|
description: Default action when no egress rule matches. Defaults to "deny".
|
|
egress:
|
|
type: array
|
|
description: List of egress rules evaluated in order.
|
|
items:
|
|
$ref: '#/components/schemas/NetworkRule'
|
|
additionalProperties: false
|
|
|
|
CredentialProxyConfig:
|
|
type: object
|
|
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.
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
default: false
|
|
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.
|
|
additionalProperties: false
|
|
|
|
NetworkRule:
|
|
type: object
|
|
properties:
|
|
action:
|
|
type: string
|
|
enum: [allow, deny]
|
|
description: Whether to allow or deny matching targets.
|
|
target:
|
|
type: string
|
|
description: |
|
|
FQDN or wildcard domain (e.g., "example.com", "*.example.com").
|
|
IP/CIDR not yet supported in the egress MVP.
|
|
required: [action, target]
|
|
additionalProperties: false
|
|
|
|
Volume:
|
|
type: object
|
|
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)
|
|
required: [name, mountPath]
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: |
|
|
Unique identifier for the volume within the sandbox.
|
|
Must be a valid DNS label (lowercase alphanumeric, hyphens allowed, max 63 chars).
|
|
pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
|
|
maxLength: 63
|
|
host:
|
|
$ref: '#/components/schemas/Host'
|
|
pvc:
|
|
$ref: '#/components/schemas/PVC'
|
|
ossfs:
|
|
$ref: '#/components/schemas/OSSFS'
|
|
mountPath:
|
|
type: string
|
|
description: |
|
|
Absolute path inside the container where the volume is mounted.
|
|
Must start with '/'.
|
|
pattern: "^/.*"
|
|
readOnly:
|
|
type: boolean
|
|
description: |
|
|
If true, the volume is mounted as read-only. Defaults to false (read-write).
|
|
default: false
|
|
subPath:
|
|
type: string
|
|
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.
|
|
additionalProperties: false
|
|
|
|
Host:
|
|
type: object
|
|
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.
|
|
required: [path]
|
|
properties:
|
|
path:
|
|
type: string
|
|
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.
|
|
pattern: "^(/|[A-Za-z]:[\\\\/])"
|
|
additionalProperties: false
|
|
|
|
PVC:
|
|
type: object
|
|
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`).
|
|
required: [claimName]
|
|
properties:
|
|
claimName:
|
|
type: string
|
|
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.
|
|
pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
|
|
maxLength: 253
|
|
createIfNotExists:
|
|
type: boolean
|
|
default: true
|
|
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.
|
|
deleteOnSandboxTermination:
|
|
type: boolean
|
|
default: false
|
|
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`).
|
|
storageClass:
|
|
type: string
|
|
nullable: true
|
|
description: |
|
|
Kubernetes StorageClass name for auto-created PVCs. Null means
|
|
use the cluster default. Ignored for Docker volumes.
|
|
storage:
|
|
type: string
|
|
nullable: true
|
|
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.
|
|
pattern: "^\\d+(\\.\\d+)?(Ki|Mi|Gi|Ti|Pi|Ei)?$"
|
|
accessModes:
|
|
type: array
|
|
nullable: true
|
|
items:
|
|
type: string
|
|
description: |
|
|
Access modes for auto-created PVCs (e.g. ["ReadWriteOnce"]).
|
|
Defaults to ["ReadWriteOnce"] when omitted. Ignored for Docker
|
|
volumes.
|
|
additionalProperties: false
|
|
|
|
OSSFS:
|
|
type: object
|
|
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.
|
|
required: [bucket, endpoint, accessKeyId, accessKeySecret]
|
|
properties:
|
|
bucket:
|
|
type: string
|
|
description: OSS bucket name.
|
|
minLength: 3
|
|
maxLength: 63
|
|
endpoint:
|
|
type: string
|
|
description: OSS endpoint (e.g., `oss-cn-hangzhou.aliyuncs.com`).
|
|
minLength: 1
|
|
version:
|
|
type: string
|
|
description: ossfs major version used by runtime mount integration.
|
|
enum: ["1.0", "2.0"]
|
|
default: "2.0"
|
|
options:
|
|
type: array
|
|
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 `-`.
|
|
items:
|
|
type: string
|
|
accessKeyId:
|
|
type: string
|
|
description: OSS access key ID for inline credentials mode.
|
|
minLength: 1
|
|
accessKeySecret:
|
|
type: string
|
|
description: OSS access key secret for inline credentials mode.
|
|
minLength: 1
|
|
additionalProperties: false
|