devcontainer setup
- Repo stars 0
- Author updated Aug 24, 2026, 11:09 PM
- Author repo skills
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @trailofbits · no license declared
- Token usage
- Lean
- Setup complexity
- Manual integration
- External API key
- Required · Anthropic
- Operating systems
- Docker
- Runtime requirements
- Node.js · Python >=3.13 · Docker
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Phase 1: Project Reconnaissance
Phase 1: Project Reconnaissance
Phase 2: Generate Configuration
Start with base templates from `resources/` directory. Substitute: `{{PROJECT_NAME}}` → Human-readable name (e.g., "My Project") `{{PROJECT_SLUG}}` → Slug for volumes (e.g., "my-project") Then apply language-specific modifications below.
# Devcontainer Setup Skill
Creates a pre-configured devcontainer with Claude Code and language-specific tooling.
## When to Use
- User asks to "set up a devcontainer" or "add devcontainer support"
- User wants a sandboxed Claude Code development environment
- User needs isolated development environments with persistent configuration
## When NOT to Use
- User already has a devcontainer configuration and just needs modifications
- User is asking about general Docker or container questions
- User wants to deploy production containers (this is for development only)
## Workflow
```mermaid
flowchart TB
start([User requests devcontainer])
recon[1. Project Reconnaissance]
detect[2. Detect Languages]
generate[3. Generate Configuration]
write[4. Write files to .devcontainer/]
done([Done])
start --> recon
recon --> detect
detect --> generate
generate --> write
write --> done
```
## Phase 1: Project Reconnaissance
### Infer Project Name
Check in order (use first match):
1. `package.json` → `name` field
2. `pyproject.toml` → `project.name`
3. `Cargo.toml` → `package.name`
4. `go.mod` → module path (last segment after `/`)
5. Directory name as fallback
Convert to slug: lowercase, replace spaces/underscores with hyphens.
### Detect Language Stack
| Language | Detection Files |
|----------|-----------------|
| Python | `pyproject.toml`, `*.py` |
| Node/TypeScript | `package.json`, `tsconfig.json` |
| Rust | `Cargo.toml` |
| Go | `go.mod`, `go.sum` |
### Multi-Language Projects
If multiple languages are detected, configure all of them in the following priority order:
1. **Python** - Primary language, uses Dockerfile for uv + Python installation
2. **Node/TypeScript** - Uses devcontainer feature
3. **Rust** - Uses devcontainer feature
4. **Go** - Uses devcontainer feature
For multi-language `postCreateCommand`, chain all setup commands:
```
uv run /opt/post_install.py && uv sync && npm ci
```
Extensions and settings from all detected languages should be merged into the configuration.
## Phase 2: Generate Configuration
Start with base templates from `resources/` directory. Substitute:
- `{{PROJECT_NAME}}` → Human-readable name (e.g., "My Project")
- `{{PROJECT_SLUG}}` → Slug for volumes (e.g., "my-project")
Then apply language-specific modifications below.
## Base Template Features
The base template includes:
- **Claude Code** with marketplace plugins (anthropics/skills, trailofbits/skills, trailofbits/skills-curated)
- **Sandboxing** via bubblewrap and socat
- **Python 3.13** via uv (fast binary download)
- **Node 22** via fnm (Fast Node Manager)
- **ast-grep** for AST-based code search
- **Network isolation tools** (iptables, ipset) with NET_ADMIN capability
- **Security mounts**: `.devcontainer/` mounted read-only to prevent container escape
- **Token forwarding**: `CLAUDE_CODE_OAUTH_TOKEN` and `ANTHROPIC_API_KEY` via `remoteEnv`
- **Modern CLI tools**: ripgrep, fd, fzf, tmux, git-delta
---
## Language-Specific Sections
### Python Projects
**Detection:** `pyproject.toml`, `requirements.txt`, `setup.py`, or `*.py` files
**Dockerfile additions:**
The base Dockerfile already includes Python 3.13 via uv. If a different version is required (detected from `pyproject.toml`), modify the Python installation:
```dockerfile
# Install Python via uv (fast binary download, not source compilation)
RUN uv python install <version> --default
```
**devcontainer.json extensions:**
Add to `customizations.vscode.extensions`:
```json
"ms-python.python",
"ms-python.vscode-pylance",
"charliermarsh.ruff"
```
Add to `customizations.vscode.settings`:
```json
"python.defaultInterpreterPath": ".venv/bin/python",
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.codeActionsOnSave": {
"source.organizeImports": "explicit"
}
}
```
**postCreateCommand:**
If `pyproject.toml` exists, chain commands:
```
rm -rf .venv && uv sync && uv run /opt/post_install.py
```
---
### Node/TypeScript Projects
**Detection:** `package.json` or `tsconfig.json`
**No Dockerfile additions needed:** The base template includes Node 22 via fnm (Fast Node Manager).
**devcontainer.json extensions:**
Add to `customizations.vscode.extensions`:
```json
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
```
Add to `customizations.vscode.settings`:
```json
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit"
}
```
**postCreateCommand:**
Detect package manager from lockfile and chain with base command:
- `pnpm-lock.yaml` → `uv run /opt/post_install.py && pnpm install --frozen-lockfile`
- `yarn.lock` → `uv run /opt/post_install.py && yarn install --frozen-lockfile`
- `package-lock.json` → `uv run /opt/post_install.py && npm ci`
- No lockfile → `uv run /opt/post_install.py && npm install`
---
### Rust Projects
**Detection:** `Cargo.toml`
**Features to add:**
```json
"ghcr.io/devcontainers/features/rust:1": {}
```
**devcontainer.json extensions:**
Add to `customizations.vscode.extensions`:
```json
"rust-lang.rust-analyzer",
"tamasfe.even-better-toml"
```
Add to `customizations.vscode.settings`:
```json
"[rust]": {
"editor.defaultFormatter": "rust-lang.rust-analyzer"
}
```
**postCreateCommand:**
If `Cargo.lock` exists, use locked builds:
```
uv run /opt/post_install.py && cargo build --locked
```
If no lockfile, use standard build:
```
uv run /opt/post_install.py && cargo build
```
---
### Go Projects
**Detection:** `go.mod`
**Features to add:**
```json
"ghcr.io/devcontainers/features/go:1": {
"version": "latest"
}
```
**devcontainer.json extensions:**
Add to `customizations.vscode.extensions`:
```json
"golang.go"
```
Add to `customizations.vscode.settings`:
```json
"[go]": {
"editor.defaultFormatter": "golang.go"
},
"go.useLanguageServer": true
```
**postCreateCommand:**
```
uv run /opt/post_install.py && go mod download
```
---
## Reference Material
For additional guidance, see:
- `references/dockerfile-best-practices.md` - Layer optimization, multi-stage builds, architecture support
- `references/features-vs-dockerfile.md` - When to use devcontainer features vs custom Dockerfile
---
## Adding Persistent Volumes
Pattern for new mounts in `devcontainer.json`:
```json
"mounts": [
"source={{PROJECT_SLUG}}-<purpose>-${devcontainerId},target=<container-path>,type=volume"
]
```
Common additions:
- `source={{PROJECT_SLUG}}-cargo-${devcontainerId},target=/home/vscode/.cargo,type=volume` (Rust)
- `source={{PROJECT_SLUG}}-go-${devcontainerId},target=/home/vscode/go,type=volume` (Go)
---
## Output Files
Generate these files in the project's `.devcontainer/` directory:
1. `Dockerfile` - Container build instructions
2. `devcontainer.json` - VS Code/devcontainer configuration
3. `post_install.py` - Post-creation setup script
4. `.zshrc` - Shell configuration
5. `install.sh` - CLI helper for managing the devcontainer (`devc` command)
---
## Validation Checklist
Before presenting files to the user, verify:
1. All `{{PROJECT_NAME}}` placeholders are replaced with the human-readable name
2. All `{{PROJECT_SLUG}}` placeholders are replaced with the slugified name
3. JSON syntax is valid in `devcontainer.json` (no trailing commas, proper nesting)
4. Language-specific extensions are added for all detected languages
5. `postCreateCommand` includes all required setup commands (chained with `&&`)
---
## User Instructions
After generating, inform the user:
1. How to start: "Open in VS Code and select 'Reopen in Container'"
2. Alternative: `devcontainer up --workspace-folder .`
3. CLI helper: Run `.devcontainer/install.sh self-install` to add the `devc` command to PATH
Sections and files
Listed in source order.
sections -> When to Use → When NOT to Use → Workflow → Phase 1: Project Reconnaissance → Infer Project Name → Detect Language Stack
terms -> Python · Node/TypeScript · Rust · Go · Claude Code · Sandboxing · Python 3.13 · Node 22
files/cmd -> package.json · name · pyproject.toml · project.name · Cargo.toml · package.name · go.mod · *.py
body sha256 -> e927aa11483f
When to Use
User asks to "set up a devcontainer" or "add devcontainer support" User wants a sandboxed Claude Code development environment User needs isolated development environments with persistent configuration
When NOT to Use
User already has a devcontainer configuration and just needs modifications User is asking about general Docker or container questions User wants to deploy production containers (this is for development only)
Infer Project Name
Check in order (use first match):
package.json→namefieldpyproject.toml→project.nameCargo.toml→package.namego.mod→ module path (last segment after/)Detect Language Stack
Language · Detection Files Python ·
pyproject.toml,*.pyNode/TypeScript ·package.json,tsconfig.jsonRust ·Cargo.tomlGo ·go.mod,go.sumMulti-Language Projects
If multiple languages are detected, configure all of them in the following priority order: Python - Primary language, uses Dockerfile for uv + Python installation Node/TypeScript - Uses devcontainer feature Rust - Uses devcontainer feature Go - Uses devcontainer feature