Secure, Fast, and Extensible Sandbox runtime for AI agents.
openapi: 3.1.0
info:
title: OpenSandbox Diagnostics API
version: 0.1.0
description: |
The OpenSandbox Diagnostics API exposes structured routing context and
best-effort plain-text diagnostic snapshots for a sandbox. It is intended for
humans and troubleshooting agents that need to locate the runtime backend and
collect troubleshooting material without depending on a stable structured
observability model.
This API is not an audit log API and does not define the canonical
observability schema for OpenSandbox. Structured telemetry, long-term
retention, filtering, pagination, and streaming may be provided separately.
Successful log and event responses return a JSON descriptor whose diagnostic
payload is either embedded inline or made available through a download URL.
The diagnostic payload itself is display-oriented `text/plain` content. Clients
should not parse individual payload lines as a stable schema. Servers may
impose implementation-defined retention and response size limits.
## 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: Diagnostics
description: Sandbox troubleshooting context and payload descriptors
paths:
/sandboxes/{sandboxId}/diagnostics/context:
get:
tags: [Diagnostics]
summary: Get diagnostic context
description: |
Retrieve structured context for routing further diagnostics of a sandbox.
`backendType` identifies the implementation that currently owns the
sandbox. `backendIdentifiers` contains implementation-defined identifiers
that may be used to correlate the sandbox with resources in that backend.
Identifier keys are scoped to the backend type and are not defined by this
API. The map may be empty when the backend does not expose additional
identifiers.
This endpoint does not return diagnostic logs or events. Use the dedicated
`logs` and `events` endpoints after resolving the diagnostic context.
parameters:
- $ref: '#/components/parameters/SandboxId'
responses:
'200':
description: Sandbox diagnostic context
content:
application/json:
schema:
$ref: '#/components/schemas/DiagnosticContextResponse'
examples:
fastSandbox:
summary: Fast Sandbox without additional backend identifiers
value:
sandboxId: fsb-abc123
state: Running
backendType: fast-sandbox
backendIdentifiers: {}
kubernetes:
summary: Kubernetes sandbox with backend identifiers
value:
sandboxId: sbx_123
state: Running
backendType: kubernetes
backendIdentifiers:
namespace: default
podName: sandbox-sbx-123
podUid: 86c4fb10-15f7-4c6e-b72e-8dd15d7d5c48
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'
'501':
$ref: '#/components/responses/NotImplemented'
/sandboxes/{sandboxId}/diagnostics/logs:
get:
tags: [Diagnostics]
summary: Get diagnostic logs
description: |
Retrieve a best-effort descriptor for sandbox diagnostic log text.
Logs are not limited to a structured observability model. Depending on the
selected `scope` and server configuration, log text may include sandbox
container stdout/stderr, lifecycle diagnostic text, network diagnostic text,
or other implementation-defined diagnostic material.
This endpoint does not provide streaming, pagination, or a stable line-level
schema in this version. The server returns a JSON descriptor for currently
available diagnostic text for the requested scope, subject to
implementation-defined retention and response size limits. The descriptor
either embeds the text as `content` or returns a `contentUrl` where the
text can be downloaded.
parameters:
- $ref: '#/components/parameters/SandboxId'
- $ref: '#/components/parameters/DiagnosticScope'
responses:
'200':
description: Diagnostic log content descriptor
content:
application/json:
schema:
$ref: '#/components/schemas/DiagnosticContentResponse'
examples:
inline:
summary: Inline container log text
value:
sandboxId: sbx_123
kind: logs
scope: container
delivery: inline
contentType: text/plain; charset=utf-8
content: |
2026-03-25T10:01:13Z execd started
2026-03-25T10:01:14Z sandbox process ready
truncated: false
url:
summary: Downloadable container log text
value:
sandboxId: sbx_123
kind: logs
scope: container
delivery: url
contentType: text/plain; charset=utf-8
contentUrl: https://example.com/diagnostics/sbx_123/logs.txt
contentLength: 10485760
expiresAt: "2026-04-14T10:30:00Z"
truncated: false
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'
'501':
$ref: '#/components/responses/NotImplemented'
/sandboxes/{sandboxId}/diagnostics/events:
get:
tags: [Diagnostics]
summary: Get diagnostic events
description: |
Retrieve a best-effort descriptor for sandbox diagnostic event text.
Events are rendered as diagnostic text rather than exposed as a stable
structured event model. Depending on the selected `scope` and runtime, event
text may include lifecycle transitions, runtime or platform events such as
Kubernetes Events, network diagnostic events, process activity events, or
other implementation-defined event material.
This endpoint does not provide streaming, pagination, or a stable line-level
schema in this version. The server returns a JSON descriptor for currently
available diagnostic event text for the requested scope, subject to
implementation-defined retention and response size limits. The descriptor
either embeds the text as `content` or returns a `contentUrl` where the
text can be downloaded.
parameters:
- $ref: '#/components/parameters/SandboxId'
- $ref: '#/components/parameters/DiagnosticScope'
responses:
'200':
description: Diagnostic event content descriptor
content:
application/json:
schema:
$ref: '#/components/schemas/DiagnosticContentResponse'
examples:
inline:
summary: Inline runtime event text
value:
sandboxId: sbx_123
kind: events
scope: runtime
delivery: inline
contentType: text/plain; charset=utf-8
content: |
2026-03-25T10:01:13Z runtime Normal Scheduled Successfully assigned sandbox pod
2026-03-25T10:01:14Z runtime Normal Pulled Container image pulled
truncated: false
url:
summary: Downloadable runtime event text
value:
sandboxId: sbx_123
kind: events
scope: runtime
delivery: url
contentType: text/plain; charset=utf-8
contentUrl: https://example.com/diagnostics/sbx_123/events.txt
contentLength: 5242880
expiresAt: "2026-04-14T10:30:00Z"
truncated: false
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'
'501':
$ref: '#/components/responses/NotImplemented'
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
DiagnosticScope:
name: scope
in: query
required: true
description: |
Required diagnostic scope selector. Known scopes may include `container`,
`lifecycle`, `runtime`, `network`, `process`, and `all`. Supported scopes
are implementation-defined; servers may add new scopes over time.
On deployments that still expose the legacy DevOps plain-text behavior on
this path, requests without `scope` are treated as deprecated legacy
requests and may return `text/plain` instead of this JSON descriptor.
schema:
type: string
examples:
container:
summary: Sandbox container diagnostics
value: container
runtime:
summary: Runtime or platform diagnostics
value: runtime
all:
summary: Best-effort aggregate across supported scopes
value: all
headers:
XRequestId:
description: Unique request identifier for tracing
schema:
type: string
format: uuid
responses:
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 sandbox does not exist
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'
NotImplemented:
description: The stable Diagnostics API is not implemented by this server
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
headers:
X-Request-ID:
$ref: '#/components/headers/XRequestId'
schemas:
DiagnosticContextResponse:
type: object
description: Structured context for routing sandbox diagnostics.
required: [sandboxId, backendType, backendIdentifiers]
properties:
sandboxId:
type: string
description: Unique sandbox identifier accepted by the OpenSandbox API.
state:
type: string
description: Current OpenSandbox lifecycle state, when available.
backendType:
type: string
description: Implementation-defined backend type.
examples: [fast-sandbox, kubernetes, docker]
backendIdentifiers:
type: object
description: |
Backend-defined identifiers used to correlate this sandbox with
backend resources. Keys are scoped to `backendType`; values are strings.
additionalProperties:
type: string
additionalProperties: false
DiagnosticContentResponse:
type: object
description: |
Descriptor for diagnostic text content.
When `delivery` is `inline`, servers MUST include `content` with the
diagnostic text and MUST omit `contentUrl` / `expiresAt`.
When `delivery` is `url`, servers MUST include `contentUrl` and `expiresAt`
to identify where the diagnostic text can be downloaded and MUST omit
`content`.
required: [sandboxId, kind, scope, delivery, contentType, truncated]
properties:
sandboxId:
type: string
description: Unique sandbox identifier.
kind:
type: string
description: Diagnostic payload kind.
enum: [logs, events]
scope:
type: string
description: Diagnostic scope used for this response.
delivery:
type: string
description: How the diagnostic text payload is delivered.
enum: [inline, url]
contentType:
type: string
description: Media type of the diagnostic payload.
examples: ["text/plain; charset=utf-8"]
content:
type: string
description: Inline diagnostic text payload. Present when `delivery` is `inline`.
contentUrl:
type: string
format: uri
description: URL where the diagnostic text payload can be downloaded. Present when `delivery` is `url`.
contentLength:
type: integer
minimum: 0
description: Payload size in bytes when known.
expiresAt:
type: string
format: date-time
description: Expiration time for the download URL. Present when `delivery` is `url`.
truncated:
type: boolean
description: |
Whether the diagnostic payload returned inline or by URL was
intentionally truncated by the server. This does not indicate backend
retention gaps such as expired Kubernetes Events; those should be
reported through `warnings` when available.
warnings:
type: array
description: Non-fatal warnings about payload completeness or availability.
items:
type: string
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.
message:
type: string
description: Human-readable error message describing what went wrong.
required: [code, message]
additionalProperties: false