Devcontainer Configuration Reference

This is a reproduction of the full devcontainer.json specification, as supported by devconcurrent, with our customizations included. It is formatted as TOML, but the same options can be set as JSON in devcontainer.json.

See the reference spec for more details.

dockerComposeFile — The name of the docker-compose file(s) used to start the services.
service — The service you want to work on.
runServices — An array of services that should be started and stopped.
workspaceFolder — The path of the workspace folder inside the container.
shutdownAction — Action to take when the user disconnects from the primary container in their editor.
overrideCommand — Whether to overwrite the command specified in the image.
$schema — The JSON schema of the devcontainer.json file.
name — A name for the dev container which can be displayed to the user.
features — Features to add to the dev container.
overrideFeatureInstallOrder — Array consisting of the Feature id (without the semantic version) of Features in the order the user wants them to be installed.
secrets — Recommended secrets for this dev container.
forwardPorts — Ports that can be forwarded from the host to the container.
portsAttributes.<name> — Settings to apply to forwardPorts.
- portsAttributes.<name>.onAutoForward
- portsAttributes.<name>.elevateIfNeeded
- portsAttributes.<name>.label
- portsAttributes.<name>.protocol
- portsAttributes.<name>.requireLocalPort
otherPortsAttributes — Default settings for forwardPorts.
- otherPortsAttributes.onAutoForward
- otherPortsAttributes.elevateIfNeeded
- otherPortsAttributes.label
- otherPortsAttributes.protocol
- otherPortsAttributes.requireLocalPort
updateRemoteUserUID — Controls whether on Linux the container’s user should be updated with the local user’s UID and GID.
containerEnv.<name> — Container environment variables.
containerUser — The user the container will be started with.
mounts — Mounts to setup on container create.
- mounts[].type
- mounts[].source — A string that may contain ${...} variable substitutions.
- mounts[].target — A string that may contain ${...} variable substitutions.
init — Passes the –init flag when creating the dev container.
privileged — Passes the –privileged flag when creating the dev container.
capAdd — Passes docker capabilities to include when creating the dev container.
securityOpt — Passes docker security options to include when creating the dev container.
remoteEnv.<name> — Remote environment variables to set for processes spawned in the container including lifecycle scripts and any remote editor/IDE server process.
remoteUser — The username to use for spawning processes in the container including lifecycle scripts and any remote editor/IDE server process.
initializeCommand — A command to run locally (i.e Your host machine, cloud VM) before anything else.
- initializeCommand.<name> — A command as written in config, before ${...} substitution.
onCreateCommand — A command to run when creating the container.
- onCreateCommand.<name> — A command as written in config, before ${...} substitution.
updateContentCommand — A command to run when creating the container and rerun when the workspace content was updated while creating the container.
- updateContentCommand.<name> — A command as written in config, before ${...} substitution.
postCreateCommand — A command to run after creating the container.
- postCreateCommand.<name> — A command as written in config, before ${...} substitution.
postStartCommand — A command to run after starting the container.
- postStartCommand.<name> — A command as written in config, before ${...} substitution.
postAttachCommand — A command to run when attaching to the container.
- postAttachCommand.<name> — A command as written in config, before ${...} substitution.
waitFor — The user command to wait for before continuing execution in the background while the UI is starting up.
userEnvProbe — User environment probe to run.
hostRequirements — Host hardware requirements.
- hostRequirements.cpus — Number of required CPUs.
- hostRequirements.memory — Amount of required RAM in bytes.
- hostRequirements.storage — Amount of required disk space in bytes.
- hostRequirements.gpu
customizations — Tool-specific configuration.
- customizations.devconcurrent
  - customizations.devconcurrent.worktreeFolder — The directory where devconcurrent will place worktrees.
  - customizations.devconcurrent.mountGit — Whether to mount the project’s git directory into each workspace’s devcontainer.
  - customizations.devconcurrent.proxy — Configure DNS hostnames and HTTP proxy.
    - customizations.devconcurrent.proxy.enable — Enable the devconcurrent DNS and HTTP proxy for this project.
    - customizations.devconcurrent.proxy.hostname — Handlebars template for the proxied hostname, used by every service that does not set its own.
    - customizations.devconcurrent.proxy.services.<name> — Configure proxy settings for each docker compose service.
      - customizations.devconcurrent.proxy.services.<name>.hostname — Handlebars template for this service’s hostname.
      - customizations.devconcurrent.proxy.services.<name>.httpProxyPort — If set, devconcurrent will run an HTTP proxy on ports 80 and 443 to this port in your container, performing TLS termination on 443.
  - customizations.devconcurrent.env.<name> — Define shell variables

`dockerComposeFile`

The name of the docker-compose file(s) used to start the services.

Type: string | array<string>

Default: []

`service`

The service you want to work on. This is considered the primary container for your dev environment which your editor will connect to.

Type: string

`runServices`

An array of services that should be started and stopped.

Type: array<string>

`workspaceFolder`

The path of the workspace folder inside the container. This is typically the target path of a volume mount in the docker-compose.yml.

Type: string

`shutdownAction`

Action to take when the user disconnects from the primary container in their editor. The default is to stop all of the compose containers.

Type: string

Values: "none", "stopCompose"

Default: "stopCompose"

`overrideCommand`

Whether to overwrite the command specified in the image. The default is false.

Type: boolean

Default: false

`$schema`

The JSON schema of the devcontainer.json file.

Type: string

`name`

A name for the dev container which can be displayed to the user.

Type: string

`features`

Features to add to the dev container. Ignored by devconcurrent.

Type: object

`overrideFeatureInstallOrder`

Array consisting of the Feature id (without the semantic version) of Features in the order the user wants them to be installed. Ignored by devconcurrent.

Type: array<string>

Default: []

`secrets`

Recommended secrets for this dev container. Ignored by devconcurrent.

Type: object

`forwardPorts`

Ports that can be forwarded from the host to the container.

Type: array<integer | string>

Default: []

`portsAttributes.<name>`

Settings to apply to forwardPorts. Ignored by devconcurrent.

Type: object

`portsAttributes.<name>.onAutoForward`

Type: string

Values: "notify", "openBrowser", "openBrowserOnce", "openPreview", "silent", "ignore"

Default: "notify"

`portsAttributes.<name>.elevateIfNeeded`

Type: boolean

Default: false

`portsAttributes.<name>.label`

Type: string

Default: "Application"

`portsAttributes.<name>.protocol`

Type: string

Values: "http", "https"

Default: "http"

`portsAttributes.<name>.requireLocalPort`

Type: boolean

Default: false

`otherPortsAttributes`

Default settings for forwardPorts. Ignored by devconcurrent.

Type: object

`otherPortsAttributes.onAutoForward`

Type: string

Values: "notify", "openBrowser", "openBrowserOnce", "openPreview", "silent", "ignore"

Default: "notify"

`otherPortsAttributes.elevateIfNeeded`

Type: boolean

Default: false

`otherPortsAttributes.label`

Type: string

Default: "Application"

`otherPortsAttributes.protocol`

Type: string

Values: "http", "https"

Default: "http"

`otherPortsAttributes.requireLocalPort`

Type: boolean

Default: false

`updateRemoteUserUID`

Controls whether on Linux the container’s user should be updated with the local user’s UID and GID. On by default when opening from a local folder.

Type: boolean

`containerEnv.<name>`

Container environment variables.

Type: string

`containerUser`

The user the container will be started with. The default is the user on the Docker image.

Type: string

`mounts`

Mounts to setup on container create.

Type: array<string | object>

Default: []

`mounts[].type`

Type: string

Values:

"bind" — A bind mount from the host filesystem.
"volume" — A named Docker volume.

Required: yes

`mounts[].source`

A string that may contain ${...} variable substitutions. Supported variables: ${localEnv:VAR[:default]} (alias ${env:VAR[:default]}), ${containerEnv:VAR[:default]}, ${localWorkspaceFolder}, ${containerWorkspaceFolder}, ${localWorkspaceFolderBasename}, ${containerWorkspaceFolderBasename}, ${devcontainerId}. https://containers.dev/implementors/json_reference/#variables-in-devcontainerjson

Type: string

`mounts[].target`

Type: string

Required: yes

`init`

Passes the –init flag when creating the dev container.

Type: boolean

`privileged`

Passes the –privileged flag when creating the dev container.

Type: boolean

`capAdd`

Passes docker capabilities to include when creating the dev container.

Type: array<string>

Default: []

`securityOpt`

Passes docker security options to include when creating the dev container.

Type: array<string>

Default: []

`remoteEnv.<name>`

Remote environment variables to set for processes spawned in the container including lifecycle scripts and any remote editor/IDE server process.

Type: string

`remoteUser`

The username to use for spawning processes in the container including lifecycle scripts and any remote editor/IDE server process. The default is the same user as the container.

Type: string

`initializeCommand`

A command to run locally (i.e Your host machine, cloud VM) before anything else. This command is run before “onCreateCommand”.

Type: string | array<string> | object

`initializeCommand.<name>`

A command as written in config, before ${...} substitution.

Type: string | array<string>

`onCreateCommand`

A command to run when creating the container. This command is run after “initializeCommand” and before “updateContentCommand”.

Type: string | array<string> | object

`onCreateCommand.<name>`

A command as written in config, before ${...} substitution.

Type: string | array<string>

`updateContentCommand`

A command to run when creating the container and rerun when the workspace content was updated while creating the container. This command is run after “onCreateCommand” and before “postCreateCommand”.

Type: string | array<string> | object

`updateContentCommand.<name>`

A command as written in config, before ${...} substitution.

Type: string | array<string>

`postCreateCommand`

A command to run after creating the container. This command is run after “updateContentCommand” and before “postStartCommand”.

Type: string | array<string> | object

`postCreateCommand.<name>`

A command as written in config, before ${...} substitution.

Type: string | array<string>

`postStartCommand`

A command to run after starting the container. This command is run after “postCreateCommand” and before “postAttachCommand”.

Type: string | array<string> | object

`postStartCommand.<name>`

A command as written in config, before ${...} substitution.

Type: string | array<string>

`postAttachCommand`

A command to run when attaching to the container. This command is run after “postStartCommand”.

Type: string | array<string> | object

`postAttachCommand.<name>`

A command as written in config, before ${...} substitution.

Type: string | array<string>

`waitFor`

The user command to wait for before continuing execution in the background while the UI is starting up.

Type: string

Values: "initializeCommand", "onCreateCommand", "updateContentCommand", "postCreateCommand", "postStartCommand"

Default: "updateContentCommand"

`userEnvProbe`

User environment probe to run.

Type: string

Values:

"none" — Do not probe the user’s shell for environment variables.
"loginShell" — Probe with a login shell (-lc).
"loginInteractiveShell" — Probe with a login, interactive shell (-lic).
"interactiveShell" — Probe with an interactive shell (-ic).

Default: "loginInteractiveShell"

`hostRequirements`

Host hardware requirements.

Type: object

`hostRequirements.cpus`

Number of required CPUs.

Type: integer

Default: 1

`hostRequirements.memory`

Amount of required RAM in bytes. Supports units tb, gb, mb and kb.

Type: string

`hostRequirements.storage`

Amount of required disk space in bytes. Supports units tb, gb, mb and kb.

Type: string

`hostRequirements.gpu`

Type: boolean | string | object

Default: false

`customizations`

Tool-specific configuration. Each tool should use a JSON object subproperty with a unique name to group its customizations.

Type: object

`customizations.devconcurrent`

Type: object

`customizations.devconcurrent.worktreeFolder`

The directory where devconcurrent will place worktrees.

Type: string

`customizations.devconcurrent.mountGit`

Whether to mount the project’s git directory into each workspace’s devcontainer.

Git worktrees have a simple .git file that points to the actual .git directory. If that directory isn’t available, then no git commands will work. By mounting it at its original path in the devcontainer, git should just work, both inside and out of the container.

Type: boolean

Default: true

`customizations.devconcurrent.proxy`

Configure DNS hostnames and HTTP proxy.

Type: object

`customizations.devconcurrent.proxy.enable`

Enable the devconcurrent DNS and HTTP proxy for this project.

Type: boolean

Default: false

`customizations.devconcurrent.proxy.hostname`

Handlebars template for the proxied hostname, used by every service that does not set its own.

Available variables:

root (bool) — whether this is the root workspace
project — project name
workspace — workspace name
service — name of the service from compose

Type: string

Default: "{{workspace}}.{{service}}.test"

Type: integer

`customizations.devconcurrent.env.<name>`

Define shell variables

These are rendered by dc show env or automatically set if shell.exportEnv is true.

The values are given by handlebars templates with the following:

The hostname helper gives the hostname for a service.
The following variables are populated: project, workspace, and root.

Type: string

Example:

{
  "BASE_URL": "{{ hostname 'app' }}",
  "DATABASE_URL": "postgres://postgres:postgres@{{hostname 'postgres'}}:5432/db"
}

Keyboard shortcuts

devconcurrent