Use your local files

Edit on your laptop and see the change in the running container, with compose watch or Mutagen.

On a Docker host, a bind mount such as ./src:/app mounts a folder on the host's disk, not your laptop's. Your files reach the host only through Docker's own connection, so instead of mounting them you copy them in as you work. Two tools do that well:

compose watchMutagen
DirectionLaptop to containerBoth ways
InstallNothing: part of Docker Compose 2.22 and laterbrew install mutagen-io/mutagen/mutagen
Files the container writesStay in the containerCome back to your laptop
Best forApp code with hot reloadAnything that has to work like a real mount: generated code, lockfiles, migrations

compose watch

Compose copies each file you save into the running container. The image already holds the code from COPY, so the container starts in sync and only changes travel.

Dockerfile
FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
compose.yaml
services:
  web:
    build: .
    ports: ["3000:3000"]
    command: npm run dev
    develop:
      watch:
        # a saved file is copied into the running container
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        # a dependency change rebuilds the image
        - action: rebuild
          path: package.json
your terminal
docker compose up --watch

Save a file and it is in the container within a second or two; a dev server that reloads on change, such as Vite, Next or nodemon, picks it up from there. New files, folders and deletions come across too. Changing package.json rebuilds the image and restarts the service.

  • One way only. Files the container writes, like a regenerated lockfile or build output, don't come back. Use Mutagen if you need them.
  • Files arrive owned by your laptop's user id (often 501 or 502). If the app runs as another user and must write to them, give that user access in the Dockerfile.
  • List what not to send under ignore. Dependencies belong in the image, not in the sync.
  • The host stays awake while it runs, as with any attached docker compose up. Stop it with Ctrl-C when you're done, and the host stops 10 minutes later.

Mutagen, both ways

Mutagen keeps a folder on your laptop and a folder in a container in step, in both directions, through Docker's connection. Keep the code in a volume, with one small container holding it for Mutagen, and mount the volume in your services.

  1. Start the sync

    In the project folder, with Docker pointing at your host:

    your terminal
    # once per project: a volume for the code, and a small container that holds it
    docker volume create shop-api-src
    docker run -d --name shop-api-sync --restart unless-stopped \
      -v shop-api-src:/app alpine sleep infinity
    
    # keep this folder and the volume in sync, both ways
    mutagen sync create --name shop-api \
      --ignore-vcs --ignore node_modules \
      . docker://shop-api-sync/app

    The first time, Mutagen installs a small agent of about 8 MB in the container, then copies your files. How long that takes depends on your upload speed. After that only changes travel.

  2. Mount the volume

    compose.yaml
    services:
      web:
        image: node:22
        working_dir: /app
        command: sh -c "npm ci && npm run dev"
        ports: ["3000:3000"]
        volumes:
          - src:/app
    
    volumes:
      src:
        name: shop-api-src
        external: true
  3. Work as usual

    Edit on your laptop and the container sees it; a file the container writes appears in your folder.

    your terminal
    mutagen sync list shop-api       # state, and any conflicts
    mutagen sync pause shop-api      # stop syncing for now
    mutagen sync resume shop-api
    mutagen sync terminate shop-api  # end it; both copies stay
  • Ignore what's big and rebuilt anyway: node_modules, target, .venv, build output. Install dependencies inside the container instead.
  • A running sync keeps the host awake. It holds a connection open, and a host with a connection doesn't stop for being idle. Run mutagen sync pause when you're done for the day, and resume when you're back; the volume keeps the files meanwhile.
  • One sync per folder. With one host per project, name the sync, the volume and the container after the project.

Uploads are your upload speed

Every byte goes up your own internet connection. On a slow uplink, keep the first copy small: build dependencies in the image, ignore generated folders, and leave large data files out of the synced folder. A .dockerignore does the same for docker build.