Thanks for the details — we can definitely get this running locally with

serve()

. A quick recap - In Prefect 3.x,

flow.serve()

runs your flows locally with an ephemeral API; there’s no dependency on Prefect Cloud or a long‑running server. - If your flow launches Docker containers, the process running

serve()

must be able to reach the Docker daemon and any host paths you bind-mount. From your description, the failure with

serve()

is almost certainly due to Docker connectivity or how the bind mounts are resolved when the flow is run under

serve()

. Checklist to make

serve()

work with local Docker containers 1) Confirm where

serve()

is running - On your host machine: your code needs the Docker SDK to reach the host daemon. - Inside a container: you must mount the Docker socket and pass it through. 2) Connect to the Docker daemon from your flow - Linux/macOS (Docker Desktop or native Docker): - DOCKER_HOST usually not required if

/var/run/docker.sock

is present. - If you set it explicitly:

DOCKER_HOST=unix:///var/run/docker.sock

- Windows (Docker Desktop): -

DOCKER_HOST=npipe:////./pipe/docker_engine

- If running

serve()

inside a container, mount the socket: -

-v /var/run/docker.sock:/var/run/docker.sock

and set

DOCKER_HOST=unix:///var/run/docker.sock

3) Bind mounts must exist on the Docker host - Docker resolves host paths on the DOCKER HOST, not inside your Python process. - If you bind a network share, pre-mount the share on the host OS (e.g.,

/mnt/share

) then bind that path into the containers. - Docker Desktop (macOS/Windows): ensure the host path is allowed in Docker Desktop file sharing. 4) Use the Prefect Docker integration and pass a DockerHost Install the integration if you haven’t already:

pip install prefect-docker docker

Minimal working example that runs a container with bind mounts under `serve()`:

from prefect import flow, task
from prefect.task_runners import ConcurrentTaskRunner
from prefect_docker.host import DockerHost
from prefect_docker.containers import (
    create_docker_container,
    start_docker_container,
    get_docker_container_logs,
    remove_docker_container,
)

@task
def run_container(image: str, name: str, binds: dict):
    # Use the correct base_url for your environment
    # Linux/macOS: "unix:///var/run/docker.sock"
    # Windows: "npipe:////./pipe/docker_engine"
    host = DockerHost(base_url="unix:///var/run/docker.sock")

    container = create_docker_container(
        image=image,
        name=name,
        detach=True,
        docker_host=host,
        # Docker SDK "binds" format: {"/host/path": {"bind": "/container/path", "mode": "rw"}}
        volumes=binds,
    )
    start_docker_container(container.id, docker_host=host)

    logs = get_docker_container_logs(container.id, docker_host=host, stream=False)
    # Clean up when finished
    remove_docker_container(container.id, docker_host=host, force=True)
    return logs

@flow(name="main-flow", task_runner=ConcurrentTaskRunner())
def main_flow():
    # Example of launching multiple containers in parallel
    binds = {"/mnt/myshare": {"bind": "/data", "mode": "rw"}}
    f1 = run_container.submit("alpine:3.19", "job-1", binds)
    f2 = run_container.submit("alpine:3.19", "job-2", binds)
    return [f1.result(), f2.result()]

if __name__ == "__main__":
    # This serves locally, with no dependency on Prefect Cloud
    main_flow.serve(name="local-serve")

5) If you run

serve()

inside a Docker container - Mount the docker socket and all host paths your child containers need:

docker run --rm -it \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /mnt/myshare:/mnt/myshare \
  -e DOCKER_HOST=unix:///var/run/docker.sock \
  -p 4200:4200 \
  your-image:latest python deploy.py

- Important: If your flow container itself needs to read/write the same files, mount those paths into the flow container too (as shown). 6) Quick connectivity test

Add a tiny task to verify Docker access from within `serve()`:

from docker import from_env
from prefect import task

@task
def test_docker_ping():
    client = from_env()
    return client.ping()

If this fails, the issue is Docker connectivity (socket/DOCKER_HOST/permissions). Fix that first. Common pitfalls - Relative host paths in bind mounts. Always use absolute host paths. - Network shares on Docker Desktop not whitelisted for file sharing. - Running

serve()

inside a container without mounting the Docker socket. - Windows path/permission issues. Use

npipe:////./pipe/docker_engine

and ensure your user has Docker access. References - Prefect Docker integration: prefect-docker - Prefect docs (search for serve): Prefect 3 docs Could you share: - The exact error message/trace you get under

main_flow.serve()

- Where you run

serve()

(host vs inside a container), and your OS - How you are launching containers now (prefect-docker functions, docker SDK, or shell commands) - One example of the volume mount you’re using (host path -> container path) With that, I can tailor the config and code to your setup.

Sorry, I encountered an error while processing your request. Please try again.