Modal.Image reference

CreateImage

Source: packages/modal/src/CreateImage.ts

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.

CreateImage: An image per repository

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))),
) {}

CreateImageHttp

Source: packages/modal/src/CreateImageHttp.ts Kind: Layer · Provides: Modal.CreateImage

CreateImage over Modal’s API. Grants the host’s identity (a scoped Modal.ServiceUser) the contributor role on the App’s environment.

Image

Source: packages/modal/src/Image.ts

A Modal Image: a container image built by Modal’s own builder (not Docker), from a registry image, a Dockerfile, or another Modal Image plus commands. Sandboxes boot from it.

With run, the image becomes a warm base: Alchemy boots a sandbox from the built image, runs the commands, snapshots its filesystem, and terminates it. Sandboxes created from the result start with the repo cloned and dependencies installed. Runtime snapshots (sandbox.snapshotFilesystem()) are images too and work anywhere an image does.

Modal builds remotely: deploying needs no local Docker.

Image: Building an Image

From a registry image with extra packages

import * as Modal from "@alchemy.run/modal";

export const Coder = Modal.App("Coder", {});
export const Node = Modal.Image("Node", {
  app: Coder,
  image: "node:22-bookworm",
  commands: ["RUN apt-get update && apt-get install -y git ripgrep"],
});

From an inline Dockerfile

import * as Dockerfile from "@alchemy.run/docker/Dockerfile";
import * as Modal from "@alchemy.run/modal";

export const Coder = Modal.App("Coder", {});
export const Python = Modal.Image("Python", {
  app: Coder,
  dockerfile: Dockerfile.inline`
    FROM python:3.12-slim
    RUN pip install pandas
  `,
});

Image: A warm base to fork from

import * as Modal from "@alchemy.run/modal";

export const Coder = Modal.App("Coder", {});
export const Node = Modal.Image("Node", { app: Coder, image: "node:22-bookworm" });
export const Warm = Modal.Image("Warm", {
  app: Coder,
  from: Node,
  run: [
    "git clone https://github.com/alchemy-run/alchemy /work",
    "cd /work && corepack enable && pnpm install",
  ],
});