@alchemy.run/modal 0.0.0-stage → 2.0.0-beta.86

package/src/ConnectSandbox.ts

@@ -0,0 +1,99 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeModalBinding } from "./BindingHttp.ts";
+import type { PersistentSandbox } from "./PersistentSandbox.ts";
+import {
+  persistentSandboxHandle,
+  type PersistentSandboxHandleOf,
+  SandboxOps,
+} from "./SandboxClient.ts";
+
+/**
+ * A declared `Modal.PersistentSandbox`, reached from a runtime: its id, and
+ * the box's session API.
+ */
+export interface ConnectedPersistentSandbox extends Omit<
+  PersistentSandboxHandleOf<RuntimeContext>,
+  "persistentSandboxId"
+> {
+  /** The box's id (`ps-…`). */
+  readonly persistentSandboxId: Effect.Effect<string>;
+}
+
+/**
+ * Connect to a declared `Modal.PersistentSandbox` from any runtime. The
+ * handle follows Modal's session API: `session()` returns the running
+ * session, resuming the box from its last session's filesystem when it's
+ * paused, and every session is a full sandbox handle (`exec`, `files`,
+ * snapshots).
+ *
+ * ### Use a persistent box
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { DevBox } from "./DevBox.ts";
+ *
+ * export default class Shell extends Cloudflare.Worker<Shell>()(
+ *   "Shell",
+ *   { main: import.meta.url, compatibility: { flags: ["nodejs_compat"] } },
+ *   Effect.gen(function* () {
+ *     const box = yield* Modal.ConnectSandbox(DevBox);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const session = yield* box.session();
+ *         const status = yield* session.exec("git status");
+ *         return HttpServerResponse.text(status.stdout);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Modal.ConnectSandboxHttp)),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Sandbox
+ */
+export interface ConnectSandbox extends Binding.Service<
+  ConnectSandbox,
+  "Modal.ConnectSandbox",
+  (box: PersistentSandbox) => Effect.Effect<ConnectedPersistentSandbox>
+> {}
+
+export const ConnectSandbox = Binding.Service<ConnectSandbox>("Modal.ConnectSandbox");
+
+/**
+ * {@link ConnectSandbox} over Modal's API. Grants the runtime's identity the
+ * `contributor` role on the box's environment.
+ *
+ * @layer
+ * @product Sandbox
+ * @provides Modal.ConnectSandbox
+ */
+export const ConnectSandboxHttp = Layer.effect(
+  ConnectSandbox,
+  makeModalBinding({
+    tag: "Modal.ConnectSandbox",
+    operations: SandboxOps,
+    role: "contributor",
+    make: Effect.fn(function* (box: PersistentSandbox, ops) {
+      const persistentSandboxId = yield* box.persistentSandboxId;
+      const environment = yield* box.environment;
+      // The box's identity resolves at runtime, on each call.
+      const handle = Effect.map(Effect.all([persistentSandboxId, environment]), ([id, env]) =>
+        persistentSandboxHandle(ops, id, { environment: env }),
+      );
+      return {
+        persistentSandboxId,
+        session: () => Effect.flatMap(handle, (h) => h.session()),
+        terminate: () => Effect.flatMap(handle, (h) => h.terminate()),
+      } satisfies ConnectedPersistentSandbox;
+    }),
+  }),
+);
+
+/** {@link ConnectSandboxHttp}: Modal has one transport, so both names provide it. */
+export const ConnectSandboxLive = ConnectSandboxHttp;

package/src/Container.ts

@@ -0,0 +1,121 @@
+import type * as Bundle from "alchemy/Bundle/Bundle";
+import type { PlatformProps } from "alchemy/Platform";
+import type * as Effect from "effect/Effect";
+import type { App } from "./App.ts";
+import type { Mount } from "./Mounts.ts";
+import type { Providers } from "./Providers.ts";
+import type { DurationInput } from "./SandboxClient.ts";
+
+/** A resource, or the module-scope Effect that declares it. */
+export type Ref<T> = T | Effect.Effect<T, never, Providers>;
+
+/**
+ * Container settings shared by `Modal.Function` and `Modal.Server`: the
+ * program, the image it runs on, and Modal's resource, scaling and
+ * placement options.
+ */
+export interface ContainerProps extends PlatformProps {
+  /**
+   * Module entrypoint, bundled into the image. Typically `import.meta.url`.
+   * A change to the bundle builds a new image.
+   */
+  main: string;
+  /** The App the function is deployed in. Changing it replaces the function. */
+  app: Ref<App>;
+  /**
+   * Name of the function in its App, unique per App. Changing it replaces
+   * the function.
+   * @default the logical ID
+   */
+  name?: string;
+  /**
+   * Base image the bundle runs on. It needs Bun on the `PATH`; Alchemy adds
+   * Python (see {@link python}).
+   * @default "oven/bun:1"
+   */
+  image?: string;
+  /** Dockerfile lines run on the base before the bundle is added. */
+  commands?: string[];
+  /**
+   * Standalone Python added to the image. Modal starts every Function
+   * container with its Python entrypoint, which then starts the program.
+   * Set `false` when the base image already has Python 3.10+ on the `PATH`.
+   * @default "3.12"
+   */
+  python?: string | false;
+  /**
+   * Port the program listens on.
+   * @default 8000
+   */
+  port?: number;
+  /**
+   * Named export to load from `main`.
+   * @default "default"
+   */
+  handler?: string;
+  /**
+   * Extra environment variables for the program. Stored, with the bindings'
+   * env, in a Modal Secret attached to the function.
+   */
+  env?: Record<string, any>;
+  /** Bundler options. */
+  build?: Bundle.BundleConfig;
+  /** Secrets whose variables the program sees as environment variables. */
+  secrets?: Array<Ref<{ readonly secretId: string }>>;
+  /**
+   * Volumes and cloud buckets mounted into every container:
+   * `{ volume: Data, path: "/data" }`, `{ bucket: Uploads, path: "/uploads", secret: R2Keys }`.
+   * `Modal.MountVolume` and `Modal.MountBucket` add more from the program.
+   */
+  mounts?: Mount[];
+  /** CPU cores to reserve (fractional allowed). */
+  cpu?: number;
+  /** Most CPU cores a container may use. */
+  cpuLimit?: number;
+  /** Memory in MiB to reserve. */
+  memory?: number;
+  /** Most memory in MiB a container may use. */
+  memoryLimit?: number;
+  /** GPU: `"T4"`, `"L4"`, `"A10G"`, `"A100-80GB"`, `"H100"`, ..., with an optional `":<count>"`. */
+  gpu?: string;
+  /** Ephemeral disk in MiB. */
+  ephemeralDisk?: number;
+  /**
+   * Most time one input (a call, a request) may run.
+   * @default 300 seconds
+   */
+  timeout?: DurationInput;
+  /**
+   * Most time a container may take to start.
+   * @default the timeout
+   */
+  startupTimeout?: DurationInput;
+  /** Containers kept running even with no traffic. @default 0 */
+  minContainers?: number;
+  /** Most containers running at once. */
+  maxContainers?: number;
+  /** Idle containers kept on top of demand while the function is busy. */
+  bufferContainers?: number;
+  /** Seconds of sustained demand before scaling up. */
+  scaleupWindow?: number;
+  /** Seconds a container may stay idle before it scales down. */
+  scaledownWindow?: number;
+  /** Regions containers may run in (`"us-east"`, `"eu"`, ...). */
+  regions?: string[];
+  /** Cloud provider containers run on. */
+  cloud?: "aws" | "gcp" | "oci" | "auto";
+  /** Run on non-preemptible capacity (costs more). */
+  nonpreemptible?: boolean;
+  /** A `Modal.Proxy` outbound traffic goes through (static egress IPs). */
+  proxy?: Ref<{ readonly proxyId: string }>;
+  /** Block all outbound network access. */
+  blockNetwork?: boolean;
+  /** Stop the program from calling Modal's API with the container's identity. */
+  restrictModalAccess?: boolean;
+  /** Snapshot the container's memory after startup, so cold starts restore it. */
+  enableMemorySnapshot?: boolean;
+  /** Enable IPv6 networking between the function's containers. */
+  i6pn?: boolean;
+  /** Pin Modal's image builder version (`"2025.06"`). */
+  builderVersion?: string;
+}

package/src/Contributions.ts

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

package/src/CreateDict.ts

@@ -0,0 +1,95 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { DictsOps } from "./CreateDictHttp.ts";
+import type { ensureDict, lookupDict } from "./Dict.ts";
+import type { DictAttributes } from "./Dict.ts";
+import type { ReadWriteDictClient } from "./DictClient.ts";
+import type { Environment } from "./Environment.ts";
+import type { ErrorOf, OpError } from "./internal.ts";
+
+/** A dict created or found at runtime: its attributes plus a read-write client. */
+export interface DictHandle extends ReadWriteDictClient {
+  readonly dictId: Effect.Effect<string>;
+  readonly name: string;
+  /** The attributes, to pass where a `Modal.Dict` is accepted (e.g. sandbox mounts). */
+  readonly attributes: DictAttributes;
+}
+
+/** Get, create, list and delete dicts by name in one environment. */
+export interface DictsClientOf<R> {
+  /** The dict named `name`, created when missing (Modal's own get-or-create). */
+  getOrCreate(name: string): Effect.Effect<DictHandle, ErrorOf<typeof ensureDict>, R>;
+  /** The dict named `name`, or `undefined`. */
+  get(name: string): Effect.Effect<DictHandle | undefined, ErrorOf<typeof lookupDict>, R>;
+  /** Delete the dict named `name` (no-op when missing). */
+  delete(
+    name: string,
+  ): Effect.Effect<
+    void,
+    | ErrorOf<typeof lookupDict>
+    | Exclude<OpError<DictsOps, "delete">, { readonly _tag: "DictNotFound" }>,
+    R
+  >;
+  /** Names of every dict in the environment. */
+  list(): Effect.Effect<ReadonlyArray<string>, OpError<DictsOps, "list">, R>;
+}
+
+/** A DictsClient whose calls run inside a deployed runtime. */
+export type DictsClient = DictsClientOf<RuntimeContext>;
+
+/**
+ * Create dicts by name at runtime: one per user, session or task.
+ * Modal's native shape is get-or-create by name, so `getOrCreate` is
+ * idempotent and safe to call on every request.
+ *
+ * Bind it to a `Modal.Environment` to keep these runtime objects in their
+ * own namespace (or to nothing, for the workspace's default environment).
+ * They aren't in Alchemy state: deleting the environment removes them.
+ *
+ * Objects created at run time are tagged with the stack, stage and binding
+ * (`alchemy::stack`, `alchemy::stage`, `alchemy::id`) and are not deleted when
+ * the stack is destroyed. A Modal dict has only a name, so the tags become
+ * its name prefix, `Modal.runtimePrefix({ stack, stage, id })`: list them
+ * with `modal dict list` and delete the ones whose name starts with it.
+ *
+ * ### One dict per user
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ * import { HttpServerRequest } from "effect/http/HttpServerRequest";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Agents, Coder } from "./Coder.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const dicts = yield* Modal.CreateDict(Agents);
+ *     const sandboxes = yield* Modal.CreateSandbox(Coder);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const user = request.headers["x-user"] ?? "anonymous";
+ *         const state = yield* dicts.getOrCreate(`state-${user}`);
+ *         yield* state.put("lastSeen", Date.now());
+ *         return HttpServerResponse.text("ok");
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Layer.mergeAll(Modal.CreateDictHttp, Modal.CreateSandboxHttp))),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Dict
+ */
+export interface CreateDict extends Binding.Service<
+  CreateDict,
+  "Modal.CreateDict",
+  (environment?: Environment) => Effect.Effect<DictsClient>
+> {}
+
+export const CreateDict = Binding.Service<CreateDict>("Modal.CreateDict");

package/src/CreateDictHttp.ts

@@ -0,0 +1,91 @@
+import * as dict from "@distilled.cloud/modal/dict";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { makeOpenModalBinding } from "./BindingHttp.ts";
+import { CreateDict, type DictHandle, type DictsClientOf } from "./CreateDict.ts";
+import { ensureDict, lookupDict, type DictAttributes } from "./Dict.ts";
+import { DictOps, makeReadWriteDictClient } from "./DictClient.ts";
+import type { Environment } from "./Environment.ts";
+import { environmentOf, listAll, operations } from "./internal.ts";
+import { ownedName, type RuntimeOwner, RuntimeOwnerOf, unownedName } from "./RuntimeOwner.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+export const DictsOps = operations({
+  getOrCreate: dict.dictGetOrCreate,
+  delete: dict.deleteDict,
+  list: dict.listDict,
+  client: DictOps,
+});
+
+export type DictsOps = Effect.Success<typeof DictsOps>;
+
+const handleOf = (attributes: DictAttributes, ops: DictsOps, name: string): DictHandle => ({
+  ...makeReadWriteDictClient(Effect.succeed(attributes.dictId), ops.client),
+  dictId: Effect.succeed(attributes.dictId),
+  name,
+  attributes,
+});
+
+/** A dicts client over an environment name resolved per call. */
+export const makeDictsClient = (
+  environment: Effect.Effect<string | undefined>,
+  ops: DictsOps,
+  owner: Effect.Effect<RuntimeOwner | undefined> = Effect.undefined,
+): DictsClientOf<never> => ({
+  getOrCreate: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([env, stamp]) =>
+      ensureDict(ops.getOrCreate, ownedName(stamp, name), env),
+    ).pipe(Effect.map((attributes) => handleOf(attributes, ops, name))),
+  get: (name) =>
+    Effect.flatMap(Effect.all([environment, owner]), ([env, stamp]) =>
+      lookupDict(ops.getOrCreate, ownedName(stamp, name), env),
+    ).pipe(Effect.map((attributes) => (attributes ? handleOf(attributes, ops, name) : undefined))),
+  delete: (name) =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      const found = yield* lookupDict(ops.getOrCreate, ownedName(yield* owner, name), env);
+      if (!found) return;
+      yield* ops
+        .delete({ dictId: found.dictId })
+        .pipe(Effect.catchTag("DictNotFound", () => Effect.void));
+    }),
+  list: () =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      const stamp = yield* owner;
+      const items = yield* listAll(
+        (pagination) =>
+          ops
+            .list({ environmentName: environmentOf(env), pagination })
+            .pipe(Effect.map((response) => response.dicts ?? [])),
+        (item) => item.createdAt,
+      );
+      return items.flatMap((item) => {
+        const own = item.name ? unownedName(stamp, item.name) : undefined;
+        return own ? [own] : [];
+      });
+    }),
+});
+
+/**
+ * {@link CreateDict} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the environment.
+ *
+ * @layer
+ * @product Dict
+ * @provides Modal.CreateDict
+ */
+export const CreateDictHttp = Layer.effect(
+  CreateDict,
+  makeOpenModalBinding({
+    tag: "Modal.CreateDict",
+    operations: DictsOps,
+    role: "contributor",
+    environmentOf: (environment?: Environment) => environment?.name,
+    make: Effect.fn(function* (ops, environment?: Environment) {
+      const name = environment ? yield* environment.name : Effect.undefined;
+      const owner = yield* RuntimeOwnerOf();
+      return makeDictsClient(name, ops, owner);
+    }),
+  }),
+);

package/src/CreateImage.ts

@@ -0,0 +1,105 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type { App } from "./App.ts";
+import type { buildFromOptions, ImagesOps } from "./CreateImageHttp.ts";
+import type { ErrorOf, OpError } from "./internal.ts";
+
+/** What to build: Modal's image inputs, in memory (no build context directory). */
+export interface ImageBuildOptions {
+  /** Start from a registry image. */
+  readonly image?: string;
+  /** Start from a Modal image (a deploy-time `Modal.Image`, or a snapshot). */
+  readonly from?: { readonly imageId: string };
+  /** A whole Dockerfile as text (`FROM` included). Exclusive with `image`/`from`. */
+  readonly dockerfile?: string;
+  /** Dockerfile lines appended to the build. */
+  readonly commands?: ReadonlyArray<string>;
+  /** Files the commands `COPY`, by path relative to the build context. */
+  readonly files?: Record<string, string | Uint8Array>;
+  /** Secrets the build steps see as environment variables. */
+  readonly secrets?: ReadonlyArray<{ readonly secretId: string }>;
+  /** Run the build on a GPU. */
+  readonly gpu?: string;
+  /** Rebuild even when Modal has the same image cached. */
+  readonly force?: boolean;
+}
+
+/** Build images in one App at runtime. */
+export interface ImagesClient {
+  /**
+   * Build an image (or return the cached one: Modal content-addresses
+   * builds) and wait until it's ready. Fails with `Modal.ImageBuildFailed`.
+   */
+  build(
+    options: ImageBuildOptions,
+  ): Effect.Effect<{ readonly imageId: string }, ErrorOf<typeof buildFromOptions>, RuntimeContext>;
+  /** The image published under `tag`, or `undefined`. */
+  fromTag(
+    tag: string,
+  ): Effect.Effect<
+    { readonly imageId: string } | undefined,
+    OpError<ImagesOps, "getByTag">,
+    RuntimeContext
+  >;
+  /** Publish an image under `tag` (moving the tag if it points elsewhere). */
+  publish(
+    image: { readonly imageId: string },
+    tag: string,
+  ): Effect.Effect<void, OpError<ImagesOps, "publish">, RuntimeContext>;
+  /** Remove a published tag (`name` or `name:tag`); the image itself stays. */
+  unpublish(tag: string): Effect.Effect<void, OpError<ImagesOps, "deleteName">, RuntimeContext>;
+  /** Delete an image. */
+  delete(image: {
+    readonly imageId: string;
+  }): Effect.Effect<void, OpError<ImagesOps, "delete">, RuntimeContext>;
+}
+
+/**
+ * Build Modal Images at runtime, e.g. one per repository a user connects,
+ * from the same inputs a `Modal.Image` takes. Modal builds remotely; the
+ * runtime needs no Docker.
+ *
+ * ### An image per repository
+ * **Example:** From a Cloudflare Worker
+ * ```typescript
+ * import * as Cloudflare from "@alchemy.run/cloudflare";
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Effect from "effect/Effect";
+ * import * as Layer from "effect/Layer";
+ * import { HttpServerRequest } from "effect/http/HttpServerRequest";
+ * import * as HttpServerResponse from "effect/http/HttpServerResponse";
+ * import { Coder } from "./Coder.ts";
+ *
+ * export default class Api extends Cloudflare.Worker<Api>()(
+ *   "Api",
+ *   { main: import.meta.url },
+ *   Effect.gen(function* () {
+ *     const images = yield* Modal.CreateImage(Coder);
+ *     const sandboxes = yield* Modal.CreateSandbox(Coder);
+ *     return {
+ *       fetch: Effect.gen(function* () {
+ *         const request = yield* HttpServerRequest;
+ *         const repo = request.headers["x-repo"] ?? "alchemy-run/alchemy";
+ *         const image = yield* images.build({
+ *           image: "node:22-bookworm",
+ *           commands: [`RUN git clone https://github.com/${repo} /work`],
+ *         });
+ *         const sandbox = yield* sandboxes.create({ image });
+ *         return HttpServerResponse.text(sandbox.sandboxId);
+ *       }).pipe(Effect.orDie),
+ *     };
+ *   }).pipe(Effect.provide(Layer.mergeAll(Modal.CreateImageHttp, Modal.CreateSandboxHttp))),
+ * ) {}
+ * ```
+ *
+ * @binding
+ * @product Image
+ */
+export interface CreateImage extends Binding.Service<
+  CreateImage,
+  "Modal.CreateImage",
+  (app: App) => Effect.Effect<ImagesClient>
+> {}
+
+export const CreateImage = Binding.Service<CreateImage>("Modal.CreateImage");

package/src/CreateImageHttp.ts

@@ -0,0 +1,117 @@
+import * as DockerfileParser from "@alchemy.run/docker/DockerfileParser";
+import * as image from "@distilled.cloud/modal/image";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type { App } from "./App.ts";
+import { makeModalBinding } from "./BindingHttp.ts";
+import { CreateImage, type ImageBuildOptions, type ImagesClient } from "./CreateImage.ts";
+import { buildImage, ImageBuildOps } from "./ImageBuild.ts";
+import { operations } from "./internal.ts";
+
+/** The operations the client calls, resolved by `ModalBindings.withCredentials`. */
+const ImagesOps = operations({
+  build: ImageBuildOps,
+  getByTag: image.imageGetByTag,
+  publish: image.publishImage,
+  deleteName: image.deleteImageName,
+  delete: image.deleteImage,
+});
+
+export type ImagesOps = Effect.Success<typeof ImagesOps>;
+
+const toBytes = (data: string | Uint8Array) =>
+  Effect.sync(() => (typeof data === "string" ? new TextEncoder().encode(data) : data));
+
+/** Build one image from runtime options in `appId`. */
+export const buildFromOptions = Effect.fn(function* (
+  ops: ImageBuildOps,
+  appId: string,
+  options: ImageBuildOptions,
+) {
+  // Parsed to normalize it; Modal's builder rejects what it can't run.
+  // (The plan-time capability check lives with BuildPlan, which imports the
+  // bundler and so stays out of runtime bundles.)
+  const parsed =
+    options.dockerfile !== undefined
+      ? yield* DockerfileParser.parse(options.dockerfile)
+      : undefined;
+  const dockerfile = parsed ? DockerfileParser.renderLines(parsed) : [];
+  const extra = options.commands ?? [];
+  const commands = [...dockerfile, ...extra];
+  const contextFiles = yield* Effect.forEach(
+    Object.entries(options.files ?? {}),
+    ([filename, data]) => Effect.map(toBytes(data), (bytes) => ({ filename, data: bytes })),
+  );
+  const imageId = yield* buildImage(ops, appId, {
+    dockerTag: options.dockerfile
+      ? undefined
+      : options.from
+        ? undefined
+        : (options.image ?? "debian:bookworm-slim"),
+    baseImageId: options.dockerfile ? undefined : options.from?.imageId,
+    commands,
+    contextFiles,
+    secretIds: options.secrets?.map((s) => s.secretId),
+    gpu: options.gpu,
+    forceBuild: options.force,
+  });
+  return { imageId };
+});
+
+/** An images client over an app id resolved per call. */
+export const makeImagesClient = (
+  appId: Effect.Effect<string>,
+  ops: ImagesOps,
+  environment: Effect.Effect<string | undefined> = Effect.undefined,
+): ImagesClient => ({
+  fromTag: (tag) =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      const found = yield* ops
+        .getByTag({ tag, environmentName: env ?? "" })
+        .pipe(Effect.catchTag("ImageNotFound", () => Effect.undefined));
+      return found?.imageId ? { imageId: found.imageId } : undefined;
+    }),
+  publish: (target, tag) =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      yield* ops.publish({ imageId: target.imageId, tag, environmentName: env ?? "" });
+    }),
+  unpublish: (tag) =>
+    Effect.gen(function* () {
+      const env = yield* environment;
+      // Modal deletes only an explicit `name:tag`; a bare name is `name:latest`.
+      const named = /:[^/]*$/.test(tag) ? tag : `${tag}:latest`;
+      yield* ops
+        .deleteName({ tag: env ? `${env}/${named}` : named })
+        .pipe(Effect.catchTag("ImageNotFound", () => Effect.void));
+    }),
+  build: (options) => Effect.flatMap(appId, (id) => buildFromOptions(ops.build, id, options)),
+  delete: (target) =>
+    ops.delete({ imageId: target.imageId }).pipe(
+      Effect.catchTag("ImageNotFound", () => Effect.void),
+      Effect.asVoid,
+    ),
+});
+
+/**
+ * {@link CreateImage} over Modal's API. Grants the host's identity (a scoped
+ * `Modal.ServiceUser`) the `contributor` role on the App's environment.
+ *
+ * @layer
+ * @product Image
+ * @provides Modal.CreateImage
+ */
+export const CreateImageHttp = Layer.effect(
+  CreateImage,
+  makeModalBinding({
+    tag: "Modal.CreateImage",
+    operations: ImagesOps,
+    role: "contributor",
+    make: Effect.fn(function* (app: App, ops) {
+      const appId = yield* app.appId;
+      const environment = yield* app.environment;
+      return makeImagesClient(appId, ops, environment);
+    }),
+  }),
+);