Docker Compose CLI for Kubernetes - Run your docker-compose.yaml on Kubernetes without learning Kubernetes.

Kappal (கப்பல்) means "ship" in Tamil. The name honors V.O. Chidambaram Pillai, known as Kappalottiya Tamizhan ("The Tamil Helmsman") - a freedom fighter who founded India's first indigenous shipping company.

The nautical theme connects to Kubernetes itself: Kubernetes (κυβερνήτης) is Greek for "helmsman" or "pilot" - the person who steers a ship. Kappal steers your containers on the Kubernetes seas, so you don't have to learn navigation.

Kappal lets you use familiar Docker Compose commands while running your services on Kubernetes (K3s). Users never see kubectl, YAML manifests, or Kubernetes concepts - just the same up, down, ps, logs, and exec commands they already know.

kappal up -d                    # Start services
kappal ps                       # List services
kappal logs api                 # View logs
kappal exec web sh              # Shell into service
kappal down                     # Stop services

• Zero Kubernetes Knowledge Required - Use Docker Compose syntax, get Kubernetes benefits
• Persistent Volumes - Named volumes survive restarts (kappal down + kappal up)
• Service Discovery - Services find each other by name (just like Docker Compose)
• Secrets & Configs - Mount secrets and config files the Compose way
• Scaling - Use deploy.replicas to scale services
• Network Isolation - Define networks to isolate service groups
• UDP Support - Full protocol support including UDP ports

Only Docker is required. Kappal handles everything else automatically.

# 1. Install Docker (if not already installed)
curl -fsSL https://get.docker.com | sh

# 2. Pull kappal image
docker pull ghcr.io/sandys/kappal:latest

# 3. Add alias (for current session)
alias kappal='docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "$(pwd):/project" -w /project --network host ghcr.io/sandys/kappal:latest'

# Or save permanently to ~/.bashrc or ~/.zshrc
echo "alias kappal='docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v \"\$(pwd):/project\" -w /project --network host ghcr.io/sandys/kappal:latest'" >> ~/.bashrc
source ~/.bashrc

That's it. You're ready to use Kappal.

# Navigate to your project with docker-compose.yaml
cd /path/to/your/project

# First-time setup (required once per project)
kappal --setup

# Start services in detached mode
kappal up -d

# Check status
kappal ps

# View logs
kappal logs

# View logs for specific service
kappal logs api

# Shell into a service
kappal exec web sh

# Stop everything
kappal down

# Stop and remove volumes
kappal down -v

If your docker-compose.yml is in a subdirectory (e.g., deploy/docker-compose/), use the -f flag:

# Project structure:
# myproject/
# ├── apps/
# ├── packages/
# └── deploy/
#     └── docker-compose/
#         └── docker-compose.yml

# Option 1: Use -f flag with relative path
kappal -f deploy/docker-compose/docker-compose.yml up

# Option 2: cd into the directory
cd deploy/docker-compose
kappal -f docker-compose.yml up

If your docker-compose.yml references parent directories (e.g., build: context: ../..), you need to mount from the project root and set the working directory:

# For monorepos, create a project-specific alias
alias kappal-myproject='docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -v "/path/to/project/root:/project" -w /project/path/to/compose/dir --network host ghcr.io/sandys/kappal:latest'

# Then use normally
kappal-myproject up --build

Kappal includes a skill file (skills/kappal/SKILL.md) that lets Claude Code and other AI coding agents deploy docker-compose projects to Kubernetes autonomously.

How it works: Claude reads the skill file and handles the full lifecycle — setup, build, deploy, logs, teardown — without the user needing to know kappal internals.

What the user says: Just tell Claude "deploy this with kappal" or "run this docker-compose in kappal" and it handles the rest.

Self-updating: The skill auto-fetches the latest version from GitHub at the start of each conversation, so it stays current with breaking changes and new features.

No other container orchestration tool offers native AI agent integration — docker compose, podman, and others require the user to know the CLI. Kappal works with AI agents out of the box.

docker-compose.yaml
        │
        ▼
┌───────────────────┐
│   compose-go     │  Parse compose file
└───────────────────┘
        │
        ▼
┌───────────────────┐
│   Transformer    │  Convert to K8s manifests
└───────────────────┘
        │
        ▼
┌───────────────────┐
│   K3s (Docker)   │  Lightweight Kubernetes
└───────────────────┘
        │
        ▼
    Your services running on Kubernetes!

Key Design Principles:

1. Users never see Kubernetes - All K8s concepts are hidden behind Compose semantics
2. Self-contained - K3s runs in Docker, no system installation needed
3. Persistent by default - Volumes survive down/up cycles (use -v to remove)
4. Standard tools - Uses compose-go (official parser), K3s, client-go

# Clone the repo
git clone https://github.com/kappal-app/kappal.git
cd kappal

# Build Docker image
make docker-build

# Run unit tests
make test

# Run conformance tests (all 8 must pass)
make conformance

# Run all lints
make lint-all

Kappal passes all 8 conformance tests based on the compose-spec:

• SimpleLifecycle - Basic up/down
• SimpleNetwork - Service-to-service DNS
• VolumeFile - Persistent volume data
• SecretFile - Secret mounting
• ConfigFile - Config file mounting
• UdpPort - UDP protocol support
• Scaling - Replica scaling
• DifferentNetworks - Network isolation

Q: Why not just use Kompose? A: Kompose converts Compose files to K8s manifests, but you still need to manage Kubernetes. Kappal hides K8s completely - same CLI experience as Docker Compose.

Q: Why K3s instead of kind/minikube? A: K3s is lightweight, fast to start, and includes essentials like ServiceLB and local-path-provisioner out of the box.

Q: Can I see the generated Kubernetes manifests? A: Yes, they're in .kappal/manifests/all.yaml (but you shouldn't need to).

Q: How do I debug issues? A: Use kappal logs <service> and kappal exec <service> sh. If you need deeper debugging, the kubeconfig is at .kappal/runtime/kubeconfig.yaml.

MIT