Introduction

Boot2Docker was the original way many macOS users ran Docker before Docker Desktop became the default. In proxy-controlled networks, getting Docker to work was never just a matter of setting shell variables on the host, because the Docker daemon was running inside a small Linux virtual machine.

Where Proxy Settings Need to Go

With Boot2Docker on OS X, there are two separate layers to think about.

The first layer is the Docker client on your Mac. That client uses environment variables such as HTTP_PROXY and HTTPS_PROXY when commands or build steps need outbound access.

The second layer is the Docker daemon inside the Boot2Docker VM. If only the host shell is configured, image pulls can still fail because the daemon itself does not know how to reach the network through the corporate proxy.

That split is the reason many partial fixes appear to work for one command and fail for another.

Configuring Boot2Docker

Start by exporting proxy variables in the shell where you run Docker commands:

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,192.168.59.103

Then add the same values inside the Boot2Docker VM so the Docker daemon inherits them on startup:

1boot2docker ssh "cat <<'EOF' | sudo tee -a /var/lib/boot2docker/profile
2export HTTP_PROXY=http://proxy.example.com:8080
3export HTTPS_PROXY=http://proxy.example.com:8080
4export NO_PROXY=localhost,127.0.0.1,192.168.59.103
5EOF"
6
7boot2docker restart
8eval "$(boot2docker shellinit)"
9docker pull alpine:3.20

The important file here is /var/lib/boot2docker/profile. Boot2Docker reads it when the VM starts, so restarting the VM is what makes the new daemon environment take effect.

NO_PROXY is just as important as the proxy URL. It prevents local addresses, registry mirrors, and internal services from being sent through the corporate proxy unnecessarily. In many setups you should include loopback addresses, your private Docker subnet, and any internal domains.

Modern Docker Desktop Equivalent

If you are on current macOS tooling, Boot2Docker is mostly a historical case. Docker Desktop can use proxy settings from its UI, and Docker also supports a client-side proxy configuration file.

A modern ~/.docker/config.json can look like this:

1{
2  "proxies": {
3    "default": {
4      "httpProxy": "http://proxy.example.com:8080",
5      "httpsProxy": "http://proxy.example.com:8080",
6      "noProxy": "localhost,127.0.0.1,.corp.example.com"
7    }
8  }
9}

That configuration is useful for builds and containers, but the exact place to set the daemon proxy depends on which Docker runtime you are using. On older Boot2Docker systems, the VM profile was the critical step. It is worth checking the runtime first so you do not spend time editing a legacy VM that is no longer part of your Docker stack.

Common Pitfalls

• Setting proxy variables only on the Mac host and forgetting the Boot2Docker VM. The daemon then fails to pull images even though the shell looks correctly configured.
• Leaving out NO_PROXY. Internal registries and local addresses can break or become slow if they are forced through the proxy.
• Forgetting to restart Boot2Docker after editing /var/lib/boot2docker/profile. The file is only read at startup.
• Embedding raw credentials in proxy URLs without URL-encoding special characters. Characters such as @ and : can change how the address is parsed.
• Applying Boot2Docker instructions to Docker Desktop without checking which runtime is actually installed.

Summary

• On Boot2Docker, proxy settings must be considered at both the Docker client layer and the daemon-in-VM layer.
• Export HTTP_PROXY, HTTPS_PROXY, and NO_PROXY in the host shell.
• Add the same values to /var/lib/boot2docker/profile and restart the VM so the daemon sees them.
• Include local and internal addresses in NO_PROXY to avoid routing the wrong traffic through the proxy.
• On modern macOS systems, prefer Docker Desktop proxy settings or ~/.docker/config.json instead of old Boot2Docker-specific steps.