VS Code Dev Container Agent Tutorial: Run AI Coding Sessions in Your Project

Visual Studio Code 1.138, released on September 16, 2026, added a practical way to run Agent Host sessions inside a project's local Dev Container. Instead of letting an AI coding agent use whatever Node.js, Python, command-line tools, and dependencies happen to be installed on your computer, the session can run against the environment defined by the project itself. That makes the feature particularly useful for repositories where the development toolchain needs to stay consistent. This VS Code Dev Container agent tutorial walks through the setup, the required configuration, a real project test, and the limits you should understand before giving an agent access to your code. 

The distinction is straightforward. A normal local agent session runs on your machine, while a Dev Container session moves the Agent Host into the container and leaves the VS Code interface on your computer. The agent therefore sees the tools and dependencies installed in that container rather than relying on your host environment. VS Code's own documentation describes Dev Containers as a way to create a well-defined development environment from a devcontainer.json configuration, which is exactly the part this workflow takes advantage of. 

Why running the agent in a Dev Container changes the workflow

AI coding agents do more than generate text. Depending on the selected agent harness and permissions, they can read files, edit source code, run terminal commands, install packages, and execute tests. That means the environment surrounding the agent affects the result: a project that expects Node.js 24, a particular package manager, and Linux command-line tools can behave differently when the agent runs against a developer laptop configured for something else. A Dev Container packages the expected development environment into a container configuration, so the agent can work against the same basic toolchain the project defines. 

This does not make generated code correct, and it does not remove the need for review. VS Code's security documentation explicitly warns that agents can produce incorrect code and can encounter prompt injection through files, tool outputs, or web content. The advantage of the container is narrower: it gives you a stronger boundary around the development environment and its installed tools, which can reduce the blast radius of agent-executed commands compared with an unrestricted host workflow. 

Prepare Docker, VS Code, and a project configuration first

You need three things before the Agent window can offer the Dev Container option: a current VS Code installation, Docker installed and running, and a local project containing a supported Dev Container configuration. VS Code 1.138 controls the feature with the chat.agentHost.devContainer.enabled setting, which is off by default. The feature is also rolling out gradually, so even on a current build the option may not appear until you enable the setting manually. 

A Dev Container configuration normally lives in .devcontainer/devcontainer.json, although VS Code also supports a .devcontainer.json file at the project root. The file tells VS Code how to create or connect to the container and which development environment should be used. You can base the container on a prebuilt image, a Dockerfile, or a more complex Docker Compose setup. 

For a simple JavaScript project, you can use one of the maintained Node.js Dev Container images instead of writing a Dockerfile from scratch. The official Dev Containers image repository currently provides Node.js 22, 24, and 26 variants, with Linux distributions such as Debian Bookworm and Trixie. Using a named major or major-minor image tag gives you a predictable starting point while still allowing the image project to publish compatible updates within that version range. 

Create a small project the agent can build and test

Create a new folder for the tutorial and add a minimal JavaScript application. The goal is not to build something elaborate; it is to give the agent a task that produces an observable result inside the container. Start with a package.json file and a small script:

{
  "name": "vscode-agent-container-demo",
  "version": "1.0.0",
  "private": true,
  "scripts": {
    "test": "node test.js"
  }
}

Then create index.js:

function add(a, b) {
  return a + b;
}

module.exports = { add };

And add test.js:

const assert = require("node:assert");
const { add } = require("./index");

assert.strictEqual(add(7, 5), 12);

console.log("All tests passed.");

You now have a deterministic task the agent can work on: change the function or add another function, run the test command, and show whether the project still passes. Because the test uses only Node.js built-ins, there are no external package dependencies to distract from the container setup. The useful checkpoint is that npm test should print All tests passed. before you introduce the agent.

Define the Dev Container that the agent will use

Inside the project, create .devcontainer/devcontainer.json. This example uses the maintained Node.js 24 image and gives the container a non-root node user, matching the image's documented setup. The exact image tag shown here is a supported pattern from the Dev Containers image repository rather than an invented image name. ([GitHub][1])

{
"name": "Node.js Agent Demo",
"image": "mcr.microsoft.com/devcontainers/javascript-node:24-bookworm",
"remoteUser": "node"
}

Save the file and reopen the project using the Dev Containers extension. VS Code will build or pull the configured environment, start it, and connect the editor to the development container. From that point, terminals and language tooling associated with the workspace operate in the container rather than directly against the host installation. The Dev Containers documentation describes devcontainer.json as the configuration that determines how the environment is created and started. 

Before involving the agent, open a terminal in the container and run node --version and npm test. The first command verifies that Node.js is available inside the environment, while the second proves that the sample project still works there. This check is worth doing because it separates container configuration problems from later agent problems. If the test already fails before the agent starts, fix the container first rather than asking the agent to diagnose two moving parts at once.

Enable Agent Host sessions inside the container

Now enable the VS Code setting that exposes the Dev Container execution target to the Agents window. Open Settings, search for agent host dev container, and turn on chat.agentHost.devContainer.enabled. You can also place the setting directly in your VS Code settings JSON:

{
"chat.agentHost.devContainer.enabled": true
}

The current VS Code settings reference lists this option with a default value of false. It controls whether eligible local folders show the Use Dev Container choice for Agent Host sessions. Because the feature is still rolling out, the setting may need to be enabled manually even after updating to 1.138. 

Start the first agent session inside the project container

Open the Agents window and select New. In the workspace picker, find your local project and open its folder menu, then choose Use Dev Container. VS Code changes the workspace label to show that the session is targeting a Dev Container; you can switch back to Use Local before starting if you change your mind. After selecting the available agent harness, enter a small coding request and submit it. 

Add a subtract(a, b) function to index.js.

Add tests for positive, negative, and zero values.

Run npm test after making the changes.

Report the files changed and the test result.

The useful part of this prompt is that it asks for both implementation and verification. The agent has to modify the repository, execute the project's test command, and report the result. Because the session is running in the Dev Container, those commands execute in the container's environment. You can confirm this yourself by asking the agent to run node --version and then checking the value against the Node.js version available from the container image. 

If the agent completes the task and npm test passes, the core setup is working. If it says the environment lacks a command that exists on your host machine, that is often useful evidence rather than a failure of the feature: it means the agent is actually seeing the container's toolchain. Install the required dependency in the Dev Container configuration, rebuild the container, and run the test again rather than quietly adding host-specific assumptions to the project.

Make the container match the project's real toolchain

A minimal image is enough for the first experiment, but production repositories usually require more than Node.js. A Python service might need a particular Python version and system libraries, a Rust project might need a Rust toolchain and native build packages, and a full-stack repository may need both a backend and frontend environment. Dev Containers support prebuilt images, Dockerfiles, Docker Compose configurations, features, extensions, forwarded ports, and post-create commands, so the configuration can grow with the repository. 

For example, a project that installs dependencies after the container is created can use postCreateCommand:

{
"name": "Node.js Agent Demo",
"image": "mcr.microsoft.com/devcontainers/javascript-node:24-bookworm",
"remoteUser": "node",
"postCreateCommand": "npm install"
}

That changes the workflow in a useful way. Instead of telling the agent to repair missing dependencies every time a session starts, you make the environment itself responsible for establishing the expected prerequisites. VS Code's Dev Containers documentation specifically supports postCreateCommand for commands that should run after the container is created. When you change devcontainer.json, the associated Dockerfile, or Compose configuration, VS Code documents rebuilding the container so the updated environment takes effect. 

Keep agent permissions separate from environment isolation

A container is not a substitute for permission controls. VS Code has a separate permission system for potentially risky agent operations, including terminal commands, and its current security guidance recommends reviewing how commands and tools are approved. Agent sandboxing and Dev Containers address different layers: the sandbox can constrain terminal subprocesses, while a Dev Container can isolate the broader development environment, including tools, files, and network access available inside that environment. ([Visual Studio Code][5])

This becomes especially important when the agent works on a repository containing secrets, deployment credentials, private configuration, or scripts with destructive side effects. A container can reduce exposure, but you should still decide which commands the agent can run automatically and which ones should require approval. VS Code also warns that prompt injection can arrive through untrusted project files or other content the agent reads, so treating every repository as trusted just because it is running inside a container defeats part of the security model. ([Visual Studio Code][5])

Know the Dev Container limitations before you depend on it

VS Code's current Agent window documentation has a specific limitation that is easy to miss: Dev Container sessions work directly in the container workspace and cannot be combined with New Worktree. A Git worktree is a separate working directory linked to the same repository, commonly used to isolate parallel changes. If your workflow depends on automatically creating an isolated worktree for every agent session, selecting Dev Container changes that workflow rather than combining both isolation mechanisms. ([Visual Studio Code][4])

Another practical issue is Git identity. During testing of the 1.138 Dev Container agent feature, a VS Code issue documented that a containerized Agent Host did not inherit the Git author identity configured on the host, which caused a baseline checkpoint to fail before a commit could be created. The same issue reports that setting a repository-local Git identity allowed the commit operation to succeed. That is a concrete reminder that a container has its own environment; configuration you take for granted on the host may not automatically exist inside it. ([GitHub][6])

git config user.name "Your Name"
git config user.email "[you@example.com](mailto:you@example.com)"

Check other environment assumptions in the same way. Verify Git configuration, package managers, compiler versions, environment variables, credential helpers, and any tools the project's tests expect. When the agent reports that a command is missing, first determine whether the tool is absent from the container rather than assuming the model made a coding mistake.

Use the container when reproducibility matters more than convenience

The strongest use case for this feature is a project where the development environment already has a clear definition. When the repository specifies its runtime, system dependencies, tooling, and setup commands, placing the agent inside that environment reduces one source of mismatch between what the agent tests and what the project expects. That is especially useful when several developers work on the same repository or when an AI agent repeatedly runs builds and tests in the background. ([Visual Studio Code][7])

For a small personal script, a local session may be simpler because there is less environment setup to maintain. For a larger repository, the opposite can be true: the few minutes spent defining the container can save repeated debugging caused by missing tools or different dependency versions. The key is to keep the container configuration part of the project rather than treating it as hidden machine setup.

Once the basic flow works, the next useful upgrade is to make the container reproduce the commands used by continuous integration, the automated system that builds and tests your code on each change. Then the agent can edit code, run those same project checks, and report failures against a development environment that is defined in source control. The result is not a guarantee that the agent's code is correct, but it gives you a much clearer answer to a more practical question: was the code tested in the environment this repository actually expects?