geoffjay · geoffjay · Mar 5, 2026
diff --git a/.dockerignore b/.dockerignore
@@ -0,0 +1,45 @@
+# Git
+.git
+.gitignore
+
+# Docker
+Dockerfile
+docker-compose*.yml
+.dockerignore
+
+# Build artifacts
+target/
+**/target/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Python virtual environment (if present)
+.venv/
+venv/
+__pycache__/
+
+# Node modules (if any)
+node_modules/
+
+# Documentation
+docs/
+*.md
+!README.md
+
+# Test fixtures
+*.lock.bak
+
+# Logs
+*.log
+logs/
+
+# macOS
+.DS_Store
+
+# Linux
+Thumbs.db
diff --git a/Dockerfile b/Dockerfile
@@ -0,0 +1,67 @@
+# Multi-stage Dockerfile for building all agentd services
+# Produces a slim runtime image with all service binaries
+
+# =============================================================================
+# Stage 1: Builder
+# =============================================================================
+FROM rust:1.75-bookworm AS builder
+
+WORKDIR /app
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    pkg-config \
+    libssl-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy workspace manifest and crate metadata
+COPY Cargo.toml Cargo.lock ./
+COPY crates/ ./crates/
+
+# Build all binaries in release mode
+# This creates a single build layer that can be cached
+RUN cargo build --release --workspace --bins
+
+# =============================================================================
+# Stage 2: Runtime
+# =============================================================================
+FROM debian:bookworm-slim AS runtime
+
+# Install runtime dependencies (tmux for wrap/orchestrator, ca-certificates for HTTPS)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    tmux \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/* \
+    && useradd --create-home --shell /bin/bash agentd
+
+# Create directories for data storage
+RUN mkdir -p /var/lib/agentd/notify \
+    && mkdir -p /var/lib/agentd/orchestrator \
+    && mkdir -p /var/log/agentd \
+    && chown -R agentd:agentd /var/lib/agentd \
+    && chown -R agentd:agentd /var/log/agentd
+
+WORKDIR /app
+
+# Copy binaries from builder
+COPY --from=builder /app/target/release/agentd-ask /usr/local/bin/
+COPY --from=builder /app/target/release/agentd-notify /usr/local/bin/
+COPY --from=builder /app/target/release/agentd-orchestrator /usr/local/bin/
+COPY --from=builder /app/target/release/agentd-wrap /usr/local/bin/
+COPY --from=builder /app/target/release/agentd-hook /usr/local/bin/
+COPY --from=builder /app/target/release/agentd-monitor /usr/local/bin/
+COPY --from=builder /app/target/release/agent /usr/local/bin/
+
+# Switch to non-root user
+USER agentd
+
+# Set environment variables
+ENV RUST_LOG=info
+ENV LOG_FORMAT=json
+
+# Expose service ports
+# Ask: 17001, Hook: 17002, Monitor: 17003, Notify: 17004, Wrap: 17005, Orchestrator: 17006
+EXPOSE 17001 17002 17003 17004 17005 17006
+
+# Default command - this is overridden in docker-compose
+CMD ["echo", "agentd services built successfully. Use docker-compose to run services."]
diff --git a/README.md b/README.md
@@ -296,6 +296,124 @@ cargo run -p cli -- orchestrator list-agents
 cargo run -p cli -- apply .agentd/
 ```
 
+## Docker Support
+
+agentd provides Docker support for simplified development setup, CI testing, and deployment to cloud environments.
+
+### Prerequisites
+
+- Docker 20.10+
+- Docker Compose 2.0+
+
+### Quick Start
+
+```bash
+# Build the Docker image
+docker build -t agentd:latest .
+
+# Start all services
+docker-compose up -d
+
+# Check service status
+docker-compose ps
+
+# View logs
+docker-compose logs -f
+
+# Stop all services
+docker-compose down
+```
+
+### Service Ports
+
+| Service | Container Port | Host Port | Description |
+|---------|---------------|-----------|-------------|
+| ask | 17001 | 17001 | Interactive question service |
+| hook | 17002 | 17002 | Shell hook integration |
+| monitor | 17003 | 17003 | System monitoring |
+| notify | 17004 | 17004 | Notification service |
+| wrap | 17005 | 17005 | Tmux session management |
+| orchestrator | 17006 | 17006 | Agent orchestration |
+
+### Using the CLI with Docker
+
+```bash
+# Use the CLI to interact with Docker services
+export ORCHESTRATOR_SERVICE_URL=http://localhost:17006
+agent status
+agent orchestrator list-agents
+agent apply .agentd/
+```
+
+### Development Mode
+
+For development with hot reload on code changes:
+
+```bash
+# Start with development override
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml up --watch
+
+# Or rebuild on changes
+docker-compose -f docker-compose.yml -f docker-compose.dev.yml build --no-cache
+```
+
+### Persistent Data
+
+SQLite databases are stored in named volumes:
+- `agentd-notify-data` - Notification service database
+- `agentd-orchestrator-data` - Orchestrator service database
+
+To remove persistent data:
+```bash
+docker-compose down -v
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RUST_LOG` | Logging level | `info` |
+| `LOG_FORMAT` | Set to `json` for structured logging | `json` (in Docker) |
+| `PORT` | Service port (per-service) | See table above |
+| `NOTIFY_SERVICE_URL` | Notification service URL | `http://notify:17004` |
+| `WRAP_SERVICE_URL` | Wrap service URL | `http://wrap:17005` |
+| `ORCHESTRATOR_SERVICE_URL` | Orchestrator URL for CLI | `http://localhost:17006` |
+
+### Health Checks
+
+All services expose `/health` endpoints for health checking:
+
+```bash
+# Check individual service health
+curl http://localhost:17006/health
+
+# Check all services via CLI
+agent status
+```
+
+### Prometheus Metrics
+
+All services expose `/metrics` endpoints for Prometheus scraping:
+
+```bash
+curl http://localhost:17006/metrics
+```
+
+### Troubleshooting
+
+```bash
+# View service logs
+docker-compose logs orchestrator
+docker-compose logs -f notify  # Follow logs
+
+# Restart a service
+docker-compose restart orchestrator
+
+# Rebuild and restart
+docker-compose build --no-cache
+docker-compose up -d --force-recreate
+```
+
 ## Configuration
 
 For the complete configuration reference including all environment variables, data storage paths, and plist/systemd customization, see the **[Configuration Guide](docs/public/configuration.md)**.

diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
@@ -0,0 +1,139 @@
+# Docker Compose development override for agentd services
+#
+# This override file provides development-friendly configurations:
+# - Debug logging
+# - Source code volume mounts for hot reload
+# - Development ports exposed
+#
+# Usage:
+#   docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
+#   docker-compose -f docker-compose.yml -f docker-compose.dev.yml build --no-cache
+#   docker-compose -f docker-compose.yml -f docker-compose.dev.yml logs -f
+
+services:
+  # ===========================================================================
+  # Notification Service (Dev)
+  # ===========================================================================
+  notify:
+    environment:
+      - RUST_LOG=debug
+      - LOG_FORMAT=json
+      - PORT=17004
+    volumes:
+      - ./crates/notify:/app/crates/notify:ro
+      - ./crates/common:/app/crates/common:ro
+    develop:
+      watch:
+        - action: rebuild
+          path: crates/notify
+          ignore:
+            - target/
+        - action: rebuild
+          path: crates/common
+
+  # ===========================================================================
+  # Ask Service (Dev)
+  # ===========================================================================
+  ask:
+    environment:
+      - RUST_LOG=debug
+      - LOG_FORMAT=json
+      - PORT=17001
+      - NOTIFY_SERVICE_URL=http://notify:17004
+    volumes:
+      - ./crates/ask:/app/crates/ask:ro
+      - ./crates/common:/app/crates/common:ro
+    develop:
+      watch:
+        - action: rebuild
+          path: crates/ask
+          ignore:
+            - target/
+        - action: rebuild
+          path: crates/common
+
+  # ===========================================================================
+  # Wrap Service (Dev)
+  # ===========================================================================
+  wrap:
+    environment:
+      - RUST_LOG=debug
+      - LOG_FORMAT=json
+      - PORT=17005
+    volumes:
+      - ./crates/wrap:/app/crates/wrap:ro
+      - ./crates/common:/app/crates/common:ro
+    develop:
+      watch:
+        - action: rebuild
+          path: crates/wrap
+          ignore:
+            - target/
+        - action: rebuild
+          path: crates/common
+
+  # ===========================================================================
+  # Orchestrator Service (Dev)
+  # ===========================================================================
+  orchestrator:
+    environment:
+      - RUST_LOG=debug
+      - LOG_FORMAT=json
+      - PORT=17006
+      - WRAP_SERVICE_URL=http://wrap:17005
+    volumes:
+      - ./crates/orchestrator:/app/crates/orchestrator:ro
+      - ./crates/wrap:/app/crates/wrap:ro
+      - ./crates/common:/app/crates/common:ro
+    develop:
+      watch:
+        - action: rebuild
+          path: crates/orchestrator
+          ignore:
+            - target/
+        - action: rebuild
+          path: crates/wrap
+        - action: rebuild
+          path: crates/common
+
+  # ===========================================================================
+  # Hook Service (Dev)
+  # ===========================================================================
+  hook:
+    environment:
+      - RUST_LOG=debug
+      - LOG_FORMAT=json
+      - PORT=17002
+      - NOTIFY_SERVICE_URL=http://notify:17004
+    volumes:
+      - ./crates/hook:/app/crates/hook:ro
+      - ./crates/common:/app/crates/common:ro
+    develop:
+      watch:
+        - action: rebuild
+          path: crates/hook
+          ignore:
+            - target/
+        - action: rebuild
+          path: crates/common
+
+  # ===========================================================================
+  # Monitor Service (Dev)
+  # ===========================================================================
+  monitor:
+    environment:
+      - RUST_LOG=debug
+      - LOG_FORMAT=json
+      - PORT=17003
+      - NOTIFY_SERVICE_URL=http://notify:17004
+    volumes:
+      - ./crates/monitor:/app/crates/monitor:ro
+      - ./crates/common:/app/crates/common:ro
+    develop:
+      watch:
+        - action: rebuild
+          path: crates/monitor
+          ignore:
+            - target/
+        - action: rebuild
+          path: crates/common