HolyClaude

Runs the official Anthropic Claude Code CLI inside a Docker container with pre-configured OAuth flow support for Claude Max/Pro plans and direct API key authentication. The container bootstraps the Claude Code environment during startup via s6-overlay service supervision, handling credential injection through environment variables and persistent configuration files mounted at runtime. This eliminates manual CLI setup, dependency resolution, and authentication friction while maintaining full feature parity with the native CLI.

Exposes a CloudCLI web interface running on port 3001 that provides HTTP/WebSocket access to the containerized AI agents (Claude Code and alternative CLIs). The web server is managed by s6-overlay as a supervised service with automatic restart on failure, and traffic is routed through the container's network stack. This enables browser-based interaction with AI agents without direct CLI access, supporting real-time streaming responses and multi-user concurrent sessions.

Provides a production-ready docker-compose.yaml template that orchestrates the HolyClaude container with pre-configured volume mounts (workspace, configuration), network exposure (port 3001 for web UI), shared memory allocation (shm_size: 2g for headless browser), and resource limits. The compose file includes environment variable references (.env file) for credentials and identity mapping (PUID/PGID), enabling users to deploy HolyClaude with a single docker-compose up command without manual configuration. The template handles common Docker pitfalls (shared memory exhaustion, permission mismatches, port conflicts) automatically.

Implements a multi-stage bootstrap system that runs at container startup to initialize services, validate configuration, set up user identity (UID/GID), and prepare the environment for AI agent execution. The bootstrap process uses shell scripts executed before s6-overlay starts supervised services, performing tasks like creating workspace directories, validating API keys, initializing Claude Code settings, and installing on-demand packages (Slim variant). This ensures the container reaches a ready state without manual post-startup configuration, enabling immediate use after docker-compose up.

Enables AI agents (Claude Code, alternative CLIs) to access the full workspace directory and inject codebase context into prompts, allowing models to generate code that is aware of existing project structure, dependencies, and coding patterns. The workspace is mounted as a Docker volume and accessible to all AI CLIs via a shared directory path. AI agents can read project files, analyze imports and dependencies, and generate code that integrates seamlessly with the existing codebase. This differs from stateless code generation by providing architectural context and reducing the need for manual context specification.

Bundles 7 distinct AI CLI tools (Claude Code, Gemini CLI, OpenAI Codex, Cursor, TaskMaster, Junie, OpenCode) into a single container with unified environment variable configuration and shared tool dependencies. Each CLI is pre-installed with its runtime dependencies and configured to use a common workspace directory. The container's bootstrap system detects which CLIs are enabled via environment variables and initializes only the necessary services, reducing startup time and memory overhead for users who only need a subset of providers.

Provides a pre-configured headless browser environment combining Chromium, Xvfb (X11 virtual framebuffer), and Playwright for automated web interaction, screenshot capture, and testing. The container allocates shared memory (shm_size: 2g) to prevent Chromium crashes during concurrent browser operations, and Playwright is pre-installed with bindings for Node.js. The browser stack is managed by s6-overlay as a supervised service, enabling AI agents to programmatically navigate websites, extract data, and generate visual artifacts without requiring a display server.

Implements a volume-based persistence strategy using Docker named volumes and bind mounts to preserve Claude Code settings, AI CLI configurations, workspace files, and memory state across container lifecycle events. Configuration files (e.g., Claude settings, .env credentials) are mounted at container startup, and the bootstrap system initializes user identity (UID/GID) to match the host to prevent permission mismatches. SQLite databases used by AI CLIs are stored on local volumes rather than network-attached storage (NAS) to avoid locking issues, and a dedicated workspace directory persists generated code artifacts.

Uses s6-overlay as the container's PID 1 process manager to supervise multiple services (Claude Code CLI, web UI, headless browser, notification daemon) with automatic restart on failure and coordinated graceful shutdown. Each service is defined as an s6 service directory with run scripts and optional finish scripts for cleanup. When the container receives a SIGTERM signal, s6 orchestrates shutdown of all supervised services in dependency order, preventing orphaned processes and ensuring data consistency. This replaces the typical single-process Docker pattern with a robust multi-service architecture.

Integrates Apprise (a unified notification library) to send alerts and status updates to 100+ services including Discord, Telegram, Slack, email, webhooks, and custom endpoints. The notify.py script is invoked by AI agents or container services to dispatch notifications with configurable templates and delivery channels. Apprise abstracts provider-specific API differences, allowing a single notification call to fan out to multiple channels simultaneously. Configuration is managed via environment variables (APPRISE_URLS) or configuration files, enabling flexible notification routing without code changes.

Enables integration with Ollama (a local LLM runtime) to run open-source models (Llama 2, Mistral, etc.) locally or connect to cloud-hosted Ollama instances. The container can be configured to use Ollama as a fallback provider when Anthropic/OpenAI APIs are unavailable or rate-limited, or as a primary provider for privacy-sensitive workloads. Configuration is managed via OLLAMA_BASE_URL environment variable, and AI CLIs are configured to route requests to the Ollama endpoint. This enables cost-effective, privacy-preserving AI coding without external API dependencies.

Distributes HolyClaude in two Docker image variants: Full (~3GB, includes all 7 AI CLIs and 50+ dev tools pre-installed) and Slim (~1.5GB, core tools only with on-demand installation). Users select the variant via docker-compose image tag (latest for Full, slim for Slim). The Slim variant uses a package manager (apt, npm, pip) to install additional tools at container startup if requested via environment variables, reducing initial image size and download time while maintaining flexibility. This enables users to optimize for startup speed (Full) or image size (Slim) based on their deployment constraints.

Implements configuration management via environment variables and .env files, enabling users to customize Claude Code settings, AI provider credentials, notification endpoints, and container behavior without modifying Dockerfile or docker-compose.yaml. The bootstrap system reads .env files at container startup and injects variables into supervised services. Common variables include ANTHROPIC_API_KEY, OLLAMA_BASE_URL, APPRISE_URLS, PUID/PGID for identity mapping, and feature flags for enabling/disabling specific services. This enables reproducible, version-controlled configuration across deployments.