CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>Dev Container metadata reference</title> <meta name="description" content="The devcontainer.json file contains any needed metadata and settings required to configurate a development container for a given well-defined tool and runtim...">  <link rel="stylesheet" href="/css/bootswatch/cosmo/bootstrap.min.css"> <link rel="stylesheet" href="/css/fontawesome-all.min.css"> <link rel="stylesheet" href="/css/main.css"> <link rel="shortcut icon" href="/img/favicon.ico"> <meta name="theme-color" content="#2753E3"> <link rel="canonical" href="https://devcontainers.github.io/implementors/json_reference/"> <link rel="alternate" type="application/rss+xml" title="Development containers" href="https://devcontainers.github.io/feed.xml" /> </head> <body> <div id='cookie-banner'></div> <header class="navbar navbar-expand-lg navbar-dark bg-primary -navbar"> <div class="container navbar-container"> <a class="navbar-brand" href="/"> <h1>Development Containers</h1> </a> <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation"> <span class="navbar-toggler-icon"></span> </button> <div class="navbar-collapse collapse" id="navbarSupportedContent" role="navigation" aria-label="Top Level"> <ul class="navbar-nav ml-auto"> <li class="nav-item" > <a class="nav-link" href='/overview'>Overview</a> </li>  <li class="nav-item" > <a class="nav-link" href="/implementors/json_reference">Reference</a> </li> <li class="nav-item active" > <a class="nav-link" href="/implementors/spec/">Specification</a> </li> <li class="nav-item" > <a class="nav-link" href='/supporting'>Supporting Tools</a> </li> <li class="nav-item" > <a class="nav-link" href='/guides'>Guides</a> </li> <li class="nav-item" > <a class="nav-link" href='/features'>Available Features</a> </li> <li class="nav-item" > <a class="nav-link" href='/templates'>Available Templates</a> </li> <li class="nav-item" > <a class="nav-link" href='/collections'>Collections</a> </li> </ul> </div> </div> </header> <div class="page-content"> <div class="wrapper"> <div class="container"> <div class="row single-page"> <div class="col-lg-2 d-none d-lg-block dap-sidebar"> <div class="card"> <ul class="nav flex-column list-unstyled"> <li class="nav-item" > <a class="nav-link" href="/implementors/spec/"> Specification </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/reference/"> Reference Implementation </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/json_schema/"> devcontainer.json schema </a> </li> <li class="nav-item active" > <a class="nav-link" href="/implementors/json_reference/"> Dev Container metadata reference </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/features/"> Features </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/features-distribution/"> Features distribution </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/templates/"> Templates </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/templates-distribution/"> Templates distribution </a> </li> <li class="nav-item" > <a class="nav-link" href="/implementors/contributing/"> Contributing </a> </li> </ul> </div> </div> <div class="col-md-12 col-lg-10" role="navigation" aria-label="Main"> <nav id="small-nav" class="docs-nav d-lg-none"> <h4>Topics</h4> <select id="small-nav-dropdown"> <option value="/implementors/spec/" >Specification</option> <option value="/implementors/reference/" >Reference Implementation</option> <option value="/implementors/json_schema/" >devcontainer.json schema</option> <option value="/implementors/json_reference/" selected >Dev Container metadata reference</option> <option value="/implementors/features/" >Features</option> <option value="/implementors/features-distribution/" >Features distribution</option> <option value="/implementors/templates/" >Templates</option> <option value="/implementors/templates-distribution/" >Templates distribution</option> <option value="/implementors/contributing/" >Contributing</option> </select> </nav> <h1>Specification</h1> <h2>Dev Container metadata reference</h2> <div id="markdown-content-container"><p>The <code class="language-plaintext highlighter-rouge">devcontainer.json</code> file contains any needed metadata and settings required to configurate a <strong>development container</strong> for a given well-defined tool and runtime stack. It can be used by <a href="../../supporting">tools and services that support the dev container spec</a> to create a <strong>development environment</strong> that contains one or more <strong>development containers</strong>.</p> <p>Metadata properties marked with a 🏷️️ can be stored in the <code class="language-plaintext highlighter-rouge">devcontainer.metadata</code> <strong><a href="/implementors/reference/#labels">container image label</a></strong> in addition to <code class="language-plaintext highlighter-rouge">devcontainer.json</code>. This label can contain an array of json snippets that will be automatically merged with <code class="language-plaintext highlighter-rouge">devcontainer.json</code> contents (if any) when a container is created.</p> <h2 id="-general-devcontainerjson-properties-"><a href="#general-properties" name="general-properties" class="anchor"> General devcontainer.json properties </a></h2> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Property</th> <th style="text-align: left">Type</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">name</code></td> <td style="text-align: left">string</td> <td style="text-align: left">A name for the dev container displayed in the UI.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">forwardPorts</code> 🏷️</td> <td style="text-align: left">array</td> <td style="text-align: left">An array of port numbers or <code class="language-plaintext highlighter-rouge">"host:port"</code> values (e.g. <code class="language-plaintext highlighter-rouge">[3000, "db:5432"]</code>) that should always be forwarded from inside the primary container to the local machine (including on the web). The property is most useful for forwarding ports that cannot be auto-forwarded because the related process that starts before the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting service / tool connects or for forwarding a service not in the primary container in Docker Compose scenarios (e.g. <code class="language-plaintext highlighter-rouge">"db:5432"</code>). Defaults to <code class="language-plaintext highlighter-rouge">[]</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">portsAttributes</code> 🏷️</td> <td style="text-align: left">object</td> <td style="text-align: left">Object that maps a port number, <code class="language-plaintext highlighter-rouge">"host:port"</code> value, range, or regular expression to a set of default options. See <a href="#port-attributes">port attributes</a> for available options. For example: <br /><code class="language-plaintext highlighter-rouge">"portsAttributes": {"3000": {"label": "Application port"}}</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">otherPortsAttributes</code> 🏷️</td> <td style="text-align: left">object</td> <td style="text-align: left">Default options for ports, port ranges, and hosts that aren’t configured using <code class="language-plaintext highlighter-rouge">portsAttributes</code>. See <a href="#port-attributes">port attributes</a> for available options. For example: <br /> <code class="language-plaintext highlighter-rouge">"otherPortsAttributes": {"onAutoForward": "silent"}</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">containerEnv</code> 🏷️</td> <td style="text-align: left">object</td> <td style="text-align: left">A set of name-value pairs that sets or overrides environment variables for the container. Environment and <a href="#variables-in-devcontainerjson">pre-defined variables</a> may be referenced in the values. For example:<br /> <code class="language-plaintext highlighter-rouge">"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }</code><br /> If you want to reference an existing container variable while setting this one (like updating the <code class="language-plaintext highlighter-rouge">PATH</code>), use <code class="language-plaintext highlighter-rouge">remoteEnv</code> instead. <br /> <code class="language-plaintext highlighter-rouge">containerEnv</code> will set the variable on the Docker container itself, so all processes spawned in the container will have access to it. But it will also be static for the life of the container - you must rebuild the container to update the value. <br /> We recommend using <code class="language-plaintext highlighter-rouge">containerEnv</code> (over <code class="language-plaintext highlighter-rouge">remoteEnv</code>) as much as possible since it allows all processes to see the variable and isn’t client-specific.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">remoteEnv</code> 🏷️</td> <td style="text-align: left">object</td> <td style="text-align: left">A set of name-value pairs that sets or overrides environment variables for the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting service / tool (or sub-processes like terminals) but not the container as a whole. Environment and <a href="#variables-in-devcontainerjson">pre-defined variables</a> may be referenced in the values. <br /> You may want to use <code class="language-plaintext highlighter-rouge">remoteEnv</code> (over <code class="language-plaintext highlighter-rouge">containerEnv</code>) if the value isn’t static since you can update its value without having to rebuild the full container.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">remoteUser</code> 🏷️</td> <td style="text-align: left">string</td> <td style="text-align: left">Overrides the user that <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services tools / runs as in the container (along with sub-processes like terminals, tasks, or debugging). Does not change the user the container as a whole runs as which can be set using <code class="language-plaintext highlighter-rouge">containerUser</code>. Defaults to the user the container as a whole is running as (often <code class="language-plaintext highlighter-rouge">root</code>). <br /> You may learn more in the <a href="#remoteUser">remoteUser section below</a>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">containerUser</code> 🏷️</td> <td style="text-align: left">string</td> <td style="text-align: left">Overrides the user for all operations run as inside the container. Defaults to either <code class="language-plaintext highlighter-rouge">root</code> or the last <code class="language-plaintext highlighter-rouge">USER</code> instruction in the related Dockerfile used to create the image. If you want any connected tools or related processes to use a different user than the one for the container, see <code class="language-plaintext highlighter-rouge">remoteUser</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">updateRemoteUserUID</code> 🏷️</td> <td style="text-align: left">boolean</td> <td style="text-align: left">On Linux, if <code class="language-plaintext highlighter-rouge">containerUser</code> or <code class="language-plaintext highlighter-rouge">remoteUser</code> is specified, the user’s UID/GID will be updated to match the local user’s UID/GID to avoid permission problems with bind mounts. Defaults to <code class="language-plaintext highlighter-rouge">true</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">userEnvProbe</code> 🏷️</td> <td style="text-align: left">enum</td> <td style="text-align: left">Indicates the type of shell to use to “probe” for user environment variables to include in <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services’ / tools’ processes: <code class="language-plaintext highlighter-rouge">none</code>, <code class="language-plaintext highlighter-rouge">interactiveShell</code>, <code class="language-plaintext highlighter-rouge">loginShell</code>, or <code class="language-plaintext highlighter-rouge">loginInteractiveShell</code> (default). The specific shell used is based on the default shell for the user (typically bash). For example, bash interactive shells will typically include variables set in <code class="language-plaintext highlighter-rouge">/etc/bash.bashrc</code> and <code class="language-plaintext highlighter-rouge">~/.bashrc</code> while login shells usually include variables from <code class="language-plaintext highlighter-rouge">/etc/profile</code> and <code class="language-plaintext highlighter-rouge">~/.profile</code>. Setting this property to <code class="language-plaintext highlighter-rouge">loginInteractiveShell</code> will get variables from all four files.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">overrideCommand</code> 🏷️</td> <td style="text-align: left">boolean</td> <td style="text-align: left">Tells <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools whether they should run <code class="language-plaintext highlighter-rouge">/bin/sh -c "while sleep 1000; do :; done"</code> when starting the container instead of the container’s default command (since the container can shut down if the default command fails). Set to <code class="language-plaintext highlighter-rouge">false</code> if the default command must run for the container to function properly. Defaults to <code class="language-plaintext highlighter-rouge">true</code> for when using an image Dockerfile and <code class="language-plaintext highlighter-rouge">false</code> when referencing a Docker Compose file.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">shutdownAction</code> 🏷️</td> <td style="text-align: left">enum</td> <td style="text-align: left">Indicates whether <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting tools should stop the containers when the related tool window is closed / shut down.<br />Values are <code class="language-plaintext highlighter-rouge">none</code>, <code class="language-plaintext highlighter-rouge">stopContainer</code> (default for image or Dockerfile), and <code class="language-plaintext highlighter-rouge">stopCompose</code> (default for Docker Compose).</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">init</code> 🏷️</td> <td style="text-align: left">boolean</td> <td style="text-align: left">Defaults to <code class="language-plaintext highlighter-rouge">false</code>. Cross-orchestrator way to indicate whether the <a href="https://github.com/krallin/tini">tini init process</a> should be used to help deal with zombie processes.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">privileged</code> 🏷️</td> <td style="text-align: left">boolean</td> <td style="text-align: left">Defaults to <code class="language-plaintext highlighter-rouge">false</code>. Cross-orchestrator way to cause the container to run in privileged mode (<code class="language-plaintext highlighter-rouge">--privileged</code>). Required for things like Docker-in-Docker, but has security implications particularly when running directly on Linux.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">capAdd</code> 🏷️</td> <td style="text-align: left">array</td> <td style="text-align: left">Defaults to <code class="language-plaintext highlighter-rouge">[]</code>. Cross-orchestrator way to add capabilities typically disabled for a container. Most often used to add the <code class="language-plaintext highlighter-rouge">ptrace</code> capability required to debug languages like C++, Go, and Rust. For example: <br /><code class="language-plaintext highlighter-rouge">"capAdd": ["SYS_PTRACE"]</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">securityOpt</code> 🏷️</td> <td style="text-align: left">array</td> <td style="text-align: left">Defaults to <code class="language-plaintext highlighter-rouge">[]</code>. Cross-orchestrator way to set container security options. For example: <br /> <code class="language-plaintext highlighter-rouge">"securityOpt": [ "seccomp=unconfined" ]</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">mounts</code> 🏷️</td> <td style="text-align: left">string or object</td> <td style="text-align: left">Defaults to unset. Cross-orchestrator way to add additional mounts to a container. Each value is a string that accepts the same values as the <a href="https://docs.docker.com/engine/reference/commandline/run/#mount">Docker CLI <code class="language-plaintext highlighter-rouge">--mount</code> flag</a>. Environment and <a href="#variables-in-devcontainerjson">pre-defined variables</a> may be referenced in the value. For example:<br /><code class="language-plaintext highlighter-rouge">"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }]</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">features</code></td> <td style="text-align: left">object</td> <td style="text-align: left">An object of <a href="../../features">Dev Container Feature IDs</a> and related options to be added into your primary container. The specific options that are available varies by feature, so see its documentation for additional details. For example: <br /><code class="language-plaintext highlighter-rouge">"features": { "ghcr.io/devcontainers/features/github-cli": {} }</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">overrideFeatureInstallOrder</code></td> <td style="text-align: left">array</td> <td style="text-align: left">By default, Features will attempt to automatically set the order they are installed based on a <code class="language-plaintext highlighter-rouge">installsAfter</code> property within each of them. This property allows you to override the Feature install order when needed. For example: <br /><code class="language-plaintext highlighter-rouge">"overrideFeatureInstallОrder": [ "ghcr.io/devcontainers/features/common-utils", "ghcr.io/devcontainers/features/github-cli" ]</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">customizations</code> 🏷️</td> <td style="text-align: left">object</td> <td style="text-align: left">Product specific properties, defined in <a href="../../supporting">supporting tools</a></td> </tr> </tbody> </table> <h2 id="-scenario-specific-properties-"><a href="#scenario-specific" name="scenario-specific" class="anchor"> Scenario specific properties </a></h2> <p>The focus of <code class="language-plaintext highlighter-rouge">devcontainer.json</code> is to describe how to enrich a container for the purposes of development rather than acting as a multi-container orchestrator format. Instead, container orchestrator formats can be referenced when needed to manage multiple containers and their lifecycles. Today, <code class="language-plaintext highlighter-rouge">devcontainer.json</code> includes scenario specific properties for working without a container orchestrator (by directly referencing an image or Dockerfile) and for using Docker Compose as a simple multi-container orchestrator.</p> <h3 id="-image-or-dockerfile-specific-properties-"><a href="#image-specific" name="image-specific" class="anchor"> Image or Dockerfile specific properties </a></h3> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Property</th> <th style="text-align: left">Type</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">image</code></td> <td style="text-align: left">string</td> <td style="text-align: left"><strong>Required</strong> when using an image. The name of an image in a container registry (<a href="https://hub.docker.com">DockerHub</a>, <a href="https://docs.github.com/packages/guides/about-github-container-registry">GitHub Container Registry</a>, <a href="https://azure.microsoft.com/services/container-registry/">Azure Container Registry</a>) that <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools should use to create the dev container.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">build.dockerfile</code></td> <td style="text-align: left">string</td> <td style="text-align: left"><strong>Required</strong> when using a Dockerfile. The location of a <a href="https://docs.docker.com/engine/reference/builder/">Dockerfile</a> that defines the contents of the container. The path is relative to the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> file.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">build.context</code></td> <td style="text-align: left">string</td> <td style="text-align: left">Path that the Docker build should be run from relative to <code class="language-plaintext highlighter-rouge">devcontainer.json</code>. For example, a value of <code class="language-plaintext highlighter-rouge">".."</code> would allow you to reference content in sibling directories. Defaults to <code class="language-plaintext highlighter-rouge">"."</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">build.args</code></td> <td style="text-align: left">Object</td> <td style="text-align: left">A set of name-value pairs containing <a href="https://docs.docker.com/engine/reference/commandline/build/#build-arg">Docker image build arguments</a> that should be passed when building a Dockerfile. Environment and <a href="#variables-in-devcontainerjson">pre-defined variables</a> may be referenced in the values. Defaults to not set. For example: <code class="language-plaintext highlighter-rouge">"build": { "args": { "MYARG": "MYVALUE", "MYARGFROMENVVAR": "${localEnv:VARIABLE_NAME}" } }</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">build.options</code></td> <td style="text-align: left">array</td> <td style="text-align: left">An array of <a href="https://docs.docker.com/engine/reference/commandline/build/#options">Docker image build options</a> that should be passed to the build command when building a Dockerfile. Defaults to <code class="language-plaintext highlighter-rouge">[]</code>. For example: <code class="language-plaintext highlighter-rouge">"build": { "options": [ "--add-host=host.docker.internal:host-gateway" ] }</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">build.target</code></td> <td style="text-align: left">string</td> <td style="text-align: left">A string that specifies a <a href="https://docs.docker.com/engine/reference/commandline/build/#target">Docker image build target</a> that should be passed when building a Dockerfile. Defaults to not set. For example: <code class="language-plaintext highlighter-rouge">"build": { "target": "development" }</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">build.cacheFrom</code></td> <td style="text-align: left">string,<br />array</td> <td style="text-align: left">A string or array of strings that specify one or more images to use as caches when building the image. Cached image identifiers are passed to the <code class="language-plaintext highlighter-rouge">docker build</code> command with <code class="language-plaintext highlighter-rouge">--cache-from</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">appPort</code></td> <td style="text-align: left">integer,<br />string,<br />array</td> <td style="text-align: left">In most cases, we recommend using the new <a href="#general-properties">forwardPorts property</a>. This property accepts a port or array of ports that should be published locally when the container is running. Unlike <code class="language-plaintext highlighter-rouge">forwardPorts</code>, your application may need to listen on all interfaces (<code class="language-plaintext highlighter-rouge">0.0.0.0</code>) not just <code class="language-plaintext highlighter-rouge">localhost</code> for it to be available externally. Defaults to <code class="language-plaintext highlighter-rouge">[]</code>.<br />Learn more about publishing vs forwarding ports <a href="#publishing-vs-forwarding-ports">here</a>.<br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">workspaceMount</code></td> <td style="text-align: left">string</td> <td style="text-align: left">Requires <code class="language-plaintext highlighter-rouge">workspaceFolder</code> be set as well. Overrides the default local mount point for the workspace when the container is created. Supports the same values as the <a href="https://docs.docker.com/engine/reference/commandline/run/#mount">Docker CLI <code class="language-plaintext highlighter-rouge">--mount</code> flag</a>. Environment and <a href="#variables-in-devcontainerjson">pre-defined variables</a> may be referenced in the value. For example: <br /><code class="language-plaintext highlighter-rouge">"workspaceMount": "source=${localWorkspaceFolder}/sub-folder,target=/workspace,type=bind,consistency=cached", "workspaceFolder": "/workspace"</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">workspaceFolder</code></td> <td style="text-align: left">string</td> <td style="text-align: left">Requires <code class="language-plaintext highlighter-rouge">workspaceMount</code> be set. Sets the default path that <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools should open when connecting to the container. Defaults to the automatic source code mount location.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">runArgs</code></td> <td style="text-align: left">array</td> <td style="text-align: left">An array of <a href="https://docs.docker.com/engine/reference/commandline/run/">Docker CLI arguments</a> that should be used when running the container. Defaults to <code class="language-plaintext highlighter-rouge">[]</code>. For example, this allows ptrace based debuggers like C++ to work in the container:<br /> <code class="language-plaintext highlighter-rouge">"runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ]</code> .</td> </tr> </tbody> </table> <h3 id="-docker-compose-specific-properties-"><a href="#compose-specific" name="compose-specific" class="anchor"> Docker Compose specific properties </a></h3> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Property</th> <th style="text-align: left">Type</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">dockerComposeFile</code></td> <td style="text-align: left">string,<br />array</td> <td style="text-align: left"><strong>Required</strong> when using <a href="https://docs.docker.com/compose/">Docker Compose</a>. Path or an ordered list of paths to Docker Compose files relative to the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> file. Using an array is useful <a href="https://docs.docker.com/compose/extends/#multiple-compose-files">when extending your Docker Compose configuration</a>. The order of the array matters since the contents of later files can override values set in previous ones.<br />The default <code class="language-plaintext highlighter-rouge">.env</code> file is picked up from the root of the project, but you can use <code class="language-plaintext highlighter-rouge">env_file</code> in your Docker Compose file to specify an alternate location.<br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">service</code></td> <td style="text-align: left">string</td> <td style="text-align: left"><strong>Required</strong> when using <a href="https://docs.docker.com/compose/">Docker Compose</a>. The name of the service <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools should connect to once running.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">runServices</code></td> <td style="text-align: left">array</td> <td style="text-align: left">An array of services in your Docker Compose configuration that should be started by <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools. These will also be stopped when you disconnect unless <code class="language-plaintext highlighter-rouge">"shutdownAction"</code> is <code class="language-plaintext highlighter-rouge">"none"</code>. Defaults to all services.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">workspaceFolder</code></td> <td style="text-align: left">string</td> <td style="text-align: left">Sets the default path that <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools should open when connecting to the container (which is often the path to a volume mount where the source code can be found in the container). Defaults to <code class="language-plaintext highlighter-rouge">"/"</code>.</td> </tr> </tbody> </table> <h2 id="-tool-specific-properties-"><a href="#tool-specific" name="tool-specific" class="anchor"> Tool-specific properties </a></h2> <p>While most properties apply to any <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting tool or service, a few are specific to certain tools. You may explore this in the <a href="../../supporting">supporting tools and services document</a>.</p> <h2 id="-lifecycle-scripts-"><a href="#lifecycle-scripts" name="lifecycle-scripts" class="anchor"> Lifecycle scripts </a></h2> <p>When creating or working with a dev container, you may need different commands to be run at different points in the container’s lifecycle. The table below lists a set of command properties you can use to update what the container’s contents in the order in which they are run (for example, <code class="language-plaintext highlighter-rouge">onCreateCommand</code> will run after <code class="language-plaintext highlighter-rouge">initializeCommand</code>). Each command property is an string or list of command arguments that should execute from the <code class="language-plaintext highlighter-rouge">workspaceFolder</code>.</p> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Property</th> <th style="text-align: left">Type</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">initializeCommand</code></td> <td style="text-align: left">string,<br />array,<br />object</td> <td style="text-align: left">A command string or list of command arguments to run on the <strong>host machine</strong> during initialization, including during container creation and on subsequent starts. The command may run more than once during a given session.<br /><br /> ⚠️ The command is run wherever the source code is located on the host. For cloud services, this is in the cloud.<br /><br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array vs object properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">onCreateCommand</code> 🏷️</td> <td style="text-align: left">string,<br />array,<br />object</td> <td style="text-align: left">This command is the first of three (along with <code class="language-plaintext highlighter-rouge">updateContentCommand</code> and <code class="language-plaintext highlighter-rouge">postCreateCommand</code>) that finalizes container setup when a dev container is created. It and subsequent commands execute <strong>inside</strong> the container immediately after it has started for the first time.<br /><br /> Cloud services can use this command when caching or prebuilding a container. This means that it will not typically have access to user-scoped assets or secrets.<br /><br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array vs object properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">updateContentCommand</code> 🏷️</td> <td style="text-align: left">string,<br />array,<br />object</td> <td style="text-align: left">This command is the second of three that finalizes container setup when a dev container is created. It executes inside the container after <code class="language-plaintext highlighter-rouge">onCreateCommand</code> whenever new content is available in the source tree during the creation process.<br /><br />It will execute at least once, but cloud services will also periodically execute the command to refresh cached or prebuilt containers. Like cloud services using <code class="language-plaintext highlighter-rouge">onCreateCommand</code>, it can only take advantage of repository and org scoped secrets or permissions.<br /><br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array vs object properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">postCreateCommand</code> 🏷️</td> <td style="text-align: left">string,<br />array,<br />object</td> <td style="text-align: left">This command is the last of three that finalizes container setup when a dev container is created. It happens after <code class="language-plaintext highlighter-rouge">updateContentCommand</code> and once the dev container has been assigned to a user for the first time.<br /><br />Cloud services can use this command to take advantage of user specific secrets and permissions.<br /><br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array vs object properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">postStartCommand</code> 🏷️</td> <td style="text-align: left">string,<br />array,<br />object</td> <td style="text-align: left">A command to run each time the container is successfully started.<br /><br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array vs object properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">postAttachCommand</code> 🏷️</td> <td style="text-align: left">string,<br />array,<br />object</td> <td style="text-align: left">A command to run each time a tool has successfully attached to the container.<br /><br />Note that the array syntax will execute the command without a shell. You can <a href="#formatting-string-vs-array-properties">learn more</a> about formatting string vs array vs object properties.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">waitFor</code> 🏷️</td> <td style="text-align: left">enum</td> <td style="text-align: left">An enum that specifies the command any tool should wait for before connecting. Defaults to <code class="language-plaintext highlighter-rouge">updateContentCommand</code>. This allows you to use <code class="language-plaintext highlighter-rouge">onCreateCommand</code> or <code class="language-plaintext highlighter-rouge">updateContentCommand</code> for steps that must happen before <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting tools connect while still using <code class="language-plaintext highlighter-rouge">postCreateCommand</code> for steps that can happen behind the scenes afterwards.</td> </tr> </tbody> </table> <p>For each command property, if the value is a single string, it will be run in <code class="language-plaintext highlighter-rouge">/bin/sh</code>. Use <code class="language-plaintext highlighter-rouge">&&</code> in a string to execute multiple commands. For example, <code class="language-plaintext highlighter-rouge">"yarn install"</code> or <code class="language-plaintext highlighter-rouge">"apt-get update && apt-get install -y curl"</code>. The array syntax <code class="language-plaintext highlighter-rouge">["yarn", "install"]</code> will invoke the command (in this case <code class="language-plaintext highlighter-rouge">yarn</code>) directly without using a shell. Each fires after your source code has been mounted, so you can also run shell scripts from your source tree. For example: <code class="language-plaintext highlighter-rouge">bash scripts/install-dev-tools.sh</code>.</p> <p>If one of the lifecycle scripts fails, any subsequent scripts will not be executed. For instance, if <code class="language-plaintext highlighter-rouge">postCreateCommand</code> fails, <code class="language-plaintext highlighter-rouge">postStartCommand</code> and any following scripts will be skipped.</p> <h2 id="-minimum-host-requirements-"><a href="#min-host-reqs" name="min-host-reqs" class="anchor"> Minimum host requirements </a></h2> <p>While <code class="language-plaintext highlighter-rouge">devcontainer.json</code> does not focus on hardware or VM provisioning, it can be useful to know your container’s minimum RAM, CPU, and storage requirements. This is what the <code class="language-plaintext highlighter-rouge">hostRequirements</code> properties allow you to do. Cloud services can use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met.</p> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Property</th> <th style="text-align: left">Type</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">hostRequirements.cpus</code> 🏷️</td> <td style="text-align: left">integer</td> <td style="text-align: left">Indicates the minimum required number of CPUs / virtual CPUs / cores. For example: <code class="language-plaintext highlighter-rouge">"hostRequirements": {"cpus": 2}</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">hostRequirements.memory</code> 🏷️</td> <td style="text-align: left">string</td> <td style="text-align: left">A string indicating minimum memory requirements with a <code class="language-plaintext highlighter-rouge">tb</code>, <code class="language-plaintext highlighter-rouge">gb</code>, <code class="language-plaintext highlighter-rouge">mb</code>, or <code class="language-plaintext highlighter-rouge">kb</code> suffix. For example, <code class="language-plaintext highlighter-rouge">"hostRequirements": {"memory": "4gb"}</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">hostRequirements.storage</code> 🏷️</td> <td style="text-align: left">string</td> <td style="text-align: left">A string indicating minimum storage requirements with a <code class="language-plaintext highlighter-rouge">tb</code>, <code class="language-plaintext highlighter-rouge">gb</code>, <code class="language-plaintext highlighter-rouge">mb</code>, or <code class="language-plaintext highlighter-rouge">kb</code> suffix. For example, <code class="language-plaintext highlighter-rouge">"hostRequirements": {"storage": "32gb"}</code></td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">hostRequirements.gpu</code> 🏷️</td> <td style="text-align: left">boolean,<br />string,<br />object</td> <td style="text-align: left">Indicates if any GPU is required. A boolean indicates if a GPU is required or not. The string <code class="language-plaintext highlighter-rouge">"optional"</code> indicates that a GPU is used when available, but is not required.<br /><br />The object syntax specifies how much GPU resources are required. The <code class="language-plaintext highlighter-rouge">cores</code> property indicates the minimum number of cores and the <code class="language-plaintext highlighter-rouge">memory</code> property indicates minimum storage requirements with a <code class="language-plaintext highlighter-rouge">tb</code>, <code class="language-plaintext highlighter-rouge">gb</code>, <code class="language-plaintext highlighter-rouge">mb</code>, or <code class="language-plaintext highlighter-rouge">kb</code> suffix. For example, <code class="language-plaintext highlighter-rouge">"gpu": { "cores": 1000, "storage": "32gb" }</code></td> </tr> </tbody> </table> <h2 id="-port-attributes-"><a href="#port-attributes" name="port-attributes" class="anchor"> Port attributes </a></h2> <p>The <code class="language-plaintext highlighter-rouge">portsAttributes</code> and <code class="language-plaintext highlighter-rouge">otherPortsAttributes</code> properties allow you to map default port options for one or more manually or automatically forwarded ports. The following is a list of options that can be set in the configuration object assigned to the property.</p> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Property</th> <th style="text-align: left">Type</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">label</code> 🏷️</td> <td style="text-align: left">string</td> <td style="text-align: left">Display name for the port in the ports view. Defaults to not set.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">protocol</code> 🏷️</td> <td style="text-align: left">enum</td> <td style="text-align: left">Controls protocol handling for forwarded ports. When not set, the port is assumed to be a raw TCP stream which, if forwarded to <code class="language-plaintext highlighter-rouge">localhost</code>, supports any number of protocols. However, if the port is forwarded to a web URL (e.g. from a cloud service on the web), only HTTP ports in the container are supported. Setting this property to <code class="language-plaintext highlighter-rouge">https</code> alters handling by ignoring any SSL/TLS certificates present when communicating on the port and using the correct certificate for the forwarded URL instead (e.g <code class="language-plaintext highlighter-rouge">https://*.githubpreview.dev</code>). If set to <code class="language-plaintext highlighter-rouge">http</code>, processing is the same as if the protocol is not set. Defaults to not set.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">onAutoForward</code> 🏷️</td> <td style="text-align: left">enum</td> <td style="text-align: left">Controls what should happen when a port is auto-forwarded once you’ve connected to the container. <code class="language-plaintext highlighter-rouge">notify</code> is the default, and a notification will appear when the port is auto-forwarded. If set to <code class="language-plaintext highlighter-rouge">openBrowser</code>, the port will be opened in the system’s default browser. A value of <code class="language-plaintext highlighter-rouge">openBrowserOnce</code> will open the browser only once. <code class="language-plaintext highlighter-rouge">openPreview</code> will open the URL in <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services’ / tools’ embedded preview browser. A value of <code class="language-plaintext highlighter-rouge">silent</code> will forward the port, but take no further action. A value of <code class="language-plaintext highlighter-rouge">ignore</code> means that this port should not be auto-forwarded at all.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">requireLocalPort</code> 🏷️</td> <td style="text-align: left">boolean</td> <td style="text-align: left">Dictates when port forwarding is required to map the port in the container to the same port locally or not. If set to <code class="language-plaintext highlighter-rouge">false</code>, the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools will attempt to use the specified port forward to <code class="language-plaintext highlighter-rouge">localhost</code>, and silently map to a different one if it is unavailable. If set to <code class="language-plaintext highlighter-rouge">true</code>, you will be notified if it is not possible to use the same port. Defaults to <code class="language-plaintext highlighter-rouge">false</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">elevateIfNeeded</code> 🏷️</td> <td style="text-align: left">boolean</td> <td style="text-align: left">Forwarding low ports like 22, 80, or 443 to <code class="language-plaintext highlighter-rouge">localhost</code> on the same port from <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting services / tools may require elevated permissions on certain operating systems. Setting this property to <code class="language-plaintext highlighter-rouge">true</code> will automatically try to elevate the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting tool’s permissions in this situation. Defaults to <code class="language-plaintext highlighter-rouge">false</code>.</td> </tr> </tbody> </table> <h2 id="-formatting-string-vs-array-properties-"><a href="#formatting-string-vs-array-properties" name="formatting-string-vs-array-properties" class="anchor"> Formatting string vs. array properties </a></h2> <p>The format of certain properties will vary depending on the involvement of a shell.</p> <p><code class="language-plaintext highlighter-rouge">postCreateCommand</code>, <code class="language-plaintext highlighter-rouge">postStartCommand</code>, <code class="language-plaintext highlighter-rouge">postAttachCommand</code>, and <code class="language-plaintext highlighter-rouge">initializeCommand</code> all have 3 types:</p> <ul> <li>Array: Passed to the OS for execution without going through a shell</li> <li>String: Goes through a shell (it needs to be parsed into command and arguments)</li> <li>Object: All lifecycle scripts have been extended to support <code class="language-plaintext highlighter-rouge">object</code> types to allow for <a href="https://containers.dev/implementors/spec/#parallel-exec">parallel execution</a></li> </ul> <p><code class="language-plaintext highlighter-rouge">runArgs</code> only has the array type. Using <code class="language-plaintext highlighter-rouge">runArgs</code> via a typical command line, you’ll need single quotes if the shell runs into parameters with spaces. However, these single quotes aren’t passed on to the executable. Thus, in your <code class="language-plaintext highlighter-rouge">devcontainer.json</code>, you’d follow the array format and leave out the single quotes:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nl">"runArgs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"--device-cgroup-rule=my rule here"</span><span class="p">]</span><span class="w"> </span></code></pre></div></div> <p>Rather than:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nl">"runArgs"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"--device-cgroup-rule='my rule here'"</span><span class="p">]</span><span class="w"> </span></code></pre></div></div> <p>We can compare the string, array, and object versions of <code class="language-plaintext highlighter-rouge">postAttachCommand</code> as well. You can use the following string format, which will remove the single quotes as part of the shell’s parsing:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nl">"postAttachCommand"</span><span class="p">:</span><span class="w"> </span><span class="s2">"echo foo='bar'"</span><span class="w"> </span></code></pre></div></div> <p>By contrast, the array format will keep the single quotes and write them to standard out (you can see the output in the dev container log):</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nl">"postAttachCommand"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"echo"</span><span class="p">,</span><span class="w"> </span><span class="s2">"foo='bar'"</span><span class="p">]</span><span class="w"> </span></code></pre></div></div> <p>Finally, you may use an object format:</p> <div class="language-json highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nl">"postAttachCommand"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="nl">"server"</span><span class="p">:</span><span class="w"> </span><span class="s2">"npm start"</span><span class="p">,</span><span class="w"> </span><span class="nl">"db"</span><span class="p">:</span><span class="w"> </span><span class="p">[</span><span class="s2">"mysql"</span><span class="p">,</span><span class="w"> </span><span class="s2">"-u"</span><span class="p">,</span><span class="w"> </span><span class="s2">"root"</span><span class="p">,</span><span class="w"> </span><span class="s2">"-p"</span><span class="p">,</span><span class="w"> </span><span class="s2">"my database"</span><span class="p">]</span><span class="w"> </span><span class="p">}</span><span class="w"> </span><span class="p">}</span><span class="w"> </span></code></pre></div></div> <h2 id="-variables-in-devcontainerjson-"><a href="#variables-in-devcontainerjson" name="variables-in-devcontainerjson" class="anchor"> Variables in devcontainer.json </a></h2> <p>Variables can be referenced in certain string values in <code class="language-plaintext highlighter-rouge">devcontainer.json</code> in the following format: <strong>${variableName}</strong>. The following is a list of available variables you can use.</p> <table class="table table-bordered"> <thead> <tr> <th style="text-align: left">Variable</th> <th style="text-align: left">Properties</th> <th style="text-align: left">Description</th> </tr> </thead> <tbody> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${localEnv:VARIABLE_NAME}</code></td> <td style="text-align: left">Any</td> <td style="text-align: left">Value of an environment variable on the <strong>host machine</strong> (in the examples below, called <code class="language-plaintext highlighter-rouge">VARIABLE_NAME</code>). Unset variables are left blank. <br /><br /> ⚠️ Clients (like VS Code) may need to be <strong>restarted</strong> to pick up newly set variables. <br /><br /> ⚠️ For a cloud service, the host is in the cloud rather than your local machine. <br /><br /> <strong>Examples</strong> <br /><br /> <strong>1.</strong> Set a variable containing your local home folder on Linux / macOS or the user folder on Windows:<br /> <code class="language-plaintext highlighter-rouge">"remoteEnv": { "LOCAL_USER_PATH": "${localEnv:HOME}${localEnv:USERPROFILE}" }</code>. <br /><br /> A default value for when the environment variable is not set can be given with <code class="language-plaintext highlighter-rouge">${localEnv:VARIABLE_NAME:default_value}</code>. <br /><br /> <strong>2.</strong> In modern versions of macOS, default configurations allow setting local variables with the command <code class="language-plaintext highlighter-rouge">echo 'export VARIABLE_NAME=my-value' >> ~/.zshenv</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${containerEnv:VARIABLE_NAME}</code></td> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">remoteEnv</code></td> <td style="text-align: left">Value of an existing environment variable inside the container once it is up and running (in this case, called <code class="language-plaintext highlighter-rouge">VARIABLE_NAME</code>). For example:<br /> <code class="language-plaintext highlighter-rouge">"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }</code> <br /><br /> A default value for when the environment variable is not set can be given with <code class="language-plaintext highlighter-rouge">${containerEnv:VARIABLE_NAME:default_value}</code>.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${localWorkspaceFolder}</code></td> <td style="text-align: left">Any</td> <td style="text-align: left">Path of the local folder that was opened in the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting service / tool (that contains <code class="language-plaintext highlighter-rouge">.devcontainer/devcontainer.json</code>).</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${containerWorkspaceFolder}</code></td> <td style="text-align: left">Any</td> <td style="text-align: left">The path that the workspaces files can be found in the container.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${localWorkspaceFolderBasename}</code></td> <td style="text-align: left">Any</td> <td style="text-align: left">Name of the local folder that was opened in the <code class="language-plaintext highlighter-rouge">devcontainer.json</code> supporting service / tool (that contains <code class="language-plaintext highlighter-rouge">.devcontainer/devcontainer.json</code>).</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${containerWorkspaceFolderBasename}</code></td> <td style="text-align: left">Any</td> <td style="text-align: left">Name of the folder where the workspace files can be found in the container.</td> </tr> <tr> <td style="text-align: left"><code class="language-plaintext highlighter-rouge">${devcontainerId}</code></td> <td style="text-align: left">Any</td> <td style="text-align: left">Allow Features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.<br /> The properties supporting it in devcontainer.json are: <code class="language-plaintext highlighter-rouge">name</code>, <code class="language-plaintext highlighter-rouge">runArgs</code>, <code class="language-plaintext highlighter-rouge">initializeCommand</code>, <code class="language-plaintext highlighter-rouge">onCreateCommand</code>, <code class="language-plaintext highlighter-rouge">updateContentCommand</code>, <code class="language-plaintext highlighter-rouge">postCreateCommand</code>, <code class="language-plaintext highlighter-rouge">postStartCommand</code>, <code class="language-plaintext highlighter-rouge">postAttachCommand</code>, <code class="language-plaintext highlighter-rouge">workspaceFolder</code>, <code class="language-plaintext highlighter-rouge">workspaceMount</code>, <code class="language-plaintext highlighter-rouge">mounts</code>, <code class="language-plaintext highlighter-rouge">containerEnv</code>, <code class="language-plaintext highlighter-rouge">remoteEnv</code>, <code class="language-plaintext highlighter-rouge">containerUser</code>, <code class="language-plaintext highlighter-rouge">remoteUser</code>, and <code class="language-plaintext highlighter-rouge">customizations</code>.</td> </tr> </tbody> </table> <h2 id="-schema-"><a href="#schema" name="schema" class="anchor"> Schema </a></h2> <p>You can see the dev container schema <a href="https://github.com/devcontainers/spec/blob/main/schemas/devContainer.base.schema.json">here</a>.</p> <h2 id="-publishing-vs-forwarding-ports-"><a href="#publishing-vs-forwarding-ports" name="publishing-vs-forwarding-ports" class="anchor"> Publishing vs forwarding ports </a></h2> <p>Docker has the concept of “publishing” ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from <code class="language-plaintext highlighter-rouge">localhost</code>, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like <code class="language-plaintext highlighter-rouge">localhost</code> to the application.</p> <h2 id="-remoteuser-"><a href="#remoteUser" name="remoteUser" class="anchor"> remoteUser </a></h2> <p>A dev container configuration will inherit the <code class="language-plaintext highlighter-rouge">remoteUser</code> property from the base image it uses.</p> <p>Using the <a href="https://github.com/devcontainers/images">images</a> and <a href="https://github.com/devcontainers/templates">Templates</a> part of the spec as an example: <code class="language-plaintext highlighter-rouge">remoteUser</code> in these images is set to a custom value - you may view an example in the <a href="https://github.com/devcontainers/images/blob/main/src/cpp/.devcontainer/devcontainer.json#L26">C++ image</a>. The <a href="https://github.com/devcontainers/templates/tree/main/src/cpp">C++ Template</a> will then inherit the custom <code class="language-plaintext highlighter-rouge">remoteUser</code> value from <a href="https://github.com/devcontainers/templates/blob/main/src/cpp/.devcontainer/Dockerfile#L1">its base C++ image</a>.</p> </div> </div>  </div> </div> </div> </div> </div> <footer class="footer"> <script> function manageConsent() { if (WcpConsent.siteConsent.isConsentRequired) { WcpConsent.siteConsent.manageConsent(); } } </script> <div class="container"> <div class="row"> <div class="col-sm-10"> <ul class="links"> <li> <a class="github-button" href="https://github.com/devcontainers/spec" data-icon="octicon-star" data-show-count="true" aria-label="Star devcontainers/spec on GitHub">Star</a> </li> <li> <a class="github-button" href="https://github.com/devcontainers/spec/subscription" aria-label="Watch devcontainers/spec on GitHub">Watch</a> </li> </ul> </div> <div class="col-sm-2"> <ul class="links"> <li style="display: none;" > <a id="footer-cookie-link" style="cursor: pointer; padding-right:20px" onclick="manageConsent()" aria-label="Manage cookies">Manage cookies</a> </li> <li> <div class="copyright"> <a id="footer-microsoft-link" class="logo" href="https://www.microsoft.com"> <img src="/img/microsoft-logo-inverted.png" height="20" alt="Microsoft"> </a> <span>© 2024 Microsoft</span> </div> </li> </ul> </div> </div> </div> </footer> <script> var baseurl = '' </script> <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>  <script src="https://wcpstatic.microsoft.com/mscc/lib/v2/wcp-consent.js"></script>  <script async src="https://www.googletagmanager.com/gtag/js?id=UA-62780441-30"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.3/umd/popper.min.js" integrity="sha384-vFJXuSJphROIrBnz7yo7oB41mKfc8JzQZiCq4NCceLEaO4IHwicKwpJf9c9IpFgh" crossorigin="anonymous"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0-beta.2/js/bootstrap.min.js" integrity="sha384-alpBpkh1PFOepccYVYDB4do5UnbKysX5WZXm3XxPqe5iKTfUKjNkCk9SaVuEZflJ" crossorigin="anonymous"></script> <script async defer src="https://buttons.github.io/buttons.js"></script> <script src="/js/page.js"></script> </body> </html>