diff --git a/Makefile b/Makefile
index ed92ae69..190c64a4 100644
--- a/Makefile
+++ b/Makefile
@@ -62,10 +62,21 @@ else
   DOCKER_COMPOSE_RUN_ARG=--rm
 endif
 
+COMPOSE_ARGS := -f compose.yaml
+
+# in DEV mode, include an override compose file for each MINI_LAB_* checkout
+# path that is set, to mount it into the deployment containers.
+ifeq ($(DEV),true)
+COMPOSE_ARGS += $(if $(MINI_LAB_METAL_ROLES),-f compose.dev/metal-roles.yaml)
+COMPOSE_ARGS += $(if $(MINI_LAB_ANSIBLE_COMMON),-f compose.dev/ansible-common.yaml)
+COMPOSE_ARGS += $(if $(MINI_LAB_METAL_ANSIBLE_MODULES),-f compose.dev/metal-ansible-modules.yaml)
+COMPOSE_ARGS += $(if $(MINI_LAB_HELM_CHARTS),-f compose.dev/helm-charts.yaml)
+endif
+
 .PHONY: up
 up: env gen-certs control-plane-bake partition-bake
 	@chmod 600 files/ssh/id_ed25519
-	docker compose up --pull=always --abort-on-container-failure --remove-orphans --force-recreate control-plane partition
+	docker compose $(COMPOSE_ARGS) up --pull=always --abort-on-container-failure --remove-orphans --force-recreate control-plane partition
 	@$(MAKE)	--no-print-directory	start-machines
 # for some reason an allocated machine will not be able to phone home
 # without restarting the metal-core
@@ -98,11 +109,11 @@ roll-certs:
 
 .PHONY: control-plane
 control-plane: control-plane-bake env
-	docker compose up --remove-orphans --force-recreate control-plane
+	docker compose $(COMPOSE_ARGS) up --remove-orphans --force-recreate control-plane
 
 .PHONY: create-proxy-registries
 create-proxy-registries:
-	docker compose up -d --force-recreate proxy-docker proxy-ghcr proxy-gcr proxy-k8s proxy-quay
+	docker compose $(COMPOSE_ARGS) up -d --force-recreate proxy-docker proxy-ghcr proxy-gcr proxy-k8s proxy-quay
 
 .PHONY: control-plane-bake
 control-plane-bake:
@@ -116,7 +127,7 @@ control-plane-bake:
 
 .PHONY: partition
 partition: partition-bake
-	docker compose up --remove-orphans --force-recreate partition
+	docker compose $(COMPOSE_ARGS) up --remove-orphans --force-recreate partition
 
 .PHONY: partition-bake
 partition-bake: external_network
@@ -159,7 +170,7 @@ cleanup: cleanup-control-plane cleanup-partition
 .PHONY: cleanup-control-plane
 cleanup-control-plane:
 	kind delete cluster --name metal-control-plane
-	docker compose down
+	docker compose $(COMPOSE_ARGS) down
 	rm -f $(KUBECONFIG)
 
 .PHONY: cleanup-partition
diff --git a/README.md b/README.md
index 7ae3e5a9..4ad787af 100644
--- a/README.md
+++ b/README.md
@@ -190,6 +190,47 @@ There are make targets to handle the power state of a machine:
 make power-<on,reset,off>-<machine name>
 ```
 
+## Development
+If you want to contribute to the _metal-stack_ project, you can use the mini-lab as a local development environment. It allows you to quickly test changes to the _metal-stack_ components without needing any external clusters or hardware. 
+You can also use it to test changes to the Ansible roles and modules used by the _metal-stack_.
+
+### Release vector
+
+You can configure the `mini-lab` to deploy specific custom or unreleased images of components by adjusting the variables in [inventories/group_vars/all/release_vector.yaml](inventories/group_vars/all/release_vector.yaml).
+
+For example, to quickly deploy `metal-api` with a custom branch tag, you can add or uncomment specific release tags in that file:
+
+```yaml
+metal_api_image_tag: my-feat-branch
+# metal_core_image_tag: v1.2.3
+```
+
+Further overrides can be looked up in `metal-roles` where the mapping is defined in [common/roles/defaults/defaults/main.yaml](https://github.com/metal-stack/metal-roles/blob/master/common/roles/defaults/defaults/main.yaml).
+
+### Using local checkouts of dependencies
+
+By default, the `mini-lab` runs with pre-packaged Ansible roles and modules. 
+If you want to use local checkouts of dependencies for development, you must start the `mini-lab` with `DEV=true`:
+
+```bash
+DEV=true make up
+```
+
+When `DEV=true` is set, you can provide the following environment variables to map local directories into the containers. Each variable is independent — only the ones you set will be mounted (via a matching override file from `compose.dev/`):
+
+- `MINI_LAB_METAL_ROLES`: path to local `metal-roles` (includes `compose.dev/metal-roles.yaml`)
+- `MINI_LAB_ANSIBLE_COMMON`: path to local `ansible-common` (includes `compose.dev/ansible-common.yaml`)
+- `MINI_LAB_METAL_ANSIBLE_MODULES`: path to local `metal-ansible-modules` (includes `compose.dev/metal-ansible-modules.yaml`)
+- `MINI_LAB_HELM_CHARTS`: path to local `helm-charts` (includes `compose.dev/helm-charts.yaml`)
+
+Example:
+
+```bash
+export MINI_LAB_METAL_ROLES=${HOME}/src/github.com/metal-stack/metal-roles
+export DEV=true
+make up
+```
+
 ## Flavors
 
 All available mini-lab flavors are listed below:
diff --git a/compose.dev/ansible-common.yaml b/compose.dev/ansible-common.yaml
new file mode 100644
index 00000000..e69a8a1b
--- /dev/null
+++ b/compose.dev/ansible-common.yaml
@@ -0,0 +1,8 @@
+---
+services:
+  control-plane:
+    volumes:
+      - ${MINI_LAB_ANSIBLE_COMMON}:/root/.ansible/roles/ansible-common:ro
+  partition:
+    volumes:
+      - ${MINI_LAB_ANSIBLE_COMMON}:/root/.ansible/roles/ansible-common:ro
diff --git a/compose.dev/helm-charts.yaml b/compose.dev/helm-charts.yaml
new file mode 100644
index 00000000..7dabbefc
--- /dev/null
+++ b/compose.dev/helm-charts.yaml
@@ -0,0 +1,5 @@
+---
+services:
+  control-plane:
+    volumes:
+      - ${MINI_LAB_HELM_CHARTS}:/helm-charts:ro
diff --git a/compose.dev/metal-ansible-modules.yaml b/compose.dev/metal-ansible-modules.yaml
new file mode 100644
index 00000000..9ddd07a2
--- /dev/null
+++ b/compose.dev/metal-ansible-modules.yaml
@@ -0,0 +1,8 @@
+---
+services:
+  control-plane:
+    volumes:
+      - ${MINI_LAB_METAL_ANSIBLE_MODULES}:/root/.ansible/roles/metal-ansible-modules:ro
+  partition:
+    volumes:
+      - ${MINI_LAB_METAL_ANSIBLE_MODULES}:/root/.ansible/roles/metal-ansible-modules:ro
diff --git a/compose.dev/metal-roles.yaml b/compose.dev/metal-roles.yaml
new file mode 100644
index 00000000..515274ef
--- /dev/null
+++ b/compose.dev/metal-roles.yaml
@@ -0,0 +1,8 @@
+---
+services:
+  control-plane:
+    volumes:
+      - ${MINI_LAB_METAL_ROLES}:/root/.ansible/roles/metal-roles:ro
+  partition:
+    volumes:
+      - ${MINI_LAB_METAL_ROLES}:/root/.ansible/roles/metal-roles:ro
diff --git a/compose.yaml b/compose.yaml
index 5ac654ab..a2f0d224 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -6,12 +6,6 @@ services:
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:z
       - .:/mini-lab
-      # for developing role dependencies
-      # TODO: make this a switch
-      # - ${HOME}/.ansible/roles/ansible-common:/root/.ansible/roles/ansible-common:ro
-      # - ${HOME}/.ansible/roles/metal-roles:/root/.ansible/roles/metal-roles:ro
-      # - ${HOME}/.ansible/roles/metal-ansible-modules:/root/.ansible/roles/metal-ansible-modules:ro
-      # - ${HOME}/git/github.com/metal-stack/helm-charts:/helm-charts:ro
     environment:
       - ANSIBLE_DISPLAY_SKIPPED_HOSTS=${ANSIBLE_DISPLAY_SKIPPED_HOSTS:-false}
       - ANSIBLE_INVENTORY=inventories/control-plane.yaml
@@ -39,11 +33,6 @@ services:
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:z
       - .:/mini-lab
-      # for developing role dependencies
-      # TODO: make this a switch
-      # - ${HOME}/.ansible/roles/ansible-common:/root/.ansible/roles/ansible-common:ro
-      # - ${HOME}/.ansible/roles/metal-roles:/root/.ansible/roles/metal-roles:ro
-      # - ${HOME}/.ansible/roles/metal-ansible-modules:/root/.ansible/roles/metal-ansible-modules:ro
     environment:
       - ANSIBLE_DISPLAY_SKIPPED_HOSTS=${ANSIBLE_DISPLAY_SKIPPED_HOSTS:-false}
       - ANSIBLE_INVENTORY=inventories/partition.yaml,clab-mini-lab/ansible-inventory.yml