Modal
Builds a modal.App programmatically: Image.from_registry pinned by digest, a serialized class with @modal.web_server that execs the container command, then app.deploy(name=f"multihull-{svc}-{provider}"), so two Modal targets in one service get two apps. destroy runs modal app stop, since the SDK has no stop call. Needs modal>=1.6.
- provider: modal-main type: modal priority: 2 modal: {environment: main, region: eu}Credentials: MODAL_TOKEN_ID and MODAL_TOKEN_SECRET, or ~/.modal.toml.
Requirements:
container.commandmust be set. Modal does not run the imageCMD, and the translator resets the imageENTRYPOINT(ENTRYPOINT []is the first setup Dockerfile line), because Modal starts its own runtime process in the container; an entrypoint such as the public vLLM image’spython3 -m vllm.entrypoints.openai.api_serverwould otherwise swallow Modal’s arguments and crash on start.- The server must listen on
0.0.0.0. - The Python running
hull deploymust match the image’s Python minor version, because the server class is serialized with cloudpickle. - An empty
resources.gpuruns the container on CPU. - Every
container.secretsname must be an environment variable name: letters, digits and underscores, not starting with a digit (^[A-Za-z_][A-Za-z0-9_]*$). Modal rejects any otherSecret.from_dictkey at deploy (“Only letters, numbers, and underscores are allowed”), sohull plannotes a name such ashf-tokenandapplyrefuses it before calling Modal. - Deploys pin Modal’s image builder to
2025.06, whatever the workspace default. Modal then mounts its client at runtime instead of runningpip installin the image, so images withoutpip(a uv venv first onPATH, for example) work.MODAL_IMAGE_BUILDER_VERSIONoverrides it. - Modal expects
pythononPATH. For an image that ships onlypython3(the public vLLM images, for example),modal.setupDockerfileCommandsadds Dockerfile lines afterFROM, passed toImage.from_registry(setup_dockerfile_commands=...):
modal: setupDockerfileCommands: ["RUN ln -s /usr/bin/python3 /usr/local/bin/python"]Private registries
Section titled “Private registries”registrySecret names two environment variables. At deploy time their values become a modal.Secret.from_dict with REGISTRY_USERNAME and REGISTRY_PASSWORD, passed to Image.from_registry. Only the names reach plan output, state and the snapshot.
modal: environment: main registrySecret: {usernameEnv: GHCR_USERNAME, passwordEnv: GHCR_TOKEN}Modal pulls the image once, during deploy, and caches it. A short-lived token, such as GITHUB_TOKEN with packages: read, is enough.
Translation
Section titled “Translation”| Spec field | Modal |
|---|---|
container.image |
modal.Image.from_registry(ref@digest, secret=), image builder 2025.06 |
container.command, port |
@modal.web_server(port, startup_timeout) wrapping subprocess.Popen(command) |
resources.gpu |
gpu="A10G", gpu="L4", and so on; None when empty |
scaling.replicas |
min_containers, max_containers, buffer_containers |
scaling.concurrency |
@modal.concurrent(max_inputs=) |
container.health |
startup_timeout (at least 60 s); hull deploy --wait and hull status report Ready only once a container runs and web_url + path answers 2xx within 5 s; the router probes the same URL |
container.secrets |
modal.Secret.from_dict, named multihull-<svc>, one key per listed name |
| endpoint | get_web_url() with label multihull-<svc>, plus proxy-auth headers injected by the router, plus the edge error signature 404 with body prefix modal-http: (what a stopped app answers) so the router fails over instead of returning it |
Ref stored in state: app name plus environment.