Imperium

A multi-container development environment with Claude Code integration.

Features

• Identical pods - all containers are the same with Claude Code
• Scalable - spin up as many pods as you need
• Globally networked - pods across different directories can communicate
• Shared proxy - all external traffic routed through single Squid proxy
• Persistent volumes - each pod has its own command history and Claude config

Prerequisites

• Docker runtime (Docker Desktop, OrbStack, or Colima)
• For VS Code: Dev Containers extension

Quick Start

Quick Start

# Install globally
make install

# Use in any project
cd ~/my-project
imperium setup    # Writes templates + builds image (one command!)
imperium up       # Start pods

Option 1: VS Code / Cursor (Recommended)

1. Install the Dev Containers extension
2. Copy imperium files to your project
3. Open project in VS Code
4. Cmd+Shift+P → "Reopen in Container"

Option 2: Terminal

# Use in any project (after `make install`)
cd ~/my-project
imperium setup    # Writes templates + builds image
imperium up       # Start pods
imperium ps       # List all pods
imperium exec 1   # Shell into pod #1

Management Commands

imperium setup           # Initialize + build shared image
imperium up              # Start containers
imperium down            # Stop containers (this directory)
imperium ps              # List all pods
imperium exec [n]        # Shell into pod n (default: 1)
imperium logs            # Show pod logs
imperium clean           # Remove containers + volumes (this directory)
imperium clean-all       # Remove ALL pods + volumes + network
imperium nuke            # Remove EVERYTHING (including images)

Structure

imperium/
├── cmd/
│   └── imperium/
│       └── main.go                 # CLI implementation (Cobra)
├── internal/
│   └── templates/
│       ├── Dockerfile              # Pod container with Claude Code
│       ├── docker-compose.yml      # Multi-container orchestration
│       ├── devcontainer.json       # VS Code devcontainer config
│       ├── squid.conf              # Proxy configuration
│       ├── .gitignore              # Generated .gitignore template
│       └── templates.go            # Embedded templates (go:embed)
├── bin/
│   └── imperium                    # Compiled binary (after build)
├── Makefile                        # Build/install commands
├── go.mod                          # Go module definition
└── README.md

Generated in your project after imperium setup:

your-project/
└── .devcontainer/
    ├── Dockerfile              # From templates
    ├── docker-compose.yml      # From templates
    └── devcontainer.json       # From templates

Architecture

• proxy service: Shared Squid proxy for all external traffic (single instance)
• pod service: All pods are identical with Claude Code (scalable)
• imperium-global: Shared bridge network across all directories
• Pods can communicate using "pod" as hostname (round-robin DNS)
• All pod external traffic → routed through shared proxy
• Pod-to-pod traffic → direct (bypasses proxy)

Cross-Directory Communication

Run imperium in multiple directories - all pods share one network:

# Terminal 1 - Directory A
cd ~/project-a
imperium setup    # Only needed once
imperium up       # Start pods in project-a

# Terminal 2 - Directory B
cd ~/project-b
imperium setup    # Only needed once (reuses same image)
imperium up       # Start pods in project-b
imperium exec 1   # Shell into project-b pod

# Inside project-b pod:
ping imperium-proxy               # Reaches shared proxy
curl http://project-a-imperium-pod-1:8080  # Talk to project-a pods

Note: Docker Compose uses directory name as project name, so containers are named {dir}-imperium-pod-{n}.