Use Dev Proxy in dev containers and GitHub Codespaces

At a glance
Goal: Install Dev Proxy in a dev container or GitHub Codespaces
Time: 10 minutes
Prerequisites: A project with a devcontainer.json file, Docker or GitHub Codespaces

If you develop in a dev container or in GitHub Codespaces, you can install Dev Proxy by using the Dev Proxy Dev Container Feature. The Feature installs Dev Proxy in the container and, after the container is created, generates a Dev Proxy root certificate unique to the container and trusts it. You don't need to follow the first run steps to trust the certificate yourself.

Add the Dev Proxy Feature to your dev container

To install Dev Proxy in your dev container, add the Dev Proxy Feature to the features section of your .devcontainer/devcontainer.json file:

{
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {}
  }
}

Rebuild the container, or create a new codespace, to apply the change. After the container starts, verify that Dev Proxy is installed:

devproxy --version

Note

The Feature is versioned separately from Dev Proxy. ghcr.io/dotnet/dev-proxy/dev-proxy:1 refers to version 1 of the Feature. To choose which version of Dev Proxy to install, use the version option.

Configure the Feature

The Feature supports the following options:

Option Description Type Default
version Dev Proxy version to install: latest, beta, or a specific version like 4.0.0 or v4.0.0. string latest
trustCertificate After the container is created, generate a Dev Proxy root certificate unique to the container and trust it system-wide and for common runtimes. boolean true

For example, to install a specific version of Dev Proxy, use the following configuration:

{
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {
      "version": "4.0.0"
    }
  }
}

To try the latest preview features, set version to beta. When you install a beta version, the Feature also adds the devproxy-beta command.

If you use Dev Proxy in a shared dev container configuration, consider pinning Dev Proxy to a specific version, instead of latest or beta. This way, you ensure that everyone working on the project uses the same version of Dev Proxy.

How the Feature handles the root certificate

Dev Proxy uses a root certificate to decrypt HTTPS traffic. The Feature doesn't generate the certificate when it builds the image. If it did, the certificate and its private key would end up in an image layer, and everyone using the same image or Codespaces prebuild would share the same trusted certificate authority.

Instead, after the container is created (postCreateCommand), the Feature:

  1. Runs devproxy cert ensure as the remote user to generate a root certificate unique to the container.
  2. Adds the certificate to the system certificate store (/usr/local/share/ca-certificates), so that curl, .NET, and other tools that use the system store trust it.

Some runtimes don't use the system certificate store, so the Feature sets the following environment variables to point them to the system CA bundle (/etc/ssl/certs/ca-certificates.crt):

Variable Used by
NODE_EXTRA_CA_CERTS Node.js
REQUESTS_CA_BUNDLE Python requests
SSL_CERT_FILE Python and other OpenSSL-based tools

To trust the certificate, the Feature installs a root-owned helper script and allows the remote user to run it with sudo without a password. If you don't want the Feature to generate and trust the certificate, set trustCertificate to false:

{
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {
      "trustCertificate": false
    }
  }
}

Important

The Feature doesn't configure Java keystores, so Java apps don't trust the Dev Proxy root certificate.

Python 3.13 and newer enable strict certificate verification, which rejects the certificates that Dev Proxy v3 and earlier generate for intercepted hosts. To call APIs through Dev Proxy from Python 3.13 or newer, use Dev Proxy v4 or newer.

Use Dev Proxy in the dev container

The Feature doesn't start Dev Proxy, and it doesn't set the HTTP_PROXY or HTTPS_PROXY environment variables for the whole container. Container-wide proxy variables would route package managers, git, and VS Code's own traffic through Dev Proxy, which breaks them when Dev Proxy isn't running.

To use Dev Proxy, start it in a terminal in the dev container with your configuration file:

devproxy --config-file .devproxy/devproxyrc.json

Then, configure the app that you're testing to use Dev Proxy. For example, to route requests from a Node.js app through Dev Proxy, start the app with the HTTPS_PROXY environment variable:

HTTPS_PROXY=http://127.0.0.1:8000 npm start

For more information about configuring your app to use Dev Proxy, see the guide for your stack, like Use Dev Proxy with Node.js applications or Use Dev Proxy with .NET applications.

Dev Proxy Toolkit

The Feature adds the Dev Proxy Toolkit extension to VS Code in the dev container. If you don't want to install the extension, exclude it in your devcontainer.json file:

{
  "features": {
    "ghcr.io/dotnet/dev-proxy/dev-proxy:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["-garrytrinder.dev-proxy-toolkit"]
    }
  }
}

Supported images

The Feature supports Debian and Ubuntu-based images on x64 and arm64. Alpine and other musl-based images aren't supported.

See also

  • Last updated on