@sandbox-kit/daytona 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sandbox-kit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# Daytona provider for Sandbox Kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Independent package over `@daytona/sdk@0.225.0`, published separately from the
+core `@sandbox-kit/sandbox` client. Use it through that shared API.
+
+```sh
+npm install @sandbox-kit/sandbox @sandbox-kit/daytona
+```
+
+## Usage
+
+```ts
+import { Client } from "@sandbox-kit/sandbox";
+import { daytona } from "@sandbox-kit/daytona";
+
+await using client = new Client({
+  provider: daytona(),
+  auth: { apiKey: { key: process.env.DAYTONA_API_KEY! } },
+  timeout: 120_000,
+});
+
+const sandbox = await client.create({
+  source: { image: { reference: "daytonaio/playground:latest" } },
+  runtime: { language: "typescript" },
+});
+console.log(sandbox.id);
+```
+
+Auth may be omitted when the native Daytona SDK should resolve credentials from
+its environment. Closing the client releases local SDK resources only.
+
+## Examples
+
+| Example    | Project                                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------------- |
+| Creation   | [create-daytona-sandbox](../../../../examples/typescript/daytona/create-daytona-sandbox/README.md)             |
+| Policies   | [create-daytona-with-policies](../../../../examples/typescript/daytona/create-daytona-with-policies/README.md) |
+| Retrieval  | [get-daytona-sandbox](../../../../examples/typescript/daytona/get-daytona-sandbox/README.md)                   |
+| Full index | [TypeScript examples](../../../../examples/typescript/README.md)                                               |
+
+## Implementation notes
+
+Checks and portable field mappings are handwritten in `checks/provider_checks.ts`,
+`mappings/provider_mappings.ts`, and `config/provider_config.ts`, kept in sync with
+`specs/providers/daytona.yaml`. `src/daytona.ts` owns typed Daytona SDK call
+ordering and lifecycle orchestration; `src/mappings.ts` owns remaining
+provider-specific composition.
+
+## Dependency audit
+
+`npm audit` reports four high-severity findings in the pinned
+`@daytona/sdk@0.225.0` dependency chain (`fast-glob` → `micromatch` → `braces`).
+The registry reports no fix (`braces` latest is still vulnerable; Daytona still
+depends on `fast-glob`). The provider does not override those transitive
+packages, because overrides could create an unsupported SDK combination.
+Reassess the audit when Daytona drops or patches that chain.

package/dist/checks/provider_checks.d.ts

@@ -0,0 +1,2 @@
+import type { CreateOptions } from "@sandbox-kit/sandbox";
+export declare function validateProviderCreate(request: CreateOptions): void;

package/dist/checks/provider_checks.js

@@ -0,0 +1,137 @@
+import { ErrorKind, PolicyMode, sandboxError, CreateFieldLifetime, CreateFieldNetworkOutboundCidrsEntries, CreateFieldNetworkOutboundDomainsEntries, CreateFieldNetworkOutboundProxyUrl, CreateFieldRuntimeLanguage, CreateFieldSecuritySecretsEnvironmentVariable } from "@sandbox-kit/sandbox";
+// validateProviderCreate rejects creation settings this provider cannot honor.
+// Rules are inventoried in specs/providers/daytona.yaml checks.
+export function validateProviderCreate(request) {
+    const language = request.runtime?.language;
+    if (language !== undefined &&
+        language !== "python" &&
+        language !== "javascript" &&
+        language !== "typescript") {
+        fail(ErrorKind.Unsupported, CreateFieldRuntimeLanguage, "runtime.language is outside supported values");
+    }
+    const outboundProxyUrl = request.network?.outboundProxyUrl;
+    if (outboundProxyUrl !== undefined && !validHttpUrl(outboundProxyUrl)) {
+        fail(ErrorKind.InvalidArgument, CreateFieldNetworkOutboundProxyUrl, "network.outbound_proxy_url is outside supported values");
+    }
+    for (const value of request.network?.outboundCidrs ?? []) {
+        if (!validCidr(value)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldNetworkOutboundCidrsEntries, "network.outbound_cidrs.entries is outside supported values");
+        }
+    }
+    for (const value of request.network?.outboundDomains ?? []) {
+        if (!validDomain(value)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldNetworkOutboundDomainsEntries, "network.outbound_domains.entries is outside supported values");
+        }
+    }
+    for (const item of request.security?.secrets ?? []) {
+        const environmentVariable = item.environmentVariable;
+        if (environmentVariable !== undefined &&
+            !validEnvName(environmentVariable)) {
+            fail(ErrorKind.InvalidArgument, CreateFieldSecuritySecretsEnvironmentVariable, "security.secrets.environment_variable is outside supported values");
+        }
+    }
+    if (delayed(request.lifetime?.idleStop) &&
+        delayed(request.lifetime?.idlePause)) {
+        invalid(CreateFieldLifetime, "incompatible lifetime policies");
+    }
+    if (delayed(request.lifetime?.idlePause) &&
+        request.lifetime?.ephemeral === true) {
+        invalid(CreateFieldLifetime, "incompatible lifetime policies");
+    }
+    if (delayed(request.lifetime?.idlePause) &&
+        immediate(request.lifetime?.stoppedDelete)) {
+        invalid(CreateFieldLifetime, "incompatible lifetime policies");
+    }
+    if (delayed(request.lifetime?.stoppedDelete) &&
+        request.lifetime?.ephemeral === true) {
+        invalid(CreateFieldLifetime, "incompatible lifetime policies");
+    }
+    if (delayed(request.lifetime?.stoppedArchive) &&
+        request.lifetime?.ephemeral === true) {
+        invalid(CreateFieldLifetime, "incompatible lifetime policies");
+    }
+}
+function delayed(policy) {
+    return ((policy?.mode ?? PolicyMode.Default) === PolicyMode.After &&
+        policy?.after !== undefined &&
+        policy.after > 0);
+}
+function immediate(policy) {
+    return ((policy?.mode ?? PolicyMode.Default) === PolicyMode.After &&
+        policy?.after !== undefined &&
+        policy.after === 0);
+}
+function validEnvName(value) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(value);
+}
+function validHttpUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return (parsed.hostname !== "" &&
+            (parsed.protocol === "http:" || parsed.protocol === "https:"));
+    }
+    catch {
+        return false;
+    }
+}
+function validDomain(value) {
+    const domain = value.startsWith("*.") ? value.slice(2) : value;
+    return (domain.length <= 253 &&
+        /^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)*[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.?$/i.test(domain));
+}
+function validCidr(value) {
+    const separator = value.lastIndexOf("/");
+    if (separator <= 0)
+        return false;
+    const address = value.slice(0, separator);
+    const prefix = Number(value.slice(separator + 1));
+    if (!Number.isInteger(prefix))
+        return false;
+    return address.includes(":")
+        ? prefix >= 0 && prefix <= 128 && validIpv6(address)
+        : prefix >= 0 && prefix <= 32 && validIpv4(address);
+}
+function validIpv4(value) {
+    const parts = value.split(".");
+    return (parts.length === 4 &&
+        parts.every((part) => /^(0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+}
+function validIpv6(value) {
+    if ((value.match(/::/g)?.length ?? 0) > 1)
+        return false;
+    const halves = value.split("::");
+    if (halves.length > 2)
+        return false;
+    const count = (part) => {
+        if (part === "")
+            return 0;
+        const groups = part.split(":");
+        let total = 0;
+        for (const group of groups) {
+            if (/^[0-9a-f]{1,4}$/i.test(group))
+                total++;
+            else if (validIpv4(group))
+                total += 2;
+            else
+                return undefined;
+        }
+        return total;
+    };
+    const left = count(halves[0] ?? "");
+    const right = count(halves[1] ?? "");
+    return (left !== undefined &&
+        right !== undefined &&
+        (halves.length === 2 ? left + right < 8 : left === 8));
+}
+function invalid(field, message) {
+    fail(ErrorKind.InvalidArgument, field, message);
+}
+function fail(kind, field, message) {
+    throw sandboxError({
+        kind,
+        provider: "daytona",
+        operation: "create",
+        field,
+        message: "sandbox-kit daytona: " + message,
+    });
+}

package/dist/config/provider_config.d.ts

@@ -0,0 +1,4 @@
+import type { DaytonaConfig as NativeClientConfig } from "@daytona/sdk";
+import { type Config } from "@sandbox-kit/sandbox";
+export type Environment = Readonly<Record<string, string | undefined>>;
+export declare function mapGeneratedClientConfig(config: Config, environment?: Environment): NativeClientConfig;

package/dist/config/provider_config.js

@@ -0,0 +1,49 @@
+// Client configuration composition for the native SDK constructor.
+// Kept in sync with specs/providers/daytona.yaml client: rules (not emitted).
+import { ErrorKind, sandboxError, validateConfig, ConfigFieldAuth, ConfigFieldScopeAppName, ConfigFieldScopeEnvironment, ConfigFieldScopeProjectId } from "@sandbox-kit/sandbox";
+import { mapAPIKeyCredentials, mapBearerAuth, mapClientSettings, mapScope, } from "#mappings/provider_mappings.js";
+export function mapGeneratedClientConfig(config, environment = environmentVariables()) {
+    let source = config;
+    if (source.endpoint === undefined)
+        source = {
+            ...source,
+            endpoint: environment.DAYTONA_API_URL ??
+                environment.DAYTONA_SERVER_URL ??
+                "https://app.daytona.io/api",
+        };
+    validateConfig(source, "daytona", "initialize");
+    const target = mapClientSettings(source, "initialize");
+    if (source.scope !== undefined) {
+        const mapped = mapScope(source.scope, "initialize");
+        Object.assign(target, mapped);
+        if (source.scope.appName !== undefined)
+            unsupported(ConfigFieldScopeAppName, "unsupported client configuration field");
+        if (source.scope.environment !== undefined)
+            unsupported(ConfigFieldScopeEnvironment, "unsupported client configuration field");
+        if (source.scope.projectId !== undefined)
+            unsupported(ConfigFieldScopeProjectId, "unsupported client configuration field");
+    }
+    if (source.auth?.apiKey !== undefined) {
+        Object.assign(target, mapAPIKeyCredentials(source.auth.apiKey, "initialize"));
+    }
+    else if (source.auth?.bearerToken !== undefined) {
+        Object.assign(target, mapBearerAuth(source.auth.bearerToken, "initialize"));
+    }
+    else if (source.auth !== undefined) {
+        unsupported(ConfigFieldAuth, "unsupported authentication mode");
+    }
+    return target;
+}
+function environmentVariables() {
+    return (globalThis
+        .process?.env ?? {});
+}
+function unsupported(field, message) {
+    throw sandboxError({
+        kind: ErrorKind.Unsupported,
+        provider: "daytona",
+        operation: "initialize",
+        field,
+        message: "sandbox-kit daytona: " + message,
+    });
+}

package/dist/daytona.d.ts

@@ -0,0 +1,22 @@
+import { type DaytonaConfig, type Sandbox as DaytonaSandbox } from "@daytona/sdk";
+import { type Provider } from "@sandbox-kit/sandbox";
+import type { Backend, Config } from "@sandbox-kit/sandbox";
+import { mapCreateRequest } from "#mappings/mappings.js";
+import { ProviderBase } from "./provider.js";
+interface NativeDaytona {
+    create(params: ReturnType<typeof mapCreateRequest>, options?: {
+        readonly timeout?: number;
+    }): Promise<DaytonaSandbox>;
+    get(id: string): Promise<DaytonaSandbox>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+type NativeFactory = (config: DaytonaConfig) => NativeDaytona;
+/** @internal Exported from this module for boundary testing, but not from the package root. */
+export declare class DaytonaProvider extends ProviderBase {
+    private readonly nativeFactory;
+    constructor(nativeFactory?: NativeFactory);
+    initialize(config: Config): Backend;
+}
+/** Selects Daytona as the provider for the shared Sandbox Kit client. */
+export declare function daytona(): Provider;
+export {};

package/dist/daytona.js

@@ -0,0 +1,108 @@
+import { Daytona, } from "@daytona/sdk";
+import { durationMs } from "@bufbuild/protobuf/wkt";
+import { IsolationKind, LifecycleCapability, metadataObjectAsMap } from "@sandbox-kit/sandbox";
+import { mapClientConfig, mapCreateRequest, mapSandboxInfo, } from "#mappings/mappings.js";
+import { mapDaytonaError } from "./errors.js";
+import { BackendBase, ProviderBase } from "./provider.js";
+/** @internal Exported from this module for boundary testing, but not from the package root. */
+export class DaytonaProvider extends ProviderBase {
+    nativeFactory;
+    constructor(nativeFactory = (config) => new Daytona(config)) {
+        super();
+        this.nativeFactory = nativeFactory;
+    }
+    initialize(config) {
+        try {
+            return new DaytonaBackend(this.nativeFactory(mapClientConfig(config)));
+        }
+        catch (error) {
+            throw mapDaytonaError(error, "initialize");
+        }
+    }
+}
+class DaytonaBackend extends BackendBase {
+    native;
+    constructor(native) {
+        super();
+        this.native = native;
+    }
+    async create(request, options) {
+        try {
+            options.signal?.throwIfAborted();
+            const params = mapCreateRequest(request);
+            const timeout = options.timeout === undefined ? undefined : options.timeout / 1_000;
+            const sandbox = await this.native.create(params, timeout === undefined ? undefined : { timeout });
+            return { sandbox: mapSandboxInfo(sandbox, "create") };
+        }
+        catch (error) {
+            throw mapDaytonaError(error, "create");
+        }
+    }
+    capabilities(info) {
+        if (info.terminal)
+            return [];
+        const result = [
+            LifecycleCapability.Refresh,
+            LifecycleCapability.Start,
+            LifecycleCapability.Stop,
+            LifecycleCapability.Delete,
+        ];
+        const metadata = metadataObjectAsMap(info.providerMetadata);
+        const gpuCount = metadata?.gpu_count;
+        const hasGpu = (typeof gpuCount === "number" && gpuCount > 0) ||
+            (typeof gpuCount === "bigint" && gpuCount > 0n);
+        if (!hasGpu &&
+            (info.isolation?.kind === IsolationKind.LinuxVm ||
+                info.isolation?.providerKind === "windows"))
+            result.push(LifecycleCapability.Pause);
+        if (!hasGpu && info.isolation?.kind === IsolationKind.Container)
+            result.push(LifecycleCapability.Archive);
+        return result;
+    }
+    async refresh(id) {
+        return this.withSandbox(id, "refresh", async (value) => {
+            await value.refreshData();
+        });
+    }
+    async start(id, request) {
+        return this.withSandbox(id, "start", (value) => value.start(seconds(request.timeout)));
+    }
+    async stop(id, request) {
+        return this.withSandbox(id, "stop", (value) => value.stop(seconds(request.timeout), request.force));
+    }
+    async pause(id, request) {
+        return this.withSandbox(id, "pause", (value) => value.pause(seconds(request.timeout)));
+    }
+    async archive(id, _request) {
+        return this.withSandbox(id, "archive", (value) => value.archive());
+    }
+    async delete(id, request) {
+        return this.withSandbox(id, "delete", (value) => value.delete(seconds(request.timeout), request.wait));
+    }
+    async closeSandbox(_id) { }
+    async withSandbox(id, operation, action) {
+        try {
+            const sandbox = await this.native.get(id);
+            await action(sandbox);
+            return mapSandboxInfo(sandbox, operation);
+        }
+        catch (error) {
+            throw mapDaytonaError(error, operation);
+        }
+    }
+    async close(_options) {
+        try {
+            await this.native[Symbol.asyncDispose]();
+        }
+        catch (error) {
+            throw mapDaytonaError(error, "close");
+        }
+    }
+}
+function seconds(value) {
+    return value === undefined ? undefined : durationMs(value) / 1_000;
+}
+/** Selects Daytona as the provider for the shared Sandbox Kit client. */
+export function daytona() {
+    return new DaytonaProvider();
+}

package/dist/errors.d.ts

@@ -0,0 +1,2 @@
+import { SandboxError } from "@sandbox-kit/sandbox";
+export declare function mapDaytonaError(error: unknown, operation: string): SandboxError;

package/dist/errors.js

@@ -0,0 +1,79 @@
+// Native Daytona error translation is handwritten.
+// Classification order: existing SandboxError, abort/timeout DOMException,
+// then DaytonaError code/status maps, then unknown. Cause stays on SandboxError.cause.
+import { DaytonaError } from "@daytona/sdk";
+import { ErrorKind, SandboxError, sandboxError } from "@sandbox-kit/sandbox";
+export function mapDaytonaError(error, operation) {
+    if (error instanceof SandboxError)
+        return error;
+    if (error instanceof DOMException && error.name === "AbortError")
+        return create(ErrorKind.Canceled, error, operation);
+    if (error instanceof DOMException && error.name === "TimeoutError")
+        return create(ErrorKind.Timeout, error, operation);
+    let kind = ErrorKind.Unknown;
+    let statusCode;
+    let providerCode;
+    let providerSource;
+    if (error instanceof DaytonaError) {
+        statusCode = error.statusCode;
+        providerCode = error.code;
+        providerSource = error.source;
+        if (kind === ErrorKind.Unknown)
+            switch (error.code) {
+                case "SANDBOX_SPOT_EVICTED":
+                    kind = ErrorKind.Unavailable;
+                    break;
+            }
+        if (kind === ErrorKind.Unknown)
+            switch (error.statusCode) {
+                case 400:
+                    kind = ErrorKind.InvalidArgument;
+                    break;
+                case 401:
+                    kind = ErrorKind.Authentication;
+                    break;
+                case 403:
+                    kind = ErrorKind.PermissionDenied;
+                    break;
+                case 404:
+                    kind = ErrorKind.NotFound;
+                    break;
+                case 408:
+                    kind = ErrorKind.Timeout;
+                    break;
+                case 409:
+                    kind = ErrorKind.Conflict;
+                    break;
+                case 410:
+                    kind = ErrorKind.NotFound;
+                    break;
+                case 412:
+                    kind = ErrorKind.FailedPrecondition;
+                    break;
+                case 422:
+                    kind = ErrorKind.InvalidArgument;
+                    break;
+                case 429:
+                    kind = ErrorKind.RateLimited;
+                    break;
+                case 500:
+                    kind = ErrorKind.Internal;
+                    break;
+                case 502:
+                    kind = ErrorKind.Unavailable;
+                    break;
+                case 503:
+                    kind = ErrorKind.Unavailable;
+                    break;
+                case 504:
+                    kind = ErrorKind.Timeout;
+                    break;
+            }
+        if (kind === ErrorKind.Unknown && error.statusCode === 0 && !error.code)
+            kind = ErrorKind.Unavailable;
+    }
+    return create(kind, error, operation, statusCode, providerCode, providerSource);
+}
+function create(kind, error, operation, statusCode, providerCode, providerSource) {
+    return sandboxError({ kind, provider: "daytona", operation, field: "", message: error instanceof Error ? error.message : "sandbox-kit daytona: provider operation failed", ...(statusCode === undefined ? {} : { statusCode }), ...(providerCode === undefined ? {} : { providerCode }), ...(providerSource === undefined ? {} : { providerSource }) }, error);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { daytona } from "./daytona.js";
+export { providerName } from "./provider.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { daytona } from "./daytona.js";
+export { providerName } from "./provider.js";

package/dist/mappings/mappings.d.ts

@@ -0,0 +1,7 @@
+import { type Config, type CreateOptions, type SandboxInfo } from "@sandbox-kit/sandbox";
+import { type CreateSandboxFromImageParams, type CreateSandboxFromSnapshotParams, type DaytonaConfig, type Sandbox as DaytonaSandbox } from "@daytona/sdk";
+import { type Environment } from "#config/provider_config.js";
+export type DaytonaCreateParams = CreateSandboxFromImageParams | CreateSandboxFromSnapshotParams;
+export declare function mapClientConfig(config: Config, environment?: Environment): DaytonaConfig;
+export declare function mapCreateRequest(request: CreateOptions): DaytonaCreateParams;
+export declare function mapSandboxInfo(value: DaytonaSandbox, operation?: string): SandboxInfo;