hal-9000 - Containerized Claude
Run Claude Code in isolated Docker containers with Docker-in-Docker orchestration, persistent storage, and full marketplace support.
Quick Start
# Install hal-9000
curl -fsSL https://raw.githubusercontent.com/Hellblazer/hal-9000/main/install-hal-9000.sh | bash
# REQUIRED: Authenticate before first use (one of the following)
# Option 1: Login with Claude subscription (recommended)
hal-9000 /login
# Note: When the OAuth URL appears, copy ALL lines of the URL
# Or press 'c' to copy to clipboard
# Option 2: Use file-based API key
mkdir -p ~/.hal9000/secrets
echo "sk-ant-api03-..." > ~/.hal9000/secrets/anthropic_key
chmod 400 ~/.hal9000/secrets/anthropic_key
# Launch Claude in current directory
hal-9000
Important: Authentication is REQUIRED before first use. Auth is stored in a shared Docker volume - login once, use everywhere.
Security
hal-9000 v2.1.0 includes comprehensive security hardening:
Authentication & Secrets (v2.1.0):
- File-based secrets only - Environment variable API keys are rejected for security
- Docker secrets integration - Secure credential injection
- Subscription login - Recommended:
hal-9000 /login
Defense in Depth:
- Seccomp syscall filtering - Blocks mount, ptrace, kernel module loading
- Per-user volume isolation - Prevents cross-user data access
- Security audit logging - Structured JSON logs with hashed credentials
- Extended hooks - Protection for Grep, NotebookEdit, file_access operations
Supply Chain Hardening:
- SHA256 digest pinning - All Docker base images pinned
- Signature verification - Critical scripts verified before execution
Read detailed security summary →
Marketplace Support
hal-9000 supports Claude Code plugins. Install agents, commands, and tools that persist across all sessions:
# Add a marketplace (use owner/repo format)
hal-9000 plugin marketplace add anthropics/skills
# Install a plugin
hal-9000 plugin install document-skills
# List installed plugins
hal-9000 plugin list
All installations are stored in a persistent Docker volume shared by all workers.
Note: Foundation MCP servers (ChromaDB, Memory Bank) require one-time setup via scripts/setup-foundation-mcp.sh on your host machine. Sequential Thinking is pre-installed in all workers. See Foundation MCP Servers Setup below.
What's Included
Every container includes:
- Claude CLI - Native binary, auto-updates
- Node.js 20 LTS - For npm-based tools and marketplace plugins
- Python + uv - For Python-based tools and marketplace plugins
- Persistent plugins and settings - Installed via marketplace, survive across sessions
Foundation MCP Servers (host-level, one-time setup):
- ChromaDB - Vector database for semantic search and embeddings
- Memory Bank - Cross-session persistent memory shared across all workers
- Sequential Thinking - Step-by-step reasoning (pre-installed in all workers)
MCP server configurations persist across all sessions. Register once, use everywhere.
Foundation MCP Servers
What are Foundation MCP Servers?
MCP (Model Context Protocol) servers extend Claude's capabilities by providing tools and knowledge access. hal-9000 includes three core Foundation MCP servers:
- ChromaDB - Vector database for semantic search
- Memory Bank - Cross-session persistent memory
- Sequential Thinking - Step-by-step reasoning
These are set up once at the host level via setup-foundation-mcp.sh and automatically available to all workers.
Foundation MCP Servers Setup
Foundation MCP Servers run at the host level, accessible to all workers. One-time setup after installing hal-9000:
~/.hal9000/scripts/setup-foundation-mcp.sh
This deploys:
- ChromaDB (port 8000) - Vector database for semantic search
- Memory Bank - Persistent storage for cross-session context
- Sequential Thinking - Step-by-step reasoning (pre-installed in workers)
Check status and manage services:
~/.hal9000/scripts/setup-foundation-mcp.sh --status # Check status
~/.hal9000/scripts/setup-foundation-mcp.sh --logs # View logs
See Foundation MCP Servers documentation for advanced configuration and troubleshooting.
Usage
Basic
