Modal.Workspace reference

ServiceUser

Source: packages/modal/src/ServiceUser.ts

A Modal service user: a workspace identity with its own token pair, for CI or another system. A scoped user acts only in the environments you grant it, as a viewer or a contributor.

Modal shows a service user’s token secret once, at creation, so a user deleted outside Alchemy is recreated with a new token on the next deploy, and an existing user can’t be adopted.

ServiceUser: Creating a service user

CI that deploys to one environment

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

export const Staging = Modal.Environment("Staging", {});
export const Deployer = Modal.ServiceUser("Deployer", {
  environments: [{ environment: Staging, role: "contributor" }],
});

A short-lived, read-only token

export const Auditor = Modal.ServiceUser("Auditor", {
  environments: [{ environment: "main", role: "viewer" }],
  expiresIn: "7 days",
});

ServiceUser: Using its token

import * as Cloudflare from "@alchemy.run/cloudflare";
import * as Effect from "effect/Effect";

export const Ci = Effect.gen(function* () {
  const deployer = yield* Deployer;
  return yield* Cloudflare.Worker("Ci", {
    main: "./src/ci.ts",
    env: { MODAL_TOKEN_ID: deployer.tokenId, MODAL_TOKEN_SECRET: deployer.tokenSecret },
  });
});

WorkspaceSettings

Source: packages/modal/src/WorkspaceSettings.ts

Workspace-wide Modal settings: the default environment, the image builder version, and whether endpoints in inheriting environments require authentication.

A workspace has one set of settings, so declare this resource once. It captures the settings it finds on first deploy and restores them when destroyed.

WorkspaceSettings: Configuring the workspace

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

export const Agents = Modal.Environment("Agents", {});
export const Settings = Modal.WorkspaceSettings("Settings", {
  defaultEnvironment: Agents,
  imageBuilderVersion: "2025.06",
});