Share feedback
Answers are generated based on the documentation.

Experimental

This API is experimental. Features, interfaces, and behavior may change.

Product manualDownload OpenAPI specificationMarkdown

Hosted API

Docker Sandboxes API

API v1 · 60 operations · 188 named schemas

Overview

Use this API to create sandboxes, run processes, work with files, and manage sandbox resources. Start with a kit through the SDK, or use the HTTP operations here directly.

Management requests use an Authorization bearer token. File and process requests go to the sandbox endpoint in core.endpoint.uri and require a short-lived scoped endpoint credential, not the management token. The SDK obtains that credential for you. Each operation also checks its declared permissions. Direct Unix socket access uses the operating system's socket access controls instead of HTTP authentication. Interactive WebSocket operations describe their supported credential transports separately.

The Docker Cloud API base URL is https://connect.docker.com/sandboxes. Append each /v1 path without removing the base URL's path prefix. For sandbox endpoint operations, use the sandbox endpoint as the base URL instead.

Operations list their success and error responses. A 202 response means work is still in progress; read the resource until it reaches the expected state. Errors contain a stable code, a message, and optional details. Inspect the code as well as the HTTP status.

Send the current ETag in If-Match when an operation requires it. Operations that accept Idempotency-Key use that HTTP header to identify retries: the same key and payload return the first result; a different payload fails. Keys are retained for at least 24 hours.

Lists use pageSize and pageToken. Continue with nextPageToken until it is empty. Supported filters and ordering are listed on each operation. Resource names contain immutable identifiers; displayName is a label. A 64-bit integer is returned as a JSON string; inputs accept a number or a string.

Connecting to the Docker Sandboxes API

bearer

A bearer credential is required for every HTTP request. Management operations use an API credential; sandbox endpoint operations use an issued credential scoped to the sandbox, audience and permitted actions.

sandboxBearer

A short-lived bearer issued by createEndpointCredential for this sandbox, audience and explicit permissions. Management credentials are not accepted.

sandboxWebSocketBearer

Sandbox-scoped credential encoded in the non-echoed subprotocol offer declared by x-websocket. Offer the API subprotocol alongside it; use this carrier only when endpoint discovery advertises webSocketSubprotocol. Never combine it with Authorization.
https://connect.docker.com/sandboxes

Authentication and authorization

Run your first cloud sandbox

Files

Read, write, copy, and manage files inside a sandbox.

Processes

Run commands and interact with processes inside a sandbox.

Credentials

Exchange credentials for the authenticated owner.

Images

Manage images used to create sandboxes.

MCP gateways

Configure MCP gateways and authorize upstream servers.

Network policies

Read enforced outbound network policies and their decision logs.

Sandboxes

Create sandboxes and manage their lifecycle, ports, and SSH access.

Secrets

Store credentials and read their metadata without returning secret material.

Snapshots

Capture sandbox state and restore it into a new sandbox.

Volumes

Manage persistent storage and attach it to sandboxes.

Operations

GET/v1/filesList lists directory entries by path ascending. DELETE/v1/filesRemove deletes a path. GET/v1/files/contentReadFile returns raw file content over HTTP; Stat exposes file metadata. PUT/v1/files/contentWriteFile accepts raw content with path and mode query parameters. PUT/v1/files/directoriesMkdir creates a directory. GET/v1/files/downloadDownload streams file headers, bytes, and per-file errors. POST/v1/files/moveMove renames or moves a path. GET/v1/files/statStat reads metadata for one path. POST/v1/files/uploadUpload streams one or more files. POST/v1/identity/exchangeExchangeDockerCredential consumes an identity token once for the authenticated owner. GET/v1/imagesListImages lists images in the caller's owner scope. POST/v1/imagesCreateImage registers pushed OCI content or disk content derived from a snapshot or sandbox. GET/v1/images/{image}GetImage reads one image by its resource name. DELETE/v1/images/{image}DeleteImage deletes an image; deleting an already absent image succeeds. GET/v1/images/{image}/pull-specGetImagePullSpec returns short-lived pull material through registry-transfer support. GET/v1/mcp-servers/{mcpServer}/authorizationGetMcpAuthorization reads the owner-scoped flow, including its pending URL, under mcp.write. POST/v1/mcp-servers/{mcpServer}/authorization/authorizeAuthorizeMcpServer authorizes credentials for one named upstream. GET/v1/network-policiesGetNetworkPolicies returns effective and exact views of the same installed generation. GET/v1/policy-logsListPolicyLogEntries lists observed policy decisions. GET/v1/processesListProcesses lists processes in creation order. POST/v1/processesCreateProcess starts a durable interactive process and returns its resource name. POST/v1/processes/execExec runs one command to completion. GET/v1/processes/{process}GetProcess reads one process by its endpoint-scoped resource name. GET/v1/processes/{process}/interactInteract binds the complete process name from the path to the first Attach frame. GET/v1/processes/{process}/outputReadOutput returns one page of retained output after a stream_sequence, the same cursor Interact resumes from, so a REST client can read what a process printed. POST/v1/processes/{process}/signalSignal sends one signal to an existing process. GET/v1/sandboxesListSandboxes lists sandboxes in the caller's owner scope. POST/v1/sandboxesCreateSandbox admits a sandbox. GET/v1/sandboxes/{sandbox}GetSandbox reads one sandbox by its resource name. DELETE/v1/sandboxes/{sandbox}DeleteSandbox returns the deleting resource while work remains, or an empty message when absent. PATCH/v1/sandboxes/{sandbox}UpdateSandbox changes only the display label under the observed etag. POST/v1/sandboxes/{sandbox}/endpoint-credentialsCreateEndpointCredential grants short-lived access to one sandbox endpoint. GET/v1/sandboxes/{sandbox}/mcp-gatewayGetMcpGateway reads gateway state for the sandbox. POST/v1/sandboxes/{sandbox}/mcp-gateway/serversAddMcpGatewayServer adds one server to an existing ready gateway. POST/v1/sandboxes/{sandbox}/mcp-gateway/startStartMcpGateway ensures a gateway exists for the sandbox. POST/v1/sandboxes/{sandbox}/mcp-gateway/stopStopMcpGateway stops or detaches the gateway and succeeds when already absent. GET/v1/sandboxes/{sandbox}/network-policiesGetNetworkPolicies returns effective and exact views of the same installed generation. GET/v1/sandboxes/{sandbox}/policy-logsListPolicyLogEntries lists observed policy decisions. GET/v1/sandboxes/{sandbox}/portsListPorts lists currently published ports for one sandbox. POST/v1/sandboxes/{sandbox}/portsCreatePort makes one sandbox port reachable outside the sandbox. GET/v1/sandboxes/{sandbox}/ports/{port}GetPort reads one published port by its resource name. DELETE/v1/sandboxes/{sandbox}/ports/{port}DeletePort withdraws one published port. POST/v1/sandboxes/{sandbox}/renew-timeoutRenewSandboxTimeout sets a TTL when timeout renewal is supported. POST/v1/sandboxes/{sandbox}/snapshotsCreateSnapshot checkpoints a running sandbox; a stopped source is rejected. POST/v1/sandboxes/{sandbox}/ssh-certificatesIssueSSHCert signs a caller-held public key for sandbox SSH access. POST/v1/sandboxes/{sandbox}/startStartSandbox starts a stopped sandbox; a backend that preserved memory resumes it. POST/v1/sandboxes/{sandbox}/stopStopSandbox stops a running sandbox; a backend advertising memory preservation hibernates it. GET/v1/secretsListSecrets lists secret metadata in the caller's owner scope. POST/v1/secretsCreateSecret stores new secret material. GET/v1/secrets/{secret}GetSecret reads one secret's metadata; material is never returned. PUT/v1/secrets/{secret}UpdateSecret replaces secret metadata and material. DELETE/v1/secrets/{secret}DeleteSecret deletes a secret; deleting an already absent secret succeeds. GET/v1/snapshotsListSnapshots lists snapshots in the caller's owner scope. GET/v1/snapshots/{snapshot}GetSnapshot reads one snapshot by its resource name. DELETE/v1/snapshots/{snapshot}DeleteSnapshot deletes a snapshot; deleting an already absent snapshot succeeds. POST/v1/snapshots/{snapshot}/restoreRestoreSnapshot forks a new sandbox from a snapshot. GET/v1/volumesListVolumes lists volumes in the caller's owner scope. POST/v1/volumesCreateVolume creates a persistent volume. GET/v1/volumes/{volume}GetVolume reads one volume by its resource name. DELETE/v1/volumes/{volume}DeleteVolume deletes a volume; deleting an already absent volume succeeds.

Schemas