Skip to main content

Windows setup (WSL2 + devcontainer)

The agent tooling — shell rituals, the generator, .claude skills — assumes a Unix-like shell. On Windows, don't run it against native PowerShell; use one of the two supported paths below. Both give you a genuine Linux userland, which is also the cleanest way to get the security isolation an agent workstation needs.

Path A — WSL2 with Ubuntu (recommended)​

WSL2 runs a real Linux kernel under Windows. Inside the distro, every command in the Agent starter kit quickstart works verbatim.

  1. Install WSL2 + Ubuntu (PowerShell as Administrator):

    wsl --install -d Ubuntu

    Reboot if prompted, then set your Linux username/password when the Ubuntu window opens.

  2. Install Node 20+ inside the distro (not on Windows). Use nvm:

    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
    exec "$SHELL"
    nvm install 20

  3. Keep your repo on the Linux filesystem (~/work/..., not /mnt/c/...). Cross-filesystem I/O over /mnt/c is slow and breaks file watchers.

  4. Run the quickstart from inside the distro — scaffold, connect the MCP, verify. Your agent client connects to WSL:

    • VS Code / Cursor: install the WSL extension and "Reopen in WSL".
    • Claude Code / Codex CLI: run them from the Ubuntu shell.

  5. Export your key in the Linux shell (add it to ~/.bashrc if you like):

    export CONSTELLATION_API_KEY="<paste the key>"

Docker Desktop's WSL2 integration also gives you docker inside the distro, which enables Path B.

Path B — devcontainer​

A devcontainer runs your repo inside a container with a pinned toolchain — the same on Windows, macOS, and Linux — and is the easiest way to isolate an agent from the host (see Secure agent workstation).

The starter kit emits a .devcontainer/devcontainer.json by default. It pins Node 20, runs as the non-root node user, drops Linux capabilities (--cap-drop=ALL, --security-opt=no-new-privileges), and forwards your CONSTELLATION_API_KEY from the host environment.

  1. Install Docker Desktop (with WSL2 backend) and the Dev Containers VS Code extension.
  2. Set CONSTELLATION_API_KEY in your host environment so the container inherits it.
  3. Open the repo and choose Reopen in Container. Node, the GitHub CLI, and the Claude Code extension are provisioned automatically.
  4. Run the quickstart steps from the container terminal.

If you skipped the devcontainer at generate time, re-run the generator with the default (drop --no-devcontainer), or copy .devcontainer/devcontainer.json from the starter kit.

Notes​

  • Native Windows + PowerShell is not a supported path — the shell rituals and symlinks (CLAUDE.md → AGENTS.md) assume a POSIX shell.
  • Line endings: configure Git to keep LF (git config --global core.autocrlf input) so committed scripts stay Unix-clean.