DevContainer Wizard

A comprehensive CLI tool to set up fully equipped Web3 development containers. Features an interactive wizard for creating custom environments with advanced security hardening, git integration, and pre-configured toolchains, or quickly launch pre-built containers for common workflows.

Important

Dev Containers can improve your workflow, but they are not a fully secure environment.
If you need to run untrusted or suspicious code, use GitHub Codespaces, GitPod, or a similar remote setup — never run it directly on your machine.

Caution

VS Code considerations:

VS Code does a lot to improve user experience, but that doesn't come without security tradeoffs. VS Code might allow API calls that can lead to running arbitrary commands on the host machine, and by default, it shares sockets such as the gpg-agent’s, which means keys stored outside the container can be used for signing. This opens the door to blind-signing commits scenarios, where a process inside the container may trigger signatures without the user’s full awareness. If you want to deep dive into these "tricks", we're working on an article covering the most relevant of them — stay tuned.

Requirements

1. Node.js 18+ and a package manager (pnpm, npm, or yarn) for installing the CLI.

2. For use with VS Code you need to install the Dev Containers extension. We recommend reading the Dev Containers documentation for more information.

Full requirements to run Dev Containers

• Operating system: Linux, macOS, or Windows 10/11. On Windows, WSL2 is recommended for best performance.
• Container runtime: One of the following:
  • Docker Desktop (macOS/Windows) or Docker Engine (Linux) with the docker CLI available
  • Alternatively, Podman 4+ with the podman-docker shim to provide a docker-compatible CLI
• Docker Compose v2: Available as docker compose (bundled with Docker Desktop; on Linux install the Compose plugin).
• Git: Version 2.x or later.
• Node.js 18+ and a package manager (pnpm, npm, or yarn) to install @devcontainers/cli globally.
• Editor: VS Code with the Dev Containers extension, or use GitHub Codespaces as an alternative (no local runtime required).
• Permissions: Ability to run containers (e.g., membership in the docker group on Linux, or run with sudo).
• Network access: To pull base images and extensions on first run.

Install

To install our pre-realease clone this repo and run:

npm i -g devcontainer-wizard

#or

pnpm add -g devcontainer-wizard

How to use

Quick start

devcontainer-wizard

Create your own devcontainer

devcontainer-wizard create --name <name>

The wizard will prompt you for:

• Devcontainer name: defaults to the current directory name.
• Languages: Solidity, Vyper.
• Frameworks: Foundry, Hardhat, Ape (ApeWorX).
• Fuzzing & testing: Echidna, Medusa, Halmos, Ityfuzz, Aderyn.
• Security tooling: Slither, Mythril, Crytic (crytic-compile), Panoramix, Semgrep, Heimdall.
• System hardening: Choose between predefined security recipes or manual configuration:
  • Security Recipes: Pre-configured security profiles for common use cases
  • Manual Configuration: Fine-grained control over individual security options
• Git repository integration: Automatically clone a repository during container build
  • Repository URL validation
  • Optional branch/tag specification
• VS Code extensions: Choose from curated extension collections or select your own.
• Save path: where .devcontainer/<name> will be created.

When finished, the CLI writes Dockerfile and devcontainer.json to .devcontainer/<name> and offers to start it immediately. It also prints the exact devcontainer up command you can run later.

Security Profiles

The wizard includes predefined security profiles copied from prebuilt devcontainers, so you can build your own container with custom tools and a tested security profile:

• Development: Balanced security for daily development work

  • Features: Secure temp directories, no privilege escalation, AppArmor, secure DNS, VS Code security

• Hardened: Ephemeral workspace without copying the host folder

  • Features: Ephemeral workspace, maximum capability restrictions

• Air-gapped: Hardened profile + no network

  • Features: No network, ephemeral workspace, maximum capability restrictions

Experimental profiles:

• Network Restricted Analysis: API access and package installs without packet crafting
• CI-like Local Runner: Mirrors CI behavior with an immutable file system
• Package Install Session: Install packages while maintaining security guardrails
• Security Research (Controlled Net): API testing without packet crafting capabilities

Manual Security Hardening Options

When choosing manual configuration, you have fine-grained control over:

File System Security:

• Read-only file system
• Secure temp directories (noexec, nosuid flags)

Workspace Isolation:

• Ephemeral workspace (tmpfs mount)

Container Security:

• Drop all capabilities
• No new privileges (prevents SUID/SGID escalation)
• AppArmor profile

Network Configuration:

• Enhanced DNS security (Cloudflare DNS)
• Complete network isolation
• Disable IPv6
• Disable raw packets (prevents packet crafting)

Application Security:

• VS Code security (disables auto-tasks, workspace trust, telemetry)

Resource Limits:

• Light (512MB, 2 cores)
• Standard (2GB, 4 cores)
• Heavy (4GB, 8 cores)

Git Repository Integration

The wizard can now automatically clone a git repository during container build:

• Repository URL: Supports https://, git@, ssh://, and git:// protocols
• Branch/Tag Selection: Optionally specify a specific branch or tag to clone
• Validation: Built-in URL validation ensures proper git repository format
• Build-time Integration: Repository is cloned into /home/vscode/repos during the image build and copied into /workspace on first start

This feature is particularly useful for:

• Setting up development environments with existing codebases
• Workshop environments with predefined project templates
• Audit environments with specific contract repositories

VS Code Extensions

The wizard offers curated extension collections:

• Recommended (default): Automatically installs Tintin's Ethereum Security Bundle
• Custom selection: Choose from organized collections:
  • Tintin's Extensions: Security-focused tools (Ethereum Security Bundle, EthOver, WeAudit, Inline Bookmarks, Solidity Language Tools, Graphviz Preview, Decompiler)
  • Nomic Foundation: Hardhat + Solidity integration
  • Olympix: AI-powered smart contract analysis

Start pre-built containers

Prebuilt containers are stored in the theredguild/devcontainer repository.

• Start a pre-built container:

devcontainer-wizard prebuilt --name <name>

• List available pre-built containers:

devcontainer-wizard prebuilt --list

• Available pre-built containers: minimal, auditor, Hardened, paranoid, eth-security-toolbox, legacy.
• You will be prompted how to open it (Terminal, VS Code, or Cursor).

GitHub Codespaces

You can also run prebuilt containers using GitHub Codespaces:

Pre-built containers

• Minimal: Use Hardhat and Foundry, doing zero config.
• Auditor: Audit smart contracts.
• Hardened: Use an Hardened workspace without copying your environment.
• Air-gapped: Air-gapped environment.
• ETH Security Toolbox: Auditor environment with Trail of Bits selected tools.
• Legacy: The Red Guild's original devcontainer.

How to contribute

Wizard

This repo uses npm workspaces with the layout:

• packages/core → @theredguild/devcontainer-wizard (the actual CLI)
• packages/wrapper → devcontainer-wizard (thin wrapper that delegates to core)

Getting started:

• Install all deps and link workspaces: npm install (run at repo root)
• Run a script in a workspace:
  • Core build: npm run -w @theredguild/devcontainer-wizard build
  • Core dev (ts-node): npm run -w @theredguild/devcontainer-wizard dev
• Run the CLI locally:
  • Via wrapper bin: node packages/wrapper/bin.js
  • Or after install: npx devcontainer-wizard

Developing wrapper against local core:

• For local development, set the wrapper’s dependency to the workspace protocol so it links your local core:
  • In packages/wrapper/package.json: "@theredguild/devcontainer-wizard": "workspace:*"
• Re-run npm install at the root to update links.

Publishing (order matters):

• Publish core first: npm publish -w packages/core --access public
• Then update wrapper to depend on the published version (if you moved off workspace:*) and publish:
  • npm publish -w packages/wrapper --access public

Notes:

• Root package.json declares workspaces: ["packages/*"] and packageManager: "npm@10".
• pnpm or yarn can work too, but npm is the reference configuration.

Pre-built containers

We welcome contributions to the pre-built containers! To get started:

1. Fork the theredguild/devcontainer repository and clone it to your machine.
2. Make your changes in a new branch.
3. Test your changes locally.
4. Commit and push your branch.
5. Open a pull request with a clear description of your changes.