From hive
Guides Docker usage: debugging container failures, writing Dockerfiles, docker-compose for integration tests, image optimization, volumes, multi-stage builds, and deployments.
npx claudepluginhub tctinh/agent-hive --plugin hiveThis skill uses the workspace's default tool permissions.
Docker is a **platform for building, shipping, and running applications**, not just isolation.
Guides Docker containers, images, Compose orchestration, networking, volumes, debugging, production hardening, and commands for stable environments. Use for Dockerfiles, builds, runtime, logs, ports, security.
Provides Docker containerization patterns, best practices, multi-stage builds, Compose configs, networking, storage, security hardening, CI/CD workflows, and debugging techniques. Auto-activates on Dockerfiles, docker-compose files, or FROM/EXPOSE patterns.
Provides expert Docker guidance on container optimization, security hardening, multi-stage builds, orchestration patterns, and production deployments. Analyzes Dockerfiles, Compose files, and validates builds.
Share bugs, ideas, or general feedback.
Docker is a platform for building, shipping, and running applications, not just isolation.
Agents should think in containers: reproducible environments, declarative dependencies, isolated execution.
Core principle: Containers are not virtual machines. They share the kernel but isolate processes, filesystems, and networks.
Violating the letter of these guidelines is violating the spirit of containerization.
UNDERSTAND THE CONTAINER BEFORE DEBUGGING INSIDE IT
Before exec'ing into a container or adding debug commands:
Random debugging inside containers wastes time. Context first, then debug.
Use this skill when working with:
Use this ESPECIALLY when:
# Build once
docker build -t myapp:latest .
# Run many times
docker run --rm myapp:latest
docker run --rm -e DEBUG=true myapp:latest
Key insight: Changes inside containers are lost unless committed or volumes are used.
Mount host directories into containers for persistence and code sharing:
# Mount current directory to /app in container
docker run -v $(pwd):/app myapp:latest
# Hive worktrees are mounted automatically
# Your code edits (via Read/Write/editFiles tools) affect the host
# Container sees the same files at runtime
How Hive uses this: Worktree is mounted into container, so file tools work on host, bash commands run in container.
Minimize image size by using multiple FROM statements:
# Build stage (large, has compilers)
FROM node:22 AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install
COPY . .
RUN bun run build
# Runtime stage (small, production only)
FROM node:22-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
Result: Builder tools (TypeScript, bundlers) not included in final image.
Define multiple services in docker-compose.yml:
version: '3.8'
services:
db:
image: postgres:15
environment:
POSTGRES_PASSWORD: testpass
ports:
- "5432:5432"
api:
build: .
environment:
DATABASE_URL: postgres://db:5432/testdb
depends_on:
- db
ports:
- "3000:3000"
Run with: docker-compose up -d
Teardown with: docker-compose down
When to use host mode: Debugging network issues, accessing host services directly.
Problem: Container exits immediately, logs unclear.
Pattern:
docker run -it --entrypoint sh myapp:latest
ls /app
which node
cat /etc/os-release
node dist/index.js
Pattern:
docker-compose.test.yml# docker-compose.test.yml
services:
db:
image: postgres:15
environment:
POSTGRES_PASSWORD: test
test:
build: .
command: bun run test:integration
depends_on:
- db
environment:
DATABASE_URL: postgres://postgres:test@db:5432/testdb
docker-compose -f docker-compose.test.yml up --abort-on-container-exit
docker-compose -f docker-compose.test.yml down
Anti-pattern:
FROM node:22
WORKDIR /app
COPY . . # Copies everything (including node_modules, .git)
RUN bun install # Invalidates cache on any file change
CMD ["bun", "run", "start"]
Optimized:
FROM node:22-slim # Use slim variant
WORKDIR /app
# Copy dependency files first (cache layer)
COPY package.json bun.lockb ./
RUN bun install --production
# Copy source code (changes frequently)
COPY src ./src
COPY tsconfig.json ./
CMD ["bun", "run", "start"]
Add .dockerignore:
node_modules
.git
.env
*.log
dist
.DS_Store
Problem: Command fails with "not found" in container.
Pattern:
docker run -it myapp:latest which git
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
node:22 instead of node:22-slim).When sandbox mode is active (sandbox: 'docker' in config):
docker run --rm -v <worktree>:/workspace -w /workspace <image> sh -c "<command>"Workers are unaware — they issue normal bash commands, Hive handles containerization.
Some operations MUST run on host:
Pattern: Use HOST: prefix to escape sandbox:
HOST: git status
HOST: docker ps
If you need host access frequently: Report as blocked and ask user if sandbox should be disabled for this task.
Current (v1.2.0): Each command runs docker run --rm (ephemeral). State does NOT persist.
Example: npm install lodash in one command → not available in next command.
Workaround: Install dependencies in Dockerfile, not at runtime.
Future: docker exec will reuse containers, persisting state across commands.
Hive detects runtime from project files:
package.json → node:22-slimrequirements.txt / pyproject.toml → python:3.12-slimgo.mod → golang:1.22-slimCargo.toml → rust:1.77-slimDockerfile → Builds from project Dockerfileubuntu:24.04Override: Set dockerImage in config (~/.config/opencode/agent_hive.json).
If you catch yourself:
docker build without .dockerignore (cache invalidation)latest tag in production (non-reproducible)docker run --rm commandsALL of these mean: STOP. Review pattern.
| Excuse | Reality |
|---|---|
| "I'll just run it on host" | Container mismatch bugs are worse to debug later. Build happens in container anyway. |
| "Works in my container, don't need CI" | CI uses different cache state. Always test in CI-like environment. |
| "I'll optimize the Dockerfile later" | Later never comes. Large images slow down deployments now. |
| "latest tag is fine for dev" | Dev should match prod. Pin versions or face surprises. |
| "Don't need .dockerignore, COPY is fast" | Invalidates cache on every file change. Wastes minutes per build. |
| "Install at runtime, not in image" | Ephemeral containers lose state. Slows down every command. |
| "Skip depends_on, services start fast" | Race conditions in integration tests. Use wait-for-it or health checks. |
Before marking Docker work complete:
docker run --rm <image> <command> exits 0.dockerignore exists if using COPY . .latest) for productiondocker-compose down)If any fail: Don't claim success. Fix or report blocker.
| Task | Command Pattern |
|---|---|
| Debug container | docker run -it --entrypoint sh <image> |
| Run with mounts | docker run -v $(pwd):/app <image> |
| Multi-service tests | docker-compose up --abort-on-container-exit |
| Check image contents | docker run --rm <image> ls /app |
| Optimize build | Add .dockerignore, use multi-stage, pin versions |
| Escape Hive sandbox | Prefix with HOST: (e.g., HOST: git status) |