Let a stopped sandbox resume on demand

Browse all recipes

Let a request to a published application start a stopped sandbox. This can suit an application that should be available on demand without remaining active between uses.

Use an authenticated client and a managed image that starts the application. Publish its port before relying on requests to reach it.

Configure resume on creation

Set automatic resume in the sandbox's lifecycle options. Omit the value when you want the service default; explicitly set false to disable it.

The example waits for the initial startup. Automatic resume does not recover a deleted sandbox, and it does not replace application startup configuration.

const sandbox = await client.create(
  { displayName: name, image, lifecycle: { autoResume } },
  { timeoutMs: 300_000, idempotencyKey: requestId },
);
return sandbox.waitUntilRunning();

import type { Sandboxes } from '@docker/sandboxes';

export async function createWithAutoResume(
  client: Sandboxes,
  name: string,
  image: string,
  autoResume: boolean | undefined,
  requestId: string,
) {
  const sandbox = await client.create(
    { displayName: name, image, lifecycle: { autoResume } },
    { timeoutMs: 300_000, idempotencyKey: requestId },
  );
  return sandbox.waitUntilRunning();
}

Read the effective setting

Get the sandbox and inspect the effective lifecycle automatic-resume value together with its state. The example falls back to the timeout value for older responses and reports an error if neither value is present. An absent value is unknown, not disabled.

This checks what the service recorded; it does not send a request to the application or prove that the application can start. Authentication is still required.

To verify the whole flow, stop the sandbox, request its published application URL, and confirm that the application becomes ready. Allow for startup time and keep the application's own authentication enabled.

const sandbox = await client.get(name);
const active =
  sandbox.effectiveFeatures?.lifecycle?.autoResume ??
  sandbox.effectiveFeatures?.timeouts?.autoResume;
if (active == null) {
  throw new Error(`sandbox ${name}: auto-resume setting is unknown`);
}
return {
  autoResume: active,
  status: sandbox.status,
};

import type { Sandboxes } from '@docker/sandboxes';

export async function autoResumeInForce(client: Sandboxes, name: string) {
  const sandbox = await client.get(name);
  const active =
    sandbox.effectiveFeatures?.lifecycle?.autoResume ??
    sandbox.effectiveFeatures?.timeouts?.autoResume;
  if (active == null) {
    throw new Error(`sandbox ${name}: auto-resume setting is unknown`);
  }
  return {
    autoResume: active,
    status: sandbox.status,
  };
}