Devbox — One-Command Docker Dev Environment#

Create isolated Docker dev environments for any project with a single command.

How It Works#

The scripts/devbox.sh script:

1. Auto-detects your project type (framework, language, package manager)
2. Reads your local language version (Node, Python, Go, Rust, Java, etc.)
3. Generates a docker-compose.dev.yml with the matching Docker image
4. Optionally attaches database services (PostgreSQL, MySQL, Redis, MongoDB, MinIO)

Volume 隔离策略#

All generated files use named volumes, never bind-mounted to the host:

• Source code → bind mount (read/write from host)
• Dependencies → named volume ( node_modules, pip, m2, gems, etc.)
• Build caches → named volume ( .nuxt, .next, go-build, cargo-target, etc.)
• Package manager stores → named volume ( pnpm-store, composer, nuget, etc.)

Benefits: no host/container cache collisions, native speed on macOS, cache survives container rebuilds.

Usage#

After installing this skill, run the bundled script directly:

bash

SKILL_DIR=$(clawhub list --json 2>/dev/null | python3 -c "import sys,json; print([s['folder'] for s in json.load(sys.stdin) if s.get('slug')=='docker-devbox'][0])" 2>/dev/null || echo "skills/docker-devbox")

# Run devbox
bash "$SKILL_DIR/scripts/devbox.sh" /path/to/project

# Or copy to PATH for convenience
cp "$SKILL_DIR/scripts/devbox.sh" /usr/local/bin/devbox
chmod +x /usr/local/bin/devbox
devbox /path/to/project

Quick Start#

bash

# Auto-detect project type
devbox /path/to/project

# Specify port + attach databases
devbox /path/to/project 8000 --with postgres,redis

# Force framework
devbox /path/to/project --framework java-spring

Supported Project Types#

TypeDetectionDefault PortDocker ImageNuxt 3/4nuxt.config.*3000node:{ver}-bookwormNext.jsnext.config.*3000node:{ver}-bookwormVue + Vitevite.config.* + vue5173node:{ver}-bookwormReact + Vitevite.config.* + react5173node:{ver}-bookwormSveltesvelte.config.*5173node:{ver}-bookwormVitePressdocs/.vitepress/5173node:{ver}-bookwormNode.js backendpackage.json3000node:{ver}-bookwormPython FastAPIrequirements.txt + fastapi8000python:{ver}-slimPython Djangomanage.py8000python:{ver}-slimPython Flaskrequirements.txt + flask5000python:{ver}-slimGogo.mod8080golang:{ver}RustCargo.toml8080rust:{ver}Java (Spring Boot)pom.xml + spring-boot8080eclipse-temurin:{ver}-jdkJava (Maven)pom.xml8080eclipse-temurin:{ver}-jdkJava (Gradle)build.gradle / .kts8080eclipse-temurin:{ver}-jdkKotlin*.kt (no build.gradle)8080eclipse-temurin:21-jdkRuby on RailsGemfile + rails3000ruby:{ver}-slimRuby SinatraGemfile4567ruby:{ver}-slimPHP Laravelcomposer.json + laravel5000php:{ver}-cliPHPcomposer.json8000php:{ver}-cliC# / .NET*.csproj / *.sln5000dotnet/sdk:{ver}SwiftPackage.swift8080swift:{ver}Hugohugo.toml1313klakegg/hugo:ext-alpineStatic HTML*.html80nginx:alpine

Attach Database Services#

bash

devbox ./app --with postgres,redis

ServiceImagePortpostgres / pg``postgres:16-alpine5432mysql``mysql:8-alpine3306redis``redis:7-alpine6379mongo``mongo:727017minio``minio/minio9000/9001

CLI Options#

text

devbox <project-path> [port] [options]

Options:
  --framework <type>    Override auto-detection
  --with <services>     Comma-separated services to attach
  --env-file <path>     Environment variable file
  --use-dockerfile      Use project's existing Dockerfile
  -h, --help            Show help

Volume 隔离速查表#

项目类型命名卷Nuxtnm, pnpm-store, nuxt, nuxt-outputNext.jsnm, nextVue/React/Vite/Sveltenm, pnpm-storePythonpipGogo-mod, go-cacheRustcargo-registry, cargo-git, cargo-targetJava Mavenm2Java GradlegradleRubygemsPHPcomposer.NETnugetSwiftswift

Included Files#

text

scripts/devbox.sh          — Main script (auto-detect + generate compose)
scripts/create-dev-env.sh  — Backward-compatible wrapper
references/docker-templates.md — Ready-to-use compose templates with volume isolation

Dependencies#

Required:

• docker + docker compose — the only hard requirement

Optional (for version detection):

• node, python3, go, rustc, java, ruby, php, dotnet, swift
• pnpm / yarn / bun — Node.js package manager detection

Optional (for port conflict detection):

• lsof — Detects host processes using a port

Only the runtimes installed on your host are used. If a language is not installed, the script falls back to a sensible default version.