diff --git a/README.md b/README.md
index 0e20449..f5a92fd 100644
--- a/README.md
+++ b/README.md
@@ -811,6 +811,39 @@ nanobot cron remove <job_id>
 > [!TIP]
 > The `-v ~/.nanobot:/root/.nanobot` flag mounts your local config directory into the container, so your config and workspace persist across container restarts.
 
+### Using Docker Compose (Recommended)
+
+The easiest way to run nanobot with Docker:
+
+```bash
+# 1. Initialize config (first time only)
+docker compose run --rm nanobot-cli onboard
+
+# 2. Edit config to add API keys
+vim ~/.nanobot/config.json
+
+# 3. Start gateway service
+docker compose up -d nanobot-gateway
+
+# 4. Check logs
+docker compose logs -f nanobot-gateway
+
+# 5. Run CLI commands
+docker compose run --rm nanobot-cli status
+docker compose run --rm nanobot-cli agent -m "Hello!"
+
+# 6. Stop services
+docker compose down
+```
+
+**Features:**
+- ✅ Resource limits (1 CPU, 1GB memory)
+- ✅ Auto-restart on failure
+- ✅ Shared configuration using YAML anchors
+- ✅ Separate CLI profile for on-demand commands
+
+### Using Docker directly
+
 Build and run nanobot in a container:
 
 ```bash
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..446f5e3
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,32 @@
+x-common-config: &common-config
+  build:
+    context: .
+    dockerfile: Dockerfile
+  volumes:
+    - ~/.nanobot:/root/.nanobot
+
+services:
+  nanobot-gateway:
+    container_name: nanobot-gateway
+    <<: *common-config
+    command: ["gateway"]
+    restart: unless-stopped
+    ports:
+      - 18790:18790
+    deploy:
+      resources:
+        limits:
+          cpus: '1'
+          memory: 1G
+        reservations:
+          cpus: '0.25'
+          memory: 256M
+  
+  nanobot-cli:
+    container_name: nanobot-cli
+    <<: *common-config
+    profiles:
+      - cli
+    command: ["status"]
+    stdin_open: true
+    tty: true