Skip to main content
synth-ai modal-serve streams a task app into Modal for an interactive session.
  • App selection works the same as other task-app commands: skip APP_ID to pick from the discovered list, or specify one directly.
  • .env files supplied via --env-file, declared on the registry entry, or auto-discovered are loaded before launch. If no file exists the helper walks you through creating one so ENVIRONMENT_API_KEY is always available.
  • Missing keys trigger prompts (and minting when supported) before the Modal CLI runs. Successful values are written back to disk for future reuse.
  • When an entry ships its own Modal script the CLI runs it verbatim; otherwise it generates a temporary entrypoint that installs synth-ai, mounts the necessary directories, applies ModalDeploymentConfig, and boots your FastAPI app.
  • Secrets for ENVIRONMENT_API_KEY, ENVIRONMENT_API_KEY_ALIASES, and optional vendor keys are inlined into the Modal command so you don’t need to configure them separately.
  • The command resolves which Modal CLI to use automatically—preferring a real modal binary on PATH, falling back to the built-in shim when only the Python package is installed, and honoring --modal-cli or SYNTH_FORCE_MODAL_WRAPPER=1 when you need explicit control.
  • Output from modal serve is streamed back in real time. If Modal prints a public URL (e.g. => https://your-app.modal.run) it is saved to the first .env as TASK_APP_BASE_URL for follow-on commands.

​
Options

  • APP_ID — Task app identifier. Omit to open the interactive picker; provide one to bypass the prompt.
  • --env-file PATH — One or more .env files to load before invoking Modal. Repeat the flag to merge multiple files.
  • --modal-cli PATH — Explicit Modal CLI executable. Useful when the binary lives outside your PATH or when you need to pin a specific version.
  • --name VALUE — Modal app name override passed directly to modal serve --name. Handy when you want distinct app names for development vs. staging runs.
uvx synth-ai modal-serve grpo-crafter --name grpo-crafter-dev --env-file .env.crafter
Example session: 
synth@Nomans-Resolve sdk % uvx synth-ai modal-serve grpo-crafter
Select env file to load:
  1) /Users/synth/qa/sdk/.env
Enter choice [1]: 1
[deploy] inline ENVIRONMENT_API_KEY prepared (sk-...46a)
[modal-prefix] modal_cli=modal selected=/opt/homebrew/bin/modal
[modal-exec] modal serve /var/folders/.../grpo_crafter_modal.py --name grpo-crafter-dev
Serving grpo-crafter-dev on https://grpo-crafter-dev.modal.run
✓ Task app URL: https://grpo-crafter-dev.modal.run

​
Notes

  • Script-backed apps (modal_script) bypass the generated entrypoint and run the author-provided script instead.
  • Inline secrets let Modal reach your backend without further setup, but you can still mount Modal secrets via ModalDeploymentConfig when you need long-term storage.
  • Because this command starts an interactive Modal session, closing the CLI stops the app. Use synth-ai deploy when you need a persistent deployment.