Modal.App reference

App

Source: packages/modal/src/App.ts

A Modal App: the named, persistent namespace that Functions, Servers, Sandboxes and Images run under. Each Modal.Function and Modal.Server of the Stack is published into its App, and stopping the App (destroying this resource) stops them and terminates its Sandboxes.

An App deployed with Modal’s Python client (modal deploy) can also be referenced by name from InvokeFunction and FunctionAutoscaler.

App: Creating an App

An app for sandboxes

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

export const Coder = Modal.App("Coder", {});

A named, tagged app in an environment

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

export const Agents = Modal.Environment("Agents", {});
export const Coder = Modal.App("Coder", {
  name: "coder",
  environment: Agents,
  tags: { team: "platform" },
});

App: Running sandboxes in it

import * as Cloudflare from "@alchemy.run/cloudflare";
import * as Modal from "@alchemy.run/modal";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
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 sandboxes = yield* Modal.CreateSandbox(Coder);
    return {
      fetch: Effect.gen(function* () {
        const sandbox = yield* sandboxes.create({ image: "node:22-slim" });
        const result = yield* sandbox.exec(["node", "--version"]);
        yield* sandbox.terminate();
        return HttpServerResponse.text(result.stdout);
      }).pipe(Effect.orDie),
    };
  }).pipe(Effect.provide(Modal.CreateSandboxHttp)),
) {}

App: Looking up an existing App

App.lookup references a App Alchemy doesn’t manage (created with the Modal CLI or by another stack). It is read during plan/deploy, never created, updated or deleted.

const app = Modal.App.lookup({ name: "inference" });

ReadApp

Source: packages/modal/src/ReadApp.ts

Read a Modal App from any runtime: its logs (every function, server and sandbox in it), function summaries and deployment history.

ReadApp: Logs

const backend = yield* Modal.ReadApp(Backend);
const lines = yield* backend.logs({ since: new Date(Date.now() - 3_600_000), stream: "stderr" });

ReadApp: Deployments

const { productionAppVersion } = yield* backend.deployments();

ReadAppHttp

Source: packages/modal/src/ReadAppHttp.ts Kind: Layer · Provides: Modal.ReadApp

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

WriteApp

Source: packages/modal/src/WriteApp.ts

Operate a Modal App from any runtime: roll back a bad version, roll the containers over, promote a staged version, or stop it. The next deploy of the Stack publishes its declared version again.

WriteApp: Roll back

const backend = yield* Modal.WriteApp(Backend);
yield* backend.rollback();

WriteAppHttp

Source: packages/modal/src/WriteAppHttp.ts Kind: Layer · Provides: Modal.WriteApp

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