Auto upload local code for remote workers (via --working-dir)

[dragongu]

Describe the current behavior

In remote-worker mode, worker machines cannot access the deploy client's local path.
Users must manually package/upload code to shared storage first, then configure pull steps.

This creates operational friction, especially for teams migrating from Ray workflows (ray job submit) where local code submission is typically one step.

Describe the proposed behavior

When deploying to remote workers, support an opt-in flow based on --working-dir:

prefect deploy ./flows/my_flow.py:my_flow \
  --name my-flow \
  --pool remote-pool \
  --working-dir /opt/prefect/flows

Behavior

• Prefect automatically packages/uploads local code to configured shared storage.
• Deployment automatically gets pull metadata and working directory.
• Worker pulls and runs directly.
• Storage location/credentials should be configured in Prefect server and worker startup config, so end users do not need to manage upload details in each deployment command.

[pratyush618]

Thanks for raising this — the friction you're describing is real, and the comparison to ray job submit is a useful framing. The good news is most of the plumbing you're asking for already exists in Prefect 3 today; what's missing is a one-shot CLI surface over it. Below is (1) how to get the workflow you described right now, and (2) what would actually be new in the proposal.

1. The workflow you want is supported today via push + pull steps

Prefect deployments have three step lifecycles in prefect.yaml:

• build — runs at prefect deploy time (e.g. build a Docker image)
• push — runs at prefect deploy time, after build (e.g. upload code/image)
• pull — runs on the remote worker, before the flow executes (e.g. download code, set CWD)

Concretely, for your S3 example:

# prefect.yaml
push:
  - prefect_aws.deployments.steps.push_to_s3:
      id: push_code
      requires: prefect-aws>=0.5
      bucket: my-prefect-bucket
      folder: my-flow

pull:
  - prefect_aws.deployments.steps.pull_from_s3:
      id: pull_code
      requires: prefect-aws>=0.5
      bucket: "{{ push_code.bucket }}"
      folder: "{{ push_code.folder }}"
  - prefect.deployments.steps.set_working_directory:
      directory: /opt/prefect/flows   # <-- your --working-dir

deployments:
  - name: my-flow
    entrypoint: flows/my_flow.py:my_flow
    work_pool:
      name: remote-pool

With that in place:

prefect deploy

…packages your local working directory, uploads it to S3 (respecting .prefectignore), records the bucket/folder on the deployment as pull metadata, and the worker pulls it before each run. That is exactly the end-to-end behavior described in the issue.

GCS and Azure are equivalent — prefect_gcp.deployments.steps.push_to_gcs / pull_from_gcs and prefect_azure.deployments.steps.push_to_azure_blob_storage / pull_from_azure_blob_storage.

2. You don't have to write that YAML by hand

prefect init ships pre-wired recipes that do exactly the push+pull pairing for you:

• s3 / docker-s3
• gcs / docker-gcs
• azure / docker-azure
• git / docker-git
• docker, local

So:

prefect init --recipe s3

…produces a prefect.yaml with the matching push_to_s3 + pull_from_s3 pair already filled in; you only fill in bucket/folder. prefect deploy run interactively will also prompt you to pick a storage backend and wire the recipe up if no prefect.yaml exists. So today's "happy path" is two commands, not one — but it's not "manually package and configure pull steps."

3. What would actually be new in the proposal

If I read the request strictly, the new thing is a CLI shortcut that infers a recipe from server-side configuration, so the user never touches prefect.yaml:

prefect deploy ./flows/my_flow.py:my_flow \
  --name my-flow --pool remote-pool \
  --working-dir /opt/prefect/flows

For this to make sense, three things need to be decided:

1. Where does the upload target come from? The proposal says "configured in Prefect server and worker startup config." That's a meaningful design choice — Prefect today keeps deployment storage per-deployment (in prefect.yaml / pull steps). A server-side default storage location would be a new concept and would need to interact with multi-tenant Cloud, work-pool-scoped storage, and credentials (which today live in blocks like S3Bucket, GcsBucket, etc.).

2. What does --working-dir mean exactly? In the example it looks like the remote path the worker should cd into (i.e. an alias for set_working_directory.directory). It could also be misread as the local path being uploaded. Worth disambiguating — perhaps --remote-working-dir plus a separate --source for the local directory.

3. Does it generate prefect.yaml, or stay ephemeral? Generating a prefect.yaml keeps deploys reproducible from CI; an ephemeral one-shot is closer to ray job submit but loses that property. A reasonable compromise: the flag implies "use the work pool's default storage block + add a set_working_directory pull step," and the resulting steps get persisted on the deployment itself (which is already how pull steps are stored).

A natural shape this could take, building on existing primitives:

• A default_storage_block field on a work pool (or workspace-level setting).
• prefect deploy --auto-upload (or --upload-from <dir>) that, when the work pool has a default storage block, automatically synthesizes the equivalent push + pull_with_block + set_working_directory steps and attaches them to the deployment.
• --working-dir becomes sugar for the trailing set_working_directory step.

That keeps the existing step model as the source of truth and only adds a CLI/server convenience layer on top — which is, I think, where the proposal's value actually lives.

4. Workaround until then

If the goal right now is "one command from a fresh checkout," a small wrapper is enough:

# scripts/deploy.sh
prefect init --recipe s3 --no-prompt 2>/dev/null || true
yq -i '.push[0]."prefect_aws.deployments.steps.push_to_s3".bucket = strenv(BUCKET)' prefect.yaml
yq -i '.pull[0]."prefect_aws.deployments.steps.pull_from_s3".bucket = strenv(BUCKET)' prefect.yaml
prefect deploy "$@"

Or, if you don't want a checked-in prefect.yaml, you can pass push/pull steps programmatically via flow.from_source(...).deploy(...) using a RemoteFileSystem / S3Bucket block — which gets you closer to the ray job submit ergonomics in pure Python, no YAML at all.

---

TL;DR: the underlying upload+pull mechanism, the storage backends, and set_working_directory already exist. What's missing — and worth tracking as the actual feature ask — is a CLI/server-config convenience that lets a user skip prefect.yaml entirely by relying on a work-pool-level default storage block. The --working-dir flag is the smallest piece of that; the bigger piece is "default storage on the work pool."

Pointers for anyone implementing this:

• Pull steps: src/prefect/deployments/steps/pull.py (set_working_directory, pull_from_remote_storage, pull_with_block, git_clone)
• Recipes: src/prefect/deployments/recipes/ (s3, gcs, azure, docker-*, git)
• Deploy CLI entry point: src/prefect/cli/deploy/_core.py, interactive storage prompt at src/prefect/cli/deploy/_actions.py
• Push step implementations live in the integration packages: prefect-aws, prefect-gcp, prefect-azure.