Can't use '--ssh default' in devcontainer.json's build options

[arntanguy]

I have a Dockerfile that needs to pull private git repositories at build time. I tried to forward the ssh-agent using

"build": {
              "dockerfile": "Dockerfile",		
               "options": [
			"--ssh default"
		]
}

In conjuction with RUN --mount=type=ssh in the docker file.

Doing

docker build --ssh default .

works as expected (including the ssh-agent forwarding).

However doing

devcontainer build --workspace-folder . --config devcontainer.json        

Fails with the following output: unknown flag: --ssh default

 devcontainer build --workspace-folder . --config devcontainer.json                                                                                                                     1 ↵
[7 ms] @devcontainers/cli 0.76.0. Node.js v24.0.1. linux 6.11.0-26-generic x64.
[2263 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/node:1'...
[4762 ms] Resolving Feature dependencies for 'ghcr.io/duduribeiro/devcontainer-features/neovim:1.0.1'...
[5461 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/github-cli'...
[6519 ms] Resolving Feature dependencies for 'ghcr.io/georgofenbeck/features/lazygit-linuxbinary:1'...
[6862 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/common-utils'...
[7121 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/git'...
[8506 ms] Files to omit: ''
[8918 ms] Files to omit: ''
[9196 ms] Files to omit: ''
[9583 ms] Files to omit: ''
[9882 ms] Files to omit: ''
[10244 ms] Files to omit: ''
[10253 ms] Start: Run: docker buildx build --load --build-arg BUILDKIT_INLINE_CACHE=1 -f /tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390/Dockerfile-with-features -t vsc-cdadance-release-b1a5b21f19b3bef64833189f9297127357ab665c4fafe4e106bd31a32e132c94 --target dev_containers_target_stage --ssh default --build-context dev_containers_feature_content_source=/tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390 --build-arg _DEV_CONTAINERS_BASE_IMAGE=build --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp /home/arnaud/devel/demo-cdadance-superbuild
unknown flag: --ssh default

Usage:  docker buildx build [OPTIONS] PATH | URL | -

Run 'docker buildx build --help' for more information
Error: Command failed: docker buildx build --load --build-arg BUILDKIT_INLINE_CACHE=1 -f /tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390/Dockerfile-with-features -t vsc-cdadance-release-b1a5b21f19b3bef64833189f9297127357ab665c4fafe4e106bd31a32e132c94 --target dev_containers_target_stage --ssh default --build-context dev_containers_feature_content_source=/tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390 --build-arg _DEV_CONTAINERS_BASE_IMAGE=build --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp /home/arnaud/devel/demo-cdadance-superbuild
    at y6 (/home/arnaud/.nvm/versions/node/v24.0.1/lib/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:468:1933)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async dw (/home/arnaud/.nvm/versions/node/v24.0.1/lib/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:467:1886)
    at async k7 (/home/arnaud/.nvm/versions/node/v24.0.1/lib/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:667:2203)
    at async R7 (/home/arnaud/.nvm/versions/node/v24.0.1/lib/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:666:4937)
    at async /home/arnaud/.nvm/versions/node/v24.0.1/lib/node_modules/@devcontainers/cli/dist/spec-node/devContainersSpecCLI.js:484:1188
{"outcome":"error","message":"Command failed: docker buildx build --load --build-arg BUILDKIT_INLINE_CACHE=1 -f /tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390/Dockerfile-with-features -t vsc-cdadance-release-b1a5b21f19b3bef64833189f9297127357ab665c4fafe4e106bd31a32e132c94 --target dev_containers_target_stage --ssh default --build-context dev_containers_feature_content_source=/tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390 --build-arg _DEV_CONTAINERS_BASE_IMAGE=build --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp /home/arnaud/devel/demo-cdadance-superbuild","description":"An error occurred building the image."}

What's odd is that if I take the exact command that devcontainer-cli is running above and run it manually in the same terminal, everything works as expected:

╰─$ docker buildx build --load --build-arg BUILDKIT_INLINE_CACHE=1 -f /tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390/Dockerfile-with-features -t vsc-cdadance-release-b1a5b21f19b3bef64833189f9297127357ab665c4fafe4e106bd31a32e132c94 --target dev_containers_target_stage --ssh default --build-context dev_containers_feature_content_source=/tmp/devcontainercli-arnaud/container-features/0.76.0-1749132768390 --build-arg _DEV_CONTAINERS_BASE_IMAGE=build --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp /home/arnaud/devel/demo-cdadance-superbuild
[+] Building 11.2s (20/25)                                                                                                                                                      docker:default
 => [internal] load build definition from Dockerfile-with-features                                                                                                                        0.0s
 => => transferring dockerfile: 8.88kB                                                                                                                                                    0.0s
 => resolve image config for docker-image://docker.io/docker/dockerfile:1.4                                                                                                               0.4s
 => CACHED docker-image://docker.io/docker/dockerfile:1.4@sha256:9ba7531bd80fb0a858632727cf7a112fbfd19b17e94c4e84ced81e24ef1a0dbc                                                         0.0s
 => [internal] load .dockerignore                                                                                                                                                         0.0s
 => => transferring context: 137B                                                                                                                                                         0.0s
 => [internal] load metadata for docker.io/library/ubuntu:jammy                                                                                                                           0.4s
 => [context dev_containers_feature_content_source] load .dockerignore                                                                                                                    0.0s
 => => transferring dev_containers_feature_content_source: 2B                                                                                                                             0.0s
 => [context dev_containers_feature_content_source] load from client                                                                                                                      0.0s
 => => transferring dev_containers_feature_content_source: 2.62kB                                                                                                                         0.0s
 => [build 1/7] FROM docker.io/library/ubuntu:jammy@sha256:01a3ee0b5e413cefaaffc6abe68c9c37879ae3cced56a8e088b1649e5b269eee                                                               0.0s
 => CACHED [build 2/7] RUN export DEBIAN_FRONTEND=noninteractive                                                                                                                          0.0s
 => CACHED [build 3/7] RUN ln -snf /usr/share/zoneinfo/Europe/Paris /etc/localtime && echo Europe/Paris > /etc/timezone                                                                   0.0s
 => CACHED [build 4/7] RUN rm -f /etc/apt/apt.conf.d/docker-clean                                                                                                                         0.0s
 => [build 5/7] RUN  --mount=type=cache,target=/var/cache/apt  apt-get update  && apt-get install -y --no-install-recommends sudo gnupg2 gpg-agent openssh-server  && rm -rf /var/lib/ap  6.6s
 => [build 6/7] RUN useradd -ms /bin/zsh vscode &&     usermod -aG sudo vscode     && echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers     && echo "User vscode (uid=`id -u vscode`:g  1.0s 
 => [build 7/7] RUN --mount=type=ssh ssh-add -l 

For good measure here is the devcontainer.json file

{
  "name": "mc-rtc-superbuild-jammy-build",

  "build": {
    "dockerfile": "Dockerfile",
    "context": "../../..",
    "options": [
      "--ssh default"
    ]
  },

  "containerEnv": {
    "DISPLAY": "${localEnv:DISPLAY}",
  },

  "mounts": [
    "source=/tmp/.X11-unix,target=/tmp/.X11-unix,type=bind,consistency=cached",
    "source=${localEnv:HOME}${localEnv:USERPROFILE}/docker-ws/mc-rtc-superbuild-jammy,target=/home/vscode/workspace,type=bind,consistency=cached"
  ],

  "features":
  {
    "ghcr.io/devcontainers/features/node:1": {},
    "ghcr.io/duduribeiro/devcontainer-features/neovim:1.0.1": {},
    "ghcr.io/devcontainers/features/github-cli": { "version": "latest" },
    "ghcr.io/georgofenbeck/features/lazygit-linuxbinary:1": { "version": "latest" }
  },

  "customizations": {
      "vscode": {
          "extensions": [
            "twxs.cmake",
            "ms-vscode.cmake-tools",
            "josetr.cmake-language-support-vscode",
            "ms-vscode.cpptools",
            "ms-vscode.docker",
            "ms-vscode.cpptools-extension-pack",
            "ms-vscode-remote.remote-containers",
            "ms-python.python",
            "GitHub.vscode-github-actions"
          ]
      }
  },

  "postCreateCommand": "~/superbuild/.devcontainer/setupShell.sh",

  "runArgs": [
    "--network=host",
  ],

  "remoteUser": "vscode",
  "workspaceMount": "source=${localWorkspaceFolder},target=/home/vscode/superbuild,type=bind",
  "workspaceFolder": "/home/vscode/superbuild"
}

What's going on here? My guess is something related to buildkit environment somehow being different when running from within the devcontainer-cli's node?

If I replace `--ssh default` with `--help` instead, it indeed seems to exist:

devcontainer build --workspace-folder . --config devcontainer.json                                                                                                                     1 ↵
[5 ms] @devcontainers/cli 0.76.0. Node.js v24.0.1. linux 6.11.0-26-generic x64.
[2212 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/node:1'...
[3468 ms] Resolving Feature dependencies for 'ghcr.io/duduribeiro/devcontainer-features/neovim:1.0.1'...
[6542 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/github-cli'...
[10290 ms] Resolving Feature dependencies for 'ghcr.io/georgofenbeck/features/lazygit-linuxbinary:1'...
[10579 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/common-utils'...
[10817 ms] Resolving Feature dependencies for 'ghcr.io/devcontainers/features/git'...
[11685 ms] Files to omit: ''
[12096 ms] Files to omit: ''
[12464 ms] Files to omit: ''
[12850 ms] Files to omit: ''
[13123 ms] Files to omit: ''
[13488 ms] Files to omit: ''
[13499 ms] Start: Run: docker buildx build --load --build-arg BUILDKIT_INLINE_CACHE=1 -f /tmp/devcontainercli-arnaud/container-features/0.76.0-1749133247772/Dockerfile-with-features -t vsc-cdadance-release-b1a5b21f19b3bef64833189f9297127357ab665c4fafe4e106bd31a32e132c94 --target dev_containers_target_stage --help --build-context dev_containers_feature_content_source=/tmp/devcontainercli-arnaud/container-features/0.76.0-1749133247772 --build-arg _DEV_CONTAINERS_BASE_IMAGE=build --build-arg _DEV_CONTAINERS_IMAGE_USER=root --build-arg _DEV_CONTAINERS_FEATURE_CONTENT_SOURCE=dev_container_feature_content_temp /home/arnaud/devel/demo-cdadance-superbuild
Start a build

Usage:  docker buildx build [OPTIONS] PATH | URL | -

Start a build

Aliases:
  docker build, docker builder build, docker image build, docker buildx b

Options:
      --add-host strings              Add a custom host-to-IP mapping (format: "host:ip")
      --allow stringArray             Allow extra privileged entitlement (e.g., "network.host", "security.insecure")
      --annotation stringArray        Add annotation to the image
      --attest stringArray            Attestation parameters (format: "type=sbom,generator=image")
      --build-arg stringArray         Set build-time variables
      --build-context stringArray     Additional build contexts (e.g., name=path)
      --builder string                Override the configured builder instance
      --cache-from stringArray        External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")
      --cache-to stringArray          Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")
      --call string                   Set method for evaluating build ("check", "outline", "targets") (default "build")
      --cgroup-parent string          Set the parent cgroup for the "RUN" instructions during build
      --check                         Shorthand for "--call=check" (default )
  -D, --debug                         Enable debug logging
  -f, --file string                   Name of the Dockerfile (default: "PATH/Dockerfile")
      --iidfile string                Write the image ID to a file
      --label stringArray             Set metadata for an image
      --load                          Shorthand for "--output=type=docker"
      --metadata-file string          Write build result metadata to a file
      --network string                Set the networking mode for the "RUN" instructions during build (default "default")
      --no-cache                      Do not use cache when building the image
      --no-cache-filter stringArray   Do not cache specified stages
  -o, --output stringArray            Output destination (format: "type=local,dest=path")
      --platform stringArray          Set target platform for build
      --progress string               Set type of progress output ("auto", "quiet", "plain", "tty", "rawjson"). Use plain to show container output (default "auto")
      --provenance string             Shorthand for "--attest=type=provenance"
      --pull                          Always attempt to pull all referenced images
      --push                          Shorthand for "--output=type=registry"
  -q, --quiet                         Suppress the build output and print image ID on success
      --sbom string                   Shorthand for "--attest=type=sbom"
      --secret stringArray            Secret to expose to the build (format: "id=mysecret[,src=/local/secret]")
      --shm-size bytes                Shared memory size for build containers
      --ssh stringArray               SSH agent socket or keys to expose to the build (format: "default|<id>[=<socket>|<key>[,<key>]]")
  -t, --tag stringArray               Name and optionally a tag (format: "name:tag")
      --target string                 Set the target build stage to build
      --ulimit ulimit                 Ulimit options (default [])

Experimental commands and flags are hidden. Set BUILDX_EXPERIMENTAL=1 to show them.
{"outcome":"success","imageName":["vsc-cdadance-release-b1a5b21f19b3bef64833189f9297127357ab665c4fafe4e106bd31a32e132c94"]}

Thanks in advance for your help, and thanks for the project!

[Kaniska244]

Hello @arntanguy ,

Thank you for reporting this issue. I think it should work for you if you use --ssh=default instead of --ssh default. I understand that the latter works locally but perhaps because of docker buildkit version or configuration only the former works with devcontainer cli. Kindly let me know in case of further concern.

  "build": {
    "context": ".",
    "dockerfile": "Dockerfile",
    "options": [
			"--ssh=default"
		]		
  }

Additional info if required to setup ssh default setting.

[arntanguy]

It does work indeed, strange that it'd behave differently in devcontainer cli than using docker cli directly.
Anyhow, thanks for your input!