Claude Code in dev containers.

Without Mastlight

1. Add the Claude Code feature to your dev container

   Claude Code ships as a Dev Container Feature. Save this as .devcontainer/devcontainer.json in your repository, or add the features block to the file you have. Replace the image line with your project’s own base image, or remove it if you use a Dockerfile.

   {
     "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
     "features": {
       "ghcr.io/anthropics/devcontainer-features/claude-code:1.0": {}
     }
   }

   Copy

   The version tag, :1.0, pins the feature’s install script, not Claude Code itself. The feature installs the latest Claude Code, and it updates itself inside the container.

2. Rebuild the container

   In VS Code, open the Command Palette (Cmd Shift P on a Mac, Ctrl Shift P on Windows) and run Dev Containers: Rebuild Container. Other tools, such as GitHub Codespaces or the Dev Containers CLI, have their own rebuild action.

3. Sign in inside the container

   Open a terminal in the rebuilt container, run claude and follow the sign-in prompt. If the browser finishes but the callback never reaches the container, copy the code the browser shows and paste it at the Paste code here if prompted prompt.

4. Keep your login when the container is rebuilt

   By default the container’s home folder is thrown away on rebuild, so you would sign in again. Claude Code keeps its login and settings in ~/.claude, and its account details in a separate ~/.claude.json, so a volume on ~/.claude alone is not enough. Mount a named volume there and set CLAUDE_CONFIG_DIR to the same path. For a container whose user is node:

   "mounts": [
     "source=claude-code-config,target=/home/node/.claude,type=volume"
   ],
   "containerEnv": {
     "CLAUDE_CONFIG_DIR": "/home/node/.claude"
   }

   Copy

   Use your container user’s own home folder in place of /home/node.

5. Mind the permission flag

   A container limits what a session can touch, but it is not a perfect wall. Claude Code’s docs warn that with --dangerously-skip-permissions, a malicious project can still send out anything reachable inside the container, including the credentials in ~/.claude. Use that only on repositories you trust, and avoid mounting secrets such as ~/.ssh into the container.

How Mastlight does it

Already have a dev container? You do not change it, and Mastlight does not add anything to your project.

• It finds the container. If a folder has a .devcontainer/devcontainer.json (or .devcontainer.json, or one in a named subfolder), in the folder or any parent below your home folder, and that container is running, the New session sheet shows a Run in dev container row with the container’s name and a checkbox. Leave it ticked and the session runs inside.
• Any running dev container started by VS Code or the devcontainer CLI works. Mastlight needs a docker command from Docker Desktop, OrbStack, Colima, Rancher Desktop, or Podman’s Docker-compatible CLI.
• Claude Code has to be installed in the container. If it is not, you get one plain message with the two fixes: npm install -g @anthropic-ai/claude-code, or the dev container feature above.
• The container’s own login. A container session uses the account signed in inside the container, and the account picker says so.
• The Conversation view and cards work. Mastlight copies the transcript to your computer as it is written, so the Conversation fills and the session groups with its project. Permission cards and questions work through a small hook in the container that calls back to Mastlight. Nothing is written into your project; the hook files live in /tmp inside the container and are removed when the session ends.
• A stopped container ends the session. The restore card offers Start it when the devcontainer CLI is installed. Otherwise open the folder in VS Code and reopen it in the container, then try again.

What does not work yet

• If the container has no curl, or no host address answers, the session still starts but cards cannot reach Mastlight. You answer prompts in the terminal and a note on the session says so.
• Container sessions show no limits in the gauges, because the status line script on your computer does not run in the container.
• Subagent transcripts are not copied; the main conversation is. A --continue you type yourself in the container starts, but that session has no Conversation view.
• Colima is the runtime this was tested on. With other runtimes the host address may not answer, which gives the no-cards note above. Linux hosts are not a target.

On Windows

Mastlight for Windows understands Docker Desktop’s folder forms, such as C:\project and /run/desktop/mnt/host/c/project. That is covered by unit tests and has not been run on a real Windows PC yet. Folders inside WSL (\\wsl$\ and \\wsl.localhost\) are not supported: the New session row says so. Dev container support arrived in Mastlight 1.0.10 on the Mac; the first Windows release is 1.1.2, an early preview.