What does `docker context use` change, and how does DOCKER_HOST interact with it?

## The CLI is a client, and a context names the server The `docker` command-line tool does very little on its own. Every `docker run`, `docker ps`, `docker pull` and `docker build` is an HTTP request to the Engine API, served by a `dockerd` process that is usually - but not necessarily - on the same machine. The only thing the CLI must settle before sending a request is *which* daemon to send it to. A **context** is a named, persisted answer to that question. It holds an endpoint - a unix socket path such as `unix:///var/run/docker.sock`, a `tcp://` URL, or an `ssh://` URL - and optionally the TLS certificate paths used to reach a TLS-protected endpoint. Contexts live in `~/.docker/contexts/` and the selected one is recorded as `currentContext` in `~/.docker/config.json`. ``` docker context create build-host --docker "host=ssh://[email protected]" docker context use build-host docker context ls # the current one is marked with * docker context inspect build-host ``` Every engine has a built-in context called `default`, which is the local daemon as configured by the CLI's defaults; Docker Desktop installs one named `desktop-linux` as well. ## What `use` does and does not do `docker context use build-host` writes one string to a config file. It does not start an SSH session, open a tunnel, sync files, or set anything in your environment that other programs can see. Nothing is validated at that moment either: if the endpoint is wrong you find out on the next command, not on the switch. What changes is the destination of everything afterwards. `docker images` lists the remote daemon's images, not your laptop's. `docker run` starts the container on the remote host, using that host's kernel, CPU architecture, disks and network interfaces. `docker pull` is performed *by the remote daemon* against the registry, so the fact that your laptop already holds the image is irrelevant. Commands that look local because they move data - `docker cp`, `docker logs`, `docker exec -it` - still work, because they stream over the same API rather than touching your filesystem directly. ## Precedence: four ways to name an endpoint Four mechanisms can select an endpoint and they are strictly ranked, strongest first: 1. `-H` / `--host` on the command itself (`docker -H ssh://[email protected] ps`) 2. the `DOCKER_HOST` environment variable 3. the `DOCKER_CONTEXT` environment variable 4. the context selected by `docker context use` The practical consequence is that environment variables outrank the thing you explicitly switched to. A CI job that exports `DOCKER_HOST`, a direnv file, or one forgotten line in `~/.zshrc` will quietly send your commands somewhere else while `docker context ls` still shows the star next to the context you picked. When a command lands on the wrong engine, `docker context ls` alone is not enough evidence - check the environment too. There is also a per-command `--context` flag (`docker --context build-host ps`) for a one-off without switching. ## Why teams point the CLI elsewhere The common motivations are all about the daemon's host being better at something than the laptop. A Kotlin service with a multi-stage Gradle build compiles far faster on a build host whose dependency cache is already warm - a run that reuses that cache at a 71% hit rate finishes in a fraction of the cold time, and the cache stays on the remote engine between runs. Other reasons: building for an architecture your machine does not have; running an integration stack that needs more RAM than a laptop has; or letting several engineers share one beefy engine. ## Contexts versus environment variables Both work; they suit different situations. A context is declarative, survives new shells, can carry TLS certificate paths inside its own definition, and can be listed and inspected. Environment variables are per-shell and per-process, which makes them the right tool inside a script or a CI job where you want an explicit, self-contained target and no dependence on whatever the machine's current context happens to be. Many teams do both: contexts for humans, `DOCKER_HOST` for automation. One last habit worth building: because switching is invisible and sticky, treat "which context am I on?" as the first question whenever a Docker command produces a result that makes no sense - an image you just built that has vanished, a port that is not listening, a volume that is empty.