Read the experimental API and SDK

What you will build

An annotated review of a cloud SDK lifecycle. This chapter does not ask you to activate a subscription or run billable compute.

Read the mechanism

Docker’s TypeScript package is @docker/sandboxes, requiring Node.js 20 or later. Both the API and SDK are explicitly experimental. Pin the package in a lockfile and read its current types; a tutorial is not a stable production contract.

Management API authentication and sandbox endpoint authentication are separate from model-provider credentials. A shell kit removes the model-provider layer for a first experiment. SDK kit catalogs are tied to the installed package version, so do not assume every local shortcut has identical SDK availability.

The API can accept a request before the desired resource transition completes. “Running,” “kit setup complete” and “application ready” are different conditions. A successful API call also does not mean the guest command exited successfully.

Worked example · review the call sequence

The current official quickstart uses these API shapes. The following is an illustrative fragment, not a complete executable program; client must be an authenticated SDK client:

const sandbox = await client.kits.launchAndWait('shell');
const result = await sandbox.processes.run(
  { args: ['printf', 'sandbox-handbook\n'] },
  { timeoutMs: 30_000 },
);
// Persist the resource name, process exit status and bounded output.
// Export any required artifact before deletion.
const latest = await sandbox.refresh();
const deleting = await latest.delete({ force: true });
await deleting?.waitUntilDeleted();

Before adapting it into a live program, add failure handling. If process execution throws, the cleanup statements in this straight-line fragment would never run. Chapter 24 moves cleanup into a reconciled lifecycle rather than relying on happy-path control flow.

Build a preflight record containing subscription owner, allowed maximum cost, chosen compute size, expected duration, TTL behavior, SDK version, exact inputs and cleanup method. Closing the SDK client releases local resources; it does not delete the remote sandbox.

Expected observations

In a future authorized run, retain the returned canonical resource name, actual lifecycle status, command exit code and output separately. After deletion is requested, wait for confirmation and record it. If confirmation is missing, the status is “cleanup unknown,” not “deleted.”

For now, mark the exercise as reviewed but not executed. The code fragment demonstrates the documented method shapes; no successful cloud result is claimed.

Troubleshooting

For a missing method or type mismatch, compare the pinned SDK version to the docs and changelog. For an authentication error, identify whether it concerns the management API, sandbox endpoint or provider. For capacity errors, inspect current account quotas rather than retrying without a bound.

The default quickstart compute size is not a universal resource recommendation. Choose a shape from current supported limits and your budget.

Interview practice

Completion check

Annotate each awaited operation with its state transition and failure case. Identify where a lost response could leave an active resource.

Sources and version notes

Checked 6 October 2026; current baseline: sbx v0.46.0. Install the Docker Sandboxes SDK · API authentication and authorization · API concepts · Run your first cloud sandbox · Docker Sandboxes API v1