Podman Containers

Run cc-deck in a local Podman container with your source code mounted from the host. Changes are bidirectional: edits inside the container appear on your host, and vice versa.

Quick Start

Interactive (Foreground)

Start a Zellij session directly:

podman run -it --rm --name mydev \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  quay.io/cc-deck/cc-deck-demo:latest

The container’s default command starts Zellij with the cc-deck layout. When you exit Zellij, the container is removed automatically (--rm).

Background

Start the container in the background, then attach when ready:

podman run -d --name mydev \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  quay.io/cc-deck/cc-deck-demo:latest \
  sleep infinity

podman exec -it mydev zellij --layout cc-deck

Override the default command with sleep infinity so the container stays running when you detach from Zellij. See Reconnecting for how to reattach later.

For Vertex AI authentication, see Credentials.

Mounting Source Code

Mount your project directories so Claude Code works directly on your files:

podman run -d --name mydev \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v ~/projects/my-app:/home/dev/my-app \
  quay.io/cc-deck/cc-deck-demo:latest

Multiple projects can be mounted simultaneously:

podman run -d --name mydev \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v ~/projects/frontend:/home/dev/frontend \
  -v ~/projects/backend:/home/dev/backend \
  quay.io/cc-deck/cc-deck-demo:latest

Each project gets its own Claude Code session and the sidebar tracks them all.

Persistent State

To preserve Zellij sessions, Claude Code history, and snapshots across container restarts, mount a named volume for the home directory:

podman run -d --name mydev \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -v mydev-home:/home/dev \
  -v ~/projects/my-app:/home/dev/my-app \
  quay.io/cc-deck/cc-deck-demo:latest

The named volume mydev-home persists even when the container is removed.

When mounting a volume on /home/dev, the container’s default configuration files (.zshrc, .config/zellij/) are replaced by the volume contents. On the first run, these files are populated from the image. On subsequent runs, the volume contents take precedence.

Reconnecting

The container runs in the background. Reconnect anytime:

podman exec -it mydev zellij attach

Or start a fresh Zellij session:

podman exec -it mydev zellij --layout cc-deck

File Permissions

The container runs as dev (UID 1000). If your host files are owned by a different UID, you may see permission issues.

On Linux, use --userns=keep-id:

podman run -d --name mydev \
  --userns=keep-id \
  -v ~/projects/my-app:/home/dev/my-app \
  quay.io/cc-deck/cc-deck-demo:latest

On macOS, the Podman VM handles most file permissions automatically. For gcloud credentials, use Podman secrets instead of volume mounts to avoid UID mapping issues. See Podman with gcloud Credentials for details.

Port Forwarding

If your container runs MCP servers or services that need to be reachable from the host:

podman run -d --name mydev \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -p 8000:8000 -p 9000:9000 \
  quay.io/cc-deck/cc-deck-demo:latest

Networking

To reach services running on the host from inside the container, use host.containers.internal (Podman 4.7+) or --network=host.

For container-to-container communication, create a Podman network:

podman network create devnet

podman run -d --name postgres --network devnet \
  -e POSTGRES_PASSWORD=dev postgres:16

podman run -d --name mydev --network devnet \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  quay.io/cc-deck/cc-deck-demo:latest

Inside mydev, PostgreSQL is reachable at postgres:5432.

SSH Agent Forwarding

To use your host SSH keys for git operations inside the container:

podman run -d --name mydev \
  -v $SSH_AUTH_SOCK:/ssh-agent:ro \
  -e SSH_AUTH_SOCK=/ssh-agent \
  quay.io/cc-deck/cc-deck-demo:latest

Resource Limits

Set memory and CPU limits to prevent runaway processes:

podman run -d --name mydev \
  --memory 8g --cpus 4 \
  quay.io/cc-deck/cc-deck-demo:latest

Claude Code requires at least 4 GB of RAM.

Podman Compose

For a full development environment with multiple services:

services:
  cc-deck:
    image: quay.io/cc-deck/cc-deck-demo:latest
    environment:
      - ANTHROPIC_API_KEY
    volumes:
      - ~/projects:/home/dev/projects
      - cc-state:/home/dev
    ports:
      - "8000:8000"

  postgres:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=dev

volumes:
  cc-state:

podman compose up -d
podman exec -it cc-deck zellij --layout cc-deck

Lifecycle

podman stop mydev      # Stop the container
podman start mydev     # Restart later
podman rm mydev        # Remove permanently