Skip to content

DevContainer

Hive DevContainer is a universal development environment for Hive projects. It connects as a git submodule and includes everything you need: languages, tools, hive-cli, and Claude Code.

Why

  • Consistent environment --- all developers work in the same setup
  • Multi-language --- Python, Go, Node.js, .NET, Rust, Java out of the box
  • hive-cli from source --- automatically built from repos/hive-api
  • Claude Code --- AI assistant with context preserved across rebuilds

Quick start

1. Add the submodule

git submodule add git@lab.xmonetize.net:infrastructure/hive/hive-devcontainer.git .devcontainer
git commit -m "Add hive devcontainer"

2. Open in VS Code

++ctrl+shift+p++ > Dev Containers: Reopen in Container

First build takes a few minutes (downloading images and language toolchains). Subsequent launches use cache.

3. Verify

hive --help          # Hive CLI
docker --version     # Docker-in-Docker
pack --version       # Cloud Native Buildpacks
claude --version     # Claude Code

CLI

You can use it without VS Code: 

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash

What's included

Languages

Language Version Source
Python 3.12 + uv devcontainer feature
Go latest devcontainer feature
Node.js LTS devcontainer feature
.NET 8.0 devcontainer feature
Rust latest devcontainer feature
Java 21 + Maven + Gradle devcontainer feature

Tools

Tool Version Purpose
hive CLI from source Build and deploy services
Docker docker-in-docker Container image builds
pack 0.40.1 Cloud Native Buildpacks
kubectl latest Kubernetes management
Helm latest Helm charts
Claude Code latest AI assistant

VS Code extensions

  • Python + Pylance
  • Go
  • Rust Analyzer
  • C# Dev Kit
  • Java (Red Hat)
  • Kubernetes Tools
  • ESLint
  • Claude Code

hive-cli

If the project contains a repos/hive-api/ directory, hive-cli is automatically installed from source when the container is first created.

hive list              # List services in the repository
hive build --all       # Build all services
hive test --all        # Test all services
hive deploy --all      # Deploy all services

After updating repos/hive-api, rebuild the CLI:

cd repos/hive-api && uv sync

Claude Code: persistence

How it works

~/.claude is mounted as a named Docker volume:

hive-claude-{workspace-name}

Examples:

  • hive-workspace -> volume hive-claude-hive-workspace
  • my-project -> volume hive-claude-my-project

This provides:

  • Persistence --- data survives container rebuilds
  • Isolation --- each project gets a separate volume, contexts don't mix

What is preserved

  • Memory (.claude/projects/*/memory/)
  • Project settings (.claude/projects/*/)
  • Global settings (.claude/settings.json)

Backup and restore

For additional protection, use backups:

# Create backup
claude-backup
# Backup created: .claude-backups/claude-backup-20260325-120000.tar.gz

# Restore from latest backup
claude-restore

# Restore from specific file
claude-restore .claude-backups/claude-backup-20260325-120000.tar.gz

Don't forget

Add .claude-backups/ to your project's .gitignore to keep backups out of git.

The last 5 backups are retained; older ones are deleted automatically.

Updating the DevContainer

git submodule update --remote .devcontainer
git add .devcontainer
git commit -m "Update hive devcontainer"

Then rebuild the container: ++ctrl+shift+p++ > Dev Containers: Rebuild Container

Data is preserved

When rebuilding the container, ~/.claude stays intact thanks to the Docker volume.

Structure

.devcontainer/
├── devcontainer.json    # Configuration: features, volumes, extensions
├── Dockerfile           # Base image (Ubuntu 24.04) + pack CLI
└── scripts/
    ├── post-create.sh   # First-time setup
    ├── post-start.sh    # Startup checks
    ├── claude-backup.sh # ~/.claude backup
    └── claude-restore.sh# Restore from backup

Customization

The DevContainer can be extended with devcontainer features. Add the features you need to devcontainer.json:

{
  "features": {
    "ghcr.io/devcontainers/features/terraform:1": {},
    "ghcr.io/devcontainers/features/aws-cli:1": {}
  }
}

For project-specific extensions, create .devcontainer/devcontainer.local.json (add it to .gitignore).