@alchemy.run/daytona 0.0.0 → 2.0.0-beta.86

package/src/AuthProvider.ts

@@ -0,0 +1,406 @@
+import { credentials, DEFAULT_API_BASE_URL } from "@distilled.cloud/daytona/Credentials";
+import { listOrganizations } from "@distilled.cloud/daytona/organizations";
+import {
+  AuthError,
+  AuthProviderLayer,
+  NeedsReauth,
+  refreshHint,
+  type ConfigureField,
+  type ConfigureMethod,
+  type ProviderDetails,
+} from "alchemy/Auth/AuthProvider";
+import { deviceOAuth } from "alchemy/Auth/BrowserOAuth";
+import { displayRedacted } from "alchemy/Auth/Credentials";
+import { getEnv, getEnvRedacted, mapPromptCancellation } from "alchemy/Auth/Env";
+import { withProfileCredentialsLock } from "alchemy/Auth/Lock";
+import {
+  collectFieldValues,
+  storedSecret,
+  storedValueText,
+  validateFieldValues,
+  type StoredValues,
+} from "alchemy/Auth/StoredAuthProvider";
+import * as Interaction from "alchemy/Interaction";
+import * as Clock from "effect/Clock";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Match from "effect/Match";
+import * as Redacted from "effect/Redacted";
+import * as Schema from "effect/Schema";
+import * as OAuthClient from "./OAuthClient.ts";
+
+export const DAYTONA_AUTH_PROVIDER_NAME = "Daytona";
+
+/**
+ * Values stored in a Daytona profile: an organization API key, or a user
+ * session from `alchemy profile login` (Daytona's device login).
+ */
+export const DaytonaAuthConfigSchema = Schema.Union([
+  Schema.Struct({
+    method: Schema.Literal("stored"),
+    apiKey: Schema.String,
+    apiBaseUrl: Schema.optional(Schema.String),
+    organizationId: Schema.optional(Schema.String),
+  }),
+  Schema.Struct({
+    method: Schema.Literal("oauth"),
+    organizationId: Schema.String,
+    apiBaseUrl: Schema.optional(Schema.String),
+    clientId: Schema.optional(Schema.String),
+    access: Schema.String,
+    refresh: Schema.String,
+    expires: Schema.Number,
+    scopes: Schema.String.pipe(Schema.Array, Schema.mutable),
+  }),
+]);
+export type DaytonaAuthConfig = typeof DaytonaAuthConfigSchema.Type;
+
+/**
+ * Resolved Daytona credentials: a bearer token and the API root. A user
+ * session (`type: "oauth"`) can also manage the organization, its roles,
+ * invitations and API keys, which Daytona refuses to organization API keys.
+ */
+export interface DaytonaResolvedCredentials {
+  type: "apiKey" | "oauth";
+  /** The organization API key, or the user's access token. */
+  token: Redacted.Redacted<string>;
+  apiBaseUrl: string;
+  /** Sent as `X-Daytona-Organization-ID`; an API key already belongs to one organization. */
+  organizationId?: string;
+  /** When a user access token expires (epoch ms). */
+  expires?: number;
+  source: { type: DaytonaAuthConfig["method"] | "env"; details?: string };
+}
+
+const apiKeyFields: ReadonlyArray<ConfigureField> = [
+  {
+    name: "apiKey",
+    label: "Daytona API key (https://app.daytona.io/dashboard/keys)",
+    secret: true,
+  },
+  {
+    name: "apiBaseUrl",
+    label: "Daytona API URL",
+    optional: true,
+    placeholder: DEFAULT_API_BASE_URL,
+  },
+];
+
+const storedConfig = (values: StoredValues): DaytonaAuthConfig => ({
+  method: "stored",
+  apiKey: Redacted.value(storedSecret(values.apiKey) ?? Redacted.make("")),
+  apiBaseUrl: storedValueText(values.apiBaseUrl),
+});
+
+const toOAuthCredentials = (
+  config: Extract<DaytonaAuthConfig, { method: "oauth" }>,
+): OAuthClient.OAuthCredentials => ({
+  type: "oauth",
+  clientId: config.clientId,
+  access: Redacted.make(config.access),
+  refresh: Redacted.make(config.refresh),
+  expires: config.expires,
+  scopes: config.scopes,
+});
+
+const fromOAuthCredentials = (fresh: OAuthClient.OAuthCredentials) => ({
+  clientId: fresh.clientId,
+  access: Redacted.value(fresh.access),
+  refresh: Redacted.value(fresh.refresh),
+  expires: fresh.expires,
+  scopes: fresh.scopes,
+});
+
+/** List the user's organizations and pick one (prompting when there are several). */
+const selectOrganization = (accessToken: Redacted.Redacted<string>) =>
+  Effect.gen(function* () {
+    const organizations = yield* listOrganizations({});
+    const [only] = organizations;
+    if (only === undefined) {
+      return yield* AuthError.make({ message: "Daytona: this user belongs to no organization." });
+    }
+    if (organizations.length === 1) {
+      yield* Interaction.info(`Daytona: using organization ${only.name} (${only.id})`);
+      return only.id;
+    }
+    return yield* Interaction.select({
+      message: "Select a Daytona organization",
+      options: organizations.map((o) => ({ value: o.id, label: o.name, description: o.id })),
+    }).pipe(mapPromptCancellation);
+  }).pipe(
+    Effect.provide(Layer.mergeAll(credentials({ apiKey: accessToken }), FetchHttpClient.layer)),
+  );
+
+/**
+ * Layer that registers the Daytona {@link AuthProvider} into the
+ * {@link AuthProviders} registry when built, so `alchemy profile edit` can
+ * configure it.
+ *
+ * Supported methods:
+ * - `oauth`: Daytona's device login (the same as `daytona login`); the
+ *   session refreshes itself and can manage the organization.
+ * - `stored`: an organization API key stored inline.
+ */
+export const DaytonaAuth = AuthProviderLayer<DaytonaAuthConfig, DaytonaResolvedCredentials>()(
+  DAYTONA_AUTH_PROVIDER_NAME,
+  Effect.gen(function* () {
+    const configureOAuth = Effect.fn(function* (_profileName: string) {
+      const authorization = yield* OAuthClient.deviceAuthorize();
+      const session = yield* deviceOAuth({
+        provider: "Daytona",
+        authorization,
+        token: OAuthClient.deviceToken(authorization),
+      });
+      const organizationId = yield* selectOrganization(session.access);
+      yield* Interaction.success("Daytona: signed in.");
+      return {
+        method: "oauth" as const,
+        organizationId,
+        ...fromOAuthCredentials(session),
+      };
+    });
+
+    const configureApiKey = (_profileName: string) =>
+      collectFieldValues(apiKeyFields).pipe(
+        Effect.map(storedConfig),
+        Effect.tap(() => Interaction.success("Daytona: credentials saved.")),
+      );
+
+    const configure = (profileName: string) =>
+      Interaction.select({
+        message: "Daytona authentication method",
+        options: [
+          {
+            value: "oauth" as const,
+            label: "Sign in",
+            description: "recommended — device login; can also manage the organization",
+          },
+          {
+            value: "stored" as const,
+            label: "API key",
+            description: "an organization API key stored inline",
+          },
+        ],
+      }).pipe(
+        mapPromptCancellation,
+        Effect.flatMap((method) =>
+          Match.value(method).pipe(
+            Match.when("oauth", () => configureOAuth(profileName)),
+            Match.when("stored", () => configureApiKey(profileName)),
+            Match.exhaustive,
+          ),
+        ),
+        Effect.mapError((e) =>
+          AuthError.make({ message: "failed to configure credentials", cause: e }),
+        ),
+      );
+
+    // Sign-in needs a browser, so only the API key has a flag-driven form.
+    const configureMethods: ReadonlyArray<ConfigureMethod> = [
+      { method: "stored", fields: apiKeyFields },
+    ];
+
+    const configureWith = (
+      _profileName: string,
+      input: { readonly method: string; readonly values: Record<string, string> },
+    ) =>
+      input.method === "stored"
+        ? validateFieldValues(DAYTONA_AUTH_PROVIDER_NAME, apiKeyFields, input.values).pipe(
+            Effect.map(storedConfig),
+            Effect.tap(() => Interaction.success("Daytona: credentials saved.")),
+          )
+        : Effect.fail(
+            AuthError.make({
+              message: `Daytona: unknown method '${input.method}'. Valid methods: stored. (Sign-in is interactive-only.)`,
+            }),
+          );
+
+    const read = (
+      profileName: string,
+      config: DaytonaAuthConfig,
+      updateConfig?: (config: DaytonaAuthConfig) => Effect.Effect<void, AuthError>,
+    ) =>
+      Match.value(config).pipe(
+        Match.when({ method: "stored" }, (stored) =>
+          Effect.succeed({
+            type: "apiKey" as const,
+            token: Redacted.make(stored.apiKey),
+            apiBaseUrl: stored.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+            organizationId: stored.organizationId,
+            source: { type: "stored" as const },
+          } satisfies DaytonaResolvedCredentials),
+        ),
+        Match.when({ method: "oauth" }, (oauth) =>
+          Effect.gen(function* () {
+            const reauth = refreshHint(DAYTONA_AUTH_PROVIDER_NAME, profileName);
+            const session = toOAuthCredentials(oauth);
+            if (!OAuthClient.usesCurrentClient(session)) {
+              return yield* NeedsReauth.make({
+                provider: DAYTONA_AUTH_PROVIDER_NAME,
+                profile: profileName,
+                message: `Daytona credentials for profile '${profileName}' were issued to another OAuth client. ${reauth}`,
+              });
+            }
+            // Refresh within a minute of expiry and persist it: WorkOS
+            // refresh tokens are single-use.
+            const now = yield* Clock.currentTimeMillis;
+            const fresh =
+              session.expires > now + 60_000
+                ? session
+                : yield* OAuthClient.refresh(session).pipe(
+                    Effect.mapError((e) =>
+                      NeedsReauth.make({
+                        provider: DAYTONA_AUTH_PROVIDER_NAME,
+                        profile: profileName,
+                        message: `Daytona session refresh failed. ${reauth}`,
+                        cause: e,
+                      }),
+                    ),
+                  );
+            if (fresh !== session) {
+              yield* updateConfig?.({ ...oauth, ...fromOAuthCredentials(fresh) }) ?? Effect.void;
+            }
+            return {
+              type: "oauth" as const,
+              token: fresh.access,
+              apiBaseUrl: oauth.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+              organizationId: oauth.organizationId,
+              expires: fresh.expires,
+              source: { type: "oauth" as const },
+            } satisfies DaytonaResolvedCredentials;
+          }),
+        ),
+        Match.exhaustive,
+      );
+
+    const login = (
+      profileName: string,
+      config: DaytonaAuthConfig,
+      updateConfig?: (config: DaytonaAuthConfig) => Effect.Effect<void, AuthError>,
+      reload?: Effect.Effect<DaytonaAuthConfig, AuthError>,
+    ) =>
+      Match.value(config).pipe(
+        Match.when({ method: "stored" }, (stored) => Effect.succeed<DaytonaAuthConfig>(stored)),
+        Match.when({ method: "oauth" }, (oauth) =>
+          Effect.gen(function* () {
+            if (!OAuthClient.usesCurrentClient(toOAuthCredentials(oauth))) {
+              return yield* configureOAuth(profileName);
+            }
+            // Refresh with the token stored now, read under the lock.
+            const outcome = yield* withProfileCredentialsLock(
+              profileName,
+              Effect.gen(function* () {
+                const current = yield* reload ?? Effect.succeed(oauth);
+                if (current.method !== "oauth") return { type: "signIn" as const };
+                const session = toOAuthCredentials(current);
+                if (!OAuthClient.usesCurrentClient(session)) return { type: "signIn" as const };
+                const fresh = yield* OAuthClient.refresh(session);
+                const config = { ...current, ...fromOAuthCredentials(fresh) };
+                if (updateConfig === undefined) return { type: "refreshed" as const, config };
+                yield* updateConfig(config);
+                return { type: "refreshed" as const, config: undefined };
+              }),
+            ).pipe(
+              Effect.catchTag(
+                [
+                  "OAuthError",
+                  "OAuthNetworkError",
+                  "OAuthServerUnavailable",
+                  "OAuthInvalidResponse",
+                ],
+                () => Effect.succeed({ type: "signIn" as const }),
+              ),
+            );
+            if (outcome.type === "signIn") return yield* configureOAuth(profileName);
+            yield* Interaction.success("Daytona: session refreshed.");
+            return outcome.config;
+          }),
+        ),
+        Match.exhaustive,
+        Effect.mapError((e) => AuthError.make({ message: "login failed", cause: e })),
+      );
+
+    const logout = (_profileName: string, _config: DaytonaAuthConfig) => Effect.void;
+
+    const details = (
+      profileName: string,
+      config: DaytonaAuthConfig,
+      updateConfig?: (config: DaytonaAuthConfig) => Effect.Effect<void, AuthError>,
+    ) =>
+      Effect.all([read(profileName, config, updateConfig), Clock.currentTimeMillis]).pipe(
+        Effect.map(([creds, now]: [DaytonaResolvedCredentials, number]): ProviderDetails => {
+          const lines = [
+            {
+              key: creds.type === "oauth" ? "accessToken" : "apiKey",
+              value: displayRedacted(creds.token),
+            },
+            { key: "apiBaseUrl", value: creds.apiBaseUrl },
+          ];
+          if (creds.organizationId !== undefined) {
+            lines.push({ key: "organizationId", value: creds.organizationId });
+          }
+          if (creds.expires !== undefined) {
+            const remaining = creds.expires - now;
+            const at = new Date(creds.expires).toISOString();
+            lines.push({
+              key: "expires",
+              value:
+                remaining <= 0
+                  ? `expired (${at})`
+                  : `in ${Duration.format(Duration.millis(remaining))} (${at})`,
+            });
+          }
+          lines.push({ key: "source", value: creds.source.type });
+          return { lines };
+        }),
+      );
+
+    const readEnvironment = Effect.gen(function* () {
+      const apiKey = yield* getEnvRedacted("DAYTONA_API_KEY");
+      if (!apiKey) {
+        return yield* AuthError.make({
+          message: "Daytona CI credentials not found. Set DAYTONA_API_KEY.",
+        });
+      }
+      return {
+        type: "apiKey" as const,
+        token: apiKey,
+        apiBaseUrl: (yield* getEnv("DAYTONA_API_URL")) ?? DEFAULT_API_BASE_URL,
+        organizationId: yield* getEnv("DAYTONA_ORGANIZATION_ID"),
+        source: { type: "env" as const },
+      } satisfies DaytonaResolvedCredentials;
+    });
+
+    return {
+      configSchema: DaytonaAuthConfigSchema,
+      configure,
+      configureWith,
+      configureMethods,
+      login,
+      logout,
+      details,
+      read,
+      readEnvironment,
+      environment: [
+        {
+          name: "DAYTONA_API_KEY",
+          required: true,
+          secret: true,
+          description: "Organization API key.",
+        },
+        {
+          name: "DAYTONA_API_URL",
+          required: false,
+          description: "API root for a self-hosted Daytona.",
+        },
+        {
+          name: "DAYTONA_ORGANIZATION_ID",
+          required: false,
+          description: "Organization id; only needed with a user token.",
+        },
+      ],
+    };
+  }),
+);

package/src/Bootstrap.ts

@@ -0,0 +1,55 @@
+/**
+ * Process bootstrap for a `Daytona.Sandbox` with `main` (a Node process in
+ * the sandbox serving the bundled program). The generated entry imports this module
+ * and the user's `main`, nothing else — see `alchemy/Runtime/Bootstrap`
+ * for why.
+ */
+import { NodeServices } from "@effect/platform-node";
+import { NodeHttpServer } from "alchemy/Http";
+import { reifyBoundConfigProvider } from "alchemy/Runtime";
+import {
+  entrypointLayer,
+  resolveProgram,
+  runProcess,
+  stackFromEnv,
+} from "alchemy/Runtime/Bootstrap";
+import * as ConfigProvider from "effect/ConfigProvider";
+import * as SecureRandom from "effect/crypto/SecureRandom";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import * as Logger from "effect/Logger";
+
+/**
+ * Resolve the bundled program (the runners registered via `host.run` /
+ * serve) and run it with a Node HTTP server bound to `PORT` on every
+ * interface, so the sandbox's preview proxy reaches the `{ fetch }`
+ * handler and `host.run` loops stay alive.
+ */
+export const bootstrap = (entrypoint: unknown): Promise<void> => {
+  const platform = Layer.mergeAll(
+    NodeServices.layer,
+    FetchHttpClient.layer,
+    SecureRandom.layerWebCrypto,
+    Logger.layer([Logger.consolePretty()]),
+  );
+
+  const program = resolveProgram("program").pipe(
+    Effect.provide(
+      entrypointLayer(entrypoint).pipe(
+        Layer.provideMerge(stackFromEnv),
+        Layer.provideMerge(NodeHttpServer({ hostname: "0.0.0.0" })),
+        Layer.provideMerge(platform),
+        Layer.provideMerge(
+          Layer.succeed(
+            ConfigProvider.ConfigProvider,
+            reifyBoundConfigProvider(ConfigProvider.fromEnv(), process.env),
+          ),
+        ),
+      ),
+    ),
+    Effect.scoped,
+  );
+
+  return runProcess("Daytona service", program);
+};

package/src/ConnectSandbox.ts

@@ -0,0 +1,76 @@
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Sandbox } from "./Sandbox.ts";
+import type { ConnectedSandbox } from "./SandboxClient.ts";
+
+/**
+ * Work with one {@link Sandbox} declared at deploy, from any host: run
+ * commands, read and write files, use git, open previews, fork it or
+ * snapshot it. The handle has the same methods as the
+ * {@link DaytonaSandbox} that {@link CreateSandbox} returns; its
+ * `sandboxId`, `name` and `toolboxProxyUrl` are Effects, resolved at
+ * runtime.
+ *
+ * The host gets its own Daytona API key with `write:sandboxes` and
+ * `delete:sandboxes`; Daytona checks permissions per kind of object, so
+ * the key can reach other sandboxes in the organization too.
+ *
+ * ### Running Commands in a Dev Box
+ * **Example:** Pull and test on request
+ * ```typescript
+ * const devBox = yield* Daytona.ConnectSandbox(DevBox);
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     yield* devBox.startSandbox();
+ *     const test = yield* devBox.exec("git pull && pnpm test", { cwd: "/home/daytona/repo" });
+ *     return yield* HttpServerResponse.json(test);
+ *   }),
+ * };
+ * ```
+ *
+ * ### Putting a Worker in Front of a Port
+ * **Example:** Proxy every request to the dev server on port 3000
+ * ```typescript
+ * const devBox = yield* Daytona.ConnectSandbox(DevBox);
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const port = yield* devBox.getTcpPort(3000);
+ *     return yield* port.fetch(yield* HttpServerRequest);
+ *   }),
+ * };
+ * ```
+ *
+ * ### Streaming a Terminal
+ * Terminals, code interpreter runs and followed logs stream over a
+ * WebSocket, so they work from a Worker too.
+ *
+ * **Example:** Run a script in a terminal and stream its output
+ * ```typescript
+ * const output = yield* Effect.scoped(
+ *   Effect.gen(function* () {
+ *     const pty = yield* devBox.process.createPty({ id: "build" });
+ *     yield* pty.write("pnpm build; exit\n");
+ *     return yield* pty.output.pipe(Stream.decodeText(), Stream.mkString);
+ *   }),
+ * );
+ * ```
+ *
+ * ### Forking a Dev Box
+ * Daytona forks `linux-vm` sandboxes; a container's fork fails with
+ * `ForkNotSupported`.
+ *
+ * **Example:** Fork it per pull request
+ * ```typescript
+ * const fork = yield* devBox.forkSandbox({ name: `pr-${number}` });
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface ConnectSandbox extends Binding.Service<
+  ConnectSandbox,
+  "Daytona.ConnectSandbox",
+  (sandbox: Sandbox) => Effect.Effect<ConnectedSandbox>
+> {}
+
+export const ConnectSandbox = Binding.Service<ConnectSandbox>("Daytona.ConnectSandbox");

package/src/ConnectSandboxHttp.ts

@@ -0,0 +1,26 @@
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { ConnectSandbox } from "./ConnectSandbox.ts";
+import { makeAccess } from "./DaytonaBindings.ts";
+import type { Sandbox } from "./Sandbox.ts";
+import { makeConnectedSandbox } from "./SandboxClient.ts";
+
+/** {@link ConnectSandbox} over Daytona's HTTP API; works on any host. */
+export const ConnectSandboxHttp = Layer.effect(
+  ConnectSandbox,
+  Effect.gen(function* () {
+    const access = yield* makeAccess;
+    return Effect.fn(function* (sandbox: Sandbox) {
+      const { authorize, organizationId } = yield* access(`${sandbox.LogicalId}Connect`, [
+        "write:sandboxes",
+        "delete:sandboxes",
+      ]);
+      const sandboxId = yield* sandbox.sandboxId;
+      const name = yield* sandbox.name;
+      const toolboxProxyUrl = yield* sandbox.toolboxProxyUrl;
+      // The sandbox's identity resolves at runtime, on each call.
+      const identity = Effect.all({ id: sandboxId, name, toolboxProxyUrl });
+      return makeConnectedSandbox(identity, organizationId, authorize);
+    });
+  }),
+);

package/src/Contributions.ts

@@ -0,0 +1,9 @@
+import * as Contributions from "alchemy/Contributions";
+
+export default Contributions.make({
+  name: "daytona",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.DaytonaAuth,
+  ),
+});

package/src/CreateSandbox.ts

@@ -0,0 +1,107 @@
+import type * as sandboxes from "@distilled.cloud/daytona/sandbox";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { StateFailed, StateTimeout } from "./internal/Wait.ts";
+import type { VolumeMount } from "./MountVolume.ts";
+import type { SandboxInfo } from "./Sandbox.ts";
+import type { DaytonaSandbox } from "./SandboxClient.ts";
+import type { Snapshot } from "./Snapshot.ts";
+
+/**
+ * `create` input: Daytona's own create request, with volumes as `mounts`.
+ * `snapshot` defaults to the binding's base; labels are merged with the
+ * binding's owner label.
+ */
+export type CreateSandboxInput = Omit<
+  sandboxes.CreateSandboxRequest,
+  "xDaytonaOrganizationID" | "volumes"
+> & {
+  /**
+   * Volumes to mount: `MountVolume` references, or entries naming a
+   * `CreateVolume` handle (`{ volume: home, path: "/home/daytona/work" }`).
+   */
+  readonly mounts?: ReadonlyArray<VolumeMount>;
+};
+
+/** `list` filters: Daytona's own, with `labels` as an object. */
+export type ListSandboxesInput = Omit<
+  sandboxes.ListSandboxesRequest,
+  "xDaytonaOrganizationID" | "labels" | "cursor"
+> & { labels?: Record<string, string> };
+
+export interface CreateSandboxClient {
+  /**
+   * Create a sandbox and wait until it has started. Returns its handle.
+   */
+  create(
+    input?: CreateSandboxInput,
+  ): Effect.Effect<
+    DaytonaSandbox,
+    sandboxes.CreateSandboxError | sandboxes.GetSandboxError | StateTimeout | StateFailed,
+    RuntimeContext
+  >;
+  /** The sandbox with this id or name, or `undefined`. */
+  get(
+    idOrName: string,
+  ): Effect.Effect<DaytonaSandbox | undefined, sandboxes.GetSandboxError, RuntimeContext>;
+  /** Sandboxes matching the filters (by default, the ones from the binding's base). */
+  list(
+    input?: ListSandboxesInput,
+  ): Effect.Effect<SandboxInfo[], sandboxes.ListSandboxesError, RuntimeContext>;
+  /** Delete a sandbox. Deleting a missing one succeeds. */
+  delete(idOrName: string): Effect.Effect<void, sandboxes.DeleteSandboxError, RuntimeContext>;
+}
+
+/**
+ * Create, find and delete Daytona sandboxes at runtime, from a Worker,
+ * Lambda or any other host: a sandbox per request, per user or per task.
+ * Pass a {@link Snapshot} to create every sandbox from it (a warm base),
+ * or nothing to pick the snapshot per call.
+ *
+ * The host gets its own Daytona API key, with only `write:sandboxes` and
+ * `delete:sandboxes`. Every sandbox it creates is labeled with the
+ * stack, stage and host as Daytona labels (`alchemy.stack`,
+ * `alchemy.stage`, `alchemy.id`; Daytona doesn't allow `::` in a label
+ * key), on top of your own labels. They are not deleted when the stack is
+ * destroyed: list them by those labels to clean them up, e.g.
+ * `sandboxes.list({ labels: { "alchemy.id": "Api" } })`.
+ * Each sandbox comes back as a {@link DaytonaSandbox} handle with the whole
+ * toolbox: processes, files, git, LSP, previews, forks and snapshots.
+ *
+ * ### Sandbox per Request
+ * **Example:** Run a command in a fresh sandbox and delete it
+ * ```typescript
+ * const sandboxes = yield* Daytona.CreateSandbox(Base);
+ * return {
+ *   fetch: Effect.gen(function* () {
+ *     const sandbox = yield* Effect.acquireRelease(
+ *       sandboxes.create({ autoDeleteInterval: 0 }),
+ *       (s) => sandboxes.delete(s.sandboxId).pipe(Effect.ignore),
+ *     );
+ *     const ls = yield* sandbox.exec("ls -la");
+ *     return yield* HttpServerResponse.json(ls);
+ *   }),
+ * };
+ * ```
+ *
+ * ### Sandbox per User
+ * **Example:** Find the user's sandbox by name, or create it
+ * ```typescript
+ * const sandbox =
+ *   (yield* sandboxes.get(`dev-${user}`)) ??
+ *   (yield* sandboxes.create({ name: `dev-${user}`, labels: { user } }));
+ * yield* sandbox.startSandbox();
+ * yield* sandbox.git.cloneRepository({ url: repoUrl, path: "/home/daytona/repo" });
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface CreateSandbox extends Binding.Service<
+  CreateSandbox,
+  "Daytona.CreateSandbox",
+  (base?: Snapshot) => Effect.Effect<CreateSandboxClient>
+> {}
+
+export const CreateSandbox = Binding.Service<CreateSandbox>("Daytona.CreateSandbox");