Claude-Flow Docker Environment

A safe, isolated, and ephemeral Docker environment for running Claude Code and Claude-Flow.

Quick Start

1. Prerequisites

• Docker Desktop installed and running
• An Anthropic API key

2. Setup

# Run the setup script (creates .env, builds image)
./scripts/setup.sh

Or manually:

# Copy and edit environment file
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

# Build the Docker image
docker-compose build

3. Start

# Start and enter the container
./scripts/start.sh

Or manually:

docker-compose up -d
docker-compose exec claude-flow bash

4. Use Claude

Inside the container:

# Start Claude Code (interactive AI assistant)
claude

# Or use Claude-Flow for multi-agent orchestration
npx claude-flow --help
npx claude-flow hive-mind spawn "Build a REST API" --claude

Directory Structure

.
├── Dockerfile              # Container definition
├── docker-compose.yml      # Service configuration
├── .env                    # Your API key (create from .env.example)
├── .env.example            # Template for .env
├── workspace/              # Your project files (mounted into container)
├── data/                   # Persistent AI state
│   ├── .swarm/             # Claude-Flow memory database
│   └── .claude-flow/       # Session state and config
└── scripts/
    ├── setup.sh            # Initial setup
    ├── start.sh            # Start and enter container
    ├── stop.sh             # Stop container
    └── reset.sh            # Full reset (clears data)

Common Operations

Task	Command
Start environment	./scripts/start.sh
Stop environment	./scripts/stop.sh
Full reset	./scripts/reset.sh
View logs	docker-compose logs -f
Rebuild image	docker-compose build --no-cache

What's Isolated?

• AI agents run inside the container as non-root user claude
• Only ./workspace/ and ./data/ are shared with your host
• No access to your host filesystem, network services, or other containers
• Resource limits can be added (see Advanced section)

Advanced Configuration

Add Resource Limits

Edit docker-compose.yml:

services:
  claude-flow:
    # ... existing config ...
    deploy:
      resources:
        limits:
          cpus: '4'
          memory: 8G
        reservations:
          cpus: '2'
          memory: 4G

Persist npm Cache

Add to volumes in docker-compose.yml:

volumes:
  - npm-cache:/home/claude/.npm

# At bottom of file:
volumes:
  npm-cache:

Troubleshooting

"Permission denied" on mounted volumes

On macOS, if you see permission errors:

# Fix ownership of data directories
sudo chown -R $(id -u):$(id -g) ./data ./workspace

Container won't start

# Check logs
docker-compose logs

# Rebuild from scratch
docker-compose down -v
docker-compose build --no-cache
docker-compose up -d

API key not working

Verify your .env file:

cat .env
# Should show: ANTHROPIC_API_KEY=sk-ant-...

Security Notes

• Never commit .env to version control
• The container runs as non-root user for security
• Use Infisical for secrets management (see below)
• Review ./workspace/ contents before committing to git

Future Improvements

• Secrets management integration (Infisical)
• Kubernetes deployment manifests
• CI/CD pipeline examples
• Multi-container setups (with databases, etc.)

License

This project is licensed under the MIT License - see the LICENSE file for details.