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 watch | Mutagen | |
|---|---|---|
| Direction | Laptop to container | Both ways |
| Install | Nothing: part of Docker Compose 2.22 and later | brew install mutagen-io/mutagen/mutagen |
| Files the container writes | Stay in the container | Come back to your laptop |
| Best for | App code with hot reload | Anything 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.
FROM node:22
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .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.jsondocker 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.
Start the sync
In the project folder, with Docker pointing at your host:
# 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/appThe 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.
Mount the volume
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: trueWork as usual
Edit on your laptop and the container sees it; a file the container writes appears in your folder.
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 pausewhen you're done for the day, andresumewhen 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.