Deploy Task Apps

• Local runtime (--runtime local) starts your task app with uvicorn.
• Modal runtime (--runtime modal) shell-executes the Modal CLI against a Python entrypoint you provide.

​

Run Locally with uvicorn

uvx synth-ai deploy \
  --task-app task_apps/crafter/task_app.py \
  --runtime local \
  --host 0.0.0.0 \
  --port 8001 \
  --no-trace

• The CLI loads ENVIRONMENT_API_KEY (and optionally other secrets) into the process using synth_ai.utils.env.resolve_env_var.
• LocalTaskAppConfig is built with the provided host, port, and trace flag and passed to deploy_uvicorn_app.
• uvicorn runs in the foreground. You can stop it with Ctrl+C.

​

Deploy via Modal

uvx synth-ai deploy \
  --task-app task_apps/crafter/task_app.py \
  --runtime modal \
  --modal-app modal/crafter_app.py \
  --name crafter-dev \
  --modal-mode deploy

• You must supply both the task app file (--task-app) and the Modal wrapper script (--modal-app). The command does not generate or discover these automatically.
• --modal-cli can point to a specific binary; otherwise get_default_modal_bin_path() is used to locate modal.
• The CLI assembles the command modal <deploy|serve> <modal_app.py>, appending --name when provided, and streams the subprocess output.
• --modal-mode serve is allowed but cannot be combined with --dry-run (the command raises an error).

​

Options

• --task-app PATH — Python file that defines your task app; omitted value triggers an interactive file picker.
• --runtime {local,modal,tunnel} — Required runtime selection.
• --env PATH — Required. Path to .env file containing SYNTH_API_KEY and ENVIRONMENT_API_KEY.
• --trace/--no-trace — Toggle trace emission for local runs (default --trace).
• --host VALUE / --port VALUE — Bind address and port for uvicorn (local and tunnel runtimes).
• --wait/--no-wait — Wait for deployment to complete (blocking mode). Default is non-blocking (background).
• --tunnel-mode {quick,managed} — Tunnel mode for tunnel runtime (default: quick).
• --tunnel-subdomain TEXT — Custom subdomain for managed tunnel (tunnel runtime only).
• --modal-app PATH — Modal entrypoint to execute (modal runtime only).
• --name TEXT — Override the Modal app name (modal runtime only).
• --modal-mode {deploy,serve} — Choose between persistent deployment or ephemeral serve (modal runtime only).
• --modal-cli PATH — Explicit path to the Modal CLI binary (modal runtime only).
• --dry-run — Print the Modal command instead of executing it (modal runtime only, not valid with --modal-mode serve).

​

Runtime Behaviors

​

Local Runtime (--runtime local)

• Non-blocking by default: Starts uvicorn server in background using nohup
• Service Records: Automatically records deployment to ~/.synth-ai/services.json
• Background Process: Server continues running after command exits
• Use --wait: To run in blocking mode (foreground)

​

Tunnel Runtime (--runtime tunnel)

• Non-blocking by default: Starts tunnel and returns immediately
• Tunnel Records: Automatically records tunnel to ~/.synth-ai/services.json
• Quick Tunnels: Free, ephemeral tunnels (no account required)
• Managed Tunnels: Stable tunnels with custom subdomains (requires SYNTH_API_KEY)
• Use --wait: To run in blocking mode and keep tunnel alive

​

Modal Runtime (--runtime modal)

• Non-blocking by default: Starts Modal deployment process and returns immediately
• Use --wait: To wait for deployment to complete

​

Notes

• API Keys Required: SYNTH_API_KEY and ENVIRONMENT_API_KEY must be present in either:
  • Your environment (exported variables), OR
  • The .env file provided via --env
• Non-Blocking Default: All deployments run in background by default to prevent indefinite stalls
• Service Discovery: Use synth-ai scan to discover deployed services and check their health