@larkup/sandbox 0.1.2 → 0.1.4

package/dist/registry.js

@@ -0,0 +1,281 @@
+/**
+ * Declarative registry of the remote sandbox providers @larkup/sandbox can
+ * execute code on, besides the always-available local Docker backend.
+ *
+ * This single object powers two consumers:
+ *  1. The Settings UI — renders `fields` dynamically so each provider asks
+ *     for exactly the credentials it needs, the same way vector store and
+ *     embedding provider fields are rendered from their own registries.
+ *  2. `SandboxManager` / the provider adapters — read `id` to route
+ *     execution and `executionSupport` to fail fast with a clear message
+ *     instead of pretending every provider can run arbitrary code.
+ *
+ * Adding a new provider = one entry here + one adapter in `./providers`.
+ */
+export const SANDBOX_PROVIDERS = {
+    e2b: {
+        id: 'e2b',
+        label: 'E2B',
+        description: 'Firecracker-microVM sandboxes purpose-built for AI code execution, with fast cold starts.',
+        sdkPackage: 'e2b',
+        docsUrl: 'https://docs.e2b.dev/',
+        icon: '/icons/e2b.png',
+        executionSupport: 'full',
+        fields: [
+            {
+                key: 'apiKey',
+                label: 'API key',
+                type: 'password',
+                required: true,
+                secret: true,
+                placeholder: 'e2b_...',
+                help: 'From the E2B dashboard. Equivalent to the E2B_API_KEY environment variable.',
+            },
+            {
+                key: 'snapshotId',
+                label: 'Snapshot or template ID',
+                type: 'text',
+                required: false,
+                help: 'Optional prebuilt environment with your required packages. New executions start from it.',
+            },
+        ],
+    },
+    vercel: {
+        id: 'vercel',
+        label: 'Vercel Sandbox',
+        description: 'Isolated Firecracker microVMs for running arbitrary or untrusted code, billed through your Vercel account.',
+        sdkPackage: '@vercel/sandbox',
+        docsUrl: 'https://vercel.com/docs/sandbox',
+        icon: '/icons/vercel.svg',
+        executionSupport: 'full',
+        fields: [
+            {
+                key: 'token',
+                label: 'Access token',
+                type: 'password',
+                required: true,
+                secret: true,
+                help: 'Vercel access token with Sandbox permissions. Equivalent to VERCEL_TOKEN.',
+            },
+            {
+                key: 'teamId',
+                label: 'Team ID',
+                type: 'text',
+                required: true,
+                placeholder: 'team_...',
+                help: 'Found in Vercel Team Settings. Equivalent to VERCEL_TEAM_ID.',
+            },
+            {
+                key: 'projectId',
+                label: 'Project ID',
+                type: 'text',
+                required: true,
+                placeholder: 'prj_...',
+                help: 'The Vercel project sandboxes run under. Equivalent to VERCEL_PROJECT_ID.',
+            },
+            {
+                key: 'snapshotId',
+                label: 'Snapshot ID',
+                type: 'text',
+                required: false,
+                help: 'Optional Vercel snapshot to restore for each execution.',
+            },
+        ],
+    },
+    modal: {
+        id: 'modal',
+        label: 'Modal',
+        description: 'Sandboxes for executing untrusted user or agent code in secure containers on Modal’s compute platform.',
+        sdkPackage: 'modal',
+        docsUrl: 'https://modal.com/docs/guide/sandboxes',
+        icon: '/icons/modal.png',
+        executionSupport: 'full',
+        fields: [
+            {
+                key: 'tokenId',
+                label: 'Token ID',
+                type: 'text',
+                required: true,
+                placeholder: 'ak-...',
+                help: 'From `modal setup` or the Modal dashboard. Equivalent to MODAL_TOKEN_ID.',
+            },
+            {
+                key: 'tokenSecret',
+                label: 'Token secret',
+                type: 'password',
+                required: true,
+                secret: true,
+                placeholder: 'as-...',
+                help: 'Equivalent to MODAL_TOKEN_SECRET.',
+            },
+        ],
+    },
+    daytona: {
+        id: 'daytona',
+        label: 'Daytona',
+        description: 'Elastic infrastructure for running AI-generated code in fast, isolated sandboxes.',
+        sdkPackage: '@daytona/sdk',
+        docsUrl: 'https://www.daytona.io/docs/en/sandboxes/',
+        icon: '/icons/daytonaio.png',
+        executionSupport: 'full',
+        fields: [
+            {
+                key: 'apiKey',
+                label: 'API key',
+                type: 'password',
+                required: true,
+                secret: true,
+                help: 'From the Daytona dashboard. Equivalent to DAYTONA_API_KEY.',
+            },
+            {
+                key: 'apiUrl',
+                label: 'API URL',
+                type: 'text',
+                required: false,
+                placeholder: 'https://app.daytona.io/api',
+                help: 'Only needed for a self-hosted Daytona instance.',
+            },
+            {
+                key: 'snapshot',
+                label: 'Snapshot',
+                type: 'text',
+                required: false,
+                help: 'Optional Daytona snapshot containing the dependencies your agent needs.',
+            },
+        ],
+    },
+    browserbase: {
+        id: 'browserbase',
+        label: 'Browserbase',
+        description: 'Headless-Chrome browser sessions for Playwright/Puppeteer automation.',
+        sdkPackage: '@browserbasehq/sdk',
+        docsUrl: 'https://docs.browserbase.com/welcome/introduction',
+        icon: '/icons/browserbase.png',
+        executionSupport: 'unsupported',
+        executionCaveat: 'Browserbase provisions remote browser sessions reachable over CDP for Playwright/Puppeteer — it does not run arbitrary Python/JS and return stdout the way a code-execution sandbox does. Verify still checks your API key and project, but code-execution tools (data analysis, corpus analytics) need a different provider.',
+        fields: [
+            {
+                key: 'apiKey',
+                label: 'API key',
+                type: 'password',
+                required: true,
+                secret: true,
+                help: 'Equivalent to BROWSERBASE_API_KEY.',
+            },
+            {
+                key: 'projectId',
+                label: 'Project ID',
+                type: 'text',
+                required: true,
+                help: 'Equivalent to BROWSERBASE_PROJECT_ID.',
+            },
+        ],
+    },
+    flyio: {
+        id: 'flyio',
+        label: 'Fly.io Sprites',
+        description: 'Persistent, fast-suspending Linux VM sandboxes for AI agents, built on Fly Machines.',
+        sdkPackage: '@fly/sprites',
+        docsUrl: 'https://fly.io/sprites/',
+        icon: '/icons/flyio.jpeg',
+        executionSupport: 'full',
+        fields: [
+            {
+                key: 'token',
+                label: 'Sprite token',
+                type: 'password',
+                required: true,
+                secret: true,
+                help: 'From `sprite org auth` or the Fly dashboard. Equivalent to SPRITE_TOKEN.',
+            },
+        ],
+    },
+    northflank: {
+        id: 'northflank',
+        label: 'Northflank',
+        description: 'On-demand sandbox containers running as Northflank services in your own project.',
+        sdkPackage: '@northflank/js-client',
+        docsUrl: 'https://northflank.com/docs/v1/application/sandboxes/sandboxes-on-northflank',
+        icon: '/icons/Northflank.png',
+        executionSupport: 'full',
+        fields: [
+            {
+                key: 'token',
+                label: 'API token',
+                type: 'password',
+                required: true,
+                secret: true,
+                help: 'A personal or team API token from Northflank → Account → API Tokens.',
+            },
+            {
+                key: 'projectId',
+                label: 'Project ID',
+                type: 'text',
+                required: true,
+                help: 'The Northflank project sandbox services are created in.',
+            },
+        ],
+    },
+    cloudflare: {
+        id: 'cloudflare',
+        label: 'Cloudflare Sandbox',
+        description: 'Container sandboxes running inside a Cloudflare Worker via the Durable Object Sandbox SDK.',
+        sdkPackage: '@cloudflare/sandbox',
+        docsUrl: 'https://developers.cloudflare.com/sandbox/',
+        icon: '/icons/cloudflare.png',
+        executionSupport: 'unsupported',
+        executionCaveat: '@cloudflare/sandbox only runs inside a Cloudflare Worker through a Durable Object binding declared in wrangler config. There is no external REST API to create or run commands in a sandbox from this server. Verify checks your account API token; actually running code here requires deploying a Worker with the Sandbox binding.',
+        fields: [
+            {
+                key: 'apiToken',
+                label: 'API token',
+                type: 'password',
+                required: true,
+                secret: true,
+                help: 'Used only to verify account access.',
+            },
+            {
+                key: 'accountId',
+                label: 'Account ID',
+                type: 'text',
+                required: true,
+            },
+        ],
+    },
+    webcontainers: {
+        id: 'webcontainers',
+        label: 'WebContainers',
+        description: 'In-browser WebAssembly Node.js runtime for running full-stack apps client-side.',
+        sdkPackage: '@webcontainer/api',
+        docsUrl: 'https://webcontainers.io/',
+        icon: '/icons/webcontainers.svg',
+        executionSupport: 'unsupported',
+        executionCaveat: 'WebContainers boots entirely inside a cross-origin-isolated browser tab (it needs SharedArrayBuffer). There is no Node.js/server-side way to run it, so this backend cannot execute code from here. Use @webcontainer/api directly in your frontend for in-browser execution instead.',
+        fields: [
+            {
+                key: 'apiKey',
+                label: 'License key (optional)',
+                type: 'password',
+                required: false,
+                secret: true,
+                help: 'StackBlitz-issued commercial key for production embeds. Leave blank for local/prototype use.',
+            },
+        ],
+    },
+};
+export const SANDBOX_PROVIDER_LIST = Object.values(SANDBOX_PROVIDERS);
+export function getSandboxProvider(id) {
+    if (id === 'local' || id === 'docker' || id === 'custom')
+        return undefined;
+    return SANDBOX_PROVIDERS[id];
+}
+/** Validates credentials against a provider's registered fields, mirroring validateStoreConfig. */
+export function validateSandboxCredentials(provider, values) {
+    const errors = {};
+    for (const field of provider.fields) {
+        if (field.required && !values[field.key]?.trim()) {
+            errors[field.key] = `${field.label} is required`;
+        }
+    }
+    return errors;
+}

package/dist/remote-exec.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Shared execution plumbing for every cloud sandbox adapter (E2B, Vercel
+ * Sandbox, Modal, Daytona, Fly Sprites, Northflank).
+ *
+ * Each of those providers exposes the same primitive — "run this shell
+ * command inside my sandbox and give me stdout/stderr/exitCode back" — but
+ * with a different SDK shape (commands.run, runCommand, exec, ...). Rather
+ * than re-implement file staging + artifact capture per provider, adapters
+ * plug their SDK's exec call in as a `RemoteExecFn` and hand it to
+ * `runScriptedExecution`, which builds one POSIX shell script that writes
+ * any input files, runs the code, and reports back any files written to an
+ * output directory (mirroring what the Docker adapter gets for free via a
+ * bind mount).
+ */
+import type { ExecutionRequest, ExecutionResult } from './types.js';
+/** Default per-execution timeout for remote adapters when a request doesn't specify one. */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export interface RemoteCommandResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Runs a single shell command/script inside a provider's sandbox instance. */
+export type RemoteExecFn = (script: string) => Promise<RemoteCommandResult>;
+/** Builds the POSIX shell script a remote adapter hands to its provider's exec call. */
+export declare function buildExecutionScript(request: ExecutionRequest): string;
+/**
+ * Runs `request` via `execFn` and reassembles an `ExecutionResult`,
+ * including a best-effort fetch of any files the code wrote to the output
+ * directory (one follow-up `base64 <file>` call per artifact).
+ */
+export declare function runScriptedExecution(execFn: RemoteExecFn, request: ExecutionRequest): Promise<ExecutionResult>;
+/** Uniform safety net for providers whose SDK doesn't take its own per-call timeout. */
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
+/**
+ * Runs a teardown call (kill/delete/terminate/stop) and swallows whatever it
+ * throws or rejects with — cleanup failures shouldn't mask the actual
+ * execution result. Wrapping in try/catch (rather than `.catch()`) also
+ * tolerates a teardown method that doesn't return a real promise.
+ */
+export declare function safeCleanup(fn: () => Promise<unknown>): Promise<void>;
+export declare function failedResult(message: string, startTime: number): ExecutionResult;

package/dist/remote-exec.js

@@ -0,0 +1,144 @@
+/**
+ * Shared execution plumbing for every cloud sandbox adapter (E2B, Vercel
+ * Sandbox, Modal, Daytona, Fly Sprites, Northflank).
+ *
+ * Each of those providers exposes the same primitive — "run this shell
+ * command inside my sandbox and give me stdout/stderr/exitCode back" — but
+ * with a different SDK shape (commands.run, runCommand, exec, ...). Rather
+ * than re-implement file staging + artifact capture per provider, adapters
+ * plug their SDK's exec call in as a `RemoteExecFn` and hand it to
+ * `runScriptedExecution`, which builds one POSIX shell script that writes
+ * any input files, runs the code, and reports back any files written to an
+ * output directory (mirroring what the Docker adapter gets for free via a
+ * bind mount).
+ */
+import { getMimeType } from './mime.js';
+/** Default per-execution timeout for remote adapters when a request doesn't specify one. */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+const WORKDIR = '/tmp/larkup-sandbox';
+const OUTPUT_DIR = `${WORKDIR}/output`;
+const ARTIFACT_MARKER = '__LARKUP_ARTIFACTS__:';
+/** Not part of the base64 alphabet, so it can never collide with an encoded file body. */
+const HEREDOC_DELIMITER = 'LARKUP__EOF__';
+function assertSafeFileName(name) {
+    if (!name ||
+        name === '.' ||
+        name === '..' ||
+        name.includes('/') ||
+        name.includes('\\') ||
+        name.includes('\0')) {
+        throw new Error('Sandbox file names must be plain file names.');
+    }
+}
+function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function writeBase64FileScript(name, base64) {
+    return `base64 -d > ${shellSingleQuote(name)} <<'${HEREDOC_DELIMITER}'\n${base64}\n${HEREDOC_DELIMITER}`;
+}
+/** Builds the POSIX shell script a remote adapter hands to its provider's exec call. */
+export function buildExecutionScript(request) {
+    const lines = [
+        'set -e',
+        `mkdir -p ${shellSingleQuote(OUTPUT_DIR)}`,
+        `cd ${shellSingleQuote(WORKDIR)}`,
+    ];
+    for (const file of request.files ?? []) {
+        assertSafeFileName(file.name);
+        const base64 = file.isBase64
+            ? file.content
+            : Buffer.from(file.content, 'utf8').toString('base64');
+        lines.push(writeBase64FileScript(file.name, base64));
+    }
+    const scriptName = request.language === 'python' ? 'run.py' : 'run.js';
+    const runner = request.language === 'python' ? 'python3' : 'node';
+    const codeBase64 = Buffer.from(request.code, 'utf8').toString('base64');
+    lines.push(writeBase64FileScript(scriptName, codeBase64));
+    lines.push(`${runner} ${shellSingleQuote(scriptName)}`);
+    lines.push(`if [ -d ${shellSingleQuote(OUTPUT_DIR)} ]; then echo "${ARTIFACT_MARKER}$(ls -1 ${shellSingleQuote(OUTPUT_DIR)} 2>/dev/null | tr '\\n' ',')"; fi`);
+    return lines.join('\n');
+}
+function extractArtifactMarker(stdout) {
+    const markerIndex = stdout.lastIndexOf(ARTIFACT_MARKER);
+    if (markerIndex === -1)
+        return { stdout, artifactNames: [] };
+    const before = stdout.slice(0, markerIndex);
+    const after = stdout.slice(markerIndex + ARTIFACT_MARKER.length);
+    const newlineIndex = after.indexOf('\n');
+    const namesPart = newlineIndex === -1 ? after : after.slice(0, newlineIndex);
+    const rest = newlineIndex === -1 ? '' : after.slice(newlineIndex + 1);
+    const artifactNames = namesPart
+        .split(',')
+        .map((name) => name.trim())
+        .filter(Boolean);
+    return { stdout: (before + rest).replace(/\n$/, ''), artifactNames };
+}
+/**
+ * Runs `request` via `execFn` and reassembles an `ExecutionResult`,
+ * including a best-effort fetch of any files the code wrote to the output
+ * directory (one follow-up `base64 <file>` call per artifact).
+ */
+export async function runScriptedExecution(execFn, request) {
+    const startTime = Date.now();
+    const script = buildExecutionScript(request);
+    const main = await execFn(script);
+    const { stdout, artifactNames } = extractArtifactMarker(main.stdout);
+    const artifacts = [];
+    for (const name of artifactNames) {
+        if (!name || name.includes('/') || name.includes('\\') || name === '.' || name === '..')
+            continue;
+        try {
+            const cat = await execFn(`base64 ${shellSingleQuote(`${OUTPUT_DIR}/${name}`)}`);
+            const data = cat.stdout.replace(/\s+/g, '');
+            if (cat.exitCode === 0 && data) {
+                artifacts.push({ name, mimeType: getMimeType(name), data });
+            }
+        }
+        catch {
+            /* one missing/unreadable artifact shouldn't fail the whole execution */
+        }
+    }
+    return {
+        stdout,
+        stderr: main.stderr,
+        exitCode: main.exitCode,
+        artifacts,
+        executionTimeMs: Date.now() - startTime,
+    };
+}
+/** Uniform safety net for providers whose SDK doesn't take its own per-call timeout. */
+export async function withTimeout(promise, timeoutMs, label) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Runs a teardown call (kill/delete/terminate/stop) and swallows whatever it
+ * throws or rejects with — cleanup failures shouldn't mask the actual
+ * execution result. Wrapping in try/catch (rather than `.catch()`) also
+ * tolerates a teardown method that doesn't return a real promise.
+ */
+export async function safeCleanup(fn) {
+    try {
+        await fn();
+    }
+    catch {
+        /* best effort */
+    }
+}
+export function failedResult(message, startTime) {
+    return {
+        stdout: '',
+        stderr: message,
+        exitCode: 1,
+        artifacts: [],
+        executionTimeMs: Date.now() - startTime,
+    };
+}

package/dist/sandbox-manager.d.ts

@@ -2,8 +2,9 @@
  * Sandbox manager — high-level API for code execution.
  *
  * Provides a unified interface that routes to the appropriate backend
- * (Docker, E2B, etc.) based on configuration. Handles health checks,
- * image setup, and execution lifecycle.
+ * (Docker or one of the remote providers in ./providers) based on
+ * configuration. Handles health checks, image setup, and execution
+ * lifecycle.
  */
 import type { SandboxConfig, ExecutionRequest, ExecutionResult, SandboxHealthCheck } from './types.js';
 export declare class SandboxManager {
@@ -16,3 +17,5 @@ export declare class SandboxManager {
     /** Execute code in the sandbox. */
     execute(request: ExecutionRequest): Promise<ExecutionResult>;
 }
+/** Verifies a remote provider's credentials — powers the Settings "Verify" button. */
+export declare function verifySandboxProvider(backend: SandboxConfig['backend'], credentials: Record<string, string>): Promise<void>;

package/dist/sandbox-manager.js

@@ -2,10 +2,13 @@
  * Sandbox manager — high-level API for code execution.
  *
  * Provides a unified interface that routes to the appropriate backend
- * (Docker, E2B, etc.) based on configuration. Handles health checks,
- * image setup, and execution lifecycle.
+ * (Docker or one of the remote providers in ./providers) based on
+ * configuration. Handles health checks, image setup, and execution
+ * lifecycle.
  */
 import { checkDockerHealth, buildSandboxImage, ensureImage, executeInDocker, } from './docker-runner.js';
+import { checkLocalRuntime, executeLocally } from './local-runner.js';
+import { getSandboxProviderAdapter } from './providers/index.js';
 const defaultDockerConfig = {
     imageName: 'larkup-sandbox:latest',
     memoryMB: 512,
@@ -17,35 +20,32 @@ export class SandboxManager {
     config;
     constructor(config) {
         this.config = {
-            backend: config?.backend ?? 'docker',
+            backend: config?.backend ?? 'local',
             docker: config?.docker,
-            remote: config?.remote,
+            credentials: config?.credentials,
         };
     }
     /** Check if the sandbox backend is available and ready. */
     async healthCheck() {
-        switch (this.config.backend) {
-            case 'docker':
-                return checkDockerHealth();
-            case 'e2b':
-            case 'modal':
-            case 'custom':
-                return {
-                    status: 'error',
-                    backend: this.config.backend,
-                    error: `${this.config.backend} backend is not yet implemented. Use Docker for local execution.`,
-                };
-            default:
-                return {
-                    status: 'error',
-                    backend: this.config.backend,
-                    error: `Unknown backend: ${this.config.backend}`,
-                };
+        if (this.config.backend === 'local')
+            return checkLocalRuntime();
+        if (this.config.backend === 'docker')
+            return checkDockerHealth();
+        const adapter = getSandboxProviderAdapter(this.config.backend);
+        if (!adapter) {
+            return {
+                status: 'error',
+                backend: this.config.backend,
+                error: `Unknown or unsupported backend: ${this.config.backend}`,
+            };
         }
+        return adapter.healthCheck(this.config.credentials ?? {});
     }
     /** Set up the sandbox backend (e.g., build Docker image). */
     async setup(onProgress) {
         switch (this.config.backend) {
+            case 'local':
+                return;
             case 'docker':
                 await buildSandboxImage(onProgress);
                 break;
@@ -55,43 +55,64 @@ export class SandboxManager {
     }
     /** Execute code in the sandbox. */
     async execute(request) {
-        switch (this.config.backend) {
-            case 'docker': {
-                // Ensure image is available
-                const imageReady = await ensureImage();
-                if (!imageReady) {
-                    return {
-                        stdout: '',
-                        stderr: 'Sandbox image not available. Run setup first or ensure Docker is installed.',
-                        exitCode: 1,
-                        artifacts: [],
-                        executionTimeMs: 0,
-                    };
-                }
-                const dockerConfig = {
-                    ...defaultDockerConfig,
-                    ...this.config.docker,
-                };
-                return executeInDocker(request, dockerConfig);
-            }
-            case 'e2b':
-            case 'modal':
-            case 'custom':
+        if (this.config.backend === 'local')
+            return executeLocally(request);
+        if (this.config.backend === 'docker') {
+            const health = await checkDockerHealth();
+            if (health.status === 'docker-not-found' || health.status === 'error') {
                 return {
                     stdout: '',
-                    stderr: `${this.config.backend} backend is not yet implemented.`,
+                    stderr: 'Local code execution is unavailable because Docker is not running. Start Docker, choose a configured remote sandbox provider, or continue without code execution.',
                     exitCode: 1,
                     artifacts: [],
                     executionTimeMs: 0,
                 };
-            default:
+            }
+            const imageReady = health.imageReady || (await ensureImage().catch(() => false));
+            if (!imageReady) {
                 return {
                     stdout: '',
-                    stderr: `Unknown backend: ${this.config.backend}`,
+                    stderr: 'Local code execution is not ready. Build the Larkup sandbox image, choose a configured remote sandbox provider, or continue without code execution.',
                     exitCode: 1,
                     artifacts: [],
                     executionTimeMs: 0,
                 };
+            }
+            const dockerConfig = {
+                ...defaultDockerConfig,
+                ...this.config.docker,
+            };
+            return executeInDocker(request, dockerConfig);
         }
+        const adapter = getSandboxProviderAdapter(this.config.backend);
+        if (!adapter) {
+            return {
+                stdout: '',
+                stderr: `Unknown or unsupported backend: ${this.config.backend}`,
+                exitCode: 1,
+                artifacts: [],
+                executionTimeMs: 0,
+            };
+        }
+        return adapter.execute(request, this.config.credentials ?? {});
+    }
+}
+/** Verifies a remote provider's credentials — powers the Settings "Verify" button. */
+export async function verifySandboxProvider(backend, credentials) {
+    if (backend === 'local') {
+        const health = await checkLocalRuntime();
+        if (health.status !== 'ready')
+            throw new Error(health.error ?? 'Local runtime is not available.');
+        return;
+    }
+    if (backend === 'docker') {
+        const health = await checkDockerHealth();
+        if (health.status !== 'ready')
+            throw new Error(health.error ?? 'Docker is not available.');
+        return;
     }
+    const adapter = getSandboxProviderAdapter(backend);
+    if (!adapter)
+        throw new Error(`Unknown or unsupported backend: ${backend}`);
+    await adapter.verifyCredentials(credentials);
 }