Skip to main content

Working Inside the DevContainer

This file applies only when project-*.md says the project uses the DevContainer Toolbox (DCT). If it says there is no devcontainer, ignore this file — do not invent a cage.

When it does apply: the AI must run all commands inside the devcontainer, never on the host machine.

The Rule​

ALL commands that install packages, run code, or execute tools MUST run inside the devcontainer.

Do NOT run these on the host machine:

  • Package managers (npm, pip, cargo, etc.)
  • Build tools and compilers
  • Test runners
  • Application servers
  • Any project-specific commands

Key Paths Inside the Container​

/opt/devcontainer-toolbox/           # DCT installation root — READ ONLY, never edit
├── additions/                        # Tool install scripts
│   ├── install-*.sh                  # Run directly to install a tool
│   ├── config-*.sh                   # Configuration scripts
│   ├── service-*.sh                  # Background service managers
│   └── lib/                          # Shared libraries
└── manage/
    └── tools.json                    # Machine-readable inventory of all available tools

/workspace/                           # Mounted project directory (always this path)
├── .devcontainer/                    # Container configuration
├── .devcontainer.extend/             # Project tool/service config (committed to git)
│   ├── enabled-tools.conf            # Tools to auto-install on container creation
│   ├── enabled-services.conf         # Services to auto-start
│   └── project-installs.sh           # Custom project setup (npm install, etc.)
└── .devcontainer.secrets/            # Local-only secrets (gitignored)
    └── env-vars/                     # Environment variables and API keys

Getting Help​

Run dev-help anywhere inside the container to see all available commands and the toolbox version:

dev-help

Universal Commands​

These commands are always available inside the container:

CommandPurpose
dev-helpShow all available commands and version info
dev-setupInteractive menu — install tools, manage services
dev-envShow installed tools and environment info
dev-toolsOutput machine-readable tool inventory (JSON)
dev-servicesManage background services (start/stop/status/logs)
dev-checkConfigure and validate Git identity and credentials
dev-syncUpdate toolbox scripts without rebuilding container
dev-updateUpdate devcontainer-toolbox to latest version
dev-templateCreate project files from templates
dev-logDisplay the container startup log

Available Tools​

The file /opt/devcontainer-toolbox/manage/tools.json contains a machine-readable inventory of all tools available for installation. It includes metadata for each tool: id, name, description, category, and a check command to verify installation.

The install scripts live in /opt/devcontainer-toolbox/additions/. To work with a tool:

# See what's available
cat /opt/devcontainer-toolbox/manage/tools.json

# Install a tool (run the script directly)
/opt/devcontainer-toolbox/additions/install-dev-python.sh

# Get help and options for a tool
/opt/devcontainer-toolbox/additions/install-dev-python.sh --help

# Uninstall a tool
/opt/devcontainer-toolbox/additions/install-dev-python.sh --uninstall

Or use the interactive menu:

dev-setup

NEVER Edit DCT Files​

NEVER edit files inside /opt/devcontainer-toolbox/. That directory is maintained by the DevContainer Toolbox project, not by individual projects.

If something needs fixing or you need a new feature, register an issue: https://github.com/helpers-no/devcontainer-toolbox/issues

Pre-installed Tools​

Every DCT container includes:

  • Python 3.12, Node.js 22 LTS
  • Docker CLI, GitHub CLI
  • Git, curl, wget, zip/unzip
  • Standard Unix tools (bash, grep, sed, awk, etc.)
  • Supervisord for background services

Additional tools are installed per project via .devcontainer.extend/enabled-tools.conf.

Accessing the Container from the Host​

When the AI runs on the host machine (e.g., Claude Code outside VS Code), use docker exec to run commands inside the container.

Find the container​

docker ps --format '{{.Names}}\t{{.Image}}' | grep devcontainer-toolbox

Run commands​

docker exec <container-name> bash -c "cd /workspace && <command>"

The project's project-*.md file will specify the container name or discovery command for this specific project.

Project Customization​

Shared with team (committed to git)​

.devcontainer.extend/enabled-tools.conf — list tool IDs to auto-install:

dev-python
dev-golang
tool-kubernetes

.devcontainer.extend/project-installs.sh — custom setup script:

cd /workspace && npm install

Local only (gitignored)​

.devcontainer.secrets/env-vars/ — API keys and credentials:

echo "your-api-key" > .devcontainer.secrets/env-vars/api-key

These are automatically available as environment variables inside the container.