diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..7861af7
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,43 @@
+# Build artifacts
+target/
+lib/ratatui-core/
+
+# Git
+.git/
+.gitignore
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Container build directory contents (avoid recursion)
+container/workspace/
+container/config/
+container/data/
+
+# Development files
+.cargo/config.toml
+
+# Documentation and non-essential files
+*.md
+!README.md
+LICENSE
+
+# Logs and temporary files
+*.log
+*.tmp
+.codey/
+
+# Environment files (may contain secrets)
+.env
+.env.*
+
+# macOS
+.DS_Store
+
+# Test fixtures and snapshots
+tests/
+snapshots/
diff --git a/container/Dockerfile b/container/Dockerfile
new file mode 100644
index 0000000..81b7c35
--- /dev/null
+++ b/container/Dockerfile
@@ -0,0 +1,71 @@
+# Codey Docker Container
+# Multi-stage build for minimal runtime image
+
+# =============================================================================
+# Builder Stage - Compile codey
+# =============================================================================
+FROM rust:1.83-slim-bookworm AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libssl-dev \
+    pkg-config \
+    git \
+    make \
+    patch \
+    perl \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up the build environment
+WORKDIR /build
+
+# Copy the source code
+COPY . .
+
+# Apply SIMD patches and build
+RUN make patch && make release
+
+# =============================================================================
+# Runtime Stage - Debian with Chromium
+# =============================================================================
+FROM debian:bookworm-slim
+
+# Install runtime dependencies
+# - chromium: for web content extraction (fetch_html tool)
+# - bash: for shell tool execution
+# - git: commonly needed for code operations
+# - neovim: optional IDE integration
+# - ca-certificates: for HTTPS requests
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    chromium \
+    bash \
+    git \
+    neovim \
+    ca-certificates \
+    curl \
+    openssh-client \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create non-root user for security
+RUN useradd -m -d /home/codey -s /bin/bash codey
+
+# Set up directories
+RUN mkdir -p /home/codey/.config/codey /work && \
+    chown -R codey:codey /home/codey /work
+
+# Copy the compiled binary from builder
+COPY --from=builder /build/target/release/codey /usr/local/bin/codey
+RUN chmod +x /usr/local/bin/codey
+
+# Set environment variables
+ENV HOME=/home/codey
+ENV CHROME_BIN=/usr/bin/chromium
+ENV CHROMIUM_FLAGS="--no-sandbox --headless --disable-gpu --disable-dev-shm-usage"
+
+# Switch to non-root user
+USER codey
+WORKDIR /work
+
+# Default entrypoint
+ENTRYPOINT ["codey"]
diff --git a/container/README.md b/container/README.md
new file mode 100644
index 0000000..4e95629
--- /dev/null
+++ b/container/README.md
@@ -0,0 +1,243 @@
+# Codey Docker Container
+
+Run codey in a containerized environment with all dependencies included.
+
+## Quick Start
+
+### 1. Set your API key
+
+```bash
+export ANTHROPIC_API_KEY=your-api-key-here
+```
+
+### 2. Build and run
+
+```bash
+cd container
+
+# Build the image
+docker compose build
+
+# Run interactively
+docker compose run --rm codey
+```
+
+## Usage
+
+### Running with Docker Compose (recommended)
+
+```bash
+# Start an interactive session
+docker compose run --rm codey
+
+# Continue a previous session
+docker compose run --rm codey --continue
+
+# Specify a model
+docker compose run --rm codey --model claude-sonnet-4-20250514
+```
+
+### Running with Docker directly
+
+```bash
+# Build the image
+docker build -t codey:latest -f container/Dockerfile .
+
+# Run interactively
+docker run -it --rm \
+  -e ANTHROPIC_API_KEY \
+  -v $(pwd):/work \
+  -v ~/.config/codey:/home/codey/.config/codey \
+  --shm-size=2gb \
+  codey:latest
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `ANTHROPIC_API_KEY` | Anthropic API key | Yes |
+| `OPENROUTER_API_KEY` | OpenRouter API key (alternative) | No |
+| `BRAVE_API_KEY` | Brave Search API key for web search | No |
+| `TZ` | Timezone (e.g., `America/New_York`) | No |
+| `CODEY_WORK_DIR` | Host path to mount as working directory | No |
+| `CODEY_CONFIG_DIR` | Host path for codey configuration | No |
+| `CODEY_DATA_DIR` | Host path for session transcripts | No |
+
+### Volume Mounts
+
+The container uses several volume mounts:
+
+- `/work` - Your working directory (code to work on)
+- `/home/codey/.config/codey` - Codey configuration
+- `/work/.codey` - Session transcripts for `--continue` feature
+- `/home/codey/.gitconfig` - Git configuration (read-only)
+
+### Custom Configuration
+
+Create a config file at `./config/config.toml`:
+
+```toml
+# Model configuration
+model = "claude-sonnet-4-20250514"
+
+# Chrome executable (already set in container)
+# chrome_executable = "/usr/bin/chromium-browser"
+
+# Auto-approve patterns (use with caution)
+# auto_approve = ["Read*", "Glob*"]
+```
+
+## Building for Different Architectures
+
+### Build for ARM64 (Apple Silicon, etc.)
+
+Use Docker buildx for multi-arch builds:
+
+```bash
+docker buildx build --platform linux/amd64,linux/arm64 -t codey:latest -f container/Dockerfile .
+```
+
+The Debian-based image supports both amd64 and arm64 natively.
+
+## Included Tools
+
+The container includes:
+
+- **Chromium** - Headless browser for web content extraction
+- **Git** - Version control operations
+- **Bash** - Shell command execution
+- **Neovim** - Optional IDE integration
+
+## Extending the Image
+
+You can create custom images based on codey for project-specific needs.
+
+### Adding Custom Tools
+
+```dockerfile
+FROM codey:latest
+
+USER root
+
+# Install additional tools
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    python3 \
+    python3-pip \
+    nodejs \
+    npm \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install a specific CLI tool
+RUN npm install -g typescript
+
+USER codey
+```
+
+### Adding a Project System Prompt
+
+```dockerfile
+FROM codey:latest
+
+# Add a project-specific system prompt
+COPY SYSTEM.md /home/codey/.config/codey/SYSTEM.md
+```
+
+Your `SYSTEM.md` might contain:
+
+```markdown
+You are working on the Acme project, a REST API built with Rust and Actix-web.
+
+Key conventions:
+- All handlers go in src/handlers/
+- Use the existing error types in src/errors.rs
+- Run `cargo test` before committing
+```
+
+### Full Example: Custom Project Image
+
+```dockerfile
+FROM codey:latest
+
+USER root
+
+# Install project-specific dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    postgresql-client \
+    redis-tools \
+    && rm -rf /var/lib/apt/lists/*
+
+# Add custom scripts
+COPY --chmod=755 scripts/deploy.sh /usr/local/bin/deploy
+
+USER codey
+
+# Add project system prompt
+COPY --chown=codey:codey SYSTEM.md /home/codey/.config/codey/SYSTEM.md
+
+# Add project config
+COPY --chown=codey:codey config.toml /home/codey/.config/codey/config.toml
+```
+
+Build and use:
+
+```bash
+docker build -t my-project-codey .
+docker run -it --rm -e ANTHROPIC_API_KEY -v $(pwd):/work my-project-codey
+```
+
+## Troubleshooting
+
+### Chromium fails to start
+
+Ensure adequate shared memory:
+
+```bash
+docker run --shm-size=2gb ...
+```
+
+### Permission denied errors
+
+The container runs as non-root user `codey`. Ensure mounted volumes have appropriate permissions:
+
+```bash
+# Fix ownership if needed
+sudo chown -R $(id -u):$(id -g) ./workspace ./config ./data
+```
+
+### Session not persisting
+
+Ensure the data volume is properly mounted:
+
+```bash
+docker compose run --rm \
+  -v $(pwd)/data:/work/.codey \
+  codey --continue
+```
+
+## Security Notes
+
+- The container runs as a non-root user by default
+- Unnecessary capabilities are dropped
+- Consider using read-only mounts where possible
+- Never expose the container's ports to the network
+
+## Development
+
+To rebuild after code changes:
+
+```bash
+docker compose build --no-cache
+```
+
+To run with local source mounted (for development):
+
+```bash
+docker run -it --rm \
+  -v $(pwd):/build \
+  -w /build \
+  rust:1.83-slim-bookworm \
+  sh -c "apt-get update && apt-get install -y libssl-dev pkg-config git make patch && make build"
+```
diff --git a/container/docker-compose.yml b/container/docker-compose.yml
new file mode 100644
index 0000000..2e4e728
--- /dev/null
+++ b/container/docker-compose.yml
@@ -0,0 +1,63 @@
+services:
+  codey:
+    build:
+      context: ..
+      dockerfile: container/Dockerfile
+    image: codey:latest
+    container_name: codey
+
+    # Interactive terminal support for TUI
+    stdin_open: true
+    tty: true
+
+    # Environment variables
+    environment:
+      # Required: Anthropic API key for AI functionality
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+
+      # Optional: Alternative providers
+      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY:-}
+
+      # Optional: Brave Search API key for web search
+      - BRAVE_API_KEY=${BRAVE_API_KEY:-}
+
+      # Chromium configuration for headless browser
+      - CHROME_BIN=/usr/bin/chromium
+
+      # Timezone (optional)
+      - TZ=${TZ:-UTC}
+
+    # Volume mounts
+    volumes:
+      # Mount your working directory (code to work on)
+      - ${CODEY_WORK_DIR:-./workspace}:/work
+
+      # Persist codey configuration
+      - ${CODEY_CONFIG_DIR:-./config}:/home/codey/.config/codey
+
+      # Persist session transcripts (for --continue feature)
+      - ${CODEY_DATA_DIR:-./data}:/work/.codey
+
+      # Git configuration (for commits)
+      - ${HOME}/.gitconfig:/home/codey/.gitconfig:ro
+
+      # SSH keys for git operations (optional)
+      # - ${HOME}/.ssh:/home/codey/.ssh:ro
+
+    # Security: drop unnecessary capabilities
+    cap_drop:
+      - ALL
+    cap_add:
+      - CHOWN
+      - SETUID
+      - SETGID
+
+    # Shared memory size for Chromium
+    shm_size: '2gb'
+
+    # Resource limits (optional, adjust as needed)
+    # deploy:
+    #   resources:
+    #     limits:
+    #       memory: 4G
+    #       cpus: '2'
diff --git a/container/run.sh b/container/run.sh
new file mode 100755
index 0000000..359e7d2
--- /dev/null
+++ b/container/run.sh
@@ -0,0 +1,31 @@
+#!/bin/bash
+# Convenience script to run codey in Docker
+#
+# Usage:
+#   ./run.sh                    # Start new session
+#   ./run.sh --continue         # Continue previous session
+#   ./run.sh --model opus       # Use specific model
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Check for API key
+if [ -z "$ANTHROPIC_API_KEY" ]; then
+    echo "Error: ANTHROPIC_API_KEY environment variable is not set"
+    echo "Export it with: export ANTHROPIC_API_KEY=your-key-here"
+    exit 1
+fi
+
+# Create local directories if they don't exist
+mkdir -p workspace config data
+
+# Build if image doesn't exist
+if ! docker image inspect codey:latest &>/dev/null; then
+    echo "Building codey image..."
+    docker compose build
+fi
+
+# Run codey with all arguments passed through
+exec docker compose run --rm codey "$@"