diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..05c3002
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,19 @@
+# Example env file — copy to .env and fill real values (DO NOT COMMIT .env)
+# Generate a secure API key: `openssl rand -hex 32` or `python -c "import secrets;print(secrets.token_urlsafe(32))"`
+
+# Gateway
+API_KEY=change-me-to-a-strong-random-value
+CLIP_URL=http://clip:8000
+BLIP_URL=http://blip:8000
+YOLO_URL=http://yolo:8000
+QDRANT_SVC_URL=http://qdrant-svc:8000
+
+# Qdrant wrapper (qdrant-svc)
+QDRANT_HOST=qdrant
+QDRANT_PORT=6333
+COLLECTION_NAME=images
+VECTOR_DIM=512
+
+# Gateway runtime
+VISION_TIMEOUT=300
+MAX_IMAGE_BYTES=52428800